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