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