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 66If you wish to affect only a single repository (i.e., to assign 67attributes to files that are particular to one user's workflow), then 68attributes should be placed in the `$GIT_DIR/info/attributes` file. 69Attributes which should be version-controlled and distributed to other 70repositories (i.e., attributes of interest to all users) should go into 71`.gitattributes` files. 72 73Sometimes you would need to override an setting of an attribute 74for a path to `unspecified` state. This can be done by listing 75the name of the attribute prefixed with an exclamation point `!`. 76 77 78EFFECTS 79------- 80 81Certain operations by git can be influenced by assigning 82particular attributes to a path. Currently, the following 83operations are attributes-aware. 84 85Checking-out and checking-in 86~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 87 88These attributes affect how the contents stored in the 89repository are copied to the working tree files when commands 90such as `git checkout` and `git merge` run. They also affect how 91git stores the contents you prepare in the working tree in the 92repository upon `git add` and `git commit`. 93 94`crlf` 95^^^^^^ 96 97This attribute controls the line-ending convention. 98 99Set:: 100 101 Setting the `crlf` attribute on a path is meant to mark 102 the path as a "text" file. 'core.autocrlf' conversion 103 takes place without guessing the content type by 104 inspection. 105 106Unset:: 107 108 Unsetting the `crlf` attribute on a path is meant to 109 mark the path as a "binary" file. The path never goes 110 through line endings conversion upon checkin/checkout. 111 112Unspecified:: 113 114 Unspecified `crlf` attribute tells git to apply the 115 `core.autocrlf` conversion when the file content looks 116 like text. 117 118Set to string value "input":: 119 120 This is similar to setting the attribute to `true`, but 121 also forces git to act as if `core.autocrlf` is set to 122 `input` for the path. 123 124Any other value set to `crlf` attribute is ignored and git acts 125as if the attribute is left unspecified. 126 127 128The `core.autocrlf` conversion 129^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 130 131If the configuration variable `core.autocrlf` is false, no 132conversion is done. 133 134When `core.autocrlf` is true, it means that the platform wants 135CRLF line endings for files in the working tree, and you want to 136convert them back to the normal LF line endings when checking 137in to the repository. 138 139When `core.autocrlf` is set to "input", line endings are 140converted to LF upon checkin, but there is no conversion done 141upon checkout. 142 143If `core.safecrlf` is set to "true" or "warn", git verifies if 144the conversion is reversible for the current setting of 145`core.autocrlf`. For "true", git rejects irreversible 146conversions; for "warn", git only prints a warning but accepts 147an irreversible conversion. The safety triggers to prevent such 148a conversion done to the files in the work tree, but there are a 149few exceptions. Even though... 150 151- "git add" itself does not touch the files in the work tree, the 152 next checkout would, so the safety triggers; 153 154- "git apply" to update a text file with a patch does touch the files 155 in the work tree, but the operation is about text files and CRLF 156 conversion is about fixing the line ending inconsistencies, so the 157 safety does not trigger; 158 159- "git diff" itself does not touch the files in the work tree, it is 160 often run to inspect the changes you intend to next "git add". To 161 catch potential problems early, safety triggers. 162 163 164`ident` 165^^^^^^^ 166 167When the attribute `ident` is set to a path, git replaces 168`$Id$` in the blob object with `$Id:`, followed by 16940-character hexadecimal blob object name, followed by a dollar 170sign `$` upon checkout. Any byte sequence that begins with 171`$Id:` and ends with `$` in the worktree file is replaced 172with `$Id$` upon check-in. 173 174 175`filter` 176^^^^^^^^ 177 178A `filter` attribute can be set to a string value that names a 179filter driver specified in the configuration. 180 181A filter driver consists of a `clean` command and a `smudge` 182command, either of which can be left unspecified. Upon 183checkout, when the `smudge` command is specified, the command is 184fed the blob object from its standard input, and its standard 185output is used to update the worktree file. Similarly, the 186`clean` command is used to convert the contents of worktree file 187upon checkin. 188 189A missing filter driver definition in the config is not an error 190but makes the filter a no-op passthru. 191 192The content filtering is done to massage the content into a 193shape that is more convenient for the platform, filesystem, and 194the user to use. The key phrase here is "more convenient" and not 195"turning something unusable into usable". In other words, the 196intent is that if someone unsets the filter driver definition, 197or does not have the appropriate filter program, the project 198should still be usable. 199 200 201Interaction between checkin/checkout attributes 202^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 203 204In the check-in codepath, the worktree file is first converted 205with `filter` driver (if specified and corresponding driver 206defined), then the result is processed with `ident` (if 207specified), and then finally with `crlf` (again, if specified 208and applicable). 209 210In the check-out codepath, the blob content is first converted 211with `crlf`, and then `ident` and fed to `filter`. 212 213 214Generating diff text 215~~~~~~~~~~~~~~~~~~~~ 216 217The attribute `diff` affects if `git diff` generates textual 218patch for the path or just says `Binary files differ`. It also 219can affect what line is shown on the hunk header `@@ -k,l +n,m @@` 220line. 221 222Set:: 223 224 A path to which the `diff` attribute is set is treated 225 as text, even when they contain byte values that 226 normally never appear in text files, such as NUL. 227 228Unset:: 229 230 A path to which the `diff` attribute is unset will 231 generate `Binary files differ`. 232 233Unspecified:: 234 235 A path to which the `diff` attribute is unspecified 236 first gets its contents inspected, and if it looks like 237 text, it is treated as text. Otherwise it would 238 generate `Binary files differ`. 239 240String:: 241 242 Diff is shown using the specified custom diff driver. 243 The driver program is given its input using the same 244 calling convention as used for GIT_EXTERNAL_DIFF 245 program. This name is also used for custom hunk header 246 selection. 247 248 249Defining a custom diff driver 250^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 251 252The definition of a diff driver is done in `gitconfig`, not 253`gitattributes` file, so strictly speaking this manual page is a 254wrong place to talk about it. However... 255 256To define a custom diff driver `jcdiff`, add a section to your 257`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 258 259---------------------------------------------------------------- 260[diff "jcdiff"] 261 command = j-c-diff 262---------------------------------------------------------------- 263 264When git needs to show you a diff for the path with `diff` 265attribute set to `jcdiff`, it calls the command you specified 266with the above configuration, i.e. `j-c-diff`, with 7 267parameters, just like `GIT_EXTERNAL_DIFF` program is called. 268See linkgit:git[1] for details. 269 270 271Defining a custom hunk-header 272^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 273 274Each group of changes (called "hunk") in the textual diff output 275is prefixed with a line of the form: 276 277 @@ -k,l +n,m @@ TEXT 278 279The text is called 'hunk header', and by default a line that 280begins with an alphabet, an underscore or a dollar sign is used, 281which matches what GNU `diff -p` output uses. This default 282selection however is not suited for some contents, and you can 283use customized pattern to make a selection. 284 285First in .gitattributes, you would assign the `diff` attribute 286for paths. 287 288------------------------ 289*.tex diff=tex 290------------------------ 291 292Then, you would define "diff.tex.funcname" configuration to 293specify a regular expression that matches a line that you would 294want to appear as the hunk header, like this: 295 296------------------------ 297[diff "tex"] 298 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$" 299------------------------ 300 301Note. A single level of backslashes are eaten by the 302configuration file parser, so you would need to double the 303backslashes; the pattern above picks a line that begins with a 304backslash, and zero or more occurrences of `sub` followed by 305`section` followed by open brace, to the end of line. 306 307There are a few built-in patterns to make this easier, and `tex` 308is one of them, so you do not have to write the above in your 309configuration file (you still need to enable this with the 310attribute mechanism, via `.gitattributes`). Another built-in 311pattern is defined for `java` that defines a pattern suitable 312for program text in Java language. 313 314 315Performing a three-way merge 316~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 317 318The attribute `merge` affects how three versions of a file is 319merged when a file-level merge is necessary during `git merge`, 320and other programs such as `git revert` and `git cherry-pick`. 321 322Set:: 323 324 Built-in 3-way merge driver is used to merge the 325 contents in a way similar to `merge` command of `RCS` 326 suite. This is suitable for ordinary text files. 327 328Unset:: 329 330 Take the version from the current branch as the 331 tentative merge result, and declare that the merge has 332 conflicts. This is suitable for binary files that does 333 not have a well-defined merge semantics. 334 335Unspecified:: 336 337 By default, this uses the same built-in 3-way merge 338 driver as is the case the `merge` attribute is set. 339 However, `merge.default` configuration variable can name 340 different merge driver to be used for paths to which the 341 `merge` attribute is unspecified. 342 343String:: 344 345 3-way merge is performed using the specified custom 346 merge driver. The built-in 3-way merge driver can be 347 explicitly specified by asking for "text" driver; the 348 built-in "take the current branch" driver can be 349 requested with "binary". 350 351 352Built-in merge drivers 353^^^^^^^^^^^^^^^^^^^^^^ 354 355There are a few built-in low-level merge drivers defined that 356can be asked for via the `merge` attribute. 357 358text:: 359 360 Usual 3-way file level merge for text files. Conflicted 361 regions are marked with conflict markers `<<<<<<<`, 362 `=======` and `>>>>>>>`. The version from your branch 363 appears before the `=======` marker, and the version 364 from the merged branch appears after the `=======` 365 marker. 366 367binary:: 368 369 Keep the version from your branch in the work tree, but 370 leave the path in the conflicted state for the user to 371 sort out. 372 373union:: 374 375 Run 3-way file level merge for text files, but take 376 lines from both versions, instead of leaving conflict 377 markers. This tends to leave the added lines in the 378 resulting file in random order and the user should 379 verify the result. Do not use this if you do not 380 understand the implications. 381 382 383Defining a custom merge driver 384^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 385 386The definition of a merge driver is done in the `.git/config` 387file, not in the `gitattributes` file, so strictly speaking this 388manual page is a wrong place to talk about it. However... 389 390To define a custom merge driver `filfre`, add a section to your 391`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 392 393---------------------------------------------------------------- 394[merge "filfre"] 395 name = feel-free merge driver 396 driver = filfre %O %A %B 397 recursive = binary 398---------------------------------------------------------------- 399 400The `merge.*.name` variable gives the driver a human-readable 401name. 402 403The `merge.*.driver` variable's value is used to construct a 404command to run to merge ancestor's version (`%O`), current 405version (`%A`) and the other branches' version (`%B`). These 406three tokens are replaced with the names of temporary files that 407hold the contents of these versions when the command line is 408built. 409 410The merge driver is expected to leave the result of the merge in 411the file named with `%A` by overwriting it, and exit with zero 412status if it managed to merge them cleanly, or non-zero if there 413were conflicts. 414 415The `merge.*.recursive` variable specifies what other merge 416driver to use when the merge driver is called for an internal 417merge between common ancestors, when there are more than one. 418When left unspecified, the driver itself is used for both 419internal merge and the final merge. 420 421 422Checking whitespace errors 423~~~~~~~~~~~~~~~~~~~~~~~~~~ 424 425`whitespace` 426^^^^^^^^^^^^ 427 428The `core.whitespace` configuration variable allows you to define what 429`diff` and `apply` should consider whitespace errors for all paths in 430the project (See linkgit:git-config[1]). This attribute gives you finer 431control per path. 432 433Set:: 434 435 Notice all types of potential whitespace errors known to git. 436 437Unset:: 438 439 Do not notice anything as error. 440 441Unspecified:: 442 443 Use the value of `core.whitespace` configuration variable to 444 decide what to notice as error. 445 446String:: 447 448 Specify a comma separate list of common whitespace problems to 449 notice in the same format as `core.whitespace` configuration 450 variable. 451 452 453Creating an archive 454~~~~~~~~~~~~~~~~~~~ 455 456`export-subst` 457^^^^^^^^^^^^^^ 458 459If the attribute `export-subst` is set for a file then git will expand 460several placeholders when adding this file to an archive. The 461expansion depends on the availability of a commit ID, i.e. if 462linkgit:git-archive[1] has been given a tree instead of a commit or a 463tag then no replacement will be done. The placeholders are the same 464as those for the option `--pretty=format:` of linkgit:git-log[1], 465except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 466in the file. E.g. the string `$Format:%H$` will be replaced by the 467commit hash. 468 469 470EXAMPLE 471------- 472 473If you have these three `gitattributes` file: 474 475---------------------------------------------------------------- 476(in $GIT_DIR/info/attributes) 477 478a* foo !bar -baz 479 480(in .gitattributes) 481abc foo bar baz 482 483(in t/.gitattributes) 484ab* merge=filfre 485abc -foo -bar 486*.c frotz 487---------------------------------------------------------------- 488 489the attributes given to path `t/abc` are computed as follows: 490 4911. By examining `t/.gitattributes` (which is in the same 492 directory as the path in question), git finds that the first 493 line matches. `merge` attribute is set. It also finds that 494 the second line matches, and attributes `foo` and `bar` 495 are unset. 496 4972. Then it examines `.gitattributes` (which is in the parent 498 directory), and finds that the first line matches, but 499 `t/.gitattributes` file already decided how `merge`, `foo` 500 and `bar` attributes should be given to this path, so it 501 leaves `foo` and `bar` unset. Attribute `baz` is set. 502 5033. Finally it examines `$GIT_DIR/info/attributes`. This file 504 is used to override the in-tree settings. The first line is 505 a match, and `foo` is set, `bar` is reverted to unspecified 506 state, and `baz` is unset. 507 508As the result, the attributes assignment to `t/abc` becomes: 509 510---------------------------------------------------------------- 511foo set to true 512bar unspecified 513baz set to false 514merge set to string value "filfre" 515frotz unspecified 516---------------------------------------------------------------- 517 518 519 520GIT 521--- 522Part of the linkgit:git[1] suite