1gitattributes(5) 2================ 3 4NAME 5---- 6gitattributes - defining attributes per path 7 8SYNOPSIS 9-------- 10.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 154Any other value set to `diff` attribute is ignored and git acts 155as if the attribute is left unspecified. 156 157 158Performing a three-way merge 159~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 160 161The attribute `merge` affects how three versions of a file is 162merged when a file-level merge is necessary during `git merge`, 163and other programs such as `git revert` and `git cherry-pick`. 164 165Set:: 166 167 Built-in 3-way merge driver is used to merge the 168 contents in a way similar to `merge` command of `RCS` 169 suite. This is suitable for ordinary text files. 170 171Unset:: 172 173 Take the version from the current branch as the 174 tentative merge result, and declare that the merge has 175 conflicts. This is suitable for binary files that does 176 not have a well-defined merge semantics. 177 178Unspecified:: 179 180 By default, this uses the same built-in 3-way merge 181 driver as is the case the `merge` attribute is set. 182 However, `merge.default` configuration variable can name 183 different merge driver to be used for paths to which the 184 `merge` attribute is unspecified. 185 186Any other string value:: 187 188 3-way merge is performed using the specified custom 189 merge driver. The built-in 3-way merge driver can be 190 explicitly specified by asking for "text" driver; the 191 built-in "take the current branch" driver can be 192 requested by "binary". 193 194 195Defining a custom merge driver 196^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 197 198The definition of a merge driver is done in `gitconfig` not 199`gitattributes` file, so strictly speaking this manual page is a 200wrong place to talk about it. However... 201 202To define a custom merge driver `filfre`, add a section to your 203`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 204 205---------------------------------------------------------------- 206[merge "filfre"] 207 name = feel-free merge driver 208 driver = filfre %O %A %B 209 recursive = binary 210---------------------------------------------------------------- 211 212The `merge.*.name` variable gives the driver a human-readable 213name. 214 215The `merge.*.driver` variable's value is used to construct a 216command to run to merge ancestor's version (`%O`), current 217version (`%A`) and the other branches' version (`%B`). These 218three tokens are replaced with the names of temporary files that 219hold the contents of these versions when the command line is 220built. 221 222The merge driver is expected to leave the result of the merge in 223the file named with `%A` by overwriting it, and exit with zero 224status if it managed to merge them cleanly, or non-zero if there 225were conflicts. 226 227The `merge.*.recursive` variable specifies what other merge 228driver to use when the merge driver is called for an internal 229merge between common ancestors, when there are more than one. 230When left unspecified, the driver itself is used for both 231internal merge and the final merge. 232 233 234EXAMPLE 235------- 236 237If you have these three `gitattributes` file: 238 239---------------------------------------------------------------- 240(in $GIT_DIR/info/attributes) 241 242a* foo !bar -baz 243 244(in .gitattributes) 245abc foo bar baz 246 247(in t/.gitattributes) 248ab* merge=filfre 249abc -foo -bar 250*.c frotz 251---------------------------------------------------------------- 252 253the attributes given to path `t/abc` are computed as follows: 254 2551. By examining `t/.gitattributes` (which is in the same 256 diretory as the path in question), git finds that the first 257 line matches. `merge` attribute is set. It also finds that 258 the second line matches, and attributes `foo` and `bar` 259 are unset. 260 2612. Then it examines `.gitattributes` (which is in the parent 262 directory), and finds that the first line matches, but 263 `t/.gitattributes` file already decided how `merge`, `foo` 264 and `bar` attributes should be given to this path, so it 265 leaves `foo` and `bar` unset. Attribute `baz` is set. 266 2673. Finally it examines `$GIT_DIR/info/gitattributes`. This file 268 is used to override the in-tree settings. The first line is 269 a match, and `foo` is set, `bar` is reverted to unspecified 270 state, and `baz` is unset. 271 272As the result, the attributes assignement to `t/abc` becomes: 273 274---------------------------------------------------------------- 275foo set to true 276bar unspecified 277baz set to false 278merge set to string value "filfre" 279frotz unspecified 280---------------------------------------------------------------- 281 282 283GIT 284--- 285Part of the gitlink:git[7] suite