Blame - gitattributes.html - external/gitster/git-htmldocs

blob: fca248c5f9200f6d30671a94c2f44eb2fa8fbe4f [file] [log] [blame]

Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
				2	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
				3	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
				4	<head>
				5	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	6	<meta name="generator" content="AsciiDoc 8.4.5" />
				7	<title>gitattributes(5)</title>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	8	<style type="text/css">
				9	/* Debug borders */
				10	p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
				11	/*
				12	border: 1px solid red;
				13	*/
				14	}
				15
				16	body {
				17	margin: 1em 5% 1em 5%;
				18	}
				19
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	20	a {
				21	color: blue;
				22	text-decoration: underline;
				23	}
				24	a:visited {
				25	color: fuchsia;
				26	}
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	27
				28	em {
				29	font-style: italic;
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	30	color: navy;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	31	}
				32
				33	strong {
				34	font-weight: bold;
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	35	color: #083194;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	36	}
				37
				38	tt {
				39	color: navy;
				40	}
				41
				42	h1, h2, h3, h4, h5, h6 {
				43	color: #527bbd;
				44	font-family: sans-serif;
				45	margin-top: 1.2em;
				46	margin-bottom: 0.5em;
				47	line-height: 1.3;
				48	}
				49
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	50	h1, h2, h3 {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	51	border-bottom: 2px solid silver;
				52	}
				53	h2 {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	54	padding-top: 0.5em;
				55	}
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	56	h3 {
				57	float: left;
				58	}
				59	h3 + * {
				60	clear: left;
				61	}
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	62
				63	div.sectionbody {
				64	font-family: serif;
				65	margin-left: 0;
				66	}
				67
				68	hr {
				69	border: 1px solid silver;
				70	}
				71
				72	p {
				73	margin-top: 0.5em;
				74	margin-bottom: 0.5em;
				75	}
				76
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	77	ul, ol, li > p {
				78	margin-top: 0;
				79	}
				80
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	81	pre {
				82	padding: 0;
				83	margin: 0;
				84	}
				85
				86	span#author {
				87	color: #527bbd;
				88	font-family: sans-serif;
				89	font-weight: bold;
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	90	font-size: 1.1em;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	91	}
				92	span#email {
				93	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	94	span#revnumber, span#revdate, span#revremark {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	95	font-family: sans-serif;
				96	}
				97
				98	div#footer {
				99	font-family: sans-serif;
				100	font-size: small;
				101	border-top: 2px solid silver;
				102	padding-top: 0.5em;
				103	margin-top: 4.0em;
				104	}
				105	div#footer-text {
				106	float: left;
				107	padding-bottom: 0.5em;
				108	}
				109	div#footer-badges {
				110	float: right;
				111	padding-bottom: 0.5em;
				112	}
				113
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	114	div#preamble {
				115	margin-top: 1.5em;
				116	margin-bottom: 1.5em;
				117	}
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	118	div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
				119	div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
				120	div.admonitionblock {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	121	margin-top: 1.5em;
				122	margin-bottom: 1.5em;
				123	}
				124	div.admonitionblock {
				125	margin-top: 2.5em;
				126	margin-bottom: 2.5em;
				127	}
				128
				129	div.content { /* Block element content. */
				130	padding: 0;
				131	}
				132
				133	/* Block element titles. */
				134	div.title, caption.title {
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	135	color: #527bbd;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	136	font-family: sans-serif;
				137	font-weight: bold;
				138	text-align: left;
				139	margin-top: 1.0em;
				140	margin-bottom: 0.5em;
				141	}
				142	div.title + * {
				143	margin-top: 0;
				144	}
				145
				146	td div.title:first-child {
				147	margin-top: 0.0em;
				148	}
				149	div.content div.title:first-child {
				150	margin-top: 0.0em;
				151	}
				152	div.content + div.title {
				153	margin-top: 0.0em;
				154	}
				155
				156	div.sidebarblock > div.content {
				157	background: #ffffee;
				158	border: 1px solid silver;
				159	padding: 0.5em;
				160	}
				161
				162	div.listingblock > div.content {
				163	border: 1px solid silver;
				164	background: #f4f4f4;
				165	padding: 0.5em;
				166	}
				167
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	168	div.quoteblock {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	169	padding-left: 2.0em;
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	170	margin-right: 10%;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	171	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	172	div.quoteblock > div.attribution {
				173	padding-top: 0.5em;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	174	text-align: right;
				175	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	176
				177	div.verseblock {
				178	padding-left: 2.0em;
				179	margin-right: 10%;
				180	}
				181	div.verseblock > div.content {
				182	white-space: pre;
				183	}
				184	div.verseblock > div.attribution {
				185	padding-top: 0.75em;
				186	text-align: left;
				187	}
				188	/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	189	div.verseblock + div.attribution {
				190	text-align: left;
				191	}
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	192
				193	div.admonitionblock .icon {
				194	vertical-align: top;
				195	font-size: 1.1em;
				196	font-weight: bold;
				197	text-decoration: underline;
				198	color: #527bbd;
				199	padding-right: 0.5em;
				200	}
				201	div.admonitionblock td.content {
				202	padding-left: 0.5em;
				203	border-left: 2px solid silver;
				204	}
				205
				206	div.exampleblock > div.content {
				207	border-left: 2px solid silver;
				208	padding: 0.5em;
				209	}
				210
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	211	div.imageblock div.content { padding-left: 0; }
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	212	span.image img { border-style: none; }
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	213	a.image:visited { color: white; }
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	214
				215	dl {
				216	margin-top: 0.8em;
				217	margin-bottom: 0.8em;
				218	}
				219	dt {
				220	margin-top: 0.5em;
				221	margin-bottom: 0;
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	222	font-style: normal;
				223	color: navy;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	224	}
				225	dd > *:first-child {
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	226	margin-top: 0.1em;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	227	}
				228
				229	ul, ol {
				230	list-style-position: outside;
				231	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	232	ol.arabic {
				233	list-style-type: decimal;
				234	}
				235	ol.loweralpha {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	236	list-style-type: lower-alpha;
				237	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	238	ol.upperalpha {
				239	list-style-type: upper-alpha;
				240	}
				241	ol.lowerroman {
				242	list-style-type: lower-roman;
				243	}
				244	ol.upperroman {
				245	list-style-type: upper-roman;
				246	}
				247
				248	div.compact ul, div.compact ol,
				249	div.compact p, div.compact p,
				250	div.compact div, div.compact div {
				251	margin-top: 0.1em;
				252	margin-bottom: 0.1em;
				253	}
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	254
				255	div.tableblock > table {
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	256	border: 3px solid #527bbd;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	257	}
				258	thead {
				259	font-family: sans-serif;
				260	font-weight: bold;
				261	}
				262	tfoot {
				263	font-weight: bold;
				264	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	265	td > div.verse {
				266	white-space: pre;
				267	}
				268	p.table {
				269	margin-top: 0;
				270	}
				271	/* Because the table frame attribute is overriden by CSS in most browsers. */
				272	div.tableblock > table[frame="void"] {
				273	border-style: none;
				274	}
				275	div.tableblock > table[frame="hsides"] {
				276	border-left-style: none;
				277	border-right-style: none;
				278	}
				279	div.tableblock > table[frame="vsides"] {
				280	border-top-style: none;
				281	border-bottom-style: none;
				282	}
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	283
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	284
				285	div.hdlist {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	286	margin-top: 0.8em;
				287	margin-bottom: 0.8em;
				288	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	289	div.hdlist tr {
				290	padding-bottom: 15px;
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	291	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	292	dt.hdlist1.strong, td.hdlist1.strong {
				293	font-weight: bold;
				294	}
				295	td.hdlist1 {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	296	vertical-align: top;
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	297	font-style: normal;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	298	padding-right: 0.8em;
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	299	color: navy;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	300	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	301	td.hdlist2 {
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	302	vertical-align: top;
				303	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	304	div.hdlist.compact tr {
				305	margin: 0;
				306	padding-bottom: 0;
				307	}
				308
				309	.comment {
				310	background: yellow;
				311	}
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	312
				313	@media print {
				314	div#footer-badges { display: none; }
				315	}
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	316
				317	div#toctitle {
				318	color: #527bbd;
				319	font-family: sans-serif;
				320	font-size: 1.1em;
				321	font-weight: bold;
				322	margin-top: 1.0em;
				323	margin-bottom: 0.1em;
				324	}
				325
				326	div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
				327	margin-top: 0;
				328	margin-bottom: 0;
				329	}
				330	div.toclevel2 {
				331	margin-left: 2em;
				332	font-size: 0.9em;
				333	}
				334	div.toclevel3 {
				335	margin-left: 4em;
				336	font-size: 0.9em;
				337	}
				338	div.toclevel4 {
				339	margin-left: 6em;
				340	font-size: 0.9em;
				341	}
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	342	/* Overrides for manpage documents */
				343	h1 {
				344	padding-top: 0.5em;
				345	padding-bottom: 0.5em;
				346	border-top: 2px solid silver;
				347	border-bottom: 2px solid silver;
				348	}
				349	h2 {
				350	border-style: none;
				351	}
				352	div.sectionbody {
				353	margin-left: 5%;
				354	}
				355
				356	@media print {
				357	div#toc { display: none; }
				358	}
				359
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	360	/* Workarounds for IE6's broken and incomplete CSS2. */
				361
				362	div.sidebar-content {
				363	background: #ffffee;
				364	border: 1px solid silver;
				365	padding: 0.5em;
				366	}
				367	div.sidebar-title, div.image-title {
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	368	color: #527bbd;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	369	font-family: sans-serif;
				370	font-weight: bold;
				371	margin-top: 0.0em;
				372	margin-bottom: 0.5em;
				373	}
				374
				375	div.listingblock div.content {
				376	border: 1px solid silver;
				377	background: #f4f4f4;
				378	padding: 0.5em;
				379	}
				380
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	381	div.quoteblock-attribution {
				382	padding-top: 0.5em;
				383	text-align: right;
				384	}
				385
				386	div.verseblock-content {
				387	white-space: pre;
				388	}
				389	div.verseblock-attribution {
				390	padding-top: 0.75em;
				391	text-align: left;
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	392	}
				393
				394	div.exampleblock-content {
				395	border-left: 2px solid silver;
				396	padding-left: 0.5em;
				397	}
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	398
				399	/* IE6 sets dynamically generated links as visited. */
				400	div#toc a:visited { color: blue; }
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	401	</style>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	402	</head>
				403	<body>
				404	<div id="header">
				405	<h1>
				406	gitattributes(5) Manual Page
				407	</h1>
				408	<h2>NAME</h2>
				409	<div class="sectionbody">
				410	<p>gitattributes -
				411	defining attributes per path
				412	</p>
				413	</div>
				414	</div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	415	<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	416	<div class="sectionbody">
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	417	<div class="paragraph"><p>$GIT_DIR/info/attributes, .gitattributes</p></div>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	418	</div>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	419	<h2 id="_description">DESCRIPTION</h2>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	420	<div class="sectionbody">
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	421	<div class="paragraph"><p>A <tt>gitattributes</tt> file is a simple text file that gives
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	422	<tt>attributes</tt> to pathnames.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	423	<div class="paragraph"><p>Each line in <tt>gitattributes</tt> file is of form:</p></div>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	424	<div class="literalblock">
				425	<div class="content">
Junio C Hamano	d533bdb	2009-02-25 09:56:58	[diff] [blame]	426	<pre><tt>pattern attr1 attr2 ...</tt></pre>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	427	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	428	<div class="paragraph"><p>That is, a pattern followed by an attributes list,
Junio C Hamano	d533bdb	2009-02-25 09:56:58	[diff] [blame]	429	separated by whitespaces. When the pattern matches the
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	430	path in question, the attributes listed on the line are given to
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	431	the path.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	432	<div class="paragraph"><p>Each attribute can be in one of these states for a given path:</p></div>
				433	<div class="dlist"><dl>
				434	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	444	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	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
				451	prefixed with a dash <tt>-</tt> in the attribute list.
				452	</p>
				453	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	454	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	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
				461	followed by an equal sign <tt>=</tt> and its value in the
				462	attribute list.
				463	</p>
				464	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	465	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	466	Unspecified
				467	</dt>
				468	<dd>
				469	<p>
Junio C Hamano	d533bdb	2009-02-25 09:56:58	[diff] [blame]	470	No pattern matches the path, and nothing says if
Junio C Hamano	22572e7	2007-04-25 05:59:25	[diff] [blame]	471	the path has or does not have the attribute, the
				472	attribute for the path is said to be Unspecified.
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	473	</p>
				474	</dd>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	475	</dl></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	476	<div class="paragraph"><p>When more than one pattern matches the path, a later line
Junio C Hamano	22572e7	2007-04-25 05:59:25	[diff] [blame]	477	overrides an earlier line. This overriding is done per
Junio C Hamano	d533bdb	2009-02-25 09:56:58	[diff] [blame]	478	attribute. The rules how the pattern matches paths are the
				479	same as in <tt>.gitignore</tt> files; see <a href="gitignore.html">gitignore(5)</a>.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	480	<div class="paragraph"><p>When deciding what attributes are assigned to a path, git
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	481	consults <tt>$GIT_DIR/info/attributes</tt> file (which has the highest
				482	precedence), <tt>.gitattributes</tt> file in the same directory as the
Junio C Hamano	b4a9ede	2009-04-08 07:36:32	[diff] [blame]	483	path in question, and its parent directories up to the toplevel of the
				484	work tree (the further the directory that contains <tt>.gitattributes</tt>
Junio C Hamano	3b4609d	2010-09-30 00:04:34	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	488	<div class="paragraph"><p>If you wish to affect only a single repository (i.e., to assign
Junio C Hamano	3b4609d	2010-09-30 00:04:34	[diff] [blame]	489	attributes to files that are particular to
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	490	one user’s workflow for that repository), then
Junio C Hamano	99dc24a	2008-03-27 23:49:50	[diff] [blame]	491	attributes should be placed in the <tt>$GIT_DIR/info/attributes</tt> file.
				492	Attributes which should be version-controlled and distributed to other
				493	repositories (i.e., attributes of interest to all users) should go into
Junio C Hamano	3b4609d	2010-09-30 00:04:34	[diff] [blame]	494	<tt>.gitattributes</tt> files. Attributes that should affect all repositories
				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
				498	<tt>$(prefix)/etc/gitattributes</tt> file.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	499	<div class="paragraph"><p>Sometimes you would need to override an setting of an attribute
Junio C Hamano	86d8436	2011-08-04 00:21:51	[diff] [blame^]	500	for a path to <tt>Unspecified</tt> state. This can be done by listing
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	501	the name of the attribute prefixed with an exclamation point <tt>!</tt>.</p></div>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	502	</div>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	503	<h2 id="_effects">EFFECTS</h2>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	504	<div class="sectionbody">
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	505	<div class="paragraph"><p>Certain operations by git can be influenced by assigning
Junio C Hamano	2a8f6dc	2007-07-09 08:48:38	[diff] [blame]	506	particular attributes to a path. Currently, the following
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	509	<div class="paragraph"><p>These attributes affect how the contents stored in the
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	510	repository are copied to the working tree files when commands
Junio C Hamano	1aa40d2	2010-01-21 17:46:43	[diff] [blame]	511	such as <em>git checkout</em> and <em>git merge</em> run. They also affect how
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	512	git stores the contents you prepare in the working tree in the
Junio C Hamano	1aa40d2	2010-01-21 17:46:43	[diff] [blame]	513	repository upon <em>git add</em> and <em>git commit</em>.</p></div>
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	514	<h4 id="_tt_text_tt"><tt>text</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	515	<div class="paragraph"><p>This attribute enables and controls end-of-line normalization. When a
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	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
				518	directory, use the <tt>eol</tt> attribute for a single file and the
				519	<tt>core.eol</tt> configuration variable for all text files.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	520	<div class="dlist"><dl>
				521	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	522	Set
				523	</dt>
				524	<dd>
				525	<p>
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	526	Setting the <tt>text</tt> attribute on a path enables end-of-line
				527	normalization and marks the path as a text file. End-of-line
				528	conversion takes place without guessing the content type.
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	529	</p>
				530	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	531	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	532	Unset
				533	</dt>
				534	<dd>
				535	<p>
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	536	Unsetting the <tt>text</tt> attribute on a path tells git not to
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	537	attempt any end-of-line conversion upon checkin or checkout.
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	538	</p>
				539	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	540	<dt class="hdlist1">
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	541	Set to string value "auto"
				542	</dt>
				543	<dd>
				544	<p>
				545	When <tt>text</tt> is set to "auto", the path is marked for automatic
				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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	550	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	551	Unspecified
				552	</dt>
				553	<dd>
				554	<p>
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	555	If the <tt>text</tt> attribute is unspecified, git uses the
				556	<tt>core.autocrlf</tt> configuration variable to determine if the
				557	file should be converted.
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	558	</p>
				559	</dd>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	560	</dl></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	561	<div class="paragraph"><p>Any other value causes git to act as if <tt>text</tt> has been left
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	562	unspecified.</p></div>
				563	<h4 id="_tt_eol_tt"><tt>eol</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	564	<div class="paragraph"><p>This attribute sets a specific line-ending style to be used in the
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	565	working directory. It enables end-of-line normalization without any
				566	content checks, effectively setting the <tt>text</tt> attribute.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	567	<div class="dlist"><dl>
				568	<dt class="hdlist1">
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	578	<dt class="hdlist1">
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	590	<div class="paragraph"><p>For backwards compatibility, the <tt>crlf</tt> attribute is interpreted as
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	591	follows:</p></div>
				592	<div class="listingblock">
				593	<div class="content">
				594	<pre><tt>crlf text
				595	-crlf -text
				596	crlf=input eol=lf</tt></pre>
				597	</div></div>
				598	<h4 id="_end_of_line_conversion">End-of-line conversion</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	599	<div class="paragraph"><p>While git normally leaves file contents alone, it can be configured to
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	600	normalize line endings to LF in the repository and, optionally, to
				601	convert them to CRLF when files are checked out.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	602	<div class="paragraph"><p>Here is an example that will make git normalize .txt, .vcproj and .sh
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	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>
				606	<div class="listingblock">
				607	<div class="content">
				608	<pre><tt>*.txt text
				609	*.vcproj eol=crlf
				610	*.sh eol=lf
				611	*.jpg -text</tt></pre>
				612	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	613	<div class="paragraph"><p>Other source code management systems normalize all text files in their
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	614	repositories, and there are two ways to enable similar automatic
				615	normalization in git.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	616	<div class="paragraph"><p>If you simply want to have CRLF line endings in your working directory
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	617	regardless of the repository you are working with, you can set the
				618	config variable "core.autocrlf" without changing any attributes.</p></div>
				619	<div class="listingblock">
				620	<div class="content">
				621	<pre><tt>[core]
				622	autocrlf = true</tt></pre>
				623	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	624	<div class="paragraph"><p>This does not force normalization of all text files, but does ensure
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	628	<div class="paragraph"><p>If you want to interoperate with a source code management system that
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	629	enforces end-of-line normalization, or you simply want all text files
				630	in your repository to be normalized, you should instead set the <tt>text</tt>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	631	attribute to "auto" for <em>all</em> files.</p></div>
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	632	<div class="listingblock">
				633	<div class="content">
				634	<pre><tt>* text=auto</tt></pre>
				635	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	636	<div class="paragraph"><p>This ensures that all files that git considers to be text will have
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	637	normalized (LF) line endings in the repository. The <tt>core.eol</tt>
				638	configuration variable controls which line endings git will use for
				639	normalized files in your working directory; the default is to use the
				640	native line ending for your platform, or CRLF if <tt>core.autocrlf</tt> is
				641	set.</p></div>
				642	<div class="admonitionblock">
				643	<table><tr>
				644	<td class="icon">
				645	<div class="title">Note</div>
				646	</td>
				647	<td class="content">When <tt>text=auto</tt> normalization is enabled in an existing
				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>
				654	<div class="listingblock">
				655	<div class="content">
				656	<pre><tt>$ echo "* text=auto" >>.gitattributes
				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
				662	$ git commit -m "Introduce end-of-line normalization"</tt></pre>
				663	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	664	<div class="paragraph"><p>If any files that should not be normalized show up in <em>git status</em>,
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	665	unset their <tt>text</tt> attribute before running <em>git add -u</em>.</p></div>
				666	<div class="listingblock">
				667	<div class="content">
				668	<pre><tt>manual.pdf -text</tt></pre>
				669	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	670	<div class="paragraph"><p>Conversely, text files that git does not detect can have normalization
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	671	enabled manually.</p></div>
				672	<div class="listingblock">
				673	<div class="content">
				674	<pre><tt>weirdchars.txt text</tt></pre>
				675	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	676	<div class="paragraph"><p>If <tt>core.safecrlf</tt> is set to "true" or "warn", git verifies if
Junio C Hamano	26e590a	2008-02-17 03:53:51	[diff] [blame]	677	the conversion is reversible for the current setting of
				678	<tt>core.autocrlf</tt>. For "true", git rejects irreversible
				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
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	682	few exceptions. Even though…</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	683	<div class="ulist"><ul>
Junio C Hamano	26e590a	2008-02-17 03:53:51	[diff] [blame]	684	<li>
				685	<p>
Junio C Hamano	1aa40d2	2010-01-21 17:46:43	[diff] [blame]	686	<em>git add</em> itself does not touch the files in the work tree, the
Junio C Hamano	26e590a	2008-02-17 03:53:51	[diff] [blame]	687	next checkout would, so the safety triggers;
				688	</p>
				689	</li>
				690	<li>
				691	<p>
Junio C Hamano	1aa40d2	2010-01-21 17:46:43	[diff] [blame]	692	<em>git apply</em> to update a text file with a patch does touch the files
Junio C Hamano	26e590a	2008-02-17 03:53:51	[diff] [blame]	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>
Junio C Hamano	1aa40d2	2010-01-21 17:46:43	[diff] [blame]	700	<em>git diff</em> itself does not touch the files in the work tree, it is
				701	often run to inspect the changes you intend to next <em>git add</em>. To
Junio C Hamano	26e590a	2008-02-17 03:53:51	[diff] [blame]	702	catch potential problems early, safety triggers.
				703	</p>
				704	</li>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	705	</ul></div>
				706	<h4 id="_tt_ident_tt"><tt>ident</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	707	<div class="paragraph"><p>When the attribute <tt>ident</tt> is set for a path, git replaces
Junio C Hamano	6f1bbb7	2008-10-31 11:32:55	[diff] [blame]	708	<tt>$Id$</tt> in the blob object with <tt>$Id:</tt>, followed by the
Junio C Hamano	469d60e	2007-04-29 18:30:34	[diff] [blame]	709	40-character hexadecimal blob object name, followed by a dollar
				710	sign <tt>$</tt> upon checkout. Any byte sequence that begins with
Junio C Hamano	0430e3a	2007-05-15 03:13:17	[diff] [blame]	711	<tt>$Id:</tt> and ends with <tt>$</tt> in the worktree file is replaced
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	712	with <tt>$Id$</tt> upon check-in.</p></div>
				713	<h4 id="_tt_filter_tt"><tt>filter</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	714	<div class="paragraph"><p>A <tt>filter</tt> attribute can be set to a string value that names a
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	715	filter driver specified in the configuration.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	716	<div class="paragraph"><p>A filter driver consists of a <tt>clean</tt> command and a <tt>smudge</tt>
Junio C Hamano	469d60e	2007-04-29 18:30:34	[diff] [blame]	717	command, either of which can be left unspecified. Upon
Junio C Hamano	361c133	2007-11-14 12:17:22	[diff] [blame]	718	checkout, when the <tt>smudge</tt> command is specified, the command is
				719	fed the blob object from its standard input, and its standard
				720	output is used to update the worktree file. Similarly, the
				721	<tt>clean</tt> command is used to convert the contents of worktree file
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	722	upon checkin.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	723	<div class="paragraph"><p>A missing filter driver definition in the config is not an error
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	724	but makes the filter a no-op passthru.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	725	<div class="paragraph"><p>The content filtering is done to massage the content into a
Junio C Hamano	469d60e	2007-04-29 18:30:34	[diff] [blame]	726	shape that is more convenient for the platform, filesystem, and
Junio C Hamano	361c133	2007-11-14 12:17:22	[diff] [blame]	727	the user to use. The key phrase here is "more convenient" and not
Junio C Hamano	4fd58d4	2007-09-30 00:51:14	[diff] [blame]	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
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	731	should still be usable.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	732	<div class="paragraph"><p>For example, in .gitattributes, you would assign the <tt>filter</tt>
Junio C Hamano	6a548ef	2009-12-17 00:16:20	[diff] [blame]	733	attribute for paths.</p></div>
				734	<div class="listingblock">
				735	<div class="content">
				736	<pre><tt>*.c filter=indent</tt></pre>
				737	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	738	<div class="paragraph"><p>Then you would define a "filter.indent.clean" and "filter.indent.smudge"
Junio C Hamano	6a548ef	2009-12-17 00:16:20	[diff] [blame]	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
				742	command is "cat").</p></div>
				743	<div class="listingblock">
				744	<div class="content">
				745	<pre><tt>[filter "indent"]
				746	clean = indent
				747	smudge = cat</tt></pre>
				748	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	749	<div class="paragraph"><p>For best results, <tt>clean</tt> should not alter its output further if it is
				750	run twice ("clean→clean" should be equivalent to "clean"), and
Junio C Hamano	2db3e75	2010-09-03 21:33:06	[diff] [blame]	751	multiple <tt>smudge</tt> commands should not alter <tt>clean</tt>'s output
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	752	("smudge→smudge→clean" should be equivalent to "clean"). See the
Junio C Hamano	2db3e75	2010-09-03 21:33:06	[diff] [blame]	753	section on merging below.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	754	<div class="paragraph"><p>The "indent" filter is well-behaved in this regard: it will not modify
Junio C Hamano	2db3e75	2010-09-03 21:33:06	[diff] [blame]	755	input that is already correctly indented. In this case, the lack of a
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	756	smudge filter means that the clean filter <em>must</em> accept its own output
Junio C Hamano	2db3e75	2010-09-03 21:33:06	[diff] [blame]	757	without modifying it.</p></div>
Junio C Hamano	e0552e4	2011-01-06 00:34:47	[diff] [blame]	758	<div class="paragraph"><p>Sequence "%f" on the filter command line is replaced with the name of
				759	the file the filter is working on. A filter might use this in keyword
				760	substitution. For example:</p></div>
				761	<div class="listingblock">
				762	<div class="content">
				763	<pre><tt>[filter "p4"]
				764	clean = git-p4-filter --clean %f
				765	smudge = git-p4-filter --smudge %f</tt></pre>
				766	</div></div>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	767	<h4 id="_interaction_between_checkin_checkout_attributes">Interaction between checkin/checkout attributes</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	768	<div class="paragraph"><p>In the check-in codepath, the worktree file is first converted
Junio C Hamano	469d60e	2007-04-29 18:30:34	[diff] [blame]	769	with <tt>filter</tt> driver (if specified and corresponding driver
				770	defined), then the result is processed with <tt>ident</tt> (if
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	771	specified), and then finally with <tt>text</tt> (again, if specified
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	772	and applicable).</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	773	<div class="paragraph"><p>In the check-out codepath, the blob content is first converted
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	774	with <tt>text</tt>, and then <tt>ident</tt> and fed to <tt>filter</tt>.</p></div>
Junio C Hamano	2db3e75	2010-09-03 21:33:06	[diff] [blame]	775	<h4 id="_merging_branches_with_differing_checkin_checkout_attributes">Merging branches with differing checkin/checkout attributes</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	776	<div class="paragraph"><p>If you have added attributes to a file that cause the canonical
Junio C Hamano	2db3e75	2010-09-03 21:33:06	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	781	<div class="paragraph"><p>To prevent these unnecessary merge conflicts, git can be told to run a
Junio C Hamano	2db3e75	2010-09-03 21:33:06	[diff] [blame]	782	virtual check-out and check-in of all three stages of a file when
				783	resolving a three-way merge by setting the <tt>merge.renormalize</tt>
				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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	787	<div class="paragraph"><p>As long as a "smudge→clean" results in the same output as a "clean"
Junio C Hamano	2db3e75	2010-09-03 21:33:06	[diff] [blame]	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>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	792	<h3 id="_generating_diff_text">Generating diff text</h3><div style="clear:left"></div>
Junio C Hamano	f7e47ee	2008-11-02 18:16:45	[diff] [blame]	793	<h4 id="_tt_diff_tt"><tt>diff</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	794	<div class="paragraph"><p>The attribute <tt>diff</tt> affects how <em>git</em> generates diffs for particular
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	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
				797	shown on the hunk header <tt>@@ -k,l +n,m @@</tt> line, tell git to use an
				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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	800	<div class="dlist"><dl>
				801	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	802	Set
				803	</dt>
				804	<dd>
				805	<p>
				806	A path to which the <tt>diff</tt> attribute is set is treated
				807	as text, even when they contain byte values that
				808	normally never appear in text files, such as NUL.
				809	</p>
				810	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	811	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	812	Unset
				813	</dt>
				814	<dd>
				815	<p>
				816	A path to which the <tt>diff</tt> attribute is unset will
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	817	generate <tt>Binary files differ</tt> (or a binary patch, if
				818	binary patches are enabled).
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	819	</p>
				820	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	821	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	822	Unspecified
				823	</dt>
				824	<dd>
				825	<p>
				826	A path to which the <tt>diff</tt> attribute is unspecified
				827	first gets its contents inspected, and if it looks like
				828	text, it is treated as text. Otherwise it would
				829	generate <tt>Binary files differ</tt>.
				830	</p>
				831	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	832	<dt class="hdlist1">
Junio C Hamano	9db95ca	2007-04-23 07:27:05	[diff] [blame]	833	String
				834	</dt>
				835	<dd>
				836	<p>
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	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.
Junio C Hamano	9db95ca	2007-04-23 07:27:05	[diff] [blame]	842	</p>
				843	</dd>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	844	</dl></div>
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	845	<h4 id="_defining_an_external_diff_driver">Defining an external diff driver</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	846	<div class="paragraph"><p>The definition of a diff driver is done in <tt>gitconfig</tt>, not
Junio C Hamano	9db95ca	2007-04-23 07:27:05	[diff] [blame]	847	<tt>gitattributes</tt> file, so strictly speaking this manual page is a
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	848	wrong place to talk about it. However…</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	849	<div class="paragraph"><p>To define an external diff driver <tt>jcdiff</tt>, add a section to your
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	850	<tt>$GIT_DIR/config</tt> file (or <tt>$HOME/.gitconfig</tt> file) like this:</p></div>
Junio C Hamano	9db95ca	2007-04-23 07:27:05	[diff] [blame]	851	<div class="listingblock">
				852	<div class="content">
				853	<pre><tt>[diff "jcdiff"]
				854	command = j-c-diff</tt></pre>
				855	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	856	<div class="paragraph"><p>When git needs to show you a diff for the path with <tt>diff</tt>
Junio C Hamano	9db95ca	2007-04-23 07:27:05	[diff] [blame]	857	attribute set to <tt>jcdiff</tt>, it calls the command you specified
				858	with the above configuration, i.e. <tt>j-c-diff</tt>, with 7
				859	parameters, just like <tt>GIT_EXTERNAL_DIFF</tt> program is called.
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	860	See <a href="git.html">git(1)</a> for details.</p></div>
				861	<h4 id="_defining_a_custom_hunk_header">Defining a custom hunk-header</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	862	<div class="paragraph"><p>Each group of changes (called a "hunk") in the textual diff output
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	863	is prefixed with a line of the form:</p></div>
Junio C Hamano	2a8f6dc	2007-07-09 08:48:38	[diff] [blame]	864	<div class="literalblock">
				865	<div class="content">
				866	<pre><tt>@@ -k,l +n,m @@ TEXT</tt></pre>
				867	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	868	<div class="paragraph"><p>This is called a <em>hunk header</em>. The "TEXT" portion is by default a line
Junio C Hamano	5e4d8de	2008-09-19 06:27:02	[diff] [blame]	869	that begins with an alphabet, an underscore or a dollar sign; this
				870	matches what GNU <em>diff -p</em> output uses. This default selection however
				871	is not suited for some contents, and you can use a customized pattern
				872	to make a selection.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	873	<div class="paragraph"><p>First, in .gitattributes, you would assign the <tt>diff</tt> attribute
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	874	for paths.</p></div>
Junio C Hamano	2a8f6dc	2007-07-09 08:48:38	[diff] [blame]	875	<div class="listingblock">
				876	<div class="content">
				877	<pre><tt>*.tex diff=tex</tt></pre>
				878	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	879	<div class="paragraph"><p>Then, you would define a "diff.tex.xfuncname" configuration to
Junio C Hamano	2a8f6dc	2007-07-09 08:48:38	[diff] [blame]	880	specify a regular expression that matches a line that you would
Junio C Hamano	3bd66e9	2009-04-18 06:17:56	[diff] [blame]	881	want to appear as the hunk header "TEXT". Add a section to your
				882	<tt>$GIT_DIR/config</tt> file (or <tt>$HOME/.gitconfig</tt> file) like this:</p></div>
Junio C Hamano	2a8f6dc	2007-07-09 08:48:38	[diff] [blame]	883	<div class="listingblock">
				884	<div class="content">
				885	<pre><tt>[diff "tex"]
Junio C Hamano	a476efa	2008-10-10 15:31:42	[diff] [blame]	886	xfuncname = "^(\\\\(sub)section\\{.)$"</tt></pre>
Junio C Hamano	2a8f6dc	2007-07-09 08:48:38	[diff] [blame]	887	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	888	<div class="paragraph"><p>Note. A single level of backslashes are eaten by the
Junio C Hamano	2a8f6dc	2007-07-09 08:48:38	[diff] [blame]	889	configuration file parser, so you would need to double the
				890	backslashes; the pattern above picks a line that begins with a
Junio C Hamano	a638742	2007-08-25 03:54:27	[diff] [blame]	891	backslash, and zero or more occurrences of <tt>sub</tt> followed by
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	892	<tt>section</tt> followed by open brace, to the end of line.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	893	<div class="paragraph"><p>There are a few built-in patterns to make this easier, and <tt>tex</tt>
Junio C Hamano	2a8f6dc	2007-07-09 08:48:38	[diff] [blame]	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
Junio C Hamano	a76cb0d	2008-08-13 20:04:10	[diff] [blame]	896	attribute mechanism, via <tt>.gitattributes</tt>). The following built in
				897	patterns are available:</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	898	<div class="ulist"><ul>
Junio C Hamano	a76cb0d	2008-08-13 20:04:10	[diff] [blame]	899	<li>
				900	<p>
				901	<tt>bibtex</tt> suitable for files with BibTeX coded references.
				902	</p>
				903	</li>
				904	<li>
				905	<p>
Junio C Hamano	20d47e3	2009-01-26 06:36:02	[diff] [blame]	906	<tt>cpp</tt> suitable for source code in the C and C++ languages.
				907	</p>
				908	</li>
				909	<li>
				910	<p>
Junio C Hamano	53ba6d0	2010-08-22 07:25:12	[diff] [blame]	911	<tt>csharp</tt> suitable for source code in the C# language.
				912	</p>
				913	</li>
				914	<li>
				915	<p>
Junio C Hamano	3b4609d	2010-09-30 00:04:34	[diff] [blame]	916	<tt>fortran</tt> suitable for source code in the Fortran language.
				917	</p>
				918	</li>
				919	<li>
				920	<p>
Junio C Hamano	f24b806	2008-09-09 01:34:39	[diff] [blame]	921	<tt>html</tt> suitable for HTML/XHTML documents.
				922	</p>
				923	</li>
				924	<li>
				925	<p>
Junio C Hamano	675570c	2008-09-13 06:07:28	[diff] [blame]	926	<tt>java</tt> suitable for source code in the Java language.
Junio C Hamano	a76cb0d	2008-08-13 20:04:10	[diff] [blame]	927	</p>
				928	</li>
				929	<li>
				930	<p>
Junio C Hamano	a476efa	2008-10-10 15:31:42	[diff] [blame]	931	<tt>objc</tt> suitable for source code in the Objective-C language.
				932	</p>
				933	</li>
				934	<li>
				935	<p>
Junio C Hamano	a76cb0d	2008-08-13 20:04:10	[diff] [blame]	936	<tt>pascal</tt> suitable for source code in the Pascal/Delphi language.
				937	</p>
				938	</li>
				939	<li>
				940	<p>
Junio C Hamano	9b6fafe	2011-01-14 00:43:22	[diff] [blame]	941	<tt>perl</tt> suitable for source code in the Perl language.
				942	</p>
				943	</li>
				944	<li>
				945	<p>
Junio C Hamano	f24b806	2008-09-09 01:34:39	[diff] [blame]	946	<tt>php</tt> suitable for source code in the PHP language.
				947	</p>
				948	</li>
				949	<li>
				950	<p>
Junio C Hamano	3f2f6e5	2008-08-21 10:34:22	[diff] [blame]	951	<tt>python</tt> suitable for source code in the Python language.
				952	</p>
				953	</li>
				954	<li>
				955	<p>
Junio C Hamano	a76cb0d	2008-08-13 20:04:10	[diff] [blame]	956	<tt>ruby</tt> suitable for source code in the Ruby language.
				957	</p>
				958	</li>
				959	<li>
				960	<p>
				961	<tt>tex</tt> suitable for source code for LaTeX documents.
				962	</p>
				963	</li>
				964	</ul></div>
Junio C Hamano	20d47e3	2009-01-26 06:36:02	[diff] [blame]	965	<h4 id="_customizing_word_diff">Customizing word diff</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	966	<div class="paragraph"><p>You can customize the rules that <tt>git diff --word-diff</tt> uses to
Junio C Hamano	20d47e3	2009-01-26 06:36:02	[diff] [blame]	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
Junio C Hamano	3bd66e9	2009-04-18 06:17:56	[diff] [blame]	971	whitespace. To separate them, use a regular expression in your
				972	<tt>$GIT_DIR/config</tt> file (or <tt>$HOME/.gitconfig</tt> file) like this:</p></div>
Junio C Hamano	20d47e3	2009-01-26 06:36:02	[diff] [blame]	973	<div class="listingblock">
				974	<div class="content">
				975	<pre><tt>[diff "tex"]
				976	wordRegex = "\\\\[a-zA-Z]+\|[{}]\|\\\\.\|[^\\{}[:space:]]+"</tt></pre>
				977	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	978	<div class="paragraph"><p>A built-in pattern is provided for all languages listed in the
Junio C Hamano	20d47e3	2009-01-26 06:36:02	[diff] [blame]	979	previous section.</p></div>
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	980	<h4 id="_performing_text_diffs_of_binary_files">Performing text diffs of binary files</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	981	<div class="paragraph"><p>Sometimes it is desirable to see the diff of a text-converted
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	987	<div class="paragraph"><p>The <tt>textconv</tt> config option is used to define a program for
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	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>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	991	<div class="paragraph"><p>For example, to show the diff of the exif information of a
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	992	file instead of the binary information (assuming you have the
Junio C Hamano	3bd66e9	2009-04-18 06:17:56	[diff] [blame]	993	exif tool installed), add the following section to your
				994	<tt>$GIT_DIR/config</tt> file (or <tt>$HOME/.gitconfig</tt> file):</p></div>
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	995	<div class="listingblock">
				996	<div class="content">
				997	<pre><tt>[diff "jpg"]
				998	textconv = exif</tt></pre>
				999	</div></div>
				1000	<div class="admonitionblock">
				1001	<table><tr>
				1002	<td class="icon">
				1003	<div class="title">Note</div>
				1004	</td>
				1005	<td class="content">The text conversion is generally a one-way conversion;
				1006	in this example, we lose the actual image contents and focus
				1007	just on the text data. This means that diffs generated by
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1008	textconv are <em>not</em> suitable for applying. For this reason,
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	1009	only <tt>git diff</tt> and the <tt>git log</tt> family of commands (i.e.,
				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
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1014	should generate it separately and send it as a comment <em>in
				1015	addition to</em> the usual binary diff that you might send.</td>
Junio C Hamano	2836349	2008-11-14 08:26:31	[diff] [blame]	1016	</tr></table>
				1017	</div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1018	<div class="paragraph"><p>Because text conversion can be slow, especially when doing a
Junio C Hamano	cb39aea	2010-05-09 07:24:48	[diff] [blame]	1019	large number of them with <tt>git log -p</tt>, git provides a mechanism
				1020	to cache the output and use it in future diffs. To enable
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1021	caching, set the "cachetextconv" variable in your diff driver’s
Junio C Hamano	cb39aea	2010-05-09 07:24:48	[diff] [blame]	1022	config. For example:</p></div>
				1023	<div class="listingblock">
				1024	<div class="content">
				1025	<pre><tt>[diff "jpg"]
				1026	textconv = exif
				1027	cachetextconv = true</tt></pre>
				1028	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1029	<div class="paragraph"><p>This will cache the result of running "exif" on each blob
Junio C Hamano	cb39aea	2010-05-09 07:24:48	[diff] [blame]	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
				1035	manually with <tt>git update-ref -d refs/notes/textconv/jpg</tt> (where
				1036	"jpg" is the name of the diff driver, as in the example above).</p></div>
Junio C Hamano	f93530e	2011-05-25 23:59:59	[diff] [blame]	1037	<h4 id="_choosing_textconv_versus_external_diff">Choosing textconv versus external diff</h4>
				1038	<div class="paragraph"><p>If you want to show differences between binary or specially-formatted
				1039	blobs in your repository, you can choose to use either an external diff
				1040	command, or to use textconv to convert them to a diff-able text format.
				1041	Which method you choose depends on your exact situation.</p></div>
				1042	<div class="paragraph"><p>The advantage of using an external diff command is flexibility. You are
				1043	not bound to find line-oriented changes, nor is it necessary for the
				1044	output to resemble unified diff. You are free to locate and report
				1045	changes in the most appropriate way for your data format.</p></div>
				1046	<div class="paragraph"><p>A textconv, by comparison, is much more limiting. You provide a
				1047	transformation of the data into a line-oriented text format, and git
				1048	uses its regular diff tools to generate the output. There are several
				1049	advantages to choosing this method:</p></div>
				1050	<div class="olist arabic"><ol class="arabic">
				1051	<li>
				1052	<p>
				1053	Ease of use. It is often much simpler to write a binary to text
				1054	transformation than it is to perform your own diff. In many cases,
				1055	existing programs can be used as textconv filters (e.g., exif,
				1056	odt2txt).
				1057	</p>
				1058	</li>
				1059	<li>
				1060	<p>
				1061	Git diff features. By performing only the transformation step
				1062	yourself, you can still utilize many of git’s diff features,
				1063	including colorization, word-diff, and combined diffs for merges.
				1064	</p>
				1065	</li>
				1066	<li>
				1067	<p>
				1068	Caching. Textconv caching can speed up repeated diffs, such as those
				1069	you might trigger by running <tt>git log -p</tt>.
				1070	</p>
				1071	</li>
				1072	</ol></div>
Junio C Hamano	9b6fafe	2011-01-14 00:43:22	[diff] [blame]	1073	<h4 id="_marking_files_as_binary">Marking files as binary</h4>
				1074	<div class="paragraph"><p>Git usually guesses correctly whether a blob contains text or binary
				1075	data by examining the beginning of the contents. However, sometimes you
				1076	may want to override its decision, either because a blob contains binary
				1077	data later in the file, or because the content, while technically
				1078	composed of text characters, is opaque to a human reader. For example,
				1079	many postscript files contain only ascii characters, but produce noisy
				1080	and meaningless diffs.</p></div>
				1081	<div class="paragraph"><p>The simplest way to mark a file as binary is to unset the diff
				1082	attribute in the <tt>.gitattributes</tt> file:</p></div>
				1083	<div class="listingblock">
				1084	<div class="content">
				1085	<pre><tt>*.ps -diff</tt></pre>
				1086	</div></div>
				1087	<div class="paragraph"><p>This will cause git to generate <tt>Binary files differ</tt> (or a binary
				1088	patch, if binary patches are enabled) instead of a regular diff.</p></div>
				1089	<div class="paragraph"><p>However, one may also want to specify other diff driver attributes. For
				1090	example, you might want to use <tt>textconv</tt> to convert postscript files to
				1091	an ascii representation for human viewing, but otherwise treat them as
				1092	binary files. You cannot specify both <tt>-diff</tt> and <tt>diff=ps</tt> attributes.
				1093	The solution is to use the <tt>diff.*.binary</tt> config option:</p></div>
				1094	<div class="listingblock">
				1095	<div class="content">
				1096	<pre><tt>[diff "ps"]
				1097	textconv = ps2ascii
				1098	binary = true</tt></pre>
				1099	</div></div>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1100	<h3 id="_performing_a_three_way_merge">Performing a three-way merge</h3><div style="clear:left"></div>
Junio C Hamano	f7e47ee	2008-11-02 18:16:45	[diff] [blame]	1101	<h4 id="_tt_merge_tt"><tt>merge</tt></h4>
Junio C Hamano	fa28cb1	2011-03-19 01:35:35	[diff] [blame]	1102	<div class="paragraph"><p>The attribute <tt>merge</tt> affects how three versions of a file are
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1103	merged when a file-level merge is necessary during <tt>git merge</tt>,
Junio C Hamano	27a128b	2009-08-13 01:23:00	[diff] [blame]	1104	and other commands such as <tt>git revert</tt> and <tt>git cherry-pick</tt>.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1105	<div class="dlist"><dl>
				1106	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1107	Set
				1108	</dt>
				1109	<dd>
				1110	<p>
				1111	Built-in 3-way merge driver is used to merge the
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1112	contents in a way similar to <em>merge</em> command of <tt>RCS</tt>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1113	suite. This is suitable for ordinary text files.
				1114	</p>
				1115	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1116	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1117	Unset
				1118	</dt>
				1119	<dd>
				1120	<p>
				1121	Take the version from the current branch as the
				1122	tentative merge result, and declare that the merge has
Junio C Hamano	fa28cb1	2011-03-19 01:35:35	[diff] [blame]	1123	conflicts. This is suitable for binary files that do
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1124	not have a well-defined merge semantics.
				1125	</p>
				1126	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1127	<dt class="hdlist1">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1128	Unspecified
				1129	</dt>
				1130	<dd>
				1131	<p>
				1132	By default, this uses the same built-in 3-way merge
Junio C Hamano	fa28cb1	2011-03-19 01:35:35	[diff] [blame]	1133	driver as is the case when the <tt>merge</tt> attribute is set.
				1134	However, the <tt>merge.default</tt> configuration variable can name
				1135	different merge driver to be used with paths for which the
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1136	<tt>merge</tt> attribute is unspecified.
				1137	</p>
				1138	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1139	<dt class="hdlist1">
Junio C Hamano	9db95ca	2007-04-23 07:27:05	[diff] [blame]	1140	String
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1141	</dt>
				1142	<dd>
				1143	<p>
				1144	3-way merge is performed using the specified custom
				1145	merge driver. The built-in 3-way merge driver can be
				1146	explicitly specified by asking for "text" driver; the
				1147	built-in "take the current branch" driver can be
Junio C Hamano	22572e7	2007-04-25 05:59:25	[diff] [blame]	1148	requested with "binary".
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1149	</p>
				1150	</dd>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1151	</dl></div>
				1152	<h4 id="_built_in_merge_drivers">Built-in merge drivers</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1153	<div class="paragraph"><p>There are a few built-in low-level merge drivers defined that
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1154	can be asked for via the <tt>merge</tt> attribute.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1155	<div class="dlist"><dl>
				1156	<dt class="hdlist1">
Junio C Hamano	f556fc2	2007-12-23 08:16:38	[diff] [blame]	1157	text
				1158	</dt>
				1159	<dd>
				1160	<p>
				1161	Usual 3-way file level merge for text files. Conflicted
				1162	regions are marked with conflict markers <tt><<<<<<<</tt>,
				1163	<tt>=======</tt> and <tt>>>>>>>></tt>. The version from your branch
				1164	appears before the <tt>=======</tt> marker, and the version
				1165	from the merged branch appears after the <tt>=======</tt>
				1166	marker.
				1167	</p>
				1168	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1169	<dt class="hdlist1">
Junio C Hamano	f556fc2	2007-12-23 08:16:38	[diff] [blame]	1170	binary
				1171	</dt>
				1172	<dd>
				1173	<p>
				1174	Keep the version from your branch in the work tree, but
				1175	leave the path in the conflicted state for the user to
				1176	sort out.
				1177	</p>
				1178	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1179	<dt class="hdlist1">
Junio C Hamano	f556fc2	2007-12-23 08:16:38	[diff] [blame]	1180	union
				1181	</dt>
				1182	<dd>
				1183	<p>
				1184	Run 3-way file level merge for text files, but take
				1185	lines from both versions, instead of leaving conflict
				1186	markers. This tends to leave the added lines in the
				1187	resulting file in random order and the user should
				1188	verify the result. Do not use this if you do not
				1189	understand the implications.
				1190	</p>
				1191	</dd>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1192	</dl></div>
				1193	<h4 id="_defining_a_custom_merge_driver">Defining a custom merge driver</h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1194	<div class="paragraph"><p>The definition of a merge driver is done in the <tt>.git/config</tt>
Junio C Hamano	f556fc2	2007-12-23 08:16:38	[diff] [blame]	1195	file, not in the <tt>gitattributes</tt> file, so strictly speaking this
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1196	manual page is a wrong place to talk about it. However…</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1197	<div class="paragraph"><p>To define a custom merge driver <tt>filfre</tt>, add a section to your
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1198	<tt>$GIT_DIR/config</tt> file (or <tt>$HOME/.gitconfig</tt> file) like this:</p></div>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1199	<div class="listingblock">
				1200	<div class="content">
				1201	<pre><tt>[merge "filfre"]
				1202	name = feel-free merge driver
				1203	driver = filfre %O %A %B
				1204	recursive = binary</tt></pre>
				1205	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1206	<div class="paragraph"><p>The <tt>merge.*.name</tt> variable gives the driver a human-readable
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1207	name.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1208	<div class="paragraph"><p>The ‘merge.*.driver` variable’s value is used to construct a
				1209	command to run to merge ancestor’s version (<tt>%O</tt>), current
				1210	version (<tt>%A</tt>) and the other branches’ version (<tt>%B</tt>). These
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1211	three tokens are replaced with the names of temporary files that
				1212	hold the contents of these versions when the command line is
Junio C Hamano	86660db	2010-02-24 01:12:54	[diff] [blame]	1213	built. Additionally, %L will be replaced with the conflict marker
				1214	size (see below).</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1215	<div class="paragraph"><p>The merge driver is expected to leave the result of the merge in
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1216	the file named with <tt>%A</tt> by overwriting it, and exit with zero
				1217	status if it managed to merge them cleanly, or non-zero if there
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1218	were conflicts.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1219	<div class="paragraph"><p>The <tt>merge.*.recursive</tt> variable specifies what other merge
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1220	driver to use when the merge driver is called for an internal
				1221	merge between common ancestors, when there are more than one.
				1222	When left unspecified, the driver itself is used for both
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1223	internal merge and the final merge.</p></div>
Junio C Hamano	1aa40d2	2010-01-21 17:46:43	[diff] [blame]	1224	<h4 id="_tt_conflict_marker_size_tt"><tt>conflict-marker-size</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1225	<div class="paragraph"><p>This attribute controls the length of conflict markers left in
Junio C Hamano	1aa40d2	2010-01-21 17:46:43	[diff] [blame]	1226	the work tree file during a conflicted merge. Only setting to
				1227	the value to a positive integer has any meaningful effect.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1228	<div class="paragraph"><p>For example, this line in <tt>.gitattributes</tt> can be used to tell the merge
Junio C Hamano	1aa40d2	2010-01-21 17:46:43	[diff] [blame]	1229	machinery to leave much longer (instead of the usual 7-character-long)
				1230	conflict markers when merging the file <tt>Documentation/git-merge.txt</tt>
				1231	results in a conflict.</p></div>
				1232	<div class="listingblock">
				1233	<div class="content">
				1234	<pre><tt>Documentation/git-merge.txt conflict-marker-size=32</tt></pre>
				1235	</div></div>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1236	<h3 id="_checking_whitespace_errors">Checking whitespace errors</h3><div style="clear:left"></div>
				1237	<h4 id="_tt_whitespace_tt"><tt>whitespace</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1238	<div class="paragraph"><p>The <tt>core.whitespace</tt> configuration variable allows you to define what
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1239	<em>diff</em> and <em>apply</em> should consider whitespace errors for all paths in
Junio C Hamano	942b35e	2007-12-09 10:19:33	[diff] [blame]	1240	the project (See <a href="git-config.html">git-config(1)</a>). This attribute gives you finer
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1241	control per path.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1242	<div class="dlist"><dl>
				1243	<dt class="hdlist1">
Junio C Hamano	942b35e	2007-12-09 10:19:33	[diff] [blame]	1244	Set
				1245	</dt>
				1246	<dd>
				1247	<p>
				1248	Notice all types of potential whitespace errors known to git.
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1249	The tab width is taken from the value of the <tt>core.whitespace</tt>
				1250	configuration variable.
Junio C Hamano	942b35e	2007-12-09 10:19:33	[diff] [blame]	1251	</p>
				1252	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1253	<dt class="hdlist1">
Junio C Hamano	942b35e	2007-12-09 10:19:33	[diff] [blame]	1254	Unset
				1255	</dt>
				1256	<dd>
				1257	<p>
				1258	Do not notice anything as error.
				1259	</p>
				1260	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1261	<dt class="hdlist1">
Junio C Hamano	942b35e	2007-12-09 10:19:33	[diff] [blame]	1262	Unspecified
				1263	</dt>
				1264	<dd>
				1265	<p>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1266	Use the value of the <tt>core.whitespace</tt> configuration variable to
Junio C Hamano	942b35e	2007-12-09 10:19:33	[diff] [blame]	1267	decide what to notice as error.
				1268	</p>
				1269	</dd>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1270	<dt class="hdlist1">
Junio C Hamano	942b35e	2007-12-09 10:19:33	[diff] [blame]	1271	String
				1272	</dt>
				1273	<dd>
				1274	<p>
				1275	Specify a comma separate list of common whitespace problems to
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1276	notice in the same format as the <tt>core.whitespace</tt> configuration
Junio C Hamano	942b35e	2007-12-09 10:19:33	[diff] [blame]	1277	variable.
				1278	</p>
				1279	</dd>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1280	</dl></div>
				1281	<h3 id="_creating_an_archive">Creating an archive</h3><div style="clear:left"></div>
				1282	<h4 id="_tt_export_ignore_tt"><tt>export-ignore</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1283	<div class="paragraph"><p>Files and directories with the attribute <tt>export-ignore</tt> won’t be added to
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1284	archive files.</p></div>
				1285	<h4 id="_tt_export_subst_tt"><tt>export-subst</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1286	<div class="paragraph"><p>If the attribute <tt>export-subst</tt> is set for a file then git will expand
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1287	several placeholders when adding this file to an archive. The
				1288	expansion depends on the availability of a commit ID, i.e., if
				1289	<a href="git-archive.html">git-archive(1)</a> has been given a tree instead of a commit or a
				1290	tag then no replacement will be done. The placeholders are the same
				1291	as those for the option <tt>--pretty=format:</tt> of <a href="git-log.html">git-log(1)</a>,
				1292	except that they need to be wrapped like this: <tt>$Format:PLACEHOLDERS$</tt>
				1293	in the file. E.g. the string <tt>$Format:%H$</tt> will be replaced by the
				1294	commit hash.</p></div>
Junio C Hamano	a10d8d2	2009-10-22 03:09:05	[diff] [blame]	1295	<h3 id="_packing_objects">Packing objects</h3><div style="clear:left"></div>
				1296	<h4 id="_tt_delta_tt"><tt>delta</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1297	<div class="paragraph"><p>Delta compression will not be attempted for blobs for paths with the
Junio C Hamano	a10d8d2	2009-10-22 03:09:05	[diff] [blame]	1298	attribute <tt>delta</tt> set to false.</p></div>
Junio C Hamano	d3452a0	2008-11-15 08:07:55	[diff] [blame]	1299	<h3 id="_viewing_files_in_gui_tools">Viewing files in GUI tools</h3><div style="clear:left"></div>
				1300	<h4 id="_tt_encoding_tt"><tt>encoding</tt></h4>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1301	<div class="paragraph"><p>The value of this attribute specifies the character encoding that should
Junio C Hamano	d3452a0	2008-11-15 08:07:55	[diff] [blame]	1302	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
				1303	display the contents of the relevant file. Note that due to performance
				1304	considerations <a href="gitk.html">gitk(1)</a> does not use this attribute unless you
				1305	manually enable per-file encodings in its options.</p></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1306	<div class="paragraph"><p>If this attribute is not set or has an invalid value, the value of the
Junio C Hamano	d3452a0	2008-11-15 08:07:55	[diff] [blame]	1307	<tt>gui.encoding</tt> configuration variable is used instead
				1308	(See <a href="git-config.html">git-config(1)</a>).</p></div>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1309	</div>
Junio C Hamano	86d8436	2011-08-04 00:21:51	[diff] [blame^]	1310	<h2 id="_using_macro_attributes">USING MACRO ATTRIBUTES</h2>
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	1311	<div class="sectionbody">
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1312	<div class="paragraph"><p>You do not want any end-of-line conversions applied to, nor textual diffs
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	1313	produced for, any binary file you track. You would need to specify e.g.</p></div>
				1314	<div class="listingblock">
				1315	<div class="content">
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	1316	<pre><tt>*.jpg -text -diff</tt></pre>
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	1317	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1318	<div class="paragraph"><p>but that may become cumbersome, when you have many attributes. Using
Junio C Hamano	86d8436	2011-08-04 00:21:51	[diff] [blame^]	1319	macro attributes, you can define an attribute that, when set, also
				1320	sets or unsets a number of other attributes at the same time. The
				1321	system knows a built-in macro attribute, <tt>binary</tt>:</p></div>
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	1322	<div class="listingblock">
				1323	<div class="content">
				1324	<pre><tt>*.jpg binary</tt></pre>
				1325	</div></div>
Junio C Hamano	86d8436	2011-08-04 00:21:51	[diff] [blame^]	1326	<div class="paragraph"><p>Setting the "binary" attribute also unsets the "text" and "diff"
				1327	attributes as above. Note that macro attributes can only be "Set",
				1328	though setting one might have the effect of setting or unsetting other
				1329	attributes or even returning other attributes to the "Unspecified"
				1330	state.</p></div>
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	1331	</div>
Junio C Hamano	86d8436	2011-08-04 00:21:51	[diff] [blame^]	1332	<h2 id="_defining_macro_attributes">DEFINING MACRO ATTRIBUTES</h2>
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	1333	<div class="sectionbody">
Junio C Hamano	86d8436	2011-08-04 00:21:51	[diff] [blame^]	1334	<div class="paragraph"><p>Custom macro attributes can be defined only in the <tt>.gitattributes</tt>
				1335	file at the toplevel (i.e. not in any subdirectory). The built-in
				1336	macro attribute "binary" is equivalent to:</p></div>
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	1337	<div class="listingblock">
				1338	<div class="content">
Junio C Hamano	bb88cf4	2010-06-21 15:23:55	[diff] [blame]	1339	<pre><tt>[attr]binary -diff -text</tt></pre>
Junio C Hamano	fcb740a	2008-08-31 06:32:05	[diff] [blame]	1340	</div></div>
				1341	</div>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1342	<h2 id="_example">EXAMPLE</h2>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1343	<div class="sectionbody">
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1344	<div class="paragraph"><p>If you have these three <tt>gitattributes</tt> file:</p></div>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1345	<div class="listingblock">
				1346	<div class="content">
				1347	<pre><tt>(in $GIT_DIR/info/attributes)
				1348
				1349	a* foo !bar -baz
				1350
				1351	(in .gitattributes)
				1352	abc foo bar baz
				1353
				1354	(in t/.gitattributes)
				1355	ab* merge=filfre
				1356	abc -foo -bar
				1357	*.c frotz</tt></pre>
				1358	</div></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1359	<div class="paragraph"><p>the attributes given to path <tt>t/abc</tt> are computed as follows:</p></div>
				1360	<div class="olist arabic"><ol class="arabic">
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1361	<li>
				1362	<p>
				1363	By examining <tt>t/.gitattributes</tt> (which is in the same
Junio C Hamano	a638742	2007-08-25 03:54:27	[diff] [blame]	1364	directory as the path in question), git finds that the first
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1365	line matches. <tt>merge</tt> attribute is set. It also finds that
				1366	the second line matches, and attributes <tt>foo</tt> and <tt>bar</tt>
				1367	are unset.
				1368	</p>
				1369	</li>
				1370	<li>
				1371	<p>
				1372	Then it examines <tt>.gitattributes</tt> (which is in the parent
				1373	directory), and finds that the first line matches, but
				1374	<tt>t/.gitattributes</tt> file already decided how <tt>merge</tt>, <tt>foo</tt>
				1375	and <tt>bar</tt> attributes should be given to this path, so it
				1376	leaves <tt>foo</tt> and <tt>bar</tt> unset. Attribute <tt>baz</tt> is set.
				1377	</p>
				1378	</li>
				1379	<li>
				1380	<p>
Junio C Hamano	bdeff82	2007-07-30 09:07:17	[diff] [blame]	1381	Finally it examines <tt>$GIT_DIR/info/attributes</tt>. This file
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1382	is used to override the in-tree settings. The first line is
				1383	a match, and <tt>foo</tt> is set, <tt>bar</tt> is reverted to unspecified
				1384	state, and <tt>baz</tt> is unset.
				1385	</p>
				1386	</li>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1387	</ol></div>
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1388	<div class="paragraph"><p>As the result, the attributes assignment to <tt>t/abc</tt> becomes:</p></div>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1389	<div class="listingblock">
				1390	<div class="content">
				1391	<pre><tt>foo set to true
				1392	bar unspecified
				1393	baz set to false
				1394	merge set to string value "filfre"
				1395	frotz unspecified</tt></pre>
				1396	</div></div>
				1397	</div>
Junio C Hamano	ba4b928	2008-07-06 05:20:31	[diff] [blame]	1398	<h2 id="_git">GIT</h2>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1399	<div class="sectionbody">
Junio C Hamano	eef01fe	2010-12-13 08:31:58	[diff] [blame]	1400	<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1401	</div>
				1402	<div id="footer">
				1403	<div id="footer-text">
Junio C Hamano	86d8436	2011-08-04 00:21:51	[diff] [blame^]	1404	Last updated 2011-08-04 00:21:28 UTC
Junio C Hamano	e90436a	2007-04-22 07:22:13	[diff] [blame]	1405	</div>
				1406	</div>
				1407	</body>
				1408	</html>