1gitattributes(5) 2================ 3 4NAME 5---- 6gitattributes - defining attributes per path 7 8SYNOPSIS 9-------- 10$GIT_DIR/info/attributes, gitattributes 11 12 13DESCRIPTION 14----------- 15 16A `gitattributes` file is a simple text file that gives 17`attributes` to pathnames. 18 19Each line in `gitattributes` file is of form: 20 21 glob attr1 attr2 ... 22 23That is, a glob pattern followed by an attributes list, 24separated by whitespaces. When the glob pattern matches the 25path in question, the attributes listed on the line are given to 26the path. 27 28Each attribute can be in one of these states for a given path: 29 30Set:: 31 32 The path has the attribute with special value "true"; 33 this is specified by listing only the name of the 34 attribute in the attribute list. 35 36Unset:: 37 38 The path has the attribute with special value "false"; 39 this is specified by listing the name of the attribute 40 prefixed with a dash `-` in the attribute list. 41 42Set to a value:: 43 44 The path has the attribute with specified string value; 45 this is specified by listing the name of the attribute 46 followed by an equal sign `=` and its value in the 47 attribute list. 48 49Unspecified:: 50 51 No glob pattern matches the path, and nothing says if 52 the path has or does not have the attribute, the 53 attribute for the path is said to be Unspecified. 54 55When more than one glob pattern matches the path, a later line 56overrides an earlier line. This overriding is done per 57attribute. 58 59When deciding what attributes are assigned to a path, git 60consults `$GIT_DIR/info/attributes` file (which has the highest 61precedence), `.gitattributes` file in the same directory as the 62path in question, and its parent directories (the further the 63directory that contains `.gitattributes` is from the path in 64question, the lower its precedence). 65 66Sometimes you would need to override an setting of an attribute 67for a path to `unspecified` state. This can be done by listing 68the name of the attribute prefixed with an exclamation point `!`. 69 70 71EFFECTS 72------- 73 74Certain operations by git can be influenced by assigning 75particular attributes to a path. Currently, the following 76operations are attributes-aware. 77 78Checking-out and checking-in 79~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 80 81These attributes affect how the contents stored in the 82repository are copied to the working tree files when commands 83such as `git checkout` and `git merge` run. They also affect how 84git stores the contents you prepare in the working tree in the 85repository upon `git add` and `git commit`. 86 87`crlf` 88^^^^^^ 89 90This attribute controls the line-ending convention. 91 92Set:: 93 94 Setting the `crlf` attribute on a path is meant to mark 95 the path as a "text" file. 'core.autocrlf' conversion 96 takes place without guessing the content type by 97 inspection. 98 99Unset:: 100 101 Unsetting the `crlf` attribute on a path is meant to 102 mark the path as a "binary" file. The path never goes 103 through line endings conversion upon checkin/checkout. 104 105Unspecified:: 106 107 Unspecified `crlf` attribute tells git to apply the 108 `core.autocrlf` conversion when the file content looks 109 like text. 110 111Set to string value "input":: 112 113 This is similar to setting the attribute to `true`, but 114 also forces git to act as if `core.autocrlf` is set to 115 `input` for the path. 116 117Any other value set to `crlf` attribute is ignored and git acts 118as if the attribute is left unspecified. 119 120 121The `core.autocrlf` conversion 122^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 123 124If the configuration variable `core.autocrlf` is false, no 125conversion is done. 126 127When `core.autocrlf` is true, it means that the platform wants 128CRLF line endings for files in the working tree, and you want to 129convert them back to the normal LF line endings when checking 130in to the repository. 131 132When `core.autocrlf` is set to "input", line endings are 133converted to LF upon checkin, but there is no conversion done 134upon checkout. 135 136 137`ident` 138^^^^^^^ 139 140When the attribute `ident` is set to a path, git replaces 141`$Id$` in the blob object with `$Id:`, followed by 14240-character hexadecimal blob object name, followed by a dollar 143sign `$` upon checkout. Any byte sequence that begins with 144`$Id:` and ends with `$` in the worktree file is replaced 145with `$Id$` upon check-in. 146 147 148`filter` 149^^^^^^^^ 150 151A `filter` attribute can be set to a string value. This names 152filter driver specified in the configuration. 153 154A filter driver consists of `clean` command and `smudge` 155command, either of which can be left unspecified. Upon 156checkout, when `smudge` command is specified, the command is fed 157the blob object from its standard input, and its standard output 158is used to update the worktree file. Similarly, `clean` command 159is used to convert the contents of worktree file upon checkin. 160 161Missing filter driver definition in the config is not an error 162but makes the filter a no-op passthru. 163 164The content filtering is done to massage the content into a 165shape that is more convenient for the platform, filesystem, and 166the user to use. The keyword here is "more convenient" and not 167"turning something unusable into usable". In other words, the 168intent is that if someone unsets the filter driver definition, 169or does not have the appropriate filter program, the project 170should still be usable. 171 172 173Interaction between checkin/checkout attributes 174^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 175 176In the check-in codepath, the worktree file is first converted 177with `filter` driver (if specified and corresponding driver 178defined), then the result is processed with `ident` (if 179specified), and then finally with `crlf` (again, if specified 180and applicable). 181 182In the check-out codepath, the blob content is first converted 183with `crlf`, and then `ident` and fed to `filter`. 184 185 186Generating diff text 187~~~~~~~~~~~~~~~~~~~~ 188 189The attribute `diff` affects if `git diff` generates textual 190patch for the path or just says `Binary files differ`. It also 191can affect what line is shown on the hunk header `@@ -k,l +n,m @@` 192line. 193 194Set:: 195 196 A path to which the `diff` attribute is set is treated 197 as text, even when they contain byte values that 198 normally never appear in text files, such as NUL. 199 200Unset:: 201 202 A path to which the `diff` attribute is unset will 203 generate `Binary files differ`. 204 205Unspecified:: 206 207 A path to which the `diff` attribute is unspecified 208 first gets its contents inspected, and if it looks like 209 text, it is treated as text. Otherwise it would 210 generate `Binary files differ`. 211 212String:: 213 214 Diff is shown using the specified custom diff driver. 215 The driver program is given its input using the same 216 calling convention as used for GIT_EXTERNAL_DIFF 217 program. This name is also used for custom hunk header 218 selection. 219 220 221Defining a custom diff driver 222^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 223 224The definition of a diff driver is done in `gitconfig`, not 225`gitattributes` file, so strictly speaking this manual page is a 226wrong place to talk about it. However... 227 228To define a custom diff driver `jcdiff`, add a section to your 229`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 230 231---------------------------------------------------------------- 232[diff "jcdiff"] 233 command = j-c-diff 234---------------------------------------------------------------- 235 236When git needs to show you a diff for the path with `diff` 237attribute set to `jcdiff`, it calls the command you specified 238with the above configuration, i.e. `j-c-diff`, with 7 239parameters, just like `GIT_EXTERNAL_DIFF` program is called. 240See gitlink:git[7] for details. 241 242 243Defining a custom hunk-header 244^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 245 246Each group of changes (called "hunk") in the textual diff output 247is prefixed with a line of the form: 248 249 @@ -k,l +n,m @@ TEXT 250 251The text is called 'hunk header', and by default a line that 252begins with an alphabet, an underscore or a dollar sign is used, 253which matches what GNU `diff -p` output uses. This default 254selection however is not suited for some contents, and you can 255use customized pattern to make a selection. 256 257First in .gitattributes, you would assign the `diff` attribute 258for paths. 259 260------------------------ 261*.tex diff=tex 262------------------------ 263 264Then, you would define "diff.tex.funcname" configuration to 265specify a regular expression that matches a line that you would 266want to appear as the hunk header, like this: 267 268------------------------ 269[diff "tex"] 270 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$" 271------------------------ 272 273Note. A single level of backslashes are eaten by the 274configuration file parser, so you would need to double the 275backslashes; the pattern above picks a line that begins with a 276backslash, and zero or more occurrences of `sub` followed by 277`section` followed by open brace, to the end of line. 278 279There are a few built-in patterns to make this easier, and `tex` 280is one of them, so you do not have to write the above in your 281configuration file (you still need to enable this with the 282attribute mechanism, via `.gitattributes`). Another built-in 283pattern is defined for `java` that defines a pattern suitable 284for program text in Java language. 285 286 287Performing a three-way merge 288~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 289 290The attribute `merge` affects how three versions of a file is 291merged when a file-level merge is necessary during `git merge`, 292and other programs such as `git revert` and `git cherry-pick`. 293 294Set:: 295 296 Built-in 3-way merge driver is used to merge the 297 contents in a way similar to `merge` command of `RCS` 298 suite. This is suitable for ordinary text files. 299 300Unset:: 301 302 Take the version from the current branch as the 303 tentative merge result, and declare that the merge has 304 conflicts. This is suitable for binary files that does 305 not have a well-defined merge semantics. 306 307Unspecified:: 308 309 By default, this uses the same built-in 3-way merge 310 driver as is the case the `merge` attribute is set. 311 However, `merge.default` configuration variable can name 312 different merge driver to be used for paths to which the 313 `merge` attribute is unspecified. 314 315String:: 316 317 3-way merge is performed using the specified custom 318 merge driver. The built-in 3-way merge driver can be 319 explicitly specified by asking for "text" driver; the 320 built-in "take the current branch" driver can be 321 requested with "binary". 322 323 324Defining a custom merge driver 325^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 326 327The definition of a merge driver is done in `gitconfig` not 328`gitattributes` file, so strictly speaking this manual page is a 329wrong place to talk about it. However... 330 331To define a custom merge driver `filfre`, add a section to your 332`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 333 334---------------------------------------------------------------- 335[merge "filfre"] 336 name = feel-free merge driver 337 driver = filfre %O %A %B 338 recursive = binary 339---------------------------------------------------------------- 340 341The `merge.*.name` variable gives the driver a human-readable 342name. 343 344The `merge.*.driver` variable's value is used to construct a 345command to run to merge ancestor's version (`%O`), current 346version (`%A`) and the other branches' version (`%B`). These 347three tokens are replaced with the names of temporary files that 348hold the contents of these versions when the command line is 349built. 350 351The merge driver is expected to leave the result of the merge in 352the file named with `%A` by overwriting it, and exit with zero 353status if it managed to merge them cleanly, or non-zero if there 354were conflicts. 355 356The `merge.*.recursive` variable specifies what other merge 357driver to use when the merge driver is called for an internal 358merge between common ancestors, when there are more than one. 359When left unspecified, the driver itself is used for both 360internal merge and the final merge. 361 362 363EXAMPLE 364------- 365 366If you have these three `gitattributes` file: 367 368---------------------------------------------------------------- 369(in $GIT_DIR/info/attributes) 370 371a* foo !bar -baz 372 373(in .gitattributes) 374abc foo bar baz 375 376(in t/.gitattributes) 377ab* merge=filfre 378abc -foo -bar 379*.c frotz 380---------------------------------------------------------------- 381 382the attributes given to path `t/abc` are computed as follows: 383 3841. By examining `t/.gitattributes` (which is in the same 385 directory as the path in question), git finds that the first 386 line matches. `merge` attribute is set. It also finds that 387 the second line matches, and attributes `foo` and `bar` 388 are unset. 389 3902. Then it examines `.gitattributes` (which is in the parent 391 directory), and finds that the first line matches, but 392 `t/.gitattributes` file already decided how `merge`, `foo` 393 and `bar` attributes should be given to this path, so it 394 leaves `foo` and `bar` unset. Attribute `baz` is set. 395 3963. Finally it examines `$GIT_DIR/info/attributes`. This file 397 is used to override the in-tree settings. The first line is 398 a match, and `foo` is set, `bar` is reverted to unspecified 399 state, and `baz` is unset. 400 401As the result, the attributes assignment to `t/abc` becomes: 402 403---------------------------------------------------------------- 404foo set to true 405bar unspecified 406baz set to false 407merge set to string value "filfre" 408frotz unspecified 409---------------------------------------------------------------- 410 411 412Creating an archive 413~~~~~~~~~~~~~~~~~~~ 414 415`export-subst` 416^^^^^^^^^^^^^^ 417 418If the attribute `export-subst` is set for a file then git will expand 419several placeholders when adding this file to an archive. The 420expansion depends on the availability of a commit ID, i.e. if 421gitlink:git-archive[1] has been given a tree instead of a commit or a 422tag then no replacement will be done. The placeholders are the same 423as those for the option `--pretty=format:` of gitlink:git-log[1], 424except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 425in the file. E.g. the string `$Format:%H$` will be replaced by the 426commit hash. 427 428 429GIT 430--- 431Part of the gitlink:git[7] suite