path: root/Documentation/gitattributes.txt

gitattributes(5)
================

NAME
----
gitattributes - defining attributes per path

SYNOPSIS
--------
$GIT_DIR/info/attributes, .gitattributes


DESCRIPTION
-----------

A `gitattributes` file is a simple text file that gives
`attributes` to pathnames.

Each line in `gitattributes` file is of form:

	pattern	attr1 attr2 ...

That is, a pattern followed by an attributes list,
separated by whitespaces.  When the pattern matches the
path in question, the attributes listed on the line are given to
the path.

Each attribute can be in one of these states for a given path:

Set::

	The path has the attribute with special value "true";
	this is specified by listing only the name of the
	attribute in the attribute list.

Unset::

	The path has the attribute with special value "false";
	this is specified by listing the name of the attribute
	prefixed with a dash `-` in the attribute list.

Set to a value::

	The path has the attribute with specified string value;
	this is specified by listing the name of the attribute
	followed by an equal sign `=` and its value in the
	attribute list.

Unspecified::

	No pattern matches the path, and nothing says if
	the path has or does not have the attribute, the
	attribute for the path is said to be Unspecified.

When more than one pattern matches the path, a later line
overrides an earlier line.  This overriding is done per
attribute.  The rules how the pattern matches paths are the
same as in `.gitignore` files; see linkgit:gitignore[5].

When deciding what attributes are assigned to a path, git
consults `$GIT_DIR/info/attributes` file (which has the highest
precedence), `.gitattributes` file in the same directory as the
path in question, and its parent directories up to the toplevel of the
work tree (the further the directory that contains `.gitattributes`
is from the path in question, the lower its precedence). Finally
global and system-wide files are considered (they have the lowest
precedence).

