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`). The following built in 311patterns are available: 312 313- `java` suitable for source code in the Java lanugage. 314 315- `pascal` suitable for source code in the Pascal/Delphi language. 316 317- `ruby` suitable for source code in the Ruby language. 318 319- `tex` suitable for source code for LaTeX documents. 320 321 322Performing a three-way merge 323~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 324 325The attribute `merge` affects how three versions of a file is 326merged when a file-level merge is necessary during `git merge`, 327and other programs such as `git revert` and `git cherry-pick`. 328 329Set:: 330 331 Built-in 3-way merge driver is used to merge the 332 contents in a way similar to 'merge' command of `RCS` 333 suite. This is suitable for ordinary text files. 334 335Unset:: 336 337 Take the version from the current branch as the 338 tentative merge result, and declare that the merge has 339 conflicts. This is suitable for binary files that does 340 not have a well-defined merge semantics. 341 342Unspecified:: 343 344 By default, this uses the same built-in 3-way merge 345 driver as is the case the `merge` attribute is set. 346 However, `merge.default` configuration variable can name 347 different merge driver to be used for paths to which the 348 `merge` attribute is unspecified. 349 350String:: 351 352 3-way merge is performed using the specified custom 353 merge driver. The built-in 3-way merge driver can be 354 explicitly specified by asking for "text" driver; the 355 built-in "take the current branch" driver can be 356 requested with "binary". 357 358 359Built-in merge drivers 360^^^^^^^^^^^^^^^^^^^^^^ 361 362There are a few built-in low-level merge drivers defined that 363can be asked for via the `merge` attribute. 364 365text:: 366 367 Usual 3-way file level merge for text files. Conflicted 368 regions are marked with conflict markers `<<<<<<<`, 369 `=======` and `>>>>>>>`. The version from your branch 370 appears before the `=======` marker, and the version 371 from the merged branch appears after the `=======` 372 marker. 373 374binary:: 375 376 Keep the version from your branch in the work tree, but 377 leave the path in the conflicted state for the user to 378 sort out. 379 380union:: 381 382 Run 3-way file level merge for text files, but take 383 lines from both versions, instead of leaving conflict 384 markers. This tends to leave the added lines in the 385 resulting file in random order and the user should 386 verify the result. Do not use this if you do not 387 understand the implications. 388 389 390Defining a custom merge driver 391^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 392 393The definition of a merge driver is done in the `.git/config` 394file, not in the `gitattributes` file, so strictly speaking this 395manual page is a wrong place to talk about it. However... 396 397To define a custom merge driver `filfre`, add a section to your 398`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 399 400---------------------------------------------------------------- 401[merge "filfre"] 402 name = feel-free merge driver 403 driver = filfre %O %A %B 404 recursive = binary 405---------------------------------------------------------------- 406 407The `merge.*.name` variable gives the driver a human-readable 408name. 409 410The `merge.*.driver` variable's value is used to construct a 411command to run to merge ancestor's version (`%O`), current 412version (`%A`) and the other branches' version (`%B`). These 413three tokens are replaced with the names of temporary files that 414hold the contents of these versions when the command line is 415built. 416 417The merge driver is expected to leave the result of the merge in 418the file named with `%A` by overwriting it, and exit with zero 419status if it managed to merge them cleanly, or non-zero if there 420were conflicts. 421 422The `merge.*.recursive` variable specifies what other merge 423driver to use when the merge driver is called for an internal 424merge between common ancestors, when there are more than one. 425When left unspecified, the driver itself is used for both 426internal merge and the final merge. 427 428 429Checking whitespace errors 430~~~~~~~~~~~~~~~~~~~~~~~~~~ 431 432`whitespace` 433^^^^^^^^^^^^ 434 435The `core.whitespace` configuration variable allows you to define what 436'diff' and 'apply' should consider whitespace errors for all paths in 437the project (See linkgit:git-config[1]). This attribute gives you finer 438control per path. 439 440Set:: 441 442 Notice all types of potential whitespace errors known to git. 443 444Unset:: 445 446 Do not notice anything as error. 447 448Unspecified:: 449 450 Use the value of `core.whitespace` configuration variable to 451 decide what to notice as error. 452 453String:: 454 455 Specify a comma separate list of common whitespace problems to 456 notice in the same format as `core.whitespace` configuration 457 variable. 458 459 460Creating an archive 461~~~~~~~~~~~~~~~~~~~ 462 463`export-ignore` 464^^^^^^^^^^^^^^^ 465 466Files and directories with the attribute `export-ignore` won't be added to 467archive files. 468 469`export-subst` 470^^^^^^^^^^^^^^ 471 472If the attribute `export-subst` is set for a file then git will expand 473several placeholders when adding this file to an archive. The 474expansion depends on the availability of a commit ID, i.e., if 475linkgit:git-archive[1] has been given a tree instead of a commit or a 476tag then no replacement will be done. The placeholders are the same 477as those for the option `--pretty=format:` of linkgit:git-log[1], 478except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 479in the file. E.g. the string `$Format:%H$` will be replaced by the 480commit hash. 481 482 483EXAMPLE 484------- 485 486If you have these three `gitattributes` file: 487 488---------------------------------------------------------------- 489(in $GIT_DIR/info/attributes) 490 491a* foo !bar -baz 492 493(in .gitattributes) 494abc foo bar baz 495 496(in t/.gitattributes) 497ab* merge=filfre 498abc -foo -bar 499*.c frotz 500---------------------------------------------------------------- 501 502the attributes given to path `t/abc` are computed as follows: 503 5041. By examining `t/.gitattributes` (which is in the same 505 directory as the path in question), git finds that the first 506 line matches. `merge` attribute is set. It also finds that 507 the second line matches, and attributes `foo` and `bar` 508 are unset. 509 5102. Then it examines `.gitattributes` (which is in the parent 511 directory), and finds that the first line matches, but 512 `t/.gitattributes` file already decided how `merge`, `foo` 513 and `bar` attributes should be given to this path, so it 514 leaves `foo` and `bar` unset. Attribute `baz` is set. 515 5163. Finally it examines `$GIT_DIR/info/attributes`. This file 517 is used to override the in-tree settings. The first line is 518 a match, and `foo` is set, `bar` is reverted to unspecified 519 state, and `baz` is unset. 520 521As the result, the attributes assignment to `t/abc` becomes: 522 523---------------------------------------------------------------- 524foo set to true 525bar unspecified 526baz set to false 527merge set to string value "filfre" 528frotz unspecified 529---------------------------------------------------------------- 530 531 532 533GIT 534--- 535Part of the linkgit:git[1] suite