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 The attribute `crlf` affects 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.  It also affects how
  84 git stores the contents you prepare in the working tree in the
  85 repository upon `git add` and `git commit`.
  86
  87 Set::
  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
  94 Unset::
  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
 100 Unspecified::
 101
 102         Unspecified `crlf` attribute tells git to apply the
 103         `core.autocrlf` conversion when the file content looks
 104         like text.
 105
 106 Set 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
 112 Any other value set to `crlf` attribute is ignored and git acts
 113 as if the attribute is left unspecified.
 114
 115
 116 The `core.autocrlf` conversion
 117 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 118
 119 If the configuration variable `core.autocrlf` is false, no
 120 conversion is done.
 121
 122 When `core.autocrlf` is true, it means that the platform wants
 123 CRLF line endings for files in the working tree, and you want to
 124 convert them back to the normal LF line endings when checking
 125 in to the repository.
 126
 127 When `core.autocrlf` is set to "input", line endings are
 128 converted to LF upon checkin, but there is no conversion done
 129 upon checkout.
 130
 131
 132 Generating diff text
 133 ~~~~~~~~~~~~~~~~~~~~
 134
 135 The attribute `diff` affects if `git diff` generates textual
 136 patch for the path or just says `Binary files differ`.
 137
 138 Set::
 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
 144 Unset::
 145
 146         A path to which the `diff` attribute is unset will
 147         generate `Binary files differ`.
 148
 149 Unspecified::
 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
 156 String::
 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
 164 Defining a custom diff driver
 165 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 166
 167 The definition of a diff driver is done in `gitconfig`, not
 168 `gitattributes` file, so strictly speaking this manual page is a
 169 wrong place to talk about it.  However...
 170
 171 To 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
 179 When git needs to show you a diff for the path with `diff`
 180 attribute set to `jcdiff`, it calls the command you specified
 181 with the above configuration, i.e. `j-c-diff`, with 7
 182 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
 183 See gitlink:git[7] for details.
 184
 185
 186 Performing a three-way merge
 187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 188
 189 The attribute `merge` affects how three versions of a file is
 190 merged when a file-level merge is necessary during `git merge`,
 191 and other programs such as `git revert` and `git cherry-pick`.
 192
 193 Set::
 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
 199 Unset::
 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
 206 Unspecified::
 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
 214 String::
 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
 223 Defining a custom merge driver
 224 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 225
 226 The definition of a merge driver is done in `gitconfig` not
 227 `gitattributes` file, so strictly speaking this manual page is a
 228 wrong place to talk about it.  However...
 229
 230 To 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
 240 The `merge.*.name` variable gives the driver a human-readable
 241 name.
 242
 243 The `merge.*.driver` variable's value is used to construct a
 244 command to run to merge ancestor's version (`%O`), current
 245 version (`%A`) and the other branches' version (`%B`).  These
 246 three tokens are replaced with the names of temporary files that
 247 hold the contents of these versions when the command line is
 248 built.
 249
 250 The merge driver is expected to leave the result of the merge in
 251 the file named with `%A` by overwriting it, and exit with zero
 252 status if it managed to merge them cleanly, or non-zero if there
 253 were conflicts.
 254
 255 The `merge.*.recursive` variable specifies what other merge
 256 driver to use when the merge driver is called for an internal
 257 merge between common ancestors, when there are more than one.
 258 When left unspecified, the driver itself is used for both
 259 internal merge and the final merge.
 260
 261
 262 EXAMPLE
 263 -------
 264
 265 If you have these three `gitattributes` file:
 266
 267 ----------------------------------------------------------------
 268 (in $GIT_DIR/info/attributes)
 269
 270 a*      foo !bar -baz
 271
 272 (in .gitattributes)
 273 abc     foo bar baz
 274
 275 (in t/.gitattributes)
 276 ab*     merge=filfre
 277 abc     -foo -bar
 278 *.c     frotz
 279 ----------------------------------------------------------------
 280
 281 the attributes given to path `t/abc` are computed as follows:
 282
 283 1. 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
 289 2. 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
 295 3. 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
 300 As the result, the attributes assignement to `t/abc` becomes:
 301
 302 ----------------------------------------------------------------
 303 foo     set to true
 304 bar     unspecified
 305 baz     set to false
 306 merge   set to string value "filfre"
 307 frotz   unspecified
 308 ----------------------------------------------------------------
 309
 310
 311 GIT
 312 ---
 313 Part of the gitlink:git[7] suite