If you wish to affect only a single repository (i.e., to assign
attributes to files that are particular to
one user's workflow for that repository), then
attributes should be placed in the `$GIT_DIR/info/attributes` file.
Attributes which should be version-controlled and distributed to other
repositories (i.e., attributes of interest to all users) should go into
`.gitattributes` files. Attributes that should affect all repositories
for a single user should be placed in a file specified by the
`core.attributesfile` configuration option (see linkgit:git-config[1]).
Attributes for all users on a system should be placed in the
`$(prefix)/etc/gitattributes` file.

Sometimes you would need to override an setting of an attribute
for a path to `unspecified` state.  This can be done by listing
the name of the attribute prefixed with an exclamation point `!`.


EFFECTS
-------

Certain operations by git can be influenced by assigning
particular attributes to a path.  Currently, the following
operations are attributes-aware.

Checking-out and checking-in
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These attributes affect how the contents stored in the
repository are copied to the working tree files when commands
such as 'git checkout' and 'git merge' run.  They also affect how
git stores the contents you prepare in the working tree in the
repository upon 'git add' and 'git commit'.

`text`
^^^^^^

This attribute enables and controls end-of-line normalization.  When a
text file is normalized, its line endings are converted to LF in the
repository.  To control what line ending style is used in the working
directory, use the `eol` attribute for a single file and the
`core.eol` configuration variable for all text files.

Set::

	Setting the `text` attribute on a path enables end-of-line
	normalization and marks the path as a text file.  End-of-line
	conversion takes place without guessing the content type.

Unset::

	Unsetting the `text` attribute on a path tells git not to
	attempt any end-of-line conversion upon checkin or checkout.

Set to string value "auto"::

	When `text` is set to "auto", the path is marked for automatic
	end-of-line normalization.  If git decides that the content is
	text, its line endings are normalized to LF on checkin.

Unspecified::

	If the `text` attribute is unspecified, git uses the
	`core.autocrlf` configuration variable to determine if the
	file should be converted.

Any other value causes git to act as if `text` has been left
unspecified.

`eol`
^^^^^

This attribute sets a specific line-ending style to be used in the
working directory.  It enables end-of-line normalization without any
content checks, effectively setting the `text` attribute.

Set to string value "crlf"::

	This setting forces git to normalize line endings for this
	file on checkin and convert them to CRLF when the file is
	checked out.

Set to string value "lf"::

	This setting forces git to normalize line endings to LF on
	checkin and prevents conversion to CRLF when the file is
	checked out.

Backwards compatibility with `crlf` attribute
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For backwards compatibility, the `crlf` attribute is interpreted as
follows:

------------------------
crlf		text
-crlf		-text
crlf=input	eol=lf
------------------------

End-of-line conversion
^^^^^^^^^^^^^^^^^^^^^^

While git normally leaves file contents alone, it can be configured to
normalize line endings to LF in the repository and, optionally, to
convert them to CRLF when files are checked out.

Here is an example that will make git normalize .txt, .vcproj and .sh
files, ensure that .vcproj files have CRLF and .sh files have LF in
the working directory, and prevent .jpg files from being normalized
regardless of their content.

------------------------
*.txt		text
*.vcproj	eol=crlf
*.sh		eol=lf
*.jpg		-text
------------------------

Other source code management systems normalize all text files in their
repositories, and there are two ways to enable similar automatic
normalization in git.

If you simply want to have CRLF line endings in your working directory
regardless of the repository you are working with, you can set the
config variable "core.autocrlf" without changing any attributes.

------------------------
[core]
	autocrlf = true
------------------------

This does not force normalization of all text files, but does ensure
that text files that you introduce to the repository have their line
endings normalized to LF when they are added, and that files that are
already normalized in the repository stay normalized.

If you want to interoperate with a source code management system that
enforces end-of-line normalization, or you simply want all text files
in your repository to be normalized, you should instead set the `text`
attribute to "auto" for _all_ files.

------------------------
*	text=auto
------------------------

This ensures that all files that git considers to be text will have
normalized (LF) line endings in the repository.  The `core.eol`
configuration variable controls which line endings git will use for
normalized files in your working directory; the default is to use the
native line ending for your platform, or CRLF if `core.autocrlf` is
set.

NOTE: When `text=auto` normalization is enabled in an existing
repository, any text files containing CRLFs should be normalized.  If
they are not they will be normalized the next time someone tries to
change them, causing unfortunate misattribution.  From a clean working
directory:

-------------------------------------------------
$ echo "* text=auto" >>.gitattributes
$ rm .git/index     # Remove the index to force git to
$ git reset         # re-scan the working directory
$ git status        # Show files that will be normalized
$ git add -u
$ git add .gitattributes
$ git commit -m "Introduce end-of-line normalization"
-------------------------------------------------

If any files that should not be normalized show up in 'git status',
unset their `text` attribute before running 'git add -u'.

------------------------
manual.pdf	-text
------------------------

Conversely, text files that git does not detect can have normalization
enabled manually.

------------------------
weirdchars.txt	text
------------------------

If `core.safecrlf` is set to "true" or "warn", git verifies if
the conversion is reversible for the current setting of
`core.autocrlf`.  For "true", git rejects irreversible
conversions; for "warn", git only prints a warning but accepts
an irreversible conversion.  The safety triggers to prevent such
a conversion done to the files in the work tree, but there are a
few exceptions.  Even though...

- 'git add' itself does not touch the files in the work tree, the
  next checkout would, so the safety triggers;

- 'git apply' to update a text file with a patch does touch the files
  in the work tree, but the operation is about text files and CRLF
  conversion is about fixing the line ending inconsistencies, so the
  safety does not trigger;

- 'git diff' itself does not touch the files in the work tree, it is
  often run to inspect the changes you intend to next 'git add'.  To
  catch potential problems early, safety triggers.


`ident`
^^^^^^^

When the attribute `ident` is set for a path, git replaces
`$Id$` in the blob object with `$Id:`, followed by the
40-character hexadecimal blob object name, followed by a dollar
sign `$` upon checkout.  Any byte sequence that begins with
`$Id:` and ends with `$` in the worktree file is replaced
with `$Id$` upon check-in.


`filter`
^^^^^^^^

A `filter` attribute can be set to a string value that names a
filter driver specified in the configuration.

A filter driver consists of a `clean` command and a `smudge`
command, either of which can be left unspecified.  Upon
checkout, when the `smudge` command is specified, the command is
fed the blob object from its standard input, and its standard
output is used to update the worktree file.  Similarly, the
`clean` command is used to convert the contents of worktree file
upon checkin.

A missing filter driver definition in the config is not an error
but makes the filter a no-op passthru.

The content filtering is done to massage the content into a
shape that is more convenient for the platform, filesystem, and
the user to use.  The key phrase here is "more convenient" and not
"turning something unusable into usable".  In other words, the
intent is that if someone unsets the filter driver definition,
or does not have the appropriate filter program, the project
should still be usable.

For example, in .gitattributes, you would assign the `filter`
attribute for paths.

------------------------
*.c	filter=indent
------------------------

Then you would define a "filter.indent.clean" and "filter.indent.smudge"
configuration in your .git/config to specify a pair of commands to
modify the contents of C programs when the source files are checked
in ("clean" is run) and checked out (no change is made because the
command is "cat").

------------------------
[filter "indent"]
	clean = indent
	smudge = cat
------------------------

For best results, `clean` should not alter its output further if it is
run twice ("clean->clean" should be equivalent to "clean"), and
multiple `smudge` commands should not alter `clean`'s output
("smudge->smudge->clean" should be equivalent to "clean").  See the
section on merging below.

The "indent" filter is well-behaved in this regard: it will not modify
input that is already correctly indented.  In this case, the lack of a
smudge filter means that the clean filter _must_ accept its own output
without modifying it.

Sequence "%f" on the filter command line is replaced with the name of
the file the filter is working on.  A filter might use this in keyword
substitution.  For example:

------------------------
[filter "p4"]
	clean = git-p4-filter --clean %f
	smudge = git-p4-filter --smudge %f
------------------------


Interaction between checkin/checkout attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the check-in codepath, the worktree file is first converted
with `filter` driver (if specified and corresponding driver
defined), then the result is processed with `ident` (if
specified), and then finally with `text` (again, if specified
and applicable).

In the check-out codepath, the blob content is first converted
with `text`, and then `ident` and fed to `filter`.


Merging branches with differing checkin/checkout attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you have added attributes to a file that cause the canonical
repository format for that file to change, such as adding a
clean/smudge filter or text/eol/ident attributes, merging anything
where the attribute is not in place would normally cause merge
conflicts.

To prevent these unnecessary merge c