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