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 Any other value set to `diff` attribute is ignored and git acts
 155 as if the attribute is left unspecified.
 156
 157
 158 Performing a three-way merge
 159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 160
 161 The attribute `merge` affects how three versions of a file is
 162 merged when a file-level merge is necessary during `git merge`,
 163 and other programs such as `git revert` and `git cherry-pick`.
 164
 165 Set::
 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
 171 Unset::
 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
 178 Unspecified::
 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
 186 Any 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
 195 Defining a custom merge driver
 196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 197
 198 The definition of a merge driver is done in `gitconfig` not
 199 `gitattributes` file, so strictly speaking this manual page is a
 200 wrong place to talk about it.  However...
 201
 202 To 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
 212 The `merge.*.name` variable gives the driver a human-readable
 213 name.
 214
 215 The `merge.*.driver` variable's value is used to construct a
 216 command to run to merge ancestor's version (`%O`), current
 217 version (`%A`) and the other branches' version (`%B`).  These
 218 three tokens are replaced with the names of temporary files that
 219 hold the contents of these versions when the command line is
 220 built.
 221
 222 The merge driver is expected to leave the result of the merge in
 223 the file named with `%A` by overwriting it, and exit with zero
 224 status if it managed to merge them cleanly, or non-zero if there
 225 were conflicts.
 226
 227 The `merge.*.recursive` variable specifies what other merge
 228 driver to use when the merge driver is called for an internal
 229 merge between common ancestors, when there are more than one.
 230 When left unspecified, the driver itself is used for both
 231 internal merge and the final merge.
 232
 233
 234 EXAMPLE
 235 -------
 236
 237 If you have these three `gitattributes` file:
 238
 239 ----------------------------------------------------------------
 240 (in $GIT_DIR/info/attributes)
 241
 242 a*      foo !bar -baz
 243
 244 (in .gitattributes)
 245 abc     foo bar baz
 246
 247 (in t/.gitattributes)
 248 ab*     merge=filfre
 249 abc     -foo -bar
 250 *.c     frotz
 251 ----------------------------------------------------------------
 252
 253 the attributes given to path `t/abc` are computed as follows:
 254
 255 1. 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
 261 2. 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
 267 3. 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
 272 As the result, the attributes assignement to `t/abc` becomes:
 273
 274 ----------------------------------------------------------------
 275 foo     set to true
 276 bar     unspecified
 277 baz     set to false
 278 merge   set to string value "filfre"
 279 frotz   unspecified
 280 ----------------------------------------------------------------
 281
 282
 283 GIT
 284 ---
 285 Part of the gitlink:git[7] suite