Documentation / gitattributes.txton commit chainlint: fix for core.autocrlf=true (1ce2b45)
   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. Leading and trailing whitespaces are
  25ignored. Lines that begin with '#' are ignored. Patterns
  26that begin with a double quote are quoted in C style.
  27When the pattern matches the path in question, the attributes
  28listed on the line are given to the path.
  29
  30Each attribute can be in one of these states for a given path:
  31
  32Set::
  33
  34        The path has the attribute with special value "true";
  35        this is specified by listing only the name of the
  36        attribute in the attribute list.
  37
  38Unset::
  39
  40        The path has the attribute with special value "false";
  41        this is specified by listing the name of the attribute
  42        prefixed with a dash `-` in the attribute list.
  43
  44Set to a value::
  45
  46        The path has the attribute with specified string value;
  47        this is specified by listing the name of the attribute
  48        followed by an equal sign `=` and its value in the
  49        attribute list.
  50
  51Unspecified::
  52
  53        No pattern matches the path, and nothing says if
  54        the path has or does not have the attribute, the
  55        attribute for the path is said to be Unspecified.
  56
  57When more than one pattern matches the path, a later line
  58overrides an earlier line.  This overriding is done per
  59attribute.
  60
  61The rules by which the pattern matches paths are the same as in
  62`.gitignore` files (see linkgit:gitignore[5]), with a few exceptions:
  63
  64  - negative patterns are forbidden
  65
  66  - patterns that match a directory do not recursively match paths
  67    inside that directory (so using the trailing-slash `path/` syntax is
  68    pointless in an attributes file; use `path/**` instead)
  69
  70When deciding what attributes are assigned to a path, Git
  71consults `$GIT_DIR/info/attributes` file (which has the highest
  72precedence), `.gitattributes` file in the same directory as the
  73path in question, and its parent directories up to the toplevel of the
  74work tree (the further the directory that contains `.gitattributes`
  75is from the path in question, the lower its precedence). Finally
  76global and system-wide files are considered (they have the lowest
  77precedence).
  78
  79When the `.gitattributes` file is missing from the work tree, the
  80path in the index is used as a fall-back.  During checkout process,
  81`.gitattributes` in the index is used and then the file in the
  82working tree is used as a fall-back.
  83
  84If you wish to affect only a single repository (i.e., to assign
  85attributes to files that are particular to
  86one user's workflow for that repository), then
  87attributes should be placed in the `$GIT_DIR/info/attributes` file.
  88Attributes which should be version-controlled and distributed to other
  89repositories (i.e., attributes of interest to all users) should go into
  90`.gitattributes` files. Attributes that should affect all repositories
  91for a single user should be placed in a file specified by the
  92`core.attributesFile` configuration option (see linkgit:git-config[1]).
  93Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME
  94is either not set or empty, $HOME/.config/git/attributes is used instead.
  95Attributes for all users on a system should be placed in the
  96`$(prefix)/etc/gitattributes` file.
  97
  98Sometimes you would need to override a setting of an attribute
  99for a path to `Unspecified` state.  This can be done by listing
 100the name of the attribute prefixed with an exclamation point `!`.
 101
 102
 103EFFECTS
 104-------
 105
 106Certain operations by Git can be influenced by assigning
 107particular attributes to a path.  Currently, the following
 108operations are attributes-aware.
 109
 110Checking-out and checking-in
 111~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113These attributes affect how the contents stored in the
 114repository are copied to the working tree files when commands
 115such as 'git checkout' and 'git merge' run.  They also affect how
 116Git stores the contents you prepare in the working tree in the
 117repository upon 'git add' and 'git commit'.
 118
 119`text`
 120^^^^^^
 121
 122This attribute enables and controls end-of-line normalization.  When a
 123text file is normalized, its line endings are converted to LF in the
 124repository.  To control what line ending style is used in the working
 125directory, use the `eol` attribute for a single file and the
 126`core.eol` configuration variable for all text files.
 127Note that `core.autocrlf` overrides `core.eol`
 128
 129Set::
 130
 131        Setting the `text` attribute on a path enables end-of-line
 132        normalization and marks the path as a text file.  End-of-line
 133        conversion takes place without guessing the content type.
 134
 135Unset::
 136
 137        Unsetting the `text` attribute on a path tells Git not to
 138        attempt any end-of-line conversion upon checkin or checkout.
 139
 140Set to string value "auto"::
 141
 142        When `text` is set to "auto", the path is marked for automatic
 143        end-of-line conversion.  If Git decides that the content is
 144        text, its line endings are converted to LF on checkin.
 145        When the file has been committed with CRLF, no conversion is done.
 146
 147Unspecified::
 148
 149        If the `text` attribute is unspecified, Git uses the
 150        `core.autocrlf` configuration variable to determine if the
 151        file should be converted.
 152
 153Any other value causes Git to act as if `text` has been left
 154unspecified.
 155
 156`eol`
 157^^^^^
 158
 159This attribute sets a specific line-ending style to be used in the
 160working directory.  It enables end-of-line conversion without any
 161content checks, effectively setting the `text` attribute.  Note that
 162setting this attribute on paths which are in the index with CRLF line
 163endings may make the paths to be considered dirty.  Adding the path to
 164the index again will normalize the line endings in the index.
 165
 166Set to string value "crlf"::
 167
 168        This setting forces Git to normalize line endings for this
 169        file on checkin and convert them to CRLF when the file is
 170        checked out.
 171
 172Set to string value "lf"::
 173
 174        This setting forces Git to normalize line endings to LF on
 175        checkin and prevents conversion to CRLF when the file is
 176        checked out.
 177
 178Backwards compatibility with `crlf` attribute
 179^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 180
 181For backwards compatibility, the `crlf` attribute is interpreted as
 182follows:
 183
 184------------------------
 185crlf            text
 186-crlf           -text
 187crlf=input      eol=lf
 188------------------------
 189
 190End-of-line conversion
 191^^^^^^^^^^^^^^^^^^^^^^
 192
 193While Git normally leaves file contents alone, it can be configured to
 194normalize line endings to LF in the repository and, optionally, to
 195convert them to CRLF when files are checked out.
 196
 197If you simply want to have CRLF line endings in your working directory
 198regardless of the repository you are working with, you can set the
 199config variable "core.autocrlf" without using any attributes.
 200
 201------------------------
 202[core]
 203        autocrlf = true
 204------------------------
 205
 206This does not force normalization of text files, but does ensure
 207that text files that you introduce to the repository have their line
 208endings normalized to LF when they are added, and that files that are
 209already normalized in the repository stay normalized.
 210
 211If you want to ensure that text files that any contributor introduces to
 212the repository have their line endings normalized, you can set the
 213`text` attribute to "auto" for _all_ files.
 214
 215------------------------
 216*       text=auto
 217------------------------
 218
 219The attributes allow a fine-grained control, how the line endings
 220are converted.
 221Here is an example that will make Git normalize .txt, .vcproj and .sh
 222files, ensure that .vcproj files have CRLF and .sh files have LF in
 223the working directory, and prevent .jpg files from being normalized
 224regardless of their content.
 225
 226------------------------
 227*               text=auto
 228*.txt           text
 229*.vcproj        text eol=crlf
 230*.sh            text eol=lf
 231*.jpg           -text
 232------------------------
 233
 234NOTE: When `text=auto` conversion is enabled in a cross-platform
 235project using push and pull to a central repository the text files
 236containing CRLFs should be normalized.
 237
 238From a clean working directory:
 239
 240-------------------------------------------------
 241$ echo "* text=auto" >.gitattributes
 242$ git add --renormalize .
 243$ git status        # Show files that will be normalized
 244$ git commit -m "Introduce end-of-line normalization"
 245-------------------------------------------------
 246
 247If any files that should not be normalized show up in 'git status',
 248unset their `text` attribute before running 'git add -u'.
 249
 250------------------------
 251manual.pdf      -text
 252------------------------
 253
 254Conversely, text files that Git does not detect can have normalization
 255enabled manually.
 256
 257------------------------
 258weirdchars.txt  text
 259------------------------
 260
 261If `core.safecrlf` is set to "true" or "warn", Git verifies if
 262the conversion is reversible for the current setting of
 263`core.autocrlf`.  For "true", Git rejects irreversible
 264conversions; for "warn", Git only prints a warning but accepts
 265an irreversible conversion.  The safety triggers to prevent such
 266a conversion done to the files in the work tree, but there are a
 267few exceptions.  Even though...
 268
 269- 'git add' itself does not touch the files in the work tree, the
 270  next checkout would, so the safety triggers;
 271
 272- 'git apply' to update a text file with a patch does touch the files
 273  in the work tree, but the operation is about text files and CRLF
 274  conversion is about fixing the line ending inconsistencies, so the
 275  safety does not trigger;
 276
 277- 'git diff' itself does not touch the files in the work tree, it is
 278  often run to inspect the changes you intend to next 'git add'.  To
 279  catch potential problems early, safety triggers.
 280
 281
 282`working-tree-encoding`
 283^^^^^^^^^^^^^^^^^^^^^^^
 284
 285Git recognizes files encoded in ASCII or one of its supersets (e.g.
 286UTF-8, ISO-8859-1, ...) as text files. Files encoded in certain other
 287encodings (e.g. UTF-16) are interpreted as binary and consequently
 288built-in Git text processing tools (e.g. 'git diff') as well as most Git
 289web front ends do not visualize the contents of these files by default.
 290
 291In these cases you can tell Git the encoding of a file in the working
 292directory with the `working-tree-encoding` attribute. If a file with this
 293attribute is added to Git, then Git reencodes the content from the
 294specified encoding to UTF-8. Finally, Git stores the UTF-8 encoded
 295content in its internal data structure (called "the index"). On checkout
 296the content is reencoded back to the specified encoding.
 297
 298Please note that using the `working-tree-encoding` attribute may have a
 299number of pitfalls:
 300
 301- Alternative Git implementations (e.g. JGit or libgit2) and older Git
 302  versions (as of March 2018) do not support the `working-tree-encoding`
 303  attribute. If you decide to use the `working-tree-encoding` attribute
 304  in your repository, then it is strongly recommended to ensure that all
 305  clients working with the repository support it.
 306
 307  For example, Microsoft Visual Studio resources files (`*.rc`) or
 308  PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
 309  If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
 310  a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
 311  stored as UTF-8 internally. A client without `working-tree-encoding`
 312  support will checkout `foo.ps1` as UTF-8 encoded file. This will
 313  typically cause trouble for the users of this file.
 314
 315  If a Git client, that does not support the `working-tree-encoding`
 316  attribute, adds a new file `bar.ps1`, then `bar.ps1` will be
 317  stored "as-is" internally (in this example probably as UTF-16).
 318  A client with `working-tree-encoding` support will interpret the
 319  internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
 320  That operation will fail and cause an error.
 321
 322- Reencoding content to non-UTF encodings can cause errors as the
 323  conversion might not be UTF-8 round trip safe. If you suspect your
 324  encoding to not be round trip safe, then add it to
 325  `core.checkRoundtripEncoding` to make Git check the round trip
 326  encoding (see linkgit:git-config[1]). SHIFT-JIS (Japanese character
 327  set) is known to have round trip issues with UTF-8 and is checked by
 328  default.
 329
 330- Reencoding content requires resources that might slow down certain
 331  Git operations (e.g 'git checkout' or 'git add').
 332
 333Use the `working-tree-encoding` attribute only if you cannot store a file
 334in UTF-8 encoding and if you want Git to be able to process the content
 335as text.
 336
 337As an example, use the following attributes if your '*.ps1' files are
 338UTF-16 encoded with byte order mark (BOM) and you want Git to perform
 339automatic line ending conversion based on your platform.
 340
 341------------------------
 342*.ps1           text working-tree-encoding=UTF-16
 343------------------------
 344
 345Use the following attributes if your '*.ps1' files are UTF-16 little
 346endian encoded without BOM and you want Git to use Windows line endings
 347in the working directory. Please note, it is highly recommended to
 348explicitly define the line endings with `eol` if the `working-tree-encoding`
 349attribute is used to avoid ambiguity.
 350
 351------------------------
 352*.ps1           text working-tree-encoding=UTF-16LE eol=CRLF
 353------------------------
 354
 355You can get a list of all available encodings on your platform with the
 356following command:
 357
 358------------------------
 359iconv --list
 360------------------------
 361
 362If you do not know the encoding of a file, then you can use the `file`
 363command to guess the encoding:
 364
 365------------------------
 366file foo.ps1
 367------------------------
 368
 369
 370`ident`
 371^^^^^^^
 372
 373When the attribute `ident` is set for a path, Git replaces
 374`$Id$` in the blob object with `$Id:`, followed by the
 37540-character hexadecimal blob object name, followed by a dollar
 376sign `$` upon checkout.  Any byte sequence that begins with
 377`$Id:` and ends with `$` in the worktree file is replaced
 378with `$Id$` upon check-in.
 379
 380
 381`filter`
 382^^^^^^^^
 383
 384A `filter` attribute can be set to a string value that names a
 385filter driver specified in the configuration.
 386
 387A filter driver consists of a `clean` command and a `smudge`
 388command, either of which can be left unspecified.  Upon
 389checkout, when the `smudge` command is specified, the command is
 390fed the blob object from its standard input, and its standard
 391output is used to update the worktree file.  Similarly, the
 392`clean` command is used to convert the contents of worktree file
 393upon checkin. By default these commands process only a single
 394blob and terminate. If a long running `process` filter is used
 395in place of `clean` and/or `smudge` filters, then Git can process
 396all blobs with a single filter command invocation for the entire
 397life of a single Git command, for example `git add --all`. If a
 398long running `process` filter is configured then it always takes
 399precedence over a configured single blob filter. See section
 400below for the description of the protocol used to communicate with
 401a `process` filter.
 402
 403One use of the content filtering is to massage the content into a shape
 404that is more convenient for the platform, filesystem, and the user to use.
 405For this mode of operation, the key phrase here is "more convenient" and
 406not "turning something unusable into usable".  In other words, the intent
 407is that if someone unsets the filter driver definition, or does not have
 408the appropriate filter program, the project should still be usable.
 409
 410Another use of the content filtering is to store the content that cannot
 411be directly used in the repository (e.g. a UUID that refers to the true
 412content stored outside Git, or an encrypted content) and turn it into a
 413usable form upon checkout (e.g. download the external content, or decrypt
 414the encrypted content).
 415
 416These two filters behave differently, and by default, a filter is taken as
 417the former, massaging the contents into more convenient shape.  A missing
 418filter driver definition in the config, or a filter driver that exits with
 419a non-zero status, is not an error but makes the filter a no-op passthru.
 420
 421You can declare that a filter turns a content that by itself is unusable
 422into a usable content by setting the filter.<driver>.required configuration
 423variable to `true`.
 424
 425Note: Whenever the clean filter is changed, the repo should be renormalized:
 426$ git add --renormalize .
 427
 428For example, in .gitattributes, you would assign the `filter`
 429attribute for paths.
 430
 431------------------------
 432*.c     filter=indent
 433------------------------
 434
 435Then you would define a "filter.indent.clean" and "filter.indent.smudge"
 436configuration in your .git/config to specify a pair of commands to
 437modify the contents of C programs when the source files are checked
 438in ("clean" is run) and checked out (no change is made because the
 439command is "cat").
 440
 441------------------------
 442[filter "indent"]
 443        clean = indent
 444        smudge = cat
 445------------------------
 446
 447For best results, `clean` should not alter its output further if it is
 448run twice ("clean->clean" should be equivalent to "clean"), and
 449multiple `smudge` commands should not alter `clean`'s output
 450("smudge->smudge->clean" should be equivalent to "clean").  See the
 451section on merging below.
 452
 453The "indent" filter is well-behaved in this regard: it will not modify
 454input that is already correctly indented.  In this case, the lack of a
 455smudge filter means that the clean filter _must_ accept its own output
 456without modifying it.
 457
 458If a filter _must_ succeed in order to make the stored contents usable,
 459you can declare that the filter is `required`, in the configuration:
 460
 461------------------------
 462[filter "crypt"]
 463        clean = openssl enc ...
 464        smudge = openssl enc -d ...
 465        required
 466------------------------
 467
 468Sequence "%f" on the filter command line is replaced with the name of
 469the file the filter is working on.  A filter might use this in keyword
 470substitution.  For example:
 471
 472------------------------
 473[filter "p4"]
 474        clean = git-p4-filter --clean %f
 475        smudge = git-p4-filter --smudge %f
 476------------------------
 477
 478Note that "%f" is the name of the path that is being worked on. Depending
 479on the version that is being filtered, the corresponding file on disk may
 480not exist, or may have different contents. So, smudge and clean commands
 481should not try to access the file on disk, but only act as filters on the
 482content provided to them on standard input.
 483
 484Long Running Filter Process
 485^^^^^^^^^^^^^^^^^^^^^^^^^^^
 486
 487If the filter command (a string value) is defined via
 488`filter.<driver>.process` then Git can process all blobs with a
 489single filter invocation for the entire life of a single Git
 490command. This is achieved by using the long-running process protocol
 491(described in technical/long-running-process-protocol.txt).
 492
 493When Git encounters the first file that needs to be cleaned or smudged,
 494it starts the filter and performs the handshake. In the handshake, the
 495welcome message sent by Git is "git-filter-client", only version 2 is
 496suppported, and the supported capabilities are "clean", "smudge", and
 497"delay".
 498
 499Afterwards Git sends a list of "key=value" pairs terminated with
 500a flush packet. The list will contain at least the filter command
 501(based on the supported capabilities) and the pathname of the file
 502to filter relative to the repository root. Right after the flush packet
 503Git sends the content split in zero or more pkt-line packets and a
 504flush packet to terminate content. Please note, that the filter
 505must not send any response before it received the content and the
 506final flush packet. Also note that the "value" of a "key=value" pair
 507can contain the "=" character whereas the key would never contain
 508that character.
 509------------------------
 510packet:          git> command=smudge
 511packet:          git> pathname=path/testfile.dat
 512packet:          git> 0000
 513packet:          git> CONTENT
 514packet:          git> 0000
 515------------------------
 516
 517The filter is expected to respond with a list of "key=value" pairs
 518terminated with a flush packet. If the filter does not experience
 519problems then the list must contain a "success" status. Right after
 520these packets the filter is expected to send the content in zero
 521or more pkt-line packets and a flush packet at the end. Finally, a
 522second list of "key=value" pairs terminated with a flush packet
 523is expected. The filter can change the status in the second list
 524or keep the status as is with an empty list. Please note that the
 525empty list must be terminated with a flush packet regardless.
 526
 527------------------------
 528packet:          git< status=success
 529packet:          git< 0000
 530packet:          git< SMUDGED_CONTENT
 531packet:          git< 0000
 532packet:          git< 0000  # empty list, keep "status=success" unchanged!
 533------------------------
 534
 535If the result content is empty then the filter is expected to respond
 536with a "success" status and a flush packet to signal the empty content.
 537------------------------
 538packet:          git< status=success
 539packet:          git< 0000
 540packet:          git< 0000  # empty content!
 541packet:          git< 0000  # empty list, keep "status=success" unchanged!
 542------------------------
 543
 544In case the filter cannot or does not want to process the content,
 545it is expected to respond with an "error" status.
 546------------------------
 547packet:          git< status=error
 548packet:          git< 0000
 549------------------------
 550
 551If the filter experiences an error during processing, then it can
 552send the status "error" after the content was (partially or
 553completely) sent.
 554------------------------
 555packet:          git< status=success
 556packet:          git< 0000
 557packet:          git< HALF_WRITTEN_ERRONEOUS_CONTENT
 558packet:          git< 0000
 559packet:          git< status=error
 560packet:          git< 0000
 561------------------------
 562
 563In case the filter cannot or does not want to process the content
 564as well as any future content for the lifetime of the Git process,
 565then it is expected to respond with an "abort" status at any point
 566in the protocol.
 567------------------------
 568packet:          git< status=abort
 569packet:          git< 0000
 570------------------------
 571
 572Git neither stops nor restarts the filter process in case the
 573"error"/"abort" status is set. However, Git sets its exit code
 574according to the `filter.<driver>.required` flag, mimicking the
 575behavior of the `filter.<driver>.clean` / `filter.<driver>.smudge`
 576mechanism.
 577
 578If the filter dies during the communication or does not adhere to
 579the protocol then Git will stop the filter process and restart it
 580with the next file that needs to be processed. Depending on the
 581`filter.<driver>.required` flag Git will interpret that as error.
 582
 583Delay
 584^^^^^
 585
 586If the filter supports the "delay" capability, then Git can send the
 587flag "can-delay" after the filter command and pathname. This flag
 588denotes that the filter can delay filtering the current blob (e.g. to
 589compensate network latencies) by responding with no content but with
 590the status "delayed" and a flush packet.
 591------------------------
 592packet:          git> command=smudge
 593packet:          git> pathname=path/testfile.dat
 594packet:          git> can-delay=1
 595packet:          git> 0000
 596packet:          git> CONTENT
 597packet:          git> 0000
 598packet:          git< status=delayed
 599packet:          git< 0000
 600------------------------
 601
 602If the filter supports the "delay" capability then it must support the
 603"list_available_blobs" command. If Git sends this command, then the
 604filter is expected to return a list of pathnames representing blobs
 605that have been delayed earlier and are now available.
 606The list must be terminated with a flush packet followed
 607by a "success" status that is also terminated with a flush packet. If
 608no blobs for the delayed paths are available, yet, then the filter is
 609expected to block the response until at least one blob becomes
 610available. The filter can tell Git that it has no more delayed blobs
 611by sending an empty list. As soon as the filter responds with an empty
 612list, Git stops asking. All blobs that Git has not received at this
 613point are considered missing and will result in an error.
 614
 615------------------------
 616packet:          git> command=list_available_blobs
 617packet:          git> 0000
 618packet:          git< pathname=path/testfile.dat
 619packet:          git< pathname=path/otherfile.dat
 620packet:          git< 0000
 621packet:          git< status=success
 622packet:          git< 0000
 623------------------------
 624
 625After Git received the pathnames, it will request the corresponding
 626blobs again. These requests contain a pathname and an empty content
 627section. The filter is expected to respond with the smudged content
 628in the usual way as explained above.
 629------------------------
 630packet:          git> command=smudge
 631packet:          git> pathname=path/testfile.dat
 632packet:          git> 0000
 633packet:          git> 0000  # empty content!
 634packet:          git< status=success
 635packet:          git< 0000
 636packet:          git< SMUDGED_CONTENT
 637packet:          git< 0000
 638packet:          git< 0000  # empty list, keep "status=success" unchanged!
 639------------------------
 640
 641Example
 642^^^^^^^
 643
 644A long running filter demo implementation can be found in
 645`contrib/long-running-filter/example.pl` located in the Git
 646core repository. If you develop your own long running filter
 647process then the `GIT_TRACE_PACKET` environment variables can be
 648very helpful for debugging (see linkgit:git[1]).
 649
 650Please note that you cannot use an existing `filter.<driver>.clean`
 651or `filter.<driver>.smudge` command with `filter.<driver>.process`
 652because the former two use a different inter process communication
 653protocol than the latter one.
 654
 655
 656Interaction between checkin/checkout attributes
 657^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 658
 659In the check-in codepath, the worktree file is first converted
 660with `filter` driver (if specified and corresponding driver
 661defined), then the result is processed with `ident` (if
 662specified), and then finally with `text` (again, if specified
 663and applicable).
 664
 665In the check-out codepath, the blob content is first converted
 666with `text`, and then `ident` and fed to `filter`.
 667
 668
 669Merging branches with differing checkin/checkout attributes
 670^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 671
 672If you have added attributes to a file that cause the canonical
 673repository format for that file to change, such as adding a
 674clean/smudge filter or text/eol/ident attributes, merging anything
 675where the attribute is not in place would normally cause merge
 676conflicts.
 677
 678To prevent these unnecessary merge conflicts, Git can be told to run a
 679virtual check-out and check-in of all three stages of a file when
 680resolving a three-way merge by setting the `merge.renormalize`
 681configuration variable.  This prevents changes caused by check-in
 682conversion from causing spurious merge conflicts when a converted file
 683is merged with an unconverted file.
 684
 685As long as a "smudge->clean" results in the same output as a "clean"
 686even on files that are already smudged, this strategy will
 687automatically resolve all filter-related conflicts.  Filters that do
 688not act in this way may cause additional merge conflicts that must be
 689resolved manually.
 690
 691
 692Generating diff text
 693~~~~~~~~~~~~~~~~~~~~
 694
 695`diff`
 696^^^^^^
 697
 698The attribute `diff` affects how Git generates diffs for particular
 699files. It can tell Git whether to generate a textual patch for the path
 700or to treat the path as a binary file.  It can also affect what line is
 701shown on the hunk header `@@ -k,l +n,m @@` line, tell Git to use an
 702external command to generate the diff, or ask Git to convert binary
 703files to a text format before generating the diff.
 704
 705Set::
 706
 707        A path to which the `diff` attribute is set is treated
 708        as text, even when they contain byte values that
 709        normally never appear in text files, such as NUL.
 710
 711Unset::
 712
 713        A path to which the `diff` attribute is unset will
 714        generate `Binary files differ` (or a binary patch, if
 715        binary patches are enabled).
 716
 717Unspecified::
 718
 719        A path to which the `diff` attribute is unspecified
 720        first gets its contents inspected, and if it looks like
 721        text and is smaller than core.bigFileThreshold, it is treated
 722        as text. Otherwise it would generate `Binary files differ`.
 723
 724String::
 725
 726        Diff is shown using the specified diff driver.  Each driver may
 727        specify one or more options, as described in the following
 728        section. The options for the diff driver "foo" are defined
 729        by the configuration variables in the "diff.foo" section of the
 730        Git config file.
 731
 732
 733Defining an external diff driver
 734^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 735
 736The definition of a diff driver is done in `gitconfig`, not
 737`gitattributes` file, so strictly speaking this manual page is a
 738wrong place to talk about it.  However...
 739
 740To define an external diff driver `jcdiff`, add a section to your
 741`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
 742
 743----------------------------------------------------------------
 744[diff "jcdiff"]
 745        command = j-c-diff
 746----------------------------------------------------------------
 747
 748When Git needs to show you a diff for the path with `diff`
 749attribute set to `jcdiff`, it calls the command you specified
 750with the above configuration, i.e. `j-c-diff`, with 7
 751parameters, just like `GIT_EXTERNAL_DIFF` program is called.
 752See linkgit:git[1] for details.
 753
 754
 755Defining a custom hunk-header
 756^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 757
 758Each group of changes (called a "hunk") in the textual diff output
 759is prefixed with a line of the form:
 760
 761        @@ -k,l +n,m @@ TEXT
 762
 763This is called a 'hunk header'.  The "TEXT" portion is by default a line
 764that begins with an alphabet, an underscore or a dollar sign; this
 765matches what GNU 'diff -p' output uses.  This default selection however
 766is not suited for some contents, and you can use a customized pattern
 767to make a selection.
 768
 769First, in .gitattributes, you would assign the `diff` attribute
 770for paths.
 771
 772------------------------
 773*.tex   diff=tex
 774------------------------
 775
 776Then, you would define a "diff.tex.xfuncname" configuration to
 777specify a regular expression that matches a line that you would
 778want to appear as the hunk header "TEXT". Add a section to your
 779`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
 780
 781------------------------
 782[diff "tex"]
 783        xfuncname = "^(\\\\(sub)*section\\{.*)$"
 784------------------------
 785
 786Note.  A single level of backslashes are eaten by the
 787configuration file parser, so you would need to double the
 788backslashes; the pattern above picks a line that begins with a
 789backslash, and zero or more occurrences of `sub` followed by
 790`section` followed by open brace, to the end of line.
 791
 792There are a few built-in patterns to make this easier, and `tex`
 793is one of them, so you do not have to write the above in your
 794configuration file (you still need to enable this with the
 795attribute mechanism, via `.gitattributes`).  The following built in
 796patterns are available:
 797
 798- `ada` suitable for source code in the Ada language.
 799
 800- `bibtex` suitable for files with BibTeX coded references.
 801
 802- `cpp` suitable for source code in the C and C++ languages.
 803
 804- `csharp` suitable for source code in the C# language.
 805
 806- `css` suitable for cascading style sheets.
 807
 808- `fortran` suitable for source code in the Fortran language.
 809
 810- `fountain` suitable for Fountain documents.
 811
 812- `golang` suitable for source code in the Go language.
 813
 814- `html` suitable for HTML/XHTML documents.
 815
 816- `java` suitable for source code in the Java language.
 817
 818- `matlab` suitable for source code in the MATLAB language.
 819
 820- `objc` suitable for source code in the Objective-C language.
 821
 822- `pascal` suitable for source code in the Pascal/Delphi language.
 823
 824- `perl` suitable for source code in the Perl language.
 825
 826- `php` suitable for source code in the PHP language.
 827
 828- `python` suitable for source code in the Python language.
 829
 830- `ruby` suitable for source code in the Ruby language.
 831
 832- `tex` suitable for source code for LaTeX documents.
 833
 834
 835Customizing word diff
 836^^^^^^^^^^^^^^^^^^^^^
 837
 838You can customize the rules that `git diff --word-diff` uses to
 839split words in a line, by specifying an appropriate regular expression
 840in the "diff.*.wordRegex" configuration variable.  For example, in TeX
 841a backslash followed by a sequence of letters forms a command, but
 842several such commands can be run together without intervening
 843whitespace.  To separate them, use a regular expression in your
 844`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
 845
 846------------------------
 847[diff "tex"]
 848        wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+"
 849------------------------
 850
 851A built-in pattern is provided for all languages listed in the
 852previous section.
 853
 854
 855Performing text diffs of binary files
 856^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 857
 858Sometimes it is desirable to see the diff of a text-converted
 859version of some binary files. For example, a word processor
 860document can be converted to an ASCII text representation, and
 861the diff of the text shown. Even though this conversion loses
 862some information, the resulting diff is useful for human
 863viewing (but cannot be applied directly).
 864
 865The `textconv` config option is used to define a program for
 866performing such a conversion. The program should take a single
 867argument, the name of a file to convert, and produce the
 868resulting text on stdout.
 869
 870For example, to show the diff of the exif information of a
 871file instead of the binary information (assuming you have the
 872exif tool installed), add the following section to your
 873`$GIT_DIR/config` file (or `$HOME/.gitconfig` file):
 874
 875------------------------
 876[diff "jpg"]
 877        textconv = exif
 878------------------------
 879
 880NOTE: The text conversion is generally a one-way conversion;
 881in this example, we lose the actual image contents and focus
 882just on the text data. This means that diffs generated by
 883textconv are _not_ suitable for applying. For this reason,
 884only `git diff` and the `git log` family of commands (i.e.,
 885log, whatchanged, show) will perform text conversion. `git
 886format-patch` will never generate this output. If you want to
 887send somebody a text-converted diff of a binary file (e.g.,
 888because it quickly conveys the changes you have made), you
 889should generate it separately and send it as a comment _in
 890addition to_ the usual binary diff that you might send.
 891
 892Because text conversion can be slow, especially when doing a
 893large number of them with `git log -p`, Git provides a mechanism
 894to cache the output and use it in future diffs.  To enable
 895caching, set the "cachetextconv" variable in your diff driver's
 896config. For example:
 897
 898------------------------
 899[diff "jpg"]
 900        textconv = exif
 901        cachetextconv = true
 902------------------------
 903
 904This will cache the result of running "exif" on each blob
 905indefinitely. If you change the textconv config variable for a
 906diff driver, Git will automatically invalidate the cache entries
 907and re-run the textconv filter. If you want to invalidate the
 908cache manually (e.g., because your version of "exif" was updated
 909and now produces better output), you can remove the cache
 910manually with `git update-ref -d refs/notes/textconv/jpg` (where
 911"jpg" is the name of the diff driver, as in the example above).
 912
 913Choosing textconv versus external diff
 914^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 915
 916If you want to show differences between binary or specially-formatted
 917blobs in your repository, you can choose to use either an external diff
 918command, or to use textconv to convert them to a diff-able text format.
 919Which method you choose depends on your exact situation.
 920
 921The advantage of using an external diff command is flexibility. You are
 922not bound to find line-oriented changes, nor is it necessary for the
 923output to resemble unified diff. You are free to locate and report
 924changes in the most appropriate way for your data format.
 925
 926A textconv, by comparison, is much more limiting. You provide a
 927transformation of the data into a line-oriented text format, and Git
 928uses its regular diff tools to generate the output. There are several
 929advantages to choosing this method:
 930
 9311. Ease of use. It is often much simpler to write a binary to text
 932   transformation than it is to perform your own diff. In many cases,
 933   existing programs can be used as textconv filters (e.g., exif,
 934   odt2txt).
 935
 9362. Git diff features. By performing only the transformation step
 937   yourself, you can still utilize many of Git's diff features,
 938   including colorization, word-diff, and combined diffs for merges.
 939
 9403. Caching. Textconv caching can speed up repeated diffs, such as those
 941   you might trigger by running `git log -p`.
 942
 943
 944Marking files as binary
 945^^^^^^^^^^^^^^^^^^^^^^^
 946
 947Git usually guesses correctly whether a blob contains text or binary
 948data by examining the beginning of the contents. However, sometimes you
 949may want to override its decision, either because a blob contains binary
 950data later in the file, or because the content, while technically
 951composed of text characters, is opaque to a human reader. For example,
 952many postscript files contain only ASCII characters, but produce noisy
 953and meaningless diffs.
 954
 955The simplest way to mark a file as binary is to unset the diff
 956attribute in the `.gitattributes` file:
 957
 958------------------------
 959*.ps -diff
 960------------------------
 961
 962This will cause Git to generate `Binary files differ` (or a binary
 963patch, if binary patches are enabled) instead of a regular diff.
 964
 965However, one may also want to specify other diff driver attributes. For
 966example, you might want to use `textconv` to convert postscript files to
 967an ASCII representation for human viewing, but otherwise treat them as
 968binary files. You cannot specify both `-diff` and `diff=ps` attributes.
 969The solution is to use the `diff.*.binary` config option:
 970
 971------------------------
 972[diff "ps"]
 973  textconv = ps2ascii
 974  binary = true
 975------------------------
 976
 977Performing a three-way merge
 978~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 979
 980`merge`
 981^^^^^^^
 982
 983The attribute `merge` affects how three versions of a file are
 984merged when a file-level merge is necessary during `git merge`,
 985and other commands such as `git revert` and `git cherry-pick`.
 986
 987Set::
 988
 989        Built-in 3-way merge driver is used to merge the
 990        contents in a way similar to 'merge' command of `RCS`
 991        suite.  This is suitable for ordinary text files.
 992
 993Unset::
 994
 995        Take the version from the current branch as the
 996        tentative merge result, and declare that the merge has
 997        conflicts.  This is suitable for binary files that do
 998        not have a well-defined merge semantics.
 999
1000Unspecified::
1001
1002        By default, this uses the same built-in 3-way merge
1003        driver as is the case when the `merge` attribute is set.
1004        However, the `merge.default` configuration variable can name
1005        different merge driver to be used with paths for which the
1006        `merge` attribute is unspecified.
1007
1008String::
1009
1010        3-way merge is performed using the specified custom
1011        merge driver.  The built-in 3-way merge driver can be
1012        explicitly specified by asking for "text" driver; the
1013        built-in "take the current branch" driver can be
1014        requested with "binary".
1015
1016
1017Built-in merge drivers
1018^^^^^^^^^^^^^^^^^^^^^^
1019
1020There are a few built-in low-level merge drivers defined that
1021can be asked for via the `merge` attribute.
1022
1023text::
1024
1025        Usual 3-way file level merge for text files.  Conflicted
1026        regions are marked with conflict markers `<<<<<<<`,
1027        `=======` and `>>>>>>>`.  The version from your branch
1028        appears before the `=======` marker, and the version
1029        from the merged branch appears after the `=======`
1030        marker.
1031
1032binary::
1033
1034        Keep the version from your branch in the work tree, but
1035        leave the path in the conflicted state for the user to
1036        sort out.
1037
1038union::
1039
1040        Run 3-way file level merge for text files, but take
1041        lines from both versions, instead of leaving conflict
1042        markers.  This tends to leave the added lines in the
1043        resulting file in random order and the user should
1044        verify the result. Do not use this if you do not
1045        understand the implications.
1046
1047
1048Defining a custom merge driver
1049^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1050
1051The definition of a merge driver is done in the `.git/config`
1052file, not in the `gitattributes` file, so strictly speaking this
1053manual page is a wrong place to talk about it.  However...
1054
1055To define a custom merge driver `filfre`, add a section to your
1056`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
1057
1058----------------------------------------------------------------
1059[merge "filfre"]
1060        name = feel-free merge driver
1061        driver = filfre %O %A %B %L %P
1062        recursive = binary
1063----------------------------------------------------------------
1064
1065The `merge.*.name` variable gives the driver a human-readable
1066name.
1067
1068The `merge.*.driver` variable's value is used to construct a
1069command to run to merge ancestor's version (`%O`), current
1070version (`%A`) and the other branches' version (`%B`).  These
1071three tokens are replaced with the names of temporary files that
1072hold the contents of these versions when the command line is
1073built. Additionally, %L will be replaced with the conflict marker
1074size (see below).
1075
1076The merge driver is expected to leave the result of the merge in
1077the file named with `%A` by overwriting it, and exit with zero
1078status if it managed to merge them cleanly, or non-zero if there
1079were conflicts.
1080
1081The `merge.*.recursive` variable specifies what other merge
1082driver to use when the merge driver is called for an internal
1083merge between common ancestors, when there are more than one.
1084When left unspecified, the driver itself is used for both
1085internal merge and the final merge.
1086
1087The merge driver can learn the pathname in which the merged result
1088will be stored via placeholder `%P`.
1089
1090
1091`conflict-marker-size`
1092^^^^^^^^^^^^^^^^^^^^^^
1093
1094This attribute controls the length of conflict markers left in
1095the work tree file during a conflicted merge.  Only setting to
1096the value to a positive integer has any meaningful effect.
1097
1098For example, this line in `.gitattributes` can be used to tell the merge
1099machinery to leave much longer (instead of the usual 7-character-long)
1100conflict markers when merging the file `Documentation/git-merge.txt`
1101results in a conflict.
1102
1103------------------------
1104Documentation/git-merge.txt     conflict-marker-size=32
1105------------------------
1106
1107
1108Checking whitespace errors
1109~~~~~~~~~~~~~~~~~~~~~~~~~~
1110
1111`whitespace`
1112^^^^^^^^^^^^
1113
1114The `core.whitespace` configuration variable allows you to define what
1115'diff' and 'apply' should consider whitespace errors for all paths in
1116the project (See linkgit:git-config[1]).  This attribute gives you finer
1117control per path.
1118
1119Set::
1120
1121        Notice all types of potential whitespace errors known to Git.
1122        The tab width is taken from the value of the `core.whitespace`
1123        configuration variable.
1124
1125Unset::
1126
1127        Do not notice anything as error.
1128
1129Unspecified::
1130
1131        Use the value of the `core.whitespace` configuration variable to
1132        decide what to notice as error.
1133
1134String::
1135
1136        Specify a comma separate list of common whitespace problems to
1137        notice in the same format as the `core.whitespace` configuration
1138        variable.
1139
1140
1141Creating an archive
1142~~~~~~~~~~~~~~~~~~~
1143
1144`export-ignore`
1145^^^^^^^^^^^^^^^
1146
1147Files and directories with the attribute `export-ignore` won't be added to
1148archive files.
1149
1150`export-subst`
1151^^^^^^^^^^^^^^
1152
1153If the attribute `export-subst` is set for a file then Git will expand
1154several placeholders when adding this file to an archive.  The
1155expansion depends on the availability of a commit ID, i.e., if
1156linkgit:git-archive[1] has been given a tree instead of a commit or a
1157tag then no replacement will be done.  The placeholders are the same
1158as those for the option `--pretty=format:` of linkgit:git-log[1],
1159except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
1160in the file.  E.g. the string `$Format:%H$` will be replaced by the
1161commit hash.
1162
1163
1164Packing objects
1165~~~~~~~~~~~~~~~
1166
1167`delta`
1168^^^^^^^
1169
1170Delta compression will not be attempted for blobs for paths with the
1171attribute `delta` set to false.
1172
1173
1174Viewing files in GUI tools
1175~~~~~~~~~~~~~~~~~~~~~~~~~~
1176
1177`encoding`
1178^^^^^^^^^^
1179
1180The value of this attribute specifies the character encoding that should
1181be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to
1182display the contents of the relevant file. Note that due to performance
1183considerations linkgit:gitk[1] does not use this attribute unless you
1184manually enable per-file encodings in its options.
1185
1186If this attribute is not set or has an invalid value, the value of the
1187`gui.encoding` configuration variable is used instead
1188(See linkgit:git-config[1]).
1189
1190
1191USING MACRO ATTRIBUTES
1192----------------------
1193
1194You do not want any end-of-line conversions applied to, nor textual diffs
1195produced for, any binary file you track.  You would need to specify e.g.
1196
1197------------
1198*.jpg -text -diff
1199------------
1200
1201but that may become cumbersome, when you have many attributes.  Using
1202macro attributes, you can define an attribute that, when set, also
1203sets or unsets a number of other attributes at the same time.  The
1204system knows a built-in macro attribute, `binary`:
1205
1206------------
1207*.jpg binary
1208------------
1209
1210Setting the "binary" attribute also unsets the "text" and "diff"
1211attributes as above.  Note that macro attributes can only be "Set",
1212though setting one might have the effect of setting or unsetting other
1213attributes or even returning other attributes to the "Unspecified"
1214state.
1215
1216
1217DEFINING MACRO ATTRIBUTES
1218-------------------------
1219
1220Custom macro attributes can be defined only in top-level gitattributes
1221files (`$GIT_DIR/info/attributes`, the `.gitattributes` file at the
1222top level of the working tree, or the global or system-wide
1223gitattributes files), not in `.gitattributes` files in working tree
1224subdirectories.  The built-in macro attribute "binary" is equivalent
1225to:
1226
1227------------
1228[attr]binary -diff -merge -text
1229------------
1230
1231
1232EXAMPLES
1233--------
1234
1235If you have these three `gitattributes` file:
1236
1237----------------------------------------------------------------
1238(in $GIT_DIR/info/attributes)
1239
1240a*      foo !bar -baz
1241
1242(in .gitattributes)
1243abc     foo bar baz
1244
1245(in t/.gitattributes)
1246ab*     merge=filfre
1247abc     -foo -bar
1248*.c     frotz
1249----------------------------------------------------------------
1250
1251the attributes given to path `t/abc` are computed as follows:
1252
12531. By examining `t/.gitattributes` (which is in the same
1254   directory as the path in question), Git finds that the first
1255   line matches.  `merge` attribute is set.  It also finds that
1256   the second line matches, and attributes `foo` and `bar`
1257   are unset.
1258
12592. Then it examines `.gitattributes` (which is in the parent
1260   directory), and finds that the first line matches, but
1261   `t/.gitattributes` file already decided how `merge`, `foo`
1262   and `bar` attributes should be given to this path, so it
1263   leaves `foo` and `bar` unset.  Attribute `baz` is set.
1264
12653. Finally it examines `$GIT_DIR/info/attributes`.  This file
1266   is used to override the in-tree settings.  The first line is
1267   a match, and `foo` is set, `bar` is reverted to unspecified
1268   state, and `baz` is unset.
1269
1270As the result, the attributes assignment to `t/abc` becomes:
1271
1272----------------------------------------------------------------
1273foo     set to true
1274bar     unspecified
1275baz     set to false
1276merge   set to string value "filfre"
1277frotz   unspecified
1278----------------------------------------------------------------
1279
1280
1281SEE ALSO
1282--------
1283linkgit:git-check-attr[1].
1284
1285GIT
1286---
1287Part of the linkgit:git[1] suite