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