Documentation / gitattributes.txton commit Add per-repository eol normalization (fd6cce9)
   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        pattern attr1 attr2 ...
  22
  23That is, a pattern followed by an attributes list,
  24separated by whitespaces.  When the 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 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
  55When more than one pattern matches the path, a later line
  56overrides an earlier line.  This overriding is done per
  57attribute.  The rules how the pattern matches paths are the
  58same as in `.gitignore` files; see linkgit:gitignore[5].
  59
  60When deciding what attributes are assigned to a path, git
  61consults `$GIT_DIR/info/attributes` file (which has the highest
  62precedence), `.gitattributes` file in the same directory as the
  63path in question, and its parent directories up to the toplevel of the
  64work tree (the further the directory that contains `.gitattributes`
  65is from the path in question, the lower its precedence).
  66
  67If you wish to affect only a single repository (i.e., to assign
  68attributes to files that are particular to one user's workflow), then
  69attributes should be placed in the `$GIT_DIR/info/attributes` file.
  70Attributes which should be version-controlled and distributed to other
  71repositories (i.e., attributes of interest to all users) should go into
  72`.gitattributes` files.
  73
  74Sometimes you would need to override an setting of an attribute
  75for a path to `unspecified` state.  This can be done by listing
  76the name of the attribute prefixed with an exclamation point `!`.
  77
  78
  79EFFECTS
  80-------
  81
  82Certain operations by git can be influenced by assigning
  83particular attributes to a path.  Currently, the following
  84operations are attributes-aware.
  85
  86Checking-out and checking-in
  87~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  88
  89These attributes affect how the contents stored in the
  90repository are copied to the working tree files when commands
  91such as 'git checkout' and 'git merge' run.  They also affect how
  92git stores the contents you prepare in the working tree in the
  93repository upon 'git add' and 'git commit'.
  94
  95`crlf`
  96^^^^^^
  97
  98This attribute enables and controls end-of-line normalization.  When a
  99text file is normalized, its line endings are converted to LF in the
 100repository.  To control what line ending style is used in the working
 101directory, use the `eol` attribute for a single file and the
 102`core.autocrlf` configuration variable for all text files.
 103
 104Set::
 105
 106        Setting the `crlf` attribute on a path enables end-of-line
 107        normalization and marks the path as a text file.  End-of-line
 108        conversion takes place without guessing the content type.
 109
 110Unset::
 111
 112        Unsetting the `crlf` attribute on a path tells git not to
 113        attempt any end-of-line conversion upon checkin or checkout.
 114
 115Set to string value "auto"::
 116
 117        When `crlf` is set to "auto", the path is marked for automatic
 118        end-of-line normalization.  If git decides that the content is
 119        text, its line endings are normalized to LF on checkin.
 120
 121Unspecified::
 122
 123        If the `crlf` attribute is unspecified, git uses the `eol`
 124        attribute and the `core.autocrlf` configuration variable to
 125        determine if the file should be converted.
 126
 127Any other value causes git to act as if `crlf` has been left
 128unspecified.
 129
 130`eol`
 131^^^^^
 132
 133This attribute sets a specific line-ending style to be used in the
 134working directory.  It enables end-of-line normalization without any
 135content checks, similar to setting the `crlf` attribute.
 136
 137Set to string value "crlf"::
 138
 139        This setting forces git to normalize line endings on checkin
 140        and convert them to CRLF when the file is checked out,
 141        regardless of `crlf` and `core.autocrlf`.
 142
 143Set to string value "lf"::
 144
 145        This setting forces git to normalize line endings to LF on
 146        checkin and prevents conversion to CRLF when the file is
 147        checked out, regardless of `crlf` and `core.autocrlf`.
 148        `crlf=input` is a backwards compatibility alias for `eol=lf`.
 149
 150End-of-line conversion
 151^^^^^^^^^^^^^^^^^^^^^^
 152
 153While git normally leaves file contents alone, it can be configured to
 154normalize line endings to LF in the repository and, optionally, to
 155convert them to CRLF when files are checked out.
 156
 157Here is an example that will make git normalize .txt, .vcproj and .sh
 158files, ensure that .vcproj files have CRLF and .sh files have LF in
 159the working directory, and prevent .jpg files from being normalized
 160regardless of their content.
 161
 162------------------------
 163*.txt           crlf
 164*.vcproj        eol=crlf
 165*.sh            eol=lf
 166*.jpg           -crlf
 167------------------------
 168
 169Other source code management systems normalize all text files in their
 170repositories, and there are two ways to enable similar automatic
 171normalization in git.
 172
 173If you simply want to have CRLF line endings in your working directory
 174regardless of the repository you are working with, you can set the
 175config variable "core.autocrlf" without changing any attributes.
 176
 177------------------------
 178[core]
 179        autocrlf = true
 180------------------------
 181
 182This does not force normalization of all text files, but does ensure
 183that text files that you introduce to the repository have their line
 184endings normalized to LF when they are added, and that files that are
 185already normalized in the repository stay normalized.  You can also
 186set `autocrlf` to "input" to have automatic normalization of new text
 187files without conversion to CRLF in the working directory.
 188
 189If you want to interoperate with a source code management system that
 190enforces end-of-line normalization, or you simply want all text files
 191in your repository to be normalized, you should instead set the `crlf`
 192attribute to "auto" for _all_ files.
 193
 194------------------------
 195*       crlf=auto
 196------------------------
 197
 198This ensures that all files that git considers to be text will have
 199normalized (LF) line endings in the repository.
 200
 201NOTE: When `crlf=auto` normalization is enabled in an existing
 202repository, any text files containing CRLFs should be normalized.  If
 203they are not they will be normalized the next time someone tries to
 204change them, causing unfortunate misattribution.  From a clean working
 205directory:
 206
 207-------------------------------------------------
 208$ echo "* crlf=auto" >>.gitattributes
 209$ rm .git/index     # Remove the index to force git to
 210$ git reset         # re-scan the working directory
 211$ git status        # Show files that will be normalized
 212$ git add -u
 213$ git add .gitattributes
 214$ git commit -m "Introduce end-of-line normalization"
 215-------------------------------------------------
 216
 217If any files that should not be normalized show up in 'git status',
 218unset their `crlf` attribute before running 'git add -u'.
 219
 220------------------------
 221manual.pdf      -crlf
 222------------------------
 223
 224Conversely, text files that git does not detect can have normalization
 225enabled manually.
 226
 227------------------------
 228weirdchars.txt  crlf
 229------------------------
 230
 231If `core.safecrlf` is set to "true" or "warn", git verifies if
 232the conversion is reversible for the current setting of
 233`core.autocrlf`.  For "true", git rejects irreversible
 234conversions; for "warn", git only prints a warning but accepts
 235an irreversible conversion.  The safety triggers to prevent such
 236a conversion done to the files in the work tree, but there are a
 237few exceptions.  Even though...
 238
 239- 'git add' itself does not touch the files in the work tree, the
 240  next checkout would, so the safety triggers;
 241
 242- 'git apply' to update a text file with a patch does touch the files
 243  in the work tree, but the operation is about text files and CRLF
 244  conversion is about fixing the line ending inconsistencies, so the
 245  safety does not trigger;
 246
 247- 'git diff' itself does not touch the files in the work tree, it is
 248  often run to inspect the changes you intend to next 'git add'.  To
 249  catch potential problems early, safety triggers.
 250
 251
 252`ident`
 253^^^^^^^
 254
 255When the attribute `ident` is set for a path, git replaces
 256`$Id$` in the blob object with `$Id:`, followed by the
 25740-character hexadecimal blob object name, followed by a dollar
 258sign `$` upon checkout.  Any byte sequence that begins with
 259`$Id:` and ends with `$` in the worktree file is replaced
 260with `$Id$` upon check-in.
 261
 262
 263`filter`
 264^^^^^^^^
 265
 266A `filter` attribute can be set to a string value that names a
 267filter driver specified in the configuration.
 268
 269A filter driver consists of a `clean` command and a `smudge`
 270command, either of which can be left unspecified.  Upon
 271checkout, when the `smudge` command is specified, the command is
 272fed the blob object from its standard input, and its standard
 273output is used to update the worktree file.  Similarly, the
 274`clean` command is used to convert the contents of worktree file
 275upon checkin.
 276
 277A missing filter driver definition in the config is not an error
 278but makes the filter a no-op passthru.
 279
 280The content filtering is done to massage the content into a
 281shape that is more convenient for the platform, filesystem, and
 282the user to use.  The key phrase here is "more convenient" and not
 283"turning something unusable into usable".  In other words, the
 284intent is that if someone unsets the filter driver definition,
 285or does not have the appropriate filter program, the project
 286should still be usable.
 287
 288For example, in .gitattributes, you would assign the `filter`
 289attribute for paths.
 290
 291------------------------
 292*.c     filter=indent
 293------------------------
 294
 295Then you would define a "filter.indent.clean" and "filter.indent.smudge"
 296configuration in your .git/config to specify a pair of commands to
 297modify the contents of C programs when the source files are checked
 298in ("clean" is run) and checked out (no change is made because the
 299command is "cat").
 300
 301------------------------
 302[filter "indent"]
 303        clean = indent
 304        smudge = cat
 305------------------------
 306
 307
 308Interaction between checkin/checkout attributes
 309^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 310
 311In the check-in codepath, the worktree file is first converted
 312with `filter` driver (if specified and corresponding driver
 313defined), then the result is processed with `ident` (if
 314specified), and then finally with `crlf` (again, if specified
 315and applicable).
 316
 317In the check-out codepath, the blob content is first converted
 318with `crlf`, and then `ident` and fed to `filter`.
 319
 320
 321Generating diff text
 322~~~~~~~~~~~~~~~~~~~~
 323
 324`diff`
 325^^^^^^
 326
 327The attribute `diff` affects how 'git' generates diffs for particular
 328files. It can tell git whether to generate a textual patch for the path
 329or to treat the path as a binary file.  It can also affect what line is
 330shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an
 331external command to generate the diff, or ask git to convert binary
 332files to a text format before generating the diff.
 333
 334Set::
 335
 336        A path to which the `diff` attribute is set is treated
 337        as text, even when they contain byte values that
 338        normally never appear in text files, such as NUL.
 339
 340Unset::
 341
 342        A path to which the `diff` attribute is unset will
 343        generate `Binary files differ` (or a binary patch, if
 344        binary patches are enabled).
 345
 346Unspecified::
 347
 348        A path to which the `diff` attribute is unspecified
 349        first gets its contents inspected, and if it looks like
 350        text, it is treated as text.  Otherwise it would
 351        generate `Binary files differ`.
 352
 353String::
 354
 355        Diff is shown using the specified diff driver.  Each driver may
 356        specify one or more options, as described in the following
 357        section. The options for the diff driver "foo" are defined
 358        by the configuration variables in the "diff.foo" section of the
 359        git config file.
 360
 361
 362Defining an external diff driver
 363^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 364
 365The definition of a diff driver is done in `gitconfig`, not
 366`gitattributes` file, so strictly speaking this manual page is a
 367wrong place to talk about it.  However...
 368
 369To define an external diff driver `jcdiff`, add a section to your
 370`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
 371
 372----------------------------------------------------------------
 373[diff "jcdiff"]
 374        command = j-c-diff
 375----------------------------------------------------------------
 376
 377When git needs to show you a diff for the path with `diff`
 378attribute set to `jcdiff`, it calls the command you specified
 379with the above configuration, i.e. `j-c-diff`, with 7
 380parameters, just like `GIT_EXTERNAL_DIFF` program is called.
 381See linkgit:git[1] for details.
 382
 383
 384Defining a custom hunk-header
 385^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 386
 387Each group of changes (called a "hunk") in the textual diff output
 388is prefixed with a line of the form:
 389
 390        @@ -k,l +n,m @@ TEXT
 391
 392This is called a 'hunk header'.  The "TEXT" portion is by default a line
 393that begins with an alphabet, an underscore or a dollar sign; this
 394matches what GNU 'diff -p' output uses.  This default selection however
 395is not suited for some contents, and you can use a customized pattern
 396to make a selection.
 397
 398First, in .gitattributes, you would assign the `diff` attribute
 399for paths.
 400
 401------------------------
 402*.tex   diff=tex
 403------------------------
 404
 405Then, you would define a "diff.tex.xfuncname" configuration to
 406specify a regular expression that matches a line that you would
 407want to appear as the hunk header "TEXT". Add a section to your
 408`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
 409
 410------------------------
 411[diff "tex"]
 412        xfuncname = "^(\\\\(sub)*section\\{.*)$"
 413------------------------
 414
 415Note.  A single level of backslashes are eaten by the
 416configuration file parser, so you would need to double the
 417backslashes; the pattern above picks a line that begins with a
 418backslash, and zero or more occurrences of `sub` followed by
 419`section` followed by open brace, to the end of line.
 420
 421There are a few built-in patterns to make this easier, and `tex`
 422is one of them, so you do not have to write the above in your
 423configuration file (you still need to enable this with the
 424attribute mechanism, via `.gitattributes`).  The following built in
 425patterns are available:
 426
 427- `bibtex` suitable for files with BibTeX coded references.
 428
 429- `cpp` suitable for source code in the C and C++ languages.
 430
 431- `html` suitable for HTML/XHTML documents.
 432
 433- `java` suitable for source code in the Java language.
 434
 435- `objc` suitable for source code in the Objective-C language.
 436
 437- `pascal` suitable for source code in the Pascal/Delphi language.
 438
 439- `php` suitable for source code in the PHP language.
 440
 441- `python` suitable for source code in the Python language.
 442
 443- `ruby` suitable for source code in the Ruby language.
 444
 445- `tex` suitable for source code for LaTeX documents.
 446
 447
 448Customizing word diff
 449^^^^^^^^^^^^^^^^^^^^^
 450
 451You can customize the rules that `git diff --color-words` uses to
 452split words in a line, by specifying an appropriate regular expression
 453in the "diff.*.wordRegex" configuration variable.  For example, in TeX
 454a backslash followed by a sequence of letters forms a command, but
 455several such commands can be run together without intervening
 456whitespace.  To separate them, use a regular expression in your
 457`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
 458
 459------------------------
 460[diff "tex"]
 461        wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+"
 462------------------------
 463
 464A built-in pattern is provided for all languages listed in the
 465previous section.
 466
 467
 468Performing text diffs of binary files
 469^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 470
 471Sometimes it is desirable to see the diff of a text-converted
 472version of some binary files. For example, a word processor
 473document can be converted to an ASCII text representation, and
 474the diff of the text shown. Even though this conversion loses
 475some information, the resulting diff is useful for human
 476viewing (but cannot be applied directly).
 477
 478The `textconv` config option is used to define a program for
 479performing such a conversion. The program should take a single
 480argument, the name of a file to convert, and produce the
 481resulting text on stdout.
 482
 483For example, to show the diff of the exif information of a
 484file instead of the binary information (assuming you have the
 485exif tool installed), add the following section to your
 486`$GIT_DIR/config` file (or `$HOME/.gitconfig` file):
 487
 488------------------------
 489[diff "jpg"]
 490        textconv = exif
 491------------------------
 492
 493NOTE: The text conversion is generally a one-way conversion;
 494in this example, we lose the actual image contents and focus
 495just on the text data. This means that diffs generated by
 496textconv are _not_ suitable for applying. For this reason,
 497only `git diff` and the `git log` family of commands (i.e.,
 498log, whatchanged, show) will perform text conversion. `git
 499format-patch` will never generate this output. If you want to
 500send somebody a text-converted diff of a binary file (e.g.,
 501because it quickly conveys the changes you have made), you
 502should generate it separately and send it as a comment _in
 503addition to_ the usual binary diff that you might send.
 504
 505
 506Performing a three-way merge
 507~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 508
 509`merge`
 510^^^^^^^
 511
 512The attribute `merge` affects how three versions of a file is
 513merged when a file-level merge is necessary during `git merge`,
 514and other commands such as `git revert` and `git cherry-pick`.
 515
 516Set::
 517
 518        Built-in 3-way merge driver is used to merge the
 519        contents in a way similar to 'merge' command of `RCS`
 520        suite.  This is suitable for ordinary text files.
 521
 522Unset::
 523
 524        Take the version from the current branch as the
 525        tentative merge result, and declare that the merge has
 526        conflicts.  This is suitable for binary files that does
 527        not have a well-defined merge semantics.
 528
 529Unspecified::
 530
 531        By default, this uses the same built-in 3-way merge
 532        driver as is the case the `merge` attribute is set.
 533        However, `merge.default` configuration variable can name
 534        different merge driver to be used for paths to which the
 535        `merge` attribute is unspecified.
 536
 537String::
 538
 539        3-way merge is performed using the specified custom
 540        merge driver.  The built-in 3-way merge driver can be
 541        explicitly specified by asking for "text" driver; the
 542        built-in "take the current branch" driver can be
 543        requested with "binary".
 544
 545
 546Built-in merge drivers
 547^^^^^^^^^^^^^^^^^^^^^^
 548
 549There are a few built-in low-level merge drivers defined that
 550can be asked for via the `merge` attribute.
 551
 552text::
 553
 554        Usual 3-way file level merge for text files.  Conflicted
 555        regions are marked with conflict markers `<<<<<<<`,
 556        `=======` and `>>>>>>>`.  The version from your branch
 557        appears before the `=======` marker, and the version
 558        from the merged branch appears after the `=======`
 559        marker.
 560
 561binary::
 562
 563        Keep the version from your branch in the work tree, but
 564        leave the path in the conflicted state for the user to
 565        sort out.
 566
 567union::
 568
 569        Run 3-way file level merge for text files, but take
 570        lines from both versions, instead of leaving conflict
 571        markers.  This tends to leave the added lines in the
 572        resulting file in random order and the user should
 573        verify the result. Do not use this if you do not
 574        understand the implications.
 575
 576
 577Defining a custom merge driver
 578^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 579
 580The definition of a merge driver is done in the `.git/config`
 581file, not in the `gitattributes` file, so strictly speaking this
 582manual page is a wrong place to talk about it.  However...
 583
 584To define a custom merge driver `filfre`, add a section to your
 585`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
 586
 587----------------------------------------------------------------
 588[merge "filfre"]
 589        name = feel-free merge driver
 590        driver = filfre %O %A %B
 591        recursive = binary
 592----------------------------------------------------------------
 593
 594The `merge.*.name` variable gives the driver a human-readable
 595name.
 596
 597The `merge.*.driver` variable's value is used to construct a
 598command to run to merge ancestor's version (`%O`), current
 599version (`%A`) and the other branches' version (`%B`).  These
 600three tokens are replaced with the names of temporary files that
 601hold the contents of these versions when the command line is
 602built.
 603
 604The merge driver is expected to leave the result of the merge in
 605the file named with `%A` by overwriting it, and exit with zero
 606status if it managed to merge them cleanly, or non-zero if there
 607were conflicts.
 608
 609The `merge.*.recursive` variable specifies what other merge
 610driver to use when the merge driver is called for an internal
 611merge between common ancestors, when there are more than one.
 612When left unspecified, the driver itself is used for both
 613internal merge and the final merge.
 614
 615
 616`conflict-marker-size`
 617^^^^^^^^^^^^^^^^^^^^^^
 618
 619This attribute controls the length of conflict markers left in
 620the work tree file during a conflicted merge.  Only setting to
 621the value to a positive integer has any meaningful effect.
 622
 623For example, this line in `.gitattributes` can be used to tell the merge
 624machinery to leave much longer (instead of the usual 7-character-long)
 625conflict markers when merging the file `Documentation/git-merge.txt`
 626results in a conflict.
 627
 628------------------------
 629Documentation/git-merge.txt     conflict-marker-size=32
 630------------------------
 631
 632
 633Checking whitespace errors
 634~~~~~~~~~~~~~~~~~~~~~~~~~~
 635
 636`whitespace`
 637^^^^^^^^^^^^
 638
 639The `core.whitespace` configuration variable allows you to define what
 640'diff' and 'apply' should consider whitespace errors for all paths in
 641the project (See linkgit:git-config[1]).  This attribute gives you finer
 642control per path.
 643
 644Set::
 645
 646        Notice all types of potential whitespace errors known to git.
 647
 648Unset::
 649
 650        Do not notice anything as error.
 651
 652Unspecified::
 653
 654        Use the value of `core.whitespace` configuration variable to
 655        decide what to notice as error.
 656
 657String::
 658
 659        Specify a comma separate list of common whitespace problems to
 660        notice in the same format as `core.whitespace` configuration
 661        variable.
 662
 663
 664Creating an archive
 665~~~~~~~~~~~~~~~~~~~
 666
 667`export-ignore`
 668^^^^^^^^^^^^^^^
 669
 670Files and directories with the attribute `export-ignore` won't be added to
 671archive files.
 672
 673`export-subst`
 674^^^^^^^^^^^^^^
 675
 676If the attribute `export-subst` is set for a file then git will expand
 677several placeholders when adding this file to an archive.  The
 678expansion depends on the availability of a commit ID, i.e., if
 679linkgit:git-archive[1] has been given a tree instead of a commit or a
 680tag then no replacement will be done.  The placeholders are the same
 681as those for the option `--pretty=format:` of linkgit:git-log[1],
 682except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
 683in the file.  E.g. the string `$Format:%H$` will be replaced by the
 684commit hash.
 685
 686
 687Packing objects
 688~~~~~~~~~~~~~~~
 689
 690`delta`
 691^^^^^^^
 692
 693Delta compression will not be attempted for blobs for paths with the
 694attribute `delta` set to false.
 695
 696
 697Viewing files in GUI tools
 698~~~~~~~~~~~~~~~~~~~~~~~~~~
 699
 700`encoding`
 701^^^^^^^^^^
 702
 703The value of this attribute specifies the character encoding that should
 704be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to
 705display the contents of the relevant file. Note that due to performance
 706considerations linkgit:gitk[1] does not use this attribute unless you
 707manually enable per-file encodings in its options.
 708
 709If this attribute is not set or has an invalid value, the value of the
 710`gui.encoding` configuration variable is used instead
 711(See linkgit:git-config[1]).
 712
 713
 714USING ATTRIBUTE MACROS
 715----------------------
 716
 717You do not want any end-of-line conversions applied to, nor textual diffs
 718produced for, any binary file you track.  You would need to specify e.g.
 719
 720------------
 721*.jpg -crlf -diff
 722------------
 723
 724but that may become cumbersome, when you have many attributes.  Using
 725attribute macros, you can specify groups of attributes set or unset at
 726the same time.  The system knows a built-in attribute macro, `binary`:
 727
 728------------
 729*.jpg binary
 730------------
 731
 732which is equivalent to the above.  Note that the attribute macros can only
 733be "Set" (see the above example that sets "binary" macro as if it were an
 734ordinary attribute --- setting it in turn unsets "crlf" and "diff").
 735
 736
 737DEFINING ATTRIBUTE MACROS
 738-------------------------
 739
 740Custom attribute macros can be defined only in the `.gitattributes` file
 741at the toplevel (i.e. not in any subdirectory).  The built-in attribute
 742macro "binary" is equivalent to:
 743
 744------------
 745[attr]binary -diff -crlf
 746------------
 747
 748
 749EXAMPLE
 750-------
 751
 752If you have these three `gitattributes` file:
 753
 754----------------------------------------------------------------
 755(in $GIT_DIR/info/attributes)
 756
 757a*      foo !bar -baz
 758
 759(in .gitattributes)
 760abc     foo bar baz
 761
 762(in t/.gitattributes)
 763ab*     merge=filfre
 764abc     -foo -bar
 765*.c     frotz
 766----------------------------------------------------------------
 767
 768the attributes given to path `t/abc` are computed as follows:
 769
 7701. By examining `t/.gitattributes` (which is in the same
 771   directory as the path in question), git finds that the first
 772   line matches.  `merge` attribute is set.  It also finds that
 773   the second line matches, and attributes `foo` and `bar`
 774   are unset.
 775
 7762. Then it examines `.gitattributes` (which is in the parent
 777   directory), and finds that the first line matches, but
 778   `t/.gitattributes` file already decided how `merge`, `foo`
 779   and `bar` attributes should be given to this path, so it
 780   leaves `foo` and `bar` unset.  Attribute `baz` is set.
 781
 7823. Finally it examines `$GIT_DIR/info/attributes`.  This file
 783   is used to override the in-tree settings.  The first line is
 784   a match, and `foo` is set, `bar` is reverted to unspecified
 785   state, and `baz` is unset.
 786
 787As the result, the attributes assignment to `t/abc` becomes:
 788
 789----------------------------------------------------------------
 790foo     set to true
 791bar     unspecified
 792baz     set to false
 793merge   set to string value "filfre"
 794frotz   unspecified
 795----------------------------------------------------------------
 796
 797
 798
 799GIT
 800---
 801Part of the linkgit:git[1] suite