Document gitattributes(5)
Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Apr 19, 2007 at 20:48 UTC
88e7fdf2cb436e068434241b0519577293055c19
3 files changed
+300
-2
Documentation/Makefile
+2
-2
@@ -2,7 +2,7 @@ MAN1_TXT= \
2
$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
3
$(wildcard git-*.txt)) \
4
gitk.txt
5
-MAN5_TXT=
5
+MAN5_TXT=gitattributes.txt
6
MAN7_TXT=git.txt
7
8
DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
@@ -68,7 +68,7 @@ install: man
68
$(INSTALL) -d -m755 $(DESTDIR)$(man5dir)
69
$(INSTALL) -d -m755 $(DESTDIR)$(man7dir)
70
$(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir)
71
- : $(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
71
+ $(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
72
$(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
73
74
Documentation/config.txt
+13
@@ -499,6 +499,19 @@ merge.verbosity::
499
conflicts, 2 outputs conflicts and file changes. Level 5 and
500
above outputs debugging information. The default is level 2.
501
502
+merge.<driver>.name::
503
+ Defines a human readable name for a custom low-level
504
+ merge driver. See gitlink:gitattributes[5] for details.
505
+
506
+merge.<driver>.driver::
507
+ Defines the command that implements a custom low-level
508
+ merge driver. See gitlink:gitattributes[5] for details.
509
+
510
+merge.<driver>.recursive::
511
+ Names a low-level merge driver to be used when
512
+ performing an internal merge between common ancestors.
513
+ See gitlink:gitattributes[5] for details.
514
+
515
pack.window::
516
The size of the window used by gitlink:git-pack-objects[1] when no
517
window size is given on the command line. Defaults to 10.
Documentation/gitattributes.txt
new
+285
@@ -0,0 +1,285 @@
1
+gitattributes(5)
2
+================
3
+
4
+NAME
5
+----
6
+gitattributes - defining attributes per path
7
+
8
+SYNOPSIS
9
+--------
10
+.gitattributes
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