[thirdparty/git.git] / 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:

	glob	attr1 attr2 ...

That is, a glob pattern followed by an attributes list,
separated by whitespaces.  When the glob 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 glob pattern matches the path, and nothing says if
	the path has or does not have the attribute.

When more than one glob pattern matches the path, a later line
overrides an earlier line.

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 (the further the
directory that contains `.gitattributes` is from the path in
question, the lower its precedence).

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, three operations
are attributes-aware.

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

The attribute `crlf` affects how the contents stored in the
repository are copied to the working tree files when commands
such as `git checkout` and `git merge` run.  It also affects how
git stores the contents you prepare in the working tree in the
repository upon `git add` and `git commit`.

Set::

	Setting the `crlf` attribute on a path is meant to mark
	the path as a "text" file.  'core.autocrlf' conversion
	takes place without guessing the content type by
	inspection.

Unset::

	Unsetting the `crlf` attribute on a path is meant to
	mark the path as a "binary" file.  The path never goes
	through line endings conversion upon checkin/checkout.

Unspecified::

	Unspecified `crlf` attribute tells git to apply the
	`core.autocrlf` conversion when the file content looks
	like text.

Set to string value "input"::

	This is similar to setting the attribute to `true`, but
	also forces git to act as if `core.autocrlf` is set to
	`input` for the path.

Any other value set to `crlf` attribute is ignored and git acts
as if the attribute is left unspecified.


The `core.autocrlf` conversion
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If the configuration variable `core.autocrlf` is false, no
conversion is done.

When `core.autocrlf` is true, it means that the platform wants
CRLF line endings for files in the working tree, and you want to
convert them back to the normal LF line endings when checking
in to the repository.

When `core.autocrlf` is set to "input", line endings are
converted to LF upon checkin, but there is no conversion done
upon checkout.


Generating diff text
~~~~~~~~~~~~~~~~~~~~

The attribute `diff` affects if `git diff` generates textual
patch for the path or just says `Binary files differ`.

Set::

	A path to which the `diff` attribute is set is treated
	as text, even when they contain byte values that
	normally never appear in text files, such as NUL.

Unset::

	A path to which the `diff` attribute is unset will
	generate `Binary files differ`.

Unspecified::

	A path to which the `diff` attribute is unspecified
	first gets its contents inspected, and if it looks like
	text, it is treated as text.  Otherwise it would
	generate `Binary files differ`.

Any other value set to `diff` attribute is ignored and git acts
as if the attribute is left unspecified.


Performing a three-way merge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The attribute `merge` affects how three versions of a file is
merged when a file-level merge is necessary during `git merge`,
and other programs such as `git revert` and `git cherry-pick`.

Set::

	Built-in 3-way merge driver is used to merge the
	contents in a way similar to `merge` command of `RCS`
	suite.  This is suitable for ordinary text files.

Unset::

	Take the version from the current branch as the
	tentative merge result, and declare that the merge has
	conflicts.  This is suitable for binary files that does
	not have a well-defined merge semantics.

Unspecified::

	By default, this uses the same built-in 3-way merge
	driver as is the case the `merge` attribute is set.
	However, `merge.default` configuration variable can name
	different merge driver to be used for paths to which the
	`merge` attribute is unspecified.

Any other string value::

	3-way merge is performed using the specified custom
	merge driver.  The built-in 3-way merge driver can be
	explicitly specified by asking for "text" driver; the
	built-in "take the current branch" driver can be
	requested by "binary".


Defining a custom merge driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The definition of a merge driver is done in `gitconfig` not
`gitattributes` file, so strictly speaking this manual page is a
wrong place to talk about it.  However...

