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