| blob | 173d7da868ea8311ffe3570b30593ef271bb2114 |
4 <head>
9 /* Debug borders */
11 /*
12 border: 1px solid red;
13 */
14 }
16 body {
18 }
20 a {
23 }
26 }
28 em {
31 }
33 strong {
36 }
38 tt {
40 }
48 }
52 }
53 h2 {
55 }
56 h3 {
58 }
59 h3 + * {
61 }
66 }
68 hr {
70 }
72 p {
75 }
79 }
81 pre {
84 }
86 span#author {
91 }
92 span#email {
93 }
96 }
98 div#footer {
104 }
105 div#footer-text {
108 }
109 div#footer-badges {
112 }
114 div#preamble {
117 }
123 }
127 }
131 }
133 /* Block element titles. */
141 }
144 }
148 }
151 }
154 }
160 }
166 }
171 }
175 }
180 }
183 }
187 }
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 }
200 }
204 }
209 }
215 dl {
218 }
219 dt {
224 }
227 }
231 }
234 }
237 }
240 }
243 }
246 }
253 }
257 }
258 thead {
261 }
262 tfoot {
264 }
267 }
270 }
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 }
278 }
282 }
288 }
291 }
294 }
300 }
303 }
307 }
311 }
315 }
317 div#toctitle {
324 }
329 }
333 }
337 }
341 }
342 /* Overrides for manpage documents */
343 h1 {
348 }
349 h2 {
351 }
354 }
358 }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
366 }
373 }
379 }
384 }
388 }
392 }
397 }
399 /* IE6 sets dynamically generated links as visited. */
401 </style>
402 </head>
403 <body>
405 <h1>
406 gitattributes(5) Manual Page
407 </h1>
410 <p>gitattributes -
411 defining attributes per path
412 </p>
413 </div>
414 </div>
418 </div>
427 </div></div>
429 separated by whitespaces. When the pattern matches the
430 path in question, the attributes listed on the line are given to
431 the path.</p></div>
432 <div class="paragraph"><p>Each attribute can be in one of these states for a given path:</p></div>
435 Set
436 </dt>
437 <dd>
438 <p>
439 The path has the attribute with special value "true";
440 this is specified by listing only the name of the
441 attribute in the attribute list.
442 </p>
443 </dd>
445 Unset
446 </dt>
447 <dd>
448 <p>
449 The path has the attribute with special value "false";
450 this is specified by listing the name of the attribute
452 </p>
453 </dd>
455 Set to a value
456 </dt>
457 <dd>
458 <p>
459 The path has the attribute with specified string value;
460 this is specified by listing the name of the attribute
462 attribute list.
463 </p>
464 </dd>
466 Unspecified
467 </dt>
468 <dd>
469 <p>
470 No pattern matches the path, and nothing says if
471 the path has or does not have the attribute, the
472 attribute for the path is said to be Unspecified.
473 </p>
474 </dd>
475 </dl></div>
477 overrides an earlier line. This overriding is done per
478 attribute. The rules how the pattern matches paths are the
483 path in question, and its parent directories up to the toplevel of the
485 is from the path in question, the lower its precedence). Finally
486 global and system-wide files are considered (they have the lowest
487 precedence).</p></div>
489 attributes to files that are particular to
490 one user’s workflow for that repository), then
492 Attributes which should be version-controlled and distributed to other
493 repositories (i.e., attributes of interest to all users) should go into
495 for a single user should be placed in a file specified by the
496 <tt>core.attributesfile</tt> configuration option (see <a href="git-config.html">git-config(1)</a>).
497 Attributes for all users on a system should be placed in the
502 </div>
506 particular attributes to a path. Currently, the following
507 operations are attributes-aware.</p></div>
508 <h3 id="_checking_out_and_checking_in">Checking-out and checking-in</h3><div style="clear:left"></div>
510 repository are copied to the working tree files when commands
512 git stores the contents you prepare in the working tree in the
516 text file is normalized, its line endings are converted to LF in the
517 repository. To control what line ending style is used in the working
522 Set
523 </dt>
524 <dd>
525 <p>
527 normalization and marks the path as a text file. End-of-line
528 conversion takes place without guessing the content type.
529 </p>
530 </dd>
532 Unset
533 </dt>
534 <dd>
535 <p>
537 attempt any end-of-line conversion upon checkin or checkout.
538 </p>
539 </dd>
541 Set to string value "auto"
542 </dt>
543 <dd>
544 <p>
546 end-of-line normalization. If git decides that the content is
547 text, its line endings are normalized to LF on checkin.
548 </p>
549 </dd>
551 Unspecified
552 </dt>
553 <dd>
554 <p>
557 file should be converted.
558 </p>
559 </dd>
560 </dl></div>
562 unspecified.</p></div>
565 working directory. It enables end-of-line normalization without any
569 Set to string value "crlf"
570 </dt>
571 <dd>
572 <p>
573 This setting forces git to normalize line endings for this
574 file on checkin and convert them to CRLF when the file is
575 checked out.
576 </p>
577 </dd>
579 Set to string value "lf"
580 </dt>
581 <dd>
582 <p>
583 This setting forces git to normalize line endings to LF on
584 checkin and prevents conversion to CRLF when the file is
585 checked out.
586 </p>
587 </dd>
588 </dl></div>
589 <h4 id="_backwards_compatibility_with_tt_crlf_tt_attribute">Backwards compatibility with <tt>crlf</tt> attribute</h4>
590 <div class="paragraph"><p>For backwards compatibility, the <tt>crlf</tt> attribute is interpreted as
591 follows:</p></div>
594 <pre><tt>crlf text
595 -crlf -text
596 crlf=input eol=lf</tt></pre>
597 </div></div>
599 <div class="paragraph"><p>While git normally leaves file contents alone, it can be configured to
600 normalize line endings to LF in the repository and, optionally, to
601 convert them to CRLF when files are checked out.</p></div>
603 files, ensure that .vcproj files have CRLF and .sh files have LF in
604 the working directory, and prevent .jpg files from being normalized
605 regardless of their content.</p></div>
608 <pre><tt>*.txt text
609 *.vcproj eol=crlf
610 *.sh eol=lf
611 *.jpg -text</tt></pre>
612 </div></div>
613 <div class="paragraph"><p>Other source code management systems normalize all text files in their
614 repositories, and there are two ways to enable similar automatic
615 normalization in git.</p></div>
616 <div class="paragraph"><p>If you simply want to have CRLF line endings in your working directory
617 regardless of the repository you are working with, you can set the
621 <pre><tt>[core]
622 autocrlf = true</tt></pre>
623 </div></div>
625 that text files that you introduce to the repository have their line
626 endings normalized to LF when they are added, and that files that are
627 already normalized in the repository stay normalized.</p></div>
629 enforces end-of-line normalization, or you simply want all text files
635 </div></div>
638 configuration variable controls which line endings git will use for
639 normalized files in your working directory; the default is to use the
641 set.</p></div>
643 <table><tr>
646 </td>
648 repository, any text files containing CRLFs should be normalized. If
649 they are not they will be normalized the next time someone tries to
650 change them, causing unfortunate misattribution. From a clean working
651 directory:</td>
652 </tr></table>
653 </div>
657 $ rm .git/index # Remove the index to force git to
658 $ git reset # re-scan the working directory
659 $ git status # Show files that will be normalized
660 $ git add -u
661 $ git add .gitattributes
663 </div></div>
664 <div class="paragraph"><p>If any files that should not be normalized show up in <em>git status</em>,
669 </div></div>
670 <div class="paragraph"><p>Conversely, text files that git does not detect can have normalization
671 enabled manually.</p></div>
675 </div></div>
677 the conversion is reversible for the current setting of
679 conversions; for "warn", git only prints a warning but accepts
680 an irreversible conversion. The safety triggers to prevent such
681 a conversion done to the files in the work tree, but there are a
684 <li>
685 <p>
687 next checkout would, so the safety triggers;
688 </p>
689 </li>
690 <li>
691 <p>
693 in the work tree, but the operation is about text files and CRLF
694 conversion is about fixing the line ending inconsistencies, so the
695 safety does not trigger;
696 </p>
697 </li>
698 <li>
699 <p>
702 catch potential problems early, safety triggers.
703 </p>
704 </li>
705 </ul></div>
709 40-character hexadecimal blob object name, followed by a dollar
715 filter driver specified in the configuration.</p></div>
716 <div class="paragraph"><p>A filter driver consists of a <tt>clean</tt> command and a <tt>smudge</tt>
717 command, either of which can be left unspecified. Upon
719 fed the blob object from its standard input, and its standard
720 output is used to update the worktree file. Similarly, the
722 upon checkin.</p></div>
724 but makes the filter a no-op passthru.</p></div>
726 shape that is more convenient for the platform, filesystem, and
727 the user to use. The key phrase here is "more convenient" and not
728 "turning something unusable into usable". In other words, the
729 intent is that if someone unsets the filter driver definition,
730 or does not have the appropriate filter program, the project
731 should still be usable.</p></div>
733 attribute for paths.</p></div>
737 </div></div>
738 <div class="paragraph"><p>Then you would define a "filter.indent.clean" and "filter.indent.smudge"
739 configuration in your .git/config to specify a pair of commands to
740 modify the contents of C programs when the source files are checked
741 in ("clean" is run) and checked out (no change is made because the
746 clean = indent
747 smudge = cat</tt></pre>
748 </div></div>
749 <div class="paragraph"><p>For best results, <tt>clean</tt> should not alter its output further if it is
753 section on merging below.</p></div>
754 <div class="paragraph"><p>The "indent" filter is well-behaved in this regard: it will not modify
755 input that is already correctly indented. In this case, the lack of a
757 without modifying it.</p></div>
759 the file the filter is working on. A filter might use this in keyword
760 substitution. For example:</p></div>
764 clean = git-p4-filter --clean %f
765 smudge = git-p4-filter --smudge %f</tt></pre>
766 </div></div>
767 <h4 id="_interaction_between_checkin_checkout_attributes">Interaction between checkin/checkout attributes</h4>
772 and applicable).</p></div>
775 <h4 id="_merging_branches_with_differing_checkin_checkout_attributes">Merging branches with differing checkin/checkout attributes</h4>
777 repository format for that file to change, such as adding a
778 clean/smudge filter or text/eol/ident attributes, merging anything
779 where the attribute is not in place would normally cause merge
780 conflicts.</p></div>
781 <div class="paragraph"><p>To prevent these unnecessary merge conflicts, git can be told to run a
782 virtual check-out and check-in of all three stages of a file when
784 configuration variable. This prevents changes caused by check-in
785 conversion from causing spurious merge conflicts when a converted file
786 is merged with an unconverted file.</p></div>
787 <div class="paragraph"><p>As long as a "smudge→clean" results in the same output as a "clean"
788 even on files that are already smudged, this strategy will
789 automatically resolve all filter-related conflicts. Filters that do
790 not act in this way may cause additional merge conflicts that must be
791 resolved manually.</p></div>
794 <div class="paragraph"><p>The attribute <tt>diff</tt> affects how <em>git</em> generates diffs for particular
795 files. It can tell git whether to generate a textual patch for the path
796 or to treat the path as a binary file. It can also affect what line is
798 external command to generate the diff, or ask git to convert binary
799 files to a text format before generating the diff.</p></div>
802 Set
803 </dt>
804 <dd>
805 <p>
807 as text, even when they contain byte values that
808 normally never appear in text files, such as NUL.
809 </p>
810 </dd>
812 Unset
813 </dt>
814 <dd>
815 <p>
818 binary patches are enabled).
819 </p>
820 </dd>
822 Unspecified
823 </dt>
824 <dd>
825 <p>
827 first gets its contents inspected, and if it looks like
828 text, it is treated as text. Otherwise it would
830 </p>
831 </dd>
833 String
834 </dt>
835 <dd>
836 <p>
837 Diff is shown using the specified diff driver. Each driver may
838 specify one or more options, as described in the following
839 section. The options for the diff driver "foo" are defined
840 by the configuration variables in the "diff.foo" section of the
841 git config file.
842 </p>
843 </dd>
844 </dl></div>
849 <div class="paragraph"><p>To define an external diff driver <tt>jcdiff</tt>, add a section to your
854 command = j-c-diff</tt></pre>
855 </div></div>
863 is prefixed with a line of the form:</p></div>
867 </div></div>
868 <div class="paragraph"><p>This is called a <em>hunk header</em>. The "TEXT" portion is by default a line
869 that begins with an alphabet, an underscore or a dollar sign; this
871 is not suited for some contents, and you can use a customized pattern
872 to make a selection.</p></div>
873 <div class="paragraph"><p>First, in .gitattributes, you would assign the <tt>diff</tt> attribute
874 for paths.</p></div>
878 </div></div>
880 specify a regular expression that matches a line that you would
881 want to appear as the hunk header "TEXT". Add a section to your
887 </div></div>
889 configuration file parser, so you would need to double the
890 backslashes; the pattern above picks a line that begins with a
893 <div class="paragraph"><p>There are a few built-in patterns to make this easier, and <tt>tex</tt>
894 is one of them, so you do not have to write the above in your
895 configuration file (you still need to enable this with the
897 patterns are available:</p></div>
899 <li>
900 <p>
902 </p>
903 </li>
904 <li>
905 <p>
907 </p>
908 </li>
909 <li>
910 <p>
912 </p>
913 </li>
914 <li>
915 <p>
917 </p>
918 </li>
919 <li>
920 <p>
922 </p>
923 </li>
924 <li>
925 <p>
927 </p>
928 </li>
929 <li>
930 <p>
932 </p>
933 </li>
934 <li>
935 <p>
937 </p>
938 </li>
939 <li>
940 <p>
942 </p>
943 </li>
944 <li>
945 <p>
947 </p>
948 </li>
949 <li>
950 <p>
952 </p>
953 </li>
954 <li>
955 <p>
957 </p>
958 </li>
959 <li>
960 <p>
962 </p>
963 </li>
964 </ul></div>
966 <div class="paragraph"><p>You can customize the rules that <tt>git diff --word-diff</tt> uses to
967 split words in a line, by specifying an appropriate regular expression
968 in the "diff.*.wordRegex" configuration variable. For example, in TeX
969 a backslash followed by a sequence of letters forms a command, but
970 several such commands can be run together without intervening
971 whitespace. To separate them, use a regular expression in your
977 </div></div>
979 previous section.</p></div>
982 version of some binary files. For example, a word processor
983 document can be converted to an ASCII text representation, and
984 the diff of the text shown. Even though this conversion loses
985 some information, the resulting diff is useful for human
986 viewing (but cannot be applied directly).</p></div>
988 performing such a conversion. The program should take a single
989 argument, the name of a file to convert, and produce the
990 resulting text on stdout.</p></div>
992 file instead of the binary information (assuming you have the
993 exif tool installed), add the following section to your
998 textconv = exif</tt></pre>
999 </div></div>
1001 <table><tr>
1004 </td>
1006 in this example, we lose the actual image contents and focus
1007 just on the text data. This means that diffs generated by
1010 log, whatchanged, show) will perform text conversion. <tt>git
1011 format-patch</tt> will never generate this output. If you want to
1012 send somebody a text-converted diff of a binary file (e.g.,
1013 because it quickly conveys the changes you have made), you
1014 should generate it separately and send it as a comment <em>in
1016 </tr></table>
1017 </div>
1020 to cache the output and use it in future diffs. To enable
1022 config. For example:</p></div>
1026 textconv = exif
1027 cachetextconv = true</tt></pre>
1028 </div></div>
1030 indefinitely. If you change the textconv config variable for a
1031 diff driver, git will automatically invalidate the cache entries
1032 and re-run the textconv filter. If you want to invalidate the
1033 cache manually (e.g., because your version of "exif" was updated
1034 and now produces better output), you can remove the cache
1039 data by examining the beginning of the contents. However, sometimes you
1040 may want to override its decision, either because a blob contains binary
1041 data later in the file, or because the content, while technically
1042 composed of text characters, is opaque to a human reader. For example,
1043 many postscript files contain only ascii characters, but produce noisy
1044 and meaningless diffs.</p></div>
1050 </div></div>
1051 <div class="paragraph"><p>This will cause git to generate <tt>Binary files differ</tt> (or a binary
1052 patch, if binary patches are enabled) instead of a regular diff.</p></div>
1053 <div class="paragraph"><p>However, one may also want to specify other diff driver attributes. For
1055 an ascii representation for human viewing, but otherwise treat them as
1061 textconv = ps2ascii
1062 binary = true</tt></pre>
1063 </div></div>
1064 <h3 id="_performing_a_three_way_merge">Performing a three-way merge</h3><div style="clear:left"></div>
1066 <div class="paragraph"><p>The attribute <tt>merge</tt> affects how three versions of a file are
1071 Set
1072 </dt>
1073 <dd>
1074 <p>
1075 Built-in 3-way merge driver is used to merge the
1077 suite. This is suitable for ordinary text files.
1078 </p>
1079 </dd>
1081 Unset
1082 </dt>
1083 <dd>
1084 <p>
1085 Take the version from the current branch as the
1086 tentative merge result, and declare that the merge has
1087 conflicts. This is suitable for binary files that do
1088 not have a well-defined merge semantics.
1089 </p>
1090 </dd>
1092 Unspecified
1093 </dt>
1094 <dd>
1095 <p>
1096 By default, this uses the same built-in 3-way merge
1099 different merge driver to be used with paths for which the
1101 </p>
1102 </dd>
1104 String
1105 </dt>
1106 <dd>
1107 <p>
1108 3-way merge is performed using the specified custom
1109 merge driver. The built-in 3-way merge driver can be
1110 explicitly specified by asking for "text" driver; the
1111 built-in "take the current branch" driver can be
1112 requested with "binary".
1113 </p>
1114 </dd>
1115 </dl></div>
1121 text
1122 </dt>
1123 <dd>
1124 <p>
1125 Usual 3-way file level merge for text files. Conflicted
1130 marker.
1131 </p>
1132 </dd>
1134 binary
1135 </dt>
1136 <dd>
1137 <p>
1138 Keep the version from your branch in the work tree, but
1139 leave the path in the conflicted state for the user to
1140 sort out.
1141 </p>
1142 </dd>
1144 union
1145 </dt>
1146 <dd>
1147 <p>
1148 Run 3-way file level merge for text files, but take
1149 lines from both versions, instead of leaving conflict
1150 markers. This tends to leave the added lines in the
1151 resulting file in random order and the user should
1152 verify the result. Do not use this if you do not
1153 understand the implications.
1154 </p>
1155 </dd>
1156 </dl></div>
1161 <div class="paragraph"><p>To define a custom merge driver <tt>filfre</tt>, add a section to your
1166 name = feel-free merge driver
1167 driver = filfre %O %A %B
1168 recursive = binary</tt></pre>
1169 </div></div>
1171 name.</p></div>
1172 <div class="paragraph"><p>The ‘merge.*.driver` variable’s value is used to construct a
1175 three tokens are replaced with the names of temporary files that
1176 hold the contents of these versions when the command line is
1177 built. Additionally, %L will be replaced with the conflict marker
1178 size (see below).</p></div>
1181 status if it managed to merge them cleanly, or non-zero if there
1182 were conflicts.</p></div>
1184 driver to use when the merge driver is called for an internal
1185 merge between common ancestors, when there are more than one.
1186 When left unspecified, the driver itself is used for both
1187 internal merge and the final merge.</p></div>
1190 the work tree file during a conflicted merge. Only setting to
1191 the value to a positive integer has any meaningful effect.</p></div>
1192 <div class="paragraph"><p>For example, this line in <tt>.gitattributes</tt> can be used to tell the merge
1193 machinery to leave much longer (instead of the usual 7-character-long)
1195 results in a conflict.</p></div>
1199 </div></div>
1200 <h3 id="_checking_whitespace_errors">Checking whitespace errors</h3><div style="clear:left"></div>
1202 <div class="paragraph"><p>The <tt>core.whitespace</tt> configuration variable allows you to define what
1205 control per path.</p></div>
1208 Set
1209 </dt>
1210 <dd>
1211 <p>
1212 Notice all types of potential whitespace errors known to git.
1214 configuration variable.
1215 </p>
1216 </dd>
1218 Unset
1219 </dt>
1220 <dd>
1221 <p>
1222 Do not notice anything as error.
1223 </p>
1224 </dd>
1226 Unspecified
1227 </dt>
1228 <dd>
1229 <p>
1231 decide what to notice as error.
1232 </p>
1233 </dd>
1235 String
1236 </dt>
1237 <dd>
1238 <p>
1239 Specify a comma separate list of common whitespace problems to
1241 variable.
1242 </p>
1243 </dd>
1244 </dl></div>
1247 <div class="paragraph"><p>Files and directories with the attribute <tt>export-ignore</tt> won’t be added to
1248 archive files.</p></div>
1250 <div class="paragraph"><p>If the attribute <tt>export-subst</tt> is set for a file then git will expand
1251 several placeholders when adding this file to an archive. The
1252 expansion depends on the availability of a commit ID, i.e., if
1254 tag then no replacement will be done. The placeholders are the same
1258 commit hash.</p></div>
1263 <h3 id="_viewing_files_in_gui_tools">Viewing files in GUI tools</h3><div style="clear:left"></div>
1265 <div class="paragraph"><p>The value of this attribute specifies the character encoding that should
1266 be used by GUI tools (e.g. <a href="gitk.html">gitk(1)</a> and <a href="git-gui.html">git-gui(1)</a>) to
1267 display the contents of the relevant file. Note that due to performance
1269 manually enable per-file encodings in its options.</p></div>
1270 <div class="paragraph"><p>If this attribute is not set or has an invalid value, the value of the
1273 </div>
1276 <div class="paragraph"><p>You do not want any end-of-line conversions applied to, nor textual diffs
1277 produced for, any binary file you track. You would need to specify e.g.</p></div>
1281 </div></div>
1283 attribute macros, you can specify groups of attributes set or unset at
1288 </div></div>
1289 <div class="paragraph"><p>which is equivalent to the above. Note that the attribute macros can only
1292 </div>
1295 <div class="paragraph"><p>Custom attribute macros can be defined only in the <tt>.gitattributes</tt> file
1296 at the toplevel (i.e. not in any subdirectory). The built-in attribute
1301 </div></div>
1302 </div>
1308 <pre><tt>(in $GIT_DIR/info/attributes)
1310 a* foo !bar -baz
1312 (in .gitattributes)
1313 abc foo bar baz
1315 (in t/.gitattributes)
1316 ab* merge=filfre
1317 abc -foo -bar
1318 *.c frotz</tt></pre>
1319 </div></div>
1320 <div class="paragraph"><p>the attributes given to path <tt>t/abc</tt> are computed as follows:</p></div>
1322 <li>
1323 <p>
1325 directory as the path in question), git finds that the first
1328 are unset.
1329 </p>
1330 </li>
1331 <li>
1332 <p>
1334 directory), and finds that the first line matches, but
1338 </p>
1339 </li>
1340 <li>
1341 <p>
1343 is used to override the in-tree settings. The first line is
1346 </p>
1347 </li>
1348 </ol></div>
1349 <div class="paragraph"><p>As the result, the attributes assignment to <tt>t/abc</tt> becomes:</p></div>
1352 <pre><tt>foo set to true
1353 bar unspecified
1354 baz set to false
1355 merge set to string value "filfre"
1356 frotz unspecified</tt></pre>
1357 </div></div>
1358 </div>
1362 </div>
1366 </div>
1367 </div>
1368 </body>
1369 </html>