To define a custom merge driver `filfre`, add a section to your
`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:

----------------------------------------------------------------
[merge "filfre"]
	name = feel-free merge driver
	driver = filfre %O %A %B
	recursive = binary
----------------------------------------------------------------

The `merge.*.name` variable gives the driver a human-readable
name.

The `merge.*.driver` variable's value is used to construct a
command to run to merge ancestor's version (`%O`), current
version (`%A`) and the other branches' version (`%B`).  These
three tokens are replaced with the names of temporary files that
hold the contents of these versions when the command line is
built.

The merge driver is expected to leave the result of the merge in
the file named with `%A` by overwriting it, and exit with zero
status if it managed to merge them cleanly, or non-zero if there
were conflicts.

The `merge.*.recursive` variable specifies what other merge
driver to use when the merge driver is called for an internal
merge between common ancestors, when there are more than one.
When left unspecified, the driver itself is used for both
internal merge and the final merge.


EXAMPLE
-------

If you have these three `gitattributes` file:

----------------------------------------------------------------
(in $GIT_DIR/info/attributes)

a*	foo !bar -baz

(in .gitattributes)
abc	foo bar baz

(in t/.gitattributes)
ab*	merge=filfre
abc	-foo -bar
*.c	frotz
----------------------------------------------------------------

the attributes given to path `t/abc` are computed as follows:

1. By examining `t/.gitattributes` (which is in the same
   diretory as the path in question), git finds that the first
   line matches.  `merge` attribute is set.  It also finds that
   the second line matches, and attributes `foo` and `bar`
   are unset.

2. Then it examines `.gitattributes` (which is in the parent
   directory), and finds that the first line matches, but
   `t/.gitattributes` file already decided how `merge`, `foo`
   and `bar` attributes should be given to this path, so it
   leaves `foo` and `bar` unset.  Attribute `baz` is set.

3. Finally it examines `$GIT_DIR/info/gitattributes`.  This file
   is used to override the in-tree settings.  The first line is
   a match, and `foo` is set, `bar` is reverted to unspecified
   state, and `baz` is unset.

As the result, the attributes assignement to `t/abc` becomes:

----------------------------------------------------------------
foo	set to true
bar	unspecified
baz	set to false
merge	set to string value "filfre"
frotz	unspecified
----------------------------------------------------------------


GIT
---
Part of the gitlink:git[7] suite
Commit	Line	Data
88e7fdf2 JH	1	gitattributes(5)
	2	================
	3
	4	NAME
	5	----
	6	gitattributes - defining attributes per path
	7
	8	SYNOPSIS
	9	--------
2d76548b	10	$GIT_DIR/info/attributes, gitattributes
88e7fdf2 JH	11
	12
	13	DESCRIPTION
	14	-----------
	15
	16	A `gitattributes` file is a simple text file that gives
	17	`attributes` to pathnames.
	18
	19	Each line in `gitattributes` file is of form:
	20
	21	glob attr1 attr2 ...
	22
	23	That is, a glob pattern followed by an attributes list,
	24	separated by whitespaces. When the glob pattern matches the
	25	path in question, the attributes listed on the line are given to
	26	the path.
	27
	28	Each attribute can be in one of these states for a given path:
	29
	30	Set::
	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
	36	Unset::
	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
	42	Set 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
	49	Unspecified::
	50
	51	No glob pattern matches the path, and nothing says if
	52	the path has or does not have the attribute.
	53
	54	When more than one glob pattern matches the path, a later line
	55	overrides an earlier line.
	56
	57	When deciding what attributes are assigned to a path, git
	58	consults `$GIT_DIR/info/attributes` file (which has the highest
	59	precedence), `.gitattributes` file in the same directory as the
	60	path in question, and its parent directories (the further the
	61	directory that contains `.gitattributes` is from the path in
	62	question, the lower its precedence).
	63
	64	Sometimes you would need to override an setting of an attribute
	65	for a path to `unspecified` state. This can be done by listing
	66	the name of the attribute prefixed with an exclamation point `!`.
	67
	68
	69	EFFECTS
	70	-------
	71
	72	Certain operations by git can be influenced by assigning
	73	particular attributes to a path. Currently, three operations
	74	are attributes-aware.
75
76	Checking-out and checking-in
77	~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78
79	The attribute `crlf` affects how the contents stored in the
80	repository are copied to the working tree files when commands
81	such as `git checkout` and `git merge` run. It also affects how
82	git stores the contents you prepare in the working tree in the
83	repository upon `git add` and `git commit`.
84
85	Set::
86
87	Setting the `crlf` attribute on a path is meant to mark
88	the path as a "text" file. 'core.autocrlf' conversion
89	takes place without guessing the content type by
90	inspection.
91
92	Unset::
93
94	Unsetting the `crlf` attribute on a path is meant to
95	mark the path as a "binary" file. The path never goes
96	through line endings conversion upon checkin/checkout.
97
98	Unspecified::
99
100	Unspecified `crlf` attribute tells git to apply the
101	`core.autocrlf` conversion when the file content looks
102	like text.
103
104	Set to string value "input"::
105
106	This is similar to setting the attribute to `true`, but
107	also forces git to act as if `core.autocrlf` is set to
108	`input` for the path.
109
110	Any other value set to `crlf` attribute is ignored and git acts
111	as if the attribute is left unspecified.
112
113
114	The `core.autocrlf` conversion
115	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
116
117	If the configuration variable `core.autocrlf` is false, no
118	conversion is done.
119
120	When `core.autocrlf` is true, it means that the platform wants
121	CRLF line endings for files in the working tree, and you want to
122	convert them back to the normal LF line endings when checking
123	in to the repository.
124
125	When `core.autocrlf` is set to "input", line endings are
126	converted to LF upon checkin, but there is no conversion done
127	upon checkout.
128
129
130	Generating diff text
131	~~~~~~~~~~~~~~~~~~~~
132
133	The attribute `diff` affects if `git diff` generates textual
134	patch for the path or just says `Binary files differ`.
135
136	Set::
137
138	A path to which the `diff` attribute is set is treated
139	as text, even when they contain byte values that
140	normally never appear in text files, such as NUL.
141
142	Unset::
143
144	A path to which the `diff` attribute is unset will
145	generate `Binary files differ`.
146
147	Unspecified::
148
149	A path to which the `diff` attribute is unspecified
150	first gets its contents inspected, and if it looks like
151	text, it is treated as text. Otherwise it would
152	generate `Binary files differ`.
153
154	Any other value set to `diff` attribute is ignored and git acts
155	as if the attribute is left unspecified.
156
157
158	Performing a three-way merge
159	~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160
161	The attribute `merge` affects how three versions of a file is
162	merged when a file-level merge is necessary during `git merge`,
163	and other programs such as `git revert` and `git cherry-pick`.
164
165	Set::
166
167	Built-in 3-way merge driver is used to merge the
168	contents in a way similar to `merge` command of `RCS`
169	suite. This is suitable for ordinary text files.
170
171	Unset::
172
173	Take the version from the current branch as the
174	tentative merge result, and declare that the merge has
175	conflicts. This is suitable for binary files that does
176	not have a well-defined merge semantics.
177
178	Unspecified::
179
180	By default, this uses the same built-in 3-way merge
181	driver as is the case the `merge` attribute is set.
182	However, `merge.default` configuration variable can name
183	different merge driver to be used for paths to which the
184	`merge` attribute is unspecified.
185
186	Any other string value::
187
188	3-way merge is performed using the specified custom
189	merge driver. The built-in 3-way merge driver can be
190	explicitly specified by asking for "text" driver; the
191	built-in "take the current branch" driver can be
192	requested by "binary".
193
194
195	Defining a custom merge driver
196	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
197
198	The definition of a merge driver is done in `gitconfig` not
199	`gitattributes` file, so strictly speaking this manual page is a
200	wrong place to talk about it. However...
201
202	To define a custom merge driver `filfre`, add a section to your
203	`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
204
205	----------------------------------------------------------------
206	[merge "filfre"]
207	name = feel-free merge driver
208	driver = filfre %O %A %B
209	recursive = binary
210	----------------------------------------------------------------
211
212	The `merge.*.name` variable gives the driver a human-readable
213	name.
214
215	The `merge.*.driver` variable's value is used to construct a
216	command to run to merge ancestor's version (`%O`), current
217	version (`%A`) and the other branches' version (`%B`). These
218	three tokens are replaced with the names of temporary files that
219	hold the contents of these versions when the command line is
220	built.
221
222	The merge driver is expected to leave the result of the merge in
223	the file named with `%A` by overwriting it, and exit with zero
224	status if it managed to merge them cleanly, or non-zero if there
225	were conflicts.
226
227	The `merge.*.recursive` variable specifies what other merge
228	driver to use when the merge driver is called for an internal
229	merge between common ancestors, when there are more than one.
230	When left unspecified, the driver itself is used for both
231	internal merge and the final merge.
232
233
234	EXAMPLE
235	-------
236
237	If you have these three `gitattributes` file:
238
239	----------------------------------------------------------------
240	(in $GIT_DIR/info/attributes)
241
242	a* foo !bar -baz
243
244	(in .gitattributes)
245	abc foo bar baz
246
247	(in t/.gitattributes)
248	ab* merge=filfre
249	abc -foo -bar
250	*.c frotz
251	----------------------------------------------------------------
252
253	the attributes given to path `t/abc` are computed as follows:
254
255	1. By examining `t/.gitattributes` (which is in the same
256	diretory as the path in question), git finds that the first
257	line matches. `merge` attribute is set. It also finds that
258	the second line matches, and attributes `foo` and `bar`
259	are unset.
260
261	2. Then it examines `.gitattributes` (which is in the parent
262	directory), and finds that the first line matches, but
263	`t/.gitattributes` file already decided how `merge`, `foo`
264	and `bar` attributes should be given to this path, so it
265	leaves `foo` and `bar` unset. Attribute `baz` is set.
266
267	3. Finally it examines `$GIT_DIR/info/gitattributes`. This file
268	is used to override the in-tree settings. The first line is
269	a match, and `foo` is set, `bar` is reverted to unspecified
270	state, and `baz` is unset.
271
272	As the result, the attributes assignement to `t/abc` becomes:
273
274	----------------------------------------------------------------
275	foo set to true
276	bar unspecified
277	baz set to false
278	merge set to string value "filfre"
279	frotz unspecified
280	----------------------------------------------------------------
281
282
283	GIT
284	---
285	Part of the gitlink:git[7] suite