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 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`. It also 203can affect what line is shown on the hunk header `@@ -k,l +n,m @@` 204line. 205 206Set:: 207 208 A path to which the `diff` attribute is set is treated 209 as text, even when they contain byte values that 210 normally never appear in text files, such as NUL. 211 212Unset:: 213 214 A path to which the `diff` attribute is unset will 215 generate `Binary files differ`. 216 217Unspecified:: 218 219 A path to which the `diff` attribute is unspecified 220 first gets its contents inspected, and if it looks like 221 text, it is treated as text. Otherwise it would 222 generate `Binary files differ`. 223 224String:: 225 226 Diff is shown using the specified custom diff driver. 227 The driver program is given its input using the same 228 calling convention as used for GIT_EXTERNAL_DIFF 229 program. This name is also used for custom hunk header 230 selection. 231 232 233Defining a custom diff driver 234^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 235 236The definition of a diff driver is done in `gitconfig`, not 237`gitattributes` file, so strictly speaking this manual page is a 238wrong place to talk about it. However... 239 240To define a custom diff driver `jcdiff`, add a section to your 241`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 242 243---------------------------------------------------------------- 244[diff "jcdiff"] 245 command = j-c-diff 246---------------------------------------------------------------- 247 248When git needs to show you a diff for the path with `diff` 249attribute set to `jcdiff`, it calls the command you specified 250with the above configuration, i.e. `j-c-diff`, with 7 251parameters, just like `GIT_EXTERNAL_DIFF` program is called. 252See gitlink:git[7] for details. 253 254 255Defining a custom hunk-header 256^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 257 258Each group of changes (called "hunk") in the textual diff output 259is prefixed with a line of the form: 260 261 @@ -k,l +n,m @@ TEXT 262 263The text is called 'hunk header', and by default a line that 264begins with an alphabet, an underscore or a dollar sign is used, 265which matches what GNU `diff -p` output uses. This default 266selection however is not suited for some contents, and you can 267use customized pattern to make a selection. 268 269First in .gitattributes, you would assign the `diff` attribute 270for paths. 271 272------------------------ 273*.tex diff=tex 274------------------------ 275 276Then, you would define "diff.tex.funcname" configuration to 277specify a regular expression that matches a line that you would 278want to appear as the hunk header, like this: 279 280------------------------ 281[diff "tex"] 282 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$" 283------------------------ 284 285Note. A single level of backslashes are eaten by the 286configuration file parser, so you would need to double the 287backslashes; the pattern above picks a line that begins with a 288backslash, and zero or more occurrences of `sub` followed by 289`section` followed by open brace, to the end of line. 290 291There are a few built-in patterns to make this easier, and `tex` 292is one of them, so you do not have to write the above in your 293configuration file (you still need to enable this with the 294attribute mechanism, via `.gitattributes`). Another built-in 295pattern is defined for `java` that defines a pattern suitable 296for program text in Java language. 297 298 299Performing a three-way merge 300~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 301 302The attribute `merge` affects how three versions of a file is 303merged when a file-level merge is necessary during `git merge`, 304and other programs such as `git revert` and `git cherry-pick`. 305 306Set:: 307 308 Built-in 3-way merge driver is used to merge the 309 contents in a way similar to `merge` command of `RCS` 310 suite. This is suitable for ordinary text files. 311 312Unset:: 313 314 Take the version from the current branch as the 315 tentative merge result, and declare that the merge has 316 conflicts. This is suitable for binary files that does 317 not have a well-defined merge semantics. 318 319Unspecified:: 320 321 By default, this uses the same built-in 3-way merge 322 driver as is the case the `merge` attribute is set. 323 However, `merge.default` configuration variable can name 324 different merge driver to be used for paths to which the 325 `merge` attribute is unspecified. 326 327String:: 328 329 3-way merge is performed using the specified custom 330 merge driver. The built-in 3-way merge driver can be 331 explicitly specified by asking for "text" driver; the 332 built-in "take the current branch" driver can be 333 requested with "binary". 334 335 336Defining a custom merge driver 337^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 338 339The definition of a merge driver is done in `gitconfig` not 340`gitattributes` file, so strictly speaking this manual page is a 341wrong place to talk about it. However... 342 343To define a custom merge driver `filfre`, add a section to your 344`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 345 346---------------------------------------------------------------- 347[merge "filfre"] 348 name = feel-free merge driver 349 driver = filfre %O %A %B 350 recursive = binary 351---------------------------------------------------------------- 352 353The `merge.*.name` variable gives the driver a human-readable 354name. 355 356The `merge.*.driver` variable's value is used to construct a 357command to run to merge ancestor's version (`%O`), current 358version (`%A`) and the other branches' version (`%B`). These 359three tokens are replaced with the names of temporary files that 360hold the contents of these versions when the command line is 361built. 362 363The merge driver is expected to leave the result of the merge in 364the file named with `%A` by overwriting it, and exit with zero 365status if it managed to merge them cleanly, or non-zero if there 366were conflicts. 367 368The `merge.*.recursive` variable specifies what other merge 369driver to use when the merge driver is called for an internal 370merge between common ancestors, when there are more than one. 371When left unspecified, the driver itself is used for both 372internal merge and the final merge. 373 374 375EXAMPLE 376------- 377 378If you have these three `gitattributes` file: 379 380---------------------------------------------------------------- 381(in $GIT_DIR/info/attributes) 382 383a* foo !bar -baz 384 385(in .gitattributes) 386abc foo bar baz 387 388(in t/.gitattributes) 389ab* merge=filfre 390abc -foo -bar 391*.c frotz 392---------------------------------------------------------------- 393 394the attributes given to path `t/abc` are computed as follows: 395 3961. By examining `t/.gitattributes` (which is in the same 397 directory as the path in question), git finds that the first 398 line matches. `merge` attribute is set. It also finds that 399 the second line matches, and attributes `foo` and `bar` 400 are unset. 401 4022. Then it examines `.gitattributes` (which is in the parent 403 directory), and finds that the first line matches, but 404 `t/.gitattributes` file already decided how `merge`, `foo` 405 and `bar` attributes should be given to this path, so it 406 leaves `foo` and `bar` unset. Attribute `baz` is set. 407 4083. Finally it examines `$GIT_DIR/info/attributes`. This file 409 is used to override the in-tree settings. The first line is 410 a match, and `foo` is set, `bar` is reverted to unspecified 411 state, and `baz` is unset. 412 413As the result, the attributes assignment to `t/abc` becomes: 414 415---------------------------------------------------------------- 416foo set to true 417bar unspecified 418baz set to false 419merge set to string value "filfre" 420frotz unspecified 421---------------------------------------------------------------- 422 423 424GIT 425--- 426Part of the gitlink:git[7] suite