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