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, three operations 76are 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 148Interaction between checkin/checkout attributes 149^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 150 151In the check-in codepath, the worktree file is first converted 152with `ident` (if specified), and then with `crlf` (again, if 153specified and applicable). 154 155In the check-out codepath, the blob content is first converted 156with `crlf`, and then `ident`. 157 158 159`filter` 160^^^^^^^^ 161 162A `filter` attribute can be set to a string value. This names 163filter driver specified in the configuration. 164 165A filter driver consists of `clean` command and `smudge` 166command, either of which can be left unspecified. Upon 167checkout, when `smudge` command is specified, the command is fed 168the blob object from its standard input, and its standard output 169is used to update the worktree file. Similarly, `clean` command 170is used to convert the contents of worktree file upon checkin. 171 172Missing filter driver definition in the config is not an error 173but makes the filter a no-op passthru. 174 175The content filtering is done to massage the content into a 176shape that is more convenient for the platform, filesystem, and 177the user to use. The keyword here is "more convenient" and not 178"turning something unusable into usable". In other words, it is 179"hanging yourself because we gave you a long rope" if your 180project uses filtering mechanism in such a way that it makes 181your project unusable unless the checkout is done with a 182specific filter in effect. 183 184 185Interaction between checkin/checkout attributes 186^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 187 188In the check-in codepath, the worktree file is first converted 189with `filter` driver (if specified and corresponding driver 190defined), then the result is processed with `ident` (if 191specified), and then finally with `crlf` (again, if specified 192and applicable). 193 194In the check-out codepath, the blob content is first converted 195with `crlf`, and then `ident` and fed to `filter`. 196 197 198Generating diff text 199~~~~~~~~~~~~~~~~~~~~ 200 201The attribute `diff` affects if `git diff` generates textual 202patch for the path or just says `Binary files differ`. 203 204Set:: 205 206 A path to which the `diff` attribute is set is treated 207 as text, even when they contain byte values that 208 normally never appear in text files, such as NUL. 209 210Unset:: 211 212 A path to which the `diff` attribute is unset will 213 generate `Binary files differ`. 214 215Unspecified:: 216 217 A path to which the `diff` attribute is unspecified 218 first gets its contents inspected, and if it looks like 219 text, it is treated as text. Otherwise it would 220 generate `Binary files differ`. 221 222String:: 223 224 Diff is shown using the specified custom diff driver. 225 The driver program is given its input using the same 226 calling convention as used for GIT_EXTERNAL_DIFF 227 program. 228 229 230Defining a custom diff driver 231^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 232 233The definition of a diff driver is done in `gitconfig`, not 234`gitattributes` file, so strictly speaking this manual page is a 235wrong place to talk about it. However... 236 237To define a custom diff driver `jcdiff`, add a section to your 238`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 239 240---------------------------------------------------------------- 241[diff "jcdiff"] 242 command = j-c-diff 243---------------------------------------------------------------- 244 245When git needs to show you a diff for the path with `diff` 246attribute set to `jcdiff`, it calls the command you specified 247with the above configuration, i.e. `j-c-diff`, with 7 248parameters, just like `GIT_EXTERNAL_DIFF` program is called. 249See gitlink:git[7] for details. 250 251 252Performing a three-way merge 253~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 254 255The attribute `merge` affects how three versions of a file is 256merged when a file-level merge is necessary during `git merge`, 257and other programs such as `git revert` and `git cherry-pick`. 258 259Set:: 260 261 Built-in 3-way merge driver is used to merge the 262 contents in a way similar to `merge` command of `RCS` 263 suite. This is suitable for ordinary text files. 264 265Unset:: 266 267 Take the version from the current branch as the 268 tentative merge result, and declare that the merge has 269 conflicts. This is suitable for binary files that does 270 not have a well-defined merge semantics. 271 272Unspecified:: 273 274 By default, this uses the same built-in 3-way merge 275 driver as is the case the `merge` attribute is set. 276 However, `merge.default` configuration variable can name 277 different merge driver to be used for paths to which the 278 `merge` attribute is unspecified. 279 280String:: 281 282 3-way merge is performed using the specified custom 283 merge driver. The built-in 3-way merge driver can be 284 explicitly specified by asking for "text" driver; the 285 built-in "take the current branch" driver can be 286 requested with "binary". 287 288 289Defining a custom merge driver 290^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 291 292The definition of a merge driver is done in `gitconfig` not 293`gitattributes` file, so strictly speaking this manual page is a 294wrong place to talk about it. However... 295 296To define a custom merge driver `filfre`, add a section to your 297`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 298 299---------------------------------------------------------------- 300[merge "filfre"] 301 name = feel-free merge driver 302 driver = filfre %O %A %B 303 recursive = binary 304---------------------------------------------------------------- 305 306The `merge.*.name` variable gives the driver a human-readable 307name. 308 309The `merge.*.driver` variable's value is used to construct a 310command to run to merge ancestor's version (`%O`), current 311version (`%A`) and the other branches' version (`%B`). These 312three tokens are replaced with the names of temporary files that 313hold the contents of these versions when the command line is 314built. 315 316The merge driver is expected to leave the result of the merge in 317the file named with `%A` by overwriting it, and exit with zero 318status if it managed to merge them cleanly, or non-zero if there 319were conflicts. 320 321The `merge.*.recursive` variable specifies what other merge 322driver to use when the merge driver is called for an internal 323merge between common ancestors, when there are more than one. 324When left unspecified, the driver itself is used for both 325internal merge and the final merge. 326 327 328EXAMPLE 329------- 330 331If you have these three `gitattributes` file: 332 333---------------------------------------------------------------- 334(in $GIT_DIR/info/attributes) 335 336a* foo !bar -baz 337 338(in .gitattributes) 339abc foo bar baz 340 341(in t/.gitattributes) 342ab* merge=filfre 343abc -foo -bar 344*.c frotz 345---------------------------------------------------------------- 346 347the attributes given to path `t/abc` are computed as follows: 348 3491. By examining `t/.gitattributes` (which is in the same 350 diretory as the path in question), git finds that the first 351 line matches. `merge` attribute is set. It also finds that 352 the second line matches, and attributes `foo` and `bar` 353 are unset. 354 3552. Then it examines `.gitattributes` (which is in the parent 356 directory), and finds that the first line matches, but 357 `t/.gitattributes` file already decided how `merge`, `foo` 358 and `bar` attributes should be given to this path, so it 359 leaves `foo` and `bar` unset. Attribute `baz` is set. 360 3613. Finally it examines `$GIT_DIR/info/gitattributes`. This file 362 is used to override the in-tree settings. The first line is 363 a match, and `foo` is set, `bar` is reverted to unspecified 364 state, and `baz` is unset. 365 366As the result, the attributes assignement to `t/abc` becomes: 367 368---------------------------------------------------------------- 369foo set to true 370bar unspecified 371baz set to false 372merge set to string value "filfre" 373frotz unspecified 374---------------------------------------------------------------- 375 376 377GIT 378--- 379Part of the gitlink:git[7] suite