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`$ident$` in the blob object with `$ident:`, followed by 14240-character hexadecimal blob object name, followed by a dollar 143sign `$` upon checkout. Any byte sequence that begins with 144`$ident:` and ends with `$` in the worktree file is replaced 145with `$ident$` 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 159Generating diff text 160~~~~~~~~~~~~~~~~~~~~ 161 162The attribute `diff` affects if `git diff` generates textual 163patch for the path or just says `Binary files differ`. 164 165Set:: 166 167 A path to which the `diff` attribute is set is treated 168 as text, even when they contain byte values that 169 normally never appear in text files, such as NUL. 170 171Unset:: 172 173 A path to which the `diff` attribute is unset will 174 generate `Binary files differ`. 175 176Unspecified:: 177 178 A path to which the `diff` attribute is unspecified 179 first gets its contents inspected, and if it looks like 180 text, it is treated as text. Otherwise it would 181 generate `Binary files differ`. 182 183String:: 184 185 Diff is shown using the specified custom diff driver. 186 The driver program is given its input using the same 187 calling convention as used for GIT_EXTERNAL_DIFF 188 program. 189 190 191Defining a custom diff driver 192^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 193 194The definition of a diff driver is done in `gitconfig`, not 195`gitattributes` file, so strictly speaking this manual page is a 196wrong place to talk about it. However... 197 198To define a custom diff driver `jcdiff`, add a section to your 199`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 200 201---------------------------------------------------------------- 202[diff "jcdiff"] 203 command = j-c-diff 204---------------------------------------------------------------- 205 206When git needs to show you a diff for the path with `diff` 207attribute set to `jcdiff`, it calls the command you specified 208with the above configuration, i.e. `j-c-diff`, with 7 209parameters, just like `GIT_EXTERNAL_DIFF` program is called. 210See gitlink:git[7] for details. 211 212 213Performing a three-way merge 214~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 215 216The attribute `merge` affects how three versions of a file is 217merged when a file-level merge is necessary during `git merge`, 218and other programs such as `git revert` and `git cherry-pick`. 219 220Set:: 221 222 Built-in 3-way merge driver is used to merge the 223 contents in a way similar to `merge` command of `RCS` 224 suite. This is suitable for ordinary text files. 225 226Unset:: 227 228 Take the version from the current branch as the 229 tentative merge result, and declare that the merge has 230 conflicts. This is suitable for binary files that does 231 not have a well-defined merge semantics. 232 233Unspecified:: 234 235 By default, this uses the same built-in 3-way merge 236 driver as is the case the `merge` attribute is set. 237 However, `merge.default` configuration variable can name 238 different merge driver to be used for paths to which the 239 `merge` attribute is unspecified. 240 241String:: 242 243 3-way merge is performed using the specified custom 244 merge driver. The built-in 3-way merge driver can be 245 explicitly specified by asking for "text" driver; the 246 built-in "take the current branch" driver can be 247 requested with "binary". 248 249 250Defining a custom merge driver 251^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 252 253The definition of a merge driver is done in `gitconfig` not 254`gitattributes` file, so strictly speaking this manual page is a 255wrong place to talk about it. However... 256 257To define a custom merge driver `filfre`, add a section to your 258`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 259 260---------------------------------------------------------------- 261[merge "filfre"] 262 name = feel-free merge driver 263 driver = filfre %O %A %B 264 recursive = binary 265---------------------------------------------------------------- 266 267The `merge.*.name` variable gives the driver a human-readable 268name. 269 270The `merge.*.driver` variable's value is used to construct a 271command to run to merge ancestor's version (`%O`), current 272version (`%A`) and the other branches' version (`%B`). These 273three tokens are replaced with the names of temporary files that 274hold the contents of these versions when the command line is 275built. 276 277The merge driver is expected to leave the result of the merge in 278the file named with `%A` by overwriting it, and exit with zero 279status if it managed to merge them cleanly, or non-zero if there 280were conflicts. 281 282The `merge.*.recursive` variable specifies what other merge 283driver to use when the merge driver is called for an internal 284merge between common ancestors, when there are more than one. 285When left unspecified, the driver itself is used for both 286internal merge and the final merge. 287 288 289EXAMPLE 290------- 291 292If you have these three `gitattributes` file: 293 294---------------------------------------------------------------- 295(in $GIT_DIR/info/attributes) 296 297a* foo !bar -baz 298 299(in .gitattributes) 300abc foo bar baz 301 302(in t/.gitattributes) 303ab* merge=filfre 304abc -foo -bar 305*.c frotz 306---------------------------------------------------------------- 307 308the attributes given to path `t/abc` are computed as follows: 309 3101. By examining `t/.gitattributes` (which is in the same 311 diretory as the path in question), git finds that the first 312 line matches. `merge` attribute is set. It also finds that 313 the second line matches, and attributes `foo` and `bar` 314 are unset. 315 3162. Then it examines `.gitattributes` (which is in the parent 317 directory), and finds that the first line matches, but 318 `t/.gitattributes` file already decided how `merge`, `foo` 319 and `bar` attributes should be given to this path, so it 320 leaves `foo` and `bar` unset. Attribute `baz` is set. 321 3223. Finally it examines `$GIT_DIR/info/gitattributes`. This file 323 is used to override the in-tree settings. The first line is 324 a match, and `foo` is set, `bar` is reverted to unspecified 325 state, and `baz` is unset. 326 327As the result, the attributes assignement to `t/abc` becomes: 328 329---------------------------------------------------------------- 330foo set to true 331bar unspecified 332baz set to false 333merge set to string value "filfre" 334frotz unspecified 335---------------------------------------------------------------- 336 337 338GIT 339--- 340Part of the gitlink:git[7] suite