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.
  53
  54 When more than one glob pattern matches the path, a later line
  55 overrides an earlier line.
  56
  57 When deciding what attributes are assigned to a path, git
  58 consults `$GIT_DIR/info/attributes` file (which has the highest
  59 precedence), `.gitattributes` file in the same directory as the
  60 path in question, and its parent directories (the further the
  61 directory that contains `.gitattributes` is from the path in
  62 question, the lower its precedence).
  63
  64 Sometimes you would need to override an setting of an attribute
  65 for a path to `unspecified` state.  This can be done by listing
  66 the name of the attribute prefixed with an exclamation point `!`.
  67
  68
  69 EFFECTS
  70 -------
  71
  72 Certain operations by git can be influenced by assigning
  73 particular attributes to a path.  Currently, three operations
  74 are attributes-aware.
  75
  76 Checking-out and checking-in
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78
  79 The attribute `crlf` affects how the contents stored in the
  80 repository are copied to the working tree files when commands
  81 such as `git checkout` and `git merge` run.  It also affects how
  82 git stores the contents you prepare in the working tree in the
  83 repository upon `git add` and `git commit`.
  84
  85 Set::
  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
  92 Unset::
  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
  98 Unspecified::
  99
 100         Unspecified `crlf` attribute tells git to apply the
 101         `core.autocrlf` conversion when the file content looks
 102         like text.
 103
 104 Set 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
 110 Any other value set to `crlf` attribute is ignored and git acts
 111 as if the attribute is left unspecified.
 112
 113
 114 The `core.autocrlf` conversion
 115 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 116
 117 If the configuration variable `core.autocrlf` is false, no
 118 conversion is done.
 119
 120 When `core.autocrlf` is true, it means that the platform wants
 121 CRLF line endings for files in the working tree, and you want to
 122 convert them back to the normal LF line endings when checking
 123 in to the repository.
 124
 125 When `core.autocrlf` is set to "input", line endings are
 126 converted to LF upon checkin, but there is no conversion done
 127 upon checkout.
 128
 129
 130 Generating diff text
 131 ~~~~~~~~~~~~~~~~~~~~
 132
 133 The attribute `diff` affects if `git diff` generates textual
 134 patch for the path or just says `Binary files differ`.
 135
 136 Set::
 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
 142 Unset::
 143
 144         A path to which the `diff` attribute is unset will
 145         generate `Binary files differ`.
 146
 147 Unspecified::
 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
 154 String::
 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
 162 Defining a custom diff driver
 163 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 164
 165 The definition of a diff driver is done in `gitconfig`, not
 166 `gitattributes` file, so strictly speaking this manual page is a
 167 wrong place to talk about it.  However...
 168
 169 To 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
 177 When git needs to show you a diff for the path with `diff`
 178 attribute set to `jcdiff`, it calls the command you specified
 179 with the above configuration, i.e. `j-c-diff`, with 7
 180 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
 181 See gitlink:git[7] for details.
 182
 183
 184 Performing a three-way merge
 185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 186
 187 The attribute `merge` affects how three versions of a file is
 188 merged when a file-level merge is necessary during `git merge`,
 189 and other programs such as `git revert` and `git cherry-pick`.
 190
 191 Set::
 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
 197 Unset::
 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
 204 Unspecified::
 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
 212 String::
 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
 221 Defining a custom merge driver
 222 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 223
 224 The definition of a merge driver is done in `gitconfig` not
 225 `gitattributes` file, so strictly speaking this manual page is a
 226 wrong place to talk about it.  However...
 227
 228 To 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
 238 The `merge.*.name` variable gives the driver a human-readable
 239 name.
 240
 241 The `merge.*.driver` variable's value is used to construct a
 242 command to run to merge ancestor's version (`%O`), current
 243 version (`%A`) and the other branches' version (`%B`).  These
 244 three tokens are replaced with the names of temporary files that
 245 hold the contents of these versions when the command line is
 246 built.
 247
 248 The merge driver is expected to leave the result of the merge in
 249 the file named with `%A` by overwriting it, and exit with zero
 250 status if it managed to merge them cleanly, or non-zero if there
 251 were conflicts.
 252
 253 The `merge.*.recursive` variable specifies what other merge
 254 driver to use when the merge driver is called for an internal
 255 merge between common ancestors, when there are more than one.
 256 When left unspecified, the driver itself is used for both
 257 internal merge and the final merge.
 258
 259
 260 EXAMPLE
 261 -------
 262
 263 If you have these three `gitattributes` file:
 264
 265 ----------------------------------------------------------------
 266 (in $GIT_DIR/info/attributes)
 267
 268 a*      foo !bar -baz
 269
 270 (in .gitattributes)
 271 abc     foo bar baz
 272
 273 (in t/.gitattributes)
 274 ab*     merge=filfre
 275 abc     -foo -bar
 276 *.c     frotz
 277 ----------------------------------------------------------------
 278
 279 the attributes given to path `t/abc` are computed as follows:
 280
 281 1. 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
 287 2. 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
 293 3. 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
 298 As the result, the attributes assignement to `t/abc` becomes:
 299
 300 ----------------------------------------------------------------
 301 foo     set to true
 302 bar     unspecified
 303 baz     set to false
 304 merge   set to string value "filfre"
 305 frotz   unspecified
 306 ----------------------------------------------------------------
 307
 308
 309 GIT
 310 ---
 311 Part of the gitlink:git[7] suite