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. 53 54When more than one glob pattern matches the path, a later line 55overrides an earlier line. 56 57When deciding what attributes are assigned to a path, git 58consults `$GIT_DIR/info/attributes` file (which has the highest 59precedence), `.gitattributes` file in the same directory as the 60path in question, and its parent directories (the further the 61directory that contains `.gitattributes` is from the path in 62question, the lower its precedence). 63 64Sometimes you would need to override an setting of an attribute 65for a path to `unspecified` state. This can be done by listing 66the name of the attribute prefixed with an exclamation point `!`. 67 68 69EFFECTS 70------- 71 72Certain operations by git can be influenced by assigning 73particular attributes to a path. Currently, three operations 74are attributes-aware. 75 76Checking-out and checking-in 77~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 78 79The attribute `crlf` affects how the contents stored in the 80repository are copied to the working tree files when commands 81such as `git checkout` and `git merge` run. It also affects how 82git stores the contents you prepare in the working tree in the 83repository upon `git add` and `git commit`. 84 85Set:: 86 87 Setting the `crlf` attribute on a path is meant to mark 88 the path as a "text" file. 'core.autocrlf' conversion 89 takes place without guessing the content type by 90 inspection. 91 92Unset:: 93 94 Unsetting the `crlf` attribute on a path is meant to 95 mark the path as a "binary" file. The path never goes 96 through line endings conversion upon checkin/checkout. 97 98Unspecified:: 99 100 Unspecified `crlf` attribute tells git to apply the 101 `core.autocrlf` conversion when the file content looks 102 like text. 103 104Set to string value "input":: 105 106 This is similar to setting the attribute to `true`, but 107 also forces git to act as if `core.autocrlf` is set to 108 `input` for the path. 109 110Any other value set to `crlf` attribute is ignored and git acts 111as if the attribute is left unspecified. 112 113 114The `core.autocrlf` conversion 115^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 116 117If the configuration variable `core.autocrlf` is false, no 118conversion is done. 119 120When `core.autocrlf` is true, it means that the platform wants 121CRLF line endings for files in the working tree, and you want to 122convert them back to the normal LF line endings when checking 123in to the repository. 124 125When `core.autocrlf` is set to "input", line endings are 126converted to LF upon checkin, but there is no conversion done 127upon checkout. 128 129 130Generating diff text 131~~~~~~~~~~~~~~~~~~~~ 132 133The attribute `diff` affects if `git diff` generates textual 134patch for the path or just says `Binary files differ`. 135 136Set:: 137 138 A path to which the `diff` attribute is set is treated 139 as text, even when they contain byte values that 140 normally never appear in text files, such as NUL. 141 142Unset:: 143 144 A path to which the `diff` attribute is unset will 145 generate `Binary files differ`. 146 147Unspecified:: 148 149 A path to which the `diff` attribute is unspecified 150 first gets its contents inspected, and if it looks like 151 text, it is treated as text. Otherwise it would 152 generate `Binary files differ`. 153 154String:: 155 156 Diff is shown using the specified custom diff driver. 157 The driver program is given its input using the same 158 calling convention as used for GIT_EXTERNAL_DIFF 159 program. 160 161 162Defining a custom diff driver 163^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 164 165The definition of a diff driver is done in `gitconfig`, not 166`gitattributes` file, so strictly speaking this manual page is a 167wrong place to talk about it. However... 168 169To define a custom diff driver `jcdiff`, add a section to your 170`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 171 172---------------------------------------------------------------- 173[diff "jcdiff"] 174 command = j-c-diff 175---------------------------------------------------------------- 176 177When git needs to show you a diff for the path with `diff` 178attribute set to `jcdiff`, it calls the command you specified 179with the above configuration, i.e. `j-c-diff`, with 7 180parameters, just like `GIT_EXTERNAL_DIFF` program is called. 181See gitlink:git[7] for details. 182 183 184Performing a three-way merge 185~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 186 187The attribute `merge` affects how three versions of a file is 188merged when a file-level merge is necessary during `git merge`, 189and other programs such as `git revert` and `git cherry-pick`. 190 191Set:: 192 193 Built-in 3-way merge driver is used to merge the 194 contents in a way similar to `merge` command of `RCS` 195 suite. This is suitable for ordinary text files. 196 197Unset:: 198 199 Take the version from the current branch as the 200 tentative merge result, and declare that the merge has 201 conflicts. This is suitable for binary files that does 202 not have a well-defined merge semantics. 203 204Unspecified:: 205 206 By default, this uses the same built-in 3-way merge 207 driver as is the case the `merge` attribute is set. 208 However, `merge.default` configuration variable can name 209 different merge driver to be used for paths to which the 210 `merge` attribute is unspecified. 211 212String:: 213 214 3-way merge is performed using the specified custom 215 merge driver. The built-in 3-way merge driver can be 216 explicitly specified by asking for "text" driver; the 217 built-in "take the current branch" driver can be 218 requested by "binary". 219 220 221Defining a custom merge driver 222^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 223 224The definition of a merge driver is done in `gitconfig` not 225`gitattributes` file, so strictly speaking this manual page is a 226wrong place to talk about it. However... 227 228To define a custom merge driver `filfre`, add a section to your 229`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 230 231---------------------------------------------------------------- 232[merge "filfre"] 233 name = feel-free merge driver 234 driver = filfre %O %A %B 235 recursive = binary 236---------------------------------------------------------------- 237 238The `merge.*.name` variable gives the driver a human-readable 239name. 240 241The `merge.*.driver` variable's value is used to construct a 242command to run to merge ancestor's version (`%O`), current 243version (`%A`) and the other branches' version (`%B`). These 244three tokens are replaced with the names of temporary files that 245hold the contents of these versions when the command line is 246built. 247 248The merge driver is expected to leave the result of the merge in 249the file named with `%A` by overwriting it, and exit with zero 250status if it managed to merge them cleanly, or non-zero if there 251were conflicts. 252 253The `merge.*.recursive` variable specifies what other merge 254driver to use when the merge driver is called for an internal 255merge between common ancestors, when there are more than one. 256When left unspecified, the driver itself is used for both 257internal merge and the final merge. 258 259 260EXAMPLE 261------- 262 263If you have these three `gitattributes` file: 264 265---------------------------------------------------------------- 266(in $GIT_DIR/info/attributes) 267 268a* foo !bar -baz 269 270(in .gitattributes) 271abc foo bar baz 272 273(in t/.gitattributes) 274ab* merge=filfre 275abc -foo -bar 276*.c frotz 277---------------------------------------------------------------- 278 279the attributes given to path `t/abc` are computed as follows: 280 2811. By examining `t/.gitattributes` (which is in the same 282 diretory as the path in question), git finds that the first 283 line matches. `merge` attribute is set. It also finds that 284 the second line matches, and attributes `foo` and `bar` 285 are unset. 286 2872. Then it examines `.gitattributes` (which is in the parent 288 directory), and finds that the first line matches, but 289 `t/.gitattributes` file already decided how `merge`, `foo` 290 and `bar` attributes should be given to this path, so it 291 leaves `foo` and `bar` unset. Attribute `baz` is set. 292 2933. Finally it examines `$GIT_DIR/info/gitattributes`. This file 294 is used to override the in-tree settings. The first line is 295 a match, and `foo` is set, `bar` is reverted to unspecified 296 state, and `baz` is unset. 297 298As the result, the attributes assignement to `t/abc` becomes: 299 300---------------------------------------------------------------- 301foo set to true 302bar unspecified 303baz set to false 304merge set to string value "filfre" 305frotz unspecified 306---------------------------------------------------------------- 307 308 309GIT 310--- 311Part of the gitlink:git[7] suite