]>
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 | |
b9d14ffb JH |
52 | the path has or does not have the attribute, the |
53 | attribute for the path is said to be Unspecified. | |
88e7fdf2 JH |
54 | |
55 | When more than one glob pattern matches the path, a later line | |
b9d14ffb JH |
56 | overrides an earlier line. This overriding is done per |
57 | attribute. | |
88e7fdf2 JH |
58 | |
59 | When deciding what attributes are assigned to a path, git | |
60 | consults `$GIT_DIR/info/attributes` file (which has the highest | |
61 | precedence), `.gitattributes` file in the same directory as the | |
62 | path in question, and its parent directories (the further the | |
63 | directory that contains `.gitattributes` is from the path in | |
64 | question, the lower its precedence). | |
65 | ||
66 | Sometimes you would need to override an setting of an attribute | |
67 | for a path to `unspecified` state. This can be done by listing | |
68 | the name of the attribute prefixed with an exclamation point `!`. | |
69 | ||
70 | ||
71 | EFFECTS | |
72 | ------- | |
73 | ||
74 | Certain operations by git can be influenced by assigning | |
ae7aa499 JH |
75 | particular attributes to a path. Currently, the following |
76 | operations are attributes-aware. | |
88e7fdf2 JH |
77 | |
78 | Checking-out and checking-in | |
79 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
80 | ||
3fed15f5 | 81 | These attributes affect how the contents stored in the |
88e7fdf2 | 82 | repository are copied to the working tree files when commands |
3fed15f5 | 83 | such as `git checkout` and `git merge` run. They also affect how |
88e7fdf2 JH |
84 | git stores the contents you prepare in the working tree in the |
85 | repository upon `git add` and `git commit`. | |
86 | ||
3fed15f5 JH |
87 | `crlf` |
88 | ^^^^^^ | |
89 | ||
90 | This attribute controls the line-ending convention. | |
91 | ||
88e7fdf2 JH |
92 | Set:: |
93 | ||
94 | Setting the `crlf` attribute on a path is meant to mark | |
95 | the path as a "text" file. 'core.autocrlf' conversion | |
96 | takes place without guessing the content type by | |
97 | inspection. | |
98 | ||
99 | Unset:: | |
100 | ||
101 | Unsetting the `crlf` attribute on a path is meant to | |
102 | mark the path as a "binary" file. The path never goes | |
103 | through line endings conversion upon checkin/checkout. | |
104 | ||
105 | Unspecified:: | |
106 | ||
107 | Unspecified `crlf` attribute tells git to apply the | |
108 | `core.autocrlf` conversion when the file content looks | |
109 | like text. | |
110 | ||
111 | Set to string value "input":: | |
112 | ||
113 | This is similar to setting the attribute to `true`, but | |
114 | also forces git to act as if `core.autocrlf` is set to | |
115 | `input` for the path. | |
116 | ||
117 | Any other value set to `crlf` attribute is ignored and git acts | |
118 | as if the attribute is left unspecified. | |
119 | ||
120 | ||
121 | The `core.autocrlf` conversion | |
122 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
123 | ||
124 | If the configuration variable `core.autocrlf` is false, no | |
125 | conversion is done. | |
126 | ||
127 | When `core.autocrlf` is true, it means that the platform wants | |
128 | CRLF line endings for files in the working tree, and you want to | |
129 | convert them back to the normal LF line endings when checking | |
130 | in to the repository. | |
131 | ||
132 | When `core.autocrlf` is set to "input", line endings are | |
133 | converted to LF upon checkin, but there is no conversion done | |
134 | upon checkout. | |
135 | ||
136 | ||
3fed15f5 JH |
137 | `ident` |
138 | ^^^^^^^ | |
139 | ||
140 | When the attribute `ident` is set to a path, git replaces | |
af9b54bb | 141 | `$Id$` in the blob object with `$Id:`, followed by |
3fed15f5 JH |
142 | 40-character hexadecimal blob object name, followed by a dollar |
143 | sign `$` upon checkout. Any byte sequence that begins with | |
af9b54bb AP |
144 | `$Id:` and ends with `$` in the worktree file is replaced |
145 | with `$Id$` upon check-in. | |
3fed15f5 JH |
146 | |
147 | ||
aa4ed402 JH |
148 | `filter` |
149 | ^^^^^^^^ | |
150 | ||
c05ef938 | 151 | A `filter` attribute can be set to a string value that names a |
aa4ed402 JH |
152 | filter driver specified in the configuration. |
153 | ||
c05ef938 | 154 | A filter driver consists of a `clean` command and a `smudge` |
aa4ed402 | 155 | command, either of which can be left unspecified. Upon |
c05ef938 WC |
156 | checkout, when the `smudge` command is specified, the command is |
157 | fed the blob object from its standard input, and its standard | |
158 | output is used to update the worktree file. Similarly, the | |
159 | `clean` command is used to convert the contents of worktree file | |
160 | upon checkin. | |
aa4ed402 | 161 | |
c05ef938 | 162 | A missing filter driver definition in the config is not an error |
aa4ed402 JH |
163 | but makes the filter a no-op passthru. |
164 | ||
165 | The content filtering is done to massage the content into a | |
166 | shape that is more convenient for the platform, filesystem, and | |
c05ef938 | 167 | the user to use. The key phrase here is "more convenient" and not |
4d84aff3 JS |
168 | "turning something unusable into usable". In other words, the |
169 | intent is that if someone unsets the filter driver definition, | |
170 | or does not have the appropriate filter program, the project | |
171 | should still be usable. | |
aa4ed402 JH |
172 | |
173 | ||
174 | Interaction between checkin/checkout attributes | |
175 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
176 | ||
177 | In the check-in codepath, the worktree file is first converted | |
178 | with `filter` driver (if specified and corresponding driver | |
179 | defined), then the result is processed with `ident` (if | |
180 | specified), and then finally with `crlf` (again, if specified | |
181 | and applicable). | |
182 | ||
183 | In the check-out codepath, the blob content is first converted | |
184 | with `crlf`, and then `ident` and fed to `filter`. | |
185 | ||
186 | ||
88e7fdf2 JH |
187 | Generating diff text |
188 | ~~~~~~~~~~~~~~~~~~~~ | |
189 | ||
190 | The attribute `diff` affects if `git diff` generates textual | |
ae7aa499 JH |
191 | patch for the path or just says `Binary files differ`. It also |
192 | can affect what line is shown on the hunk header `@@ -k,l +n,m @@` | |
193 | line. | |
88e7fdf2 JH |
194 | |
195 | Set:: | |
196 | ||
197 | A path to which the `diff` attribute is set is treated | |
198 | as text, even when they contain byte values that | |
199 | normally never appear in text files, such as NUL. | |
200 | ||
201 | Unset:: | |
202 | ||
203 | A path to which the `diff` attribute is unset will | |
204 | generate `Binary files differ`. | |
205 | ||
206 | Unspecified:: | |
207 | ||
208 | A path to which the `diff` attribute is unspecified | |
209 | first gets its contents inspected, and if it looks like | |
210 | text, it is treated as text. Otherwise it would | |
211 | generate `Binary files differ`. | |
212 | ||
2cc3167c JH |
213 | String:: |
214 | ||
215 | Diff is shown using the specified custom diff driver. | |
216 | The driver program is given its input using the same | |
217 | calling convention as used for GIT_EXTERNAL_DIFF | |
ae7aa499 JH |
218 | program. This name is also used for custom hunk header |
219 | selection. | |
2cc3167c JH |
220 | |
221 | ||
222 | Defining a custom diff driver | |
223 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
224 | ||
225 | The definition of a diff driver is done in `gitconfig`, not | |
226 | `gitattributes` file, so strictly speaking this manual page is a | |
227 | wrong place to talk about it. However... | |
228 | ||
229 | To define a custom diff driver `jcdiff`, add a section to your | |
230 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
231 | ||
232 | ---------------------------------------------------------------- | |
233 | [diff "jcdiff"] | |
234 | command = j-c-diff | |
235 | ---------------------------------------------------------------- | |
236 | ||
237 | When git needs to show you a diff for the path with `diff` | |
238 | attribute set to `jcdiff`, it calls the command you specified | |
239 | with the above configuration, i.e. `j-c-diff`, with 7 | |
240 | parameters, just like `GIT_EXTERNAL_DIFF` program is called. | |
241 | See gitlink:git[7] for details. | |
88e7fdf2 JH |
242 | |
243 | ||
ae7aa499 JH |
244 | Defining a custom hunk-header |
245 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
246 | ||
247 | Each group of changes (called "hunk") in the textual diff output | |
248 | is prefixed with a line of the form: | |
249 | ||
250 | @@ -k,l +n,m @@ TEXT | |
251 | ||
252 | The text is called 'hunk header', and by default a line that | |
253 | begins with an alphabet, an underscore or a dollar sign is used, | |
254 | which matches what GNU `diff -p` output uses. This default | |
255 | selection however is not suited for some contents, and you can | |
256 | use customized pattern to make a selection. | |
257 | ||
258 | First in .gitattributes, you would assign the `diff` attribute | |
259 | for paths. | |
260 | ||
261 | ------------------------ | |
262 | *.tex diff=tex | |
263 | ------------------------ | |
264 | ||
265 | Then, you would define "diff.tex.funcname" configuration to | |
266 | specify a regular expression that matches a line that you would | |
267 | want to appear as the hunk header, like this: | |
268 | ||
269 | ------------------------ | |
270 | [diff "tex"] | |
271 | funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$" | |
272 | ------------------------ | |
273 | ||
274 | Note. A single level of backslashes are eaten by the | |
275 | configuration file parser, so you would need to double the | |
276 | backslashes; the pattern above picks a line that begins with a | |
02783075 | 277 | backslash, and zero or more occurrences of `sub` followed by |
ae7aa499 JH |
278 | `section` followed by open brace, to the end of line. |
279 | ||
280 | There are a few built-in patterns to make this easier, and `tex` | |
281 | is one of them, so you do not have to write the above in your | |
282 | configuration file (you still need to enable this with the | |
283 | attribute mechanism, via `.gitattributes`). Another built-in | |
284 | pattern is defined for `java` that defines a pattern suitable | |
285 | for program text in Java language. | |
286 | ||
287 | ||
88e7fdf2 JH |
288 | Performing a three-way merge |
289 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
290 | ||
291 | The attribute `merge` affects how three versions of a file is | |
292 | merged when a file-level merge is necessary during `git merge`, | |
293 | and other programs such as `git revert` and `git cherry-pick`. | |
294 | ||
295 | Set:: | |
296 | ||
297 | Built-in 3-way merge driver is used to merge the | |
298 | contents in a way similar to `merge` command of `RCS` | |
299 | suite. This is suitable for ordinary text files. | |
300 | ||
301 | Unset:: | |
302 | ||
303 | Take the version from the current branch as the | |
304 | tentative merge result, and declare that the merge has | |
305 | conflicts. This is suitable for binary files that does | |
306 | not have a well-defined merge semantics. | |
307 | ||
308 | Unspecified:: | |
309 | ||
310 | By default, this uses the same built-in 3-way merge | |
311 | driver as is the case the `merge` attribute is set. | |
312 | However, `merge.default` configuration variable can name | |
313 | different merge driver to be used for paths to which the | |
314 | `merge` attribute is unspecified. | |
315 | ||
2cc3167c | 316 | String:: |
88e7fdf2 JH |
317 | |
318 | 3-way merge is performed using the specified custom | |
319 | merge driver. The built-in 3-way merge driver can be | |
320 | explicitly specified by asking for "text" driver; the | |
321 | built-in "take the current branch" driver can be | |
b9d14ffb | 322 | requested with "binary". |
88e7fdf2 JH |
323 | |
324 | ||
325 | Defining a custom merge driver | |
326 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
327 | ||
328 | The definition of a merge driver is done in `gitconfig` not | |
329 | `gitattributes` file, so strictly speaking this manual page is a | |
330 | wrong place to talk about it. However... | |
331 | ||
332 | To define a custom merge driver `filfre`, add a section to your | |
333 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
334 | ||
335 | ---------------------------------------------------------------- | |
336 | [merge "filfre"] | |
337 | name = feel-free merge driver | |
338 | driver = filfre %O %A %B | |
339 | recursive = binary | |
340 | ---------------------------------------------------------------- | |
341 | ||
342 | The `merge.*.name` variable gives the driver a human-readable | |
343 | name. | |
344 | ||
345 | The `merge.*.driver` variable's value is used to construct a | |
346 | command to run to merge ancestor's version (`%O`), current | |
347 | version (`%A`) and the other branches' version (`%B`). These | |
348 | three tokens are replaced with the names of temporary files that | |
349 | hold the contents of these versions when the command line is | |
350 | built. | |
351 | ||
352 | The merge driver is expected to leave the result of the merge in | |
353 | the file named with `%A` by overwriting it, and exit with zero | |
354 | status if it managed to merge them cleanly, or non-zero if there | |
355 | were conflicts. | |
356 | ||
357 | The `merge.*.recursive` variable specifies what other merge | |
358 | driver to use when the merge driver is called for an internal | |
359 | merge between common ancestors, when there are more than one. | |
360 | When left unspecified, the driver itself is used for both | |
361 | internal merge and the final merge. | |
362 | ||
363 | ||
364 | EXAMPLE | |
365 | ------- | |
366 | ||
367 | If you have these three `gitattributes` file: | |
368 | ||
369 | ---------------------------------------------------------------- | |
370 | (in $GIT_DIR/info/attributes) | |
371 | ||
372 | a* foo !bar -baz | |
373 | ||
374 | (in .gitattributes) | |
375 | abc foo bar baz | |
376 | ||
377 | (in t/.gitattributes) | |
378 | ab* merge=filfre | |
379 | abc -foo -bar | |
380 | *.c frotz | |
381 | ---------------------------------------------------------------- | |
382 | ||
383 | the attributes given to path `t/abc` are computed as follows: | |
384 | ||
385 | 1. By examining `t/.gitattributes` (which is in the same | |
02783075 | 386 | directory as the path in question), git finds that the first |
88e7fdf2 JH |
387 | line matches. `merge` attribute is set. It also finds that |
388 | the second line matches, and attributes `foo` and `bar` | |
389 | are unset. | |
390 | ||
391 | 2. Then it examines `.gitattributes` (which is in the parent | |
392 | directory), and finds that the first line matches, but | |
393 | `t/.gitattributes` file already decided how `merge`, `foo` | |
394 | and `bar` attributes should be given to this path, so it | |
395 | leaves `foo` and `bar` unset. Attribute `baz` is set. | |
396 | ||
5c759f96 | 397 | 3. Finally it examines `$GIT_DIR/info/attributes`. This file |
88e7fdf2 JH |
398 | is used to override the in-tree settings. The first line is |
399 | a match, and `foo` is set, `bar` is reverted to unspecified | |
400 | state, and `baz` is unset. | |
401 | ||
02783075 | 402 | As the result, the attributes assignment to `t/abc` becomes: |
88e7fdf2 JH |
403 | |
404 | ---------------------------------------------------------------- | |
405 | foo set to true | |
406 | bar unspecified | |
407 | baz set to false | |
408 | merge set to string value "filfre" | |
409 | frotz unspecified | |
410 | ---------------------------------------------------------------- | |
411 | ||
412 | ||
8460b2fc RS |
413 | Creating an archive |
414 | ~~~~~~~~~~~~~~~~~~~ | |
415 | ||
38c9c9b7 RS |
416 | `export-subst` |
417 | ^^^^^^^^^^^^^^ | |
8460b2fc | 418 | |
38c9c9b7 | 419 | If the attribute `export-subst` is set for a file then git will expand |
8460b2fc RS |
420 | several placeholders when adding this file to an archive. The |
421 | expansion depends on the availability of a commit ID, i.e. if | |
422 | gitlink:git-archive[1] has been given a tree instead of a commit or a | |
423 | tag then no replacement will be done. The placeholders are the same | |
df4a394f RS |
424 | as those for the option `--pretty=format:` of gitlink:git-log[1], |
425 | except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` | |
426 | in the file. E.g. the string `$Format:%H$` will be replaced by the | |
427 | commit hash. | |
8460b2fc RS |
428 | |
429 | ||
88e7fdf2 JH |
430 | GIT |
431 | --- | |
432 | Part of the gitlink:git[7] suite |