Documentation/gitattributes.txt

   1 gitattributes(5)
   2 ================
   3
   4 NAME
   5 ----
   6 gitattributes - defining attributes per path
   7
   8 SYNOPSIS
   9 --------
  10 $GIT_DIR/info/attributes, gitattributes
  11
  12
  13 DESCRIPTION
  14 -----------
  15
  16 A `gitattributes` file is a simple text file that gives
  17 `attributes` to pathnames.
  18
  19 Each line in `gitattributes` file is of form:
  20
  21         glob    attr1 attr2 ...
  22
  23 That is, a glob pattern followed by an attributes list,
  24 separated by whitespaces.  When the glob pattern matches the
  25 path in question, the attributes listed on the line are given to
  26 the path.
  27
  28 Each attribute can be in one of these states for a given path:
  29
  30 Set::
  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
  36 Unset::
  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
  42 Set 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
  49 Unspecified::
  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
  55 When more than one glob pattern matches the path, a later line
  56 overrides an earlier line.  This overriding is done per
  57 attribute.
  58
  59 When deciding what attributes are assigned to a path, git
  60 consults `$GIT_DIR/info/attributes` file (which has the highest
  61 precedence), `.gitattributes` file in the same directory as the
  62 path in question, and its parent directories (the further the
  63 directory that contains `.gitattributes` is from the path in
  64 question, the lower its precedence).
  65
  66 Sometimes you would need to override an setting of an attribute
  67 for a path to `unspecified` state.  This can be done by listing
  68 the name of the attribute prefixed with an exclamation point `!`.
  69
  70
  71 EFFECTS
  72 -------
  73
  74 Certain operations by git can be influenced by assigning
  75 particular attributes to a path.  Currently, three operations
  76 are attributes-aware.
  77
  78 Checking-out and checking-in
  79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80
  81 These attributes affect how the contents stored in the
  82 repository are copied to the working tree files when commands
  83 such as `git checkout` and `git merge` run.  They also affect how
  84 git stores the contents you prepare in the working tree in the
  85 repository upon `git add` and `git commit`.
  86
  87 `crlf`
  88 ^^^^^^
  89
  90 This attribute controls the line-ending convention.
  91
  92 Set::
  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
  99 Unset::
 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
 105 Unspecified::
 106
 107         Unspecified `crlf` attribute tells git to apply the
 108         `core.autocrlf` conversion when the file content looks
 109         like text.
 110
 111 Set 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
 117 Any other value set to `crlf` attribute is ignored and git acts
 118 as if the attribute is left unspecified.
 119
 120
 121 The `core.autocrlf` conversion
 122 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 123
 124 If the configuration variable `core.autocrlf` is false, no
 125 conversion is done.
 126
 127 When `core.autocrlf` is true, it means that the platform wants
 128 CRLF line endings for files in the working tree, and you want to
 129 convert them back to the normal LF line endings when checking
 130 in to the repository.
 131
 132 When `core.autocrlf` is set to "input", line endings are
 133 converted to LF upon checkin, but there is no conversion done
 134 upon checkout.
 135
 136
 137 `ident`
 138 ^^^^^^^
 139
 140 When the attribute `ident` is set to a path, git replaces
 141 `$ident$` in the blob object with `$ident:`, followed by
 142 40-character hexadecimal blob object name, followed by a dollar
 143 sign `$` upon checkout.  Any byte sequence that begins with
 144 `$ident:` and ends with `$` in the worktree file is replaced
 145 with `$ident$` upon check-in.
 146
 147
 148 Interaction between checkin/checkout attributes
 149 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 150
 151 In the check-in codepath, the worktree file is first converted
 152 with `ident` (if specified), and then with `crlf` (again, if
 153 specified and applicable).
 154
 155 In the check-out codepath, the blob content is first converted
 156 with `crlf`, and then `ident`.
 157
 158
 159 Generating diff text
 160 ~~~~~~~~~~~~~~~~~~~~
 161
 162 The attribute `diff` affects if `git diff` generates textual
 163 patch for the path or just says `Binary files differ`.
 164
 165 Set::
 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
 171 Unset::
 172
 173         A path to which the `diff` attribute is unset will
 174         generate `Binary files differ`.
 175
 176 Unspecified::
 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
 183 String::
 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
 191 Defining a custom diff driver
 192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 193
 194 The definition of a diff driver is done in `gitconfig`, not
 195 `gitattributes` file, so strictly speaking this manual page is a
 196 wrong place to talk about it.  However...
 197
 198 To 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
 206 When git needs to show you a diff for the path with `diff`
 207 attribute set to `jcdiff`, it calls the command you specified
 208 with the above configuration, i.e. `j-c-diff`, with 7
 209 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
 210 See gitlink:git[7] for details.
 211
 212
 213 Performing a three-way merge
 214 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 215
 216 The attribute `merge` affects how three versions of a file is
 217 merged when a file-level merge is necessary during `git merge`,
 218 and other programs such as `git revert` and `git cherry-pick`.
 219
 220 Set::
 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
 226 Unset::
 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
 233 Unspecified::
 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
 241 String::
 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
 250 Defining a custom merge driver
 251 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 252
 253 The definition of a merge driver is done in `gitconfig` not
 254 `gitattributes` file, so strictly speaking this manual page is a
 255 wrong place to talk about it.  However...
 256
 257 To 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
 267 The `merge.*.name` variable gives the driver a human-readable
 268 name.
 269
 270 The `merge.*.driver` variable's value is used to construct a
 271 command to run to merge ancestor's version (`%O`), current
 272 version (`%A`) and the other branches' version (`%B`).  These
 273 three tokens are replaced with the names of temporary files that
 274 hold the contents of these versions when the command line is
 275 built.
 276
 277 The merge driver is expected to leave the result of the merge in
 278 the file named with `%A` by overwriting it, and exit with zero
 279 status if it managed to merge them cleanly, or non-zero if there
 280 were conflicts.
 281
 282 The `merge.*.recursive` variable specifies what other merge
 283 driver to use when the merge driver is called for an internal
 284 merge between common ancestors, when there are more than one.
 285 When left unspecified, the driver itself is used for both
 286 internal merge and the final merge.
 287
 288
 289 EXAMPLE
 290 -------
 291
 292 If you have these three `gitattributes` file:
 293
 294 ----------------------------------------------------------------
 295 (in $GIT_DIR/info/attributes)
 296
 297 a*      foo !bar -baz
 298
 299 (in .gitattributes)
 300 abc     foo bar baz
 301
 302 (in t/.gitattributes)
 303 ab*     merge=filfre
 304 abc     -foo -bar
 305 *.c     frotz
 306 ----------------------------------------------------------------
 307
 308 the attributes given to path `t/abc` are computed as follows:
 309
 310 1. 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
 316 2. 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
 322 3. 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
 327 As the result, the attributes assignement to `t/abc` becomes:
 328
 329 ----------------------------------------------------------------
 330 foo     set to true
 331 bar     unspecified
 332 baz     set to false
 333 merge   set to string value "filfre"
 334 frotz   unspecified
 335 ----------------------------------------------------------------
 336
 337
 338 GIT
 339 ---
 340 Part of the gitlink:git[7] suite