@matheusbsbs / matheus-bagliano / commits / 88e7fdf2cb
Fork 0

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