so that gitlink:git-pull[1] will appropriately merge from that
remote branch. Note that even if this option is not set,
this behavior can be chosen per-branch using the `--track`
- and `--no-track` options. This option defaults to false.
+ and `--no-track` options. This option can have values
+ 'false' (never touch the configuration), 'all' (do this
+ for all branches), or 'true' (do this only when
+ branching from a remote tracking branch), and defaults to 'true'.
branch.<name>.remote::
When in branch <name>, it tells `git fetch` which remote to fetch.
set up configuration so that git-pull will automatically\r
retrieve data from the remote branch. Set the\r
branch.autosetupmerge configuration variable to true if you\r
- want git-checkout and git-branch to always behave as if\r
- <em>--track</em> were given.\r
+ want git-checkout and git-branch to behave as if\r
+ <em>--track</em> were given when you branch from a remote\r
+ tracking branch.\r
</p>\r
</dd>\r
<dt>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 03-Jul-2007 07:03:39 UTC\r
+Last updated 09-Jul-2007 08:47:47 UTC\r
</div>\r
</div>\r
</body>\r
set up configuration so that git-pull will automatically
retrieve data from the remote branch. Set the
branch.autosetupmerge configuration variable to true if you
- want git-checkout and git-branch to always behave as if
- '--track' were given.
+ want git-checkout and git-branch to behave as if
+ '--track' were given when you branch from a remote
+ tracking branch.
--no-track::
When -b is given and a branch is created off a remote branch,
so that <a href="git-pull.html">git-pull(1)</a> will appropriately merge from that\r
remote branch. Note that even if this option is not set,\r
this behavior can be chosen per-branch using the <tt>--track</tt>\r
- and <tt>--no-track</tt> options. This option defaults to false.\r
+ and <tt>--no-track</tt> options. This option can have values\r
+ <em>false</em> (never touch the configuration), <em>all</em> (do this\r
+ for all branches), or <em>true</em> (do this only when\r
+ branching from a remote tracking branch), and defaults to <em>true</em>.\r
</p>\r
</dd>\r
<dt>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 07-Jul-2007 21:52:19 UTC\r
+Last updated 09-Jul-2007 08:47:48 UTC\r
</div>\r
</div>\r
</body>\r
<h2>EFFECTS</h2>\r
<div class="sectionbody">\r
<p>Certain operations by git can be influenced by assigning\r
-particular attributes to a path. Currently, three operations\r
-are attributes-aware.</p>\r
+particular attributes to a path. Currently, the following\r
+operations are attributes-aware.</p>\r
<h3>Checking-out and checking-in</h3>\r
<p>These attributes affect how the contents stored in the\r
repository are copied to the working tree files when commands\r
with <tt>crlf</tt>, and then <tt>ident</tt> and fed to <tt>filter</tt>.</p>\r
<h3>Generating diff text</h3>\r
<p>The attribute <tt>diff</tt> affects if <tt>git diff</tt> generates textual\r
-patch for the path or just says <tt>Binary files differ</tt>.</p>\r
+patch for the path or just says <tt>Binary files differ</tt>. It also\r
+can affect what line is shown on the hunk header <tt>@@ -k,l +n,m @@</tt>\r
+line.</p>\r
<dl>\r
<dt>\r
Set\r
Diff is shown using the specified custom diff driver.\r
The driver program is given its input using the same\r
calling convention as used for GIT_EXTERNAL_DIFF\r
- program.\r
+ program. This name is also used for custom hunk header\r
+ selection.\r
</p>\r
</dd>\r
</dl>\r
with the above configuration, i.e. <tt>j-c-diff</tt>, with 7\r
parameters, just like <tt>GIT_EXTERNAL_DIFF</tt> program is called.\r
See <a href="git.html">git(7)</a> for details.</p>\r
+<h4>Defining a custom hunk-header</h4>\r
+<p>Each group of changes (called "hunk") in the textual diff output\r
+is prefixed with a line of the form:</p>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>@@ -k,l +n,m @@ TEXT</tt></pre>\r
+</div></div>\r
+<p>The text is called <em>hunk header</em>, and by default a line that\r
+begins with an alphabet, an underscore or a dollar sign is used,\r
+which matches what GNU <tt>diff -p</tt> output uses. This default\r
+selection however is not suited for some contents, and you can\r
+use customized pattern to make a selection.</p>\r
+<p>First in .gitattributes, you would assign the <tt>diff</tt> attribute\r
+for paths.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>*.tex diff=tex</tt></pre>\r
+</div></div>\r
+<p>Then, you would define "diff.tex.funcname" configuration to\r
+specify a regular expression that matches a line that you would\r
+want to appear as the hunk header, like this:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[diff "tex"]\r
+ funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"</tt></pre>\r
+</div></div>\r
+<p>Note. A single level of backslashes are eaten by the\r
+configuration file parser, so you would need to double the\r
+backslashes; the pattern above picks a line that begins with a\r
+backslash, and zero or more occurences of <tt>sub</tt> followed by\r
+<tt>section</tt> followed by open brace, to the end of line.</p>\r
+<p>There are a few built-in patterns to make this easier, and <tt>tex</tt>\r
+is one of them, so you do not have to write the above in your\r
+configuration file (you still need to enable this with the\r
+attribute mechanism, via <tt>.gitattributes</tt>). Another built-in\r
+pattern is defined for <tt>java</tt> that defines a pattern suitable\r
+for program text in Java language.</p>\r
<h3>Performing a three-way merge</h3>\r
<p>The attribute <tt>merge</tt> affects how three versions of a file is\r
merged when a file-level merge is necessary during <tt>git merge</tt>,\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 16-Jun-2007 09:49:27 UTC\r
+Last updated 09-Jul-2007 08:47:49 UTC\r
</div>\r
</div>\r
</body>\r
-------
Certain operations by git can be influenced by assigning
-particular attributes to a path. Currently, three operations
-are attributes-aware.
+particular attributes to a path. Currently, the following
+operations are attributes-aware.
Checking-out and checking-in
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~
The attribute `diff` affects if `git diff` generates textual
-patch for the path or just says `Binary files differ`.
+patch for the path or just says `Binary files differ`. It also
+can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
+line.
Set::
Diff is shown using the specified custom diff driver.
The driver program is given its input using the same
calling convention as used for GIT_EXTERNAL_DIFF
- program.
+ program. This name is also used for custom hunk header
+ selection.
Defining a custom diff driver
See gitlink:git[7] for details.
+Defining a custom hunk-header
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each group of changes (called "hunk") in the textual diff output
+is prefixed with a line of the form:
+
+ @@ -k,l +n,m @@ TEXT
+
+The text is called 'hunk header', and by default a line that
+begins with an alphabet, an underscore or a dollar sign is used,
+which matches what GNU `diff -p` output uses. This default
+selection however is not suited for some contents, and you can
+use customized pattern to make a selection.
+
+First in .gitattributes, you would assign the `diff` attribute
+for paths.
+
+------------------------
+*.tex diff=tex
+------------------------
+
+Then, you would define "diff.tex.funcname" configuration to
+specify a regular expression that matches a line that you would
+want to appear as the hunk header, like this:
+
+------------------------
+[diff "tex"]
+ funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
+------------------------
+
+Note. A single level of backslashes are eaten by the
+configuration file parser, so you would need to double the
+backslashes; the pattern above picks a line that begins with a
+backslash, and zero or more occurences of `sub` followed by
+`section` followed by open brace, to the end of line.
+
+There are a few built-in patterns to make this easier, and `tex`
+is one of them, so you do not have to write the above in your
+configuration file (you still need to enable this with the
+attribute mechanism, via `.gitattributes`). Another built-in
+pattern is defined for `java` that defines a pattern suitable
+for program text in Java language.
+
+
Performing a three-way merge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<div class="content">\r
<pre><tt>$ git remote add bob /home/bob/myrepo</tt></pre>\r
</div></div>\r
-<p>With this, you can perform the first operation alone using the\r
+<p>With this, Alice can perform the first operation alone using the\r
"git fetch" command without merging them with her own branch,\r
using:</p>\r
<div class="listingblock">\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 06-Jul-2007 17:01:32 UTC\r
+Last updated 09-Jul-2007 08:47:51 UTC\r
</div>\r
</div>\r
</body>\r
$ git remote add bob /home/bob/myrepo
------------------------------------------------
-With this, you can perform the first operation alone using the
+With this, Alice can perform the first operation alone using the
"git fetch" command without merging them with her own branch,
using:
commits reachable from some head but not from any tag in the repository:</p><div class="literallayout"><p>$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )</p></div><p>(See <a href="git-rev-parse.html" target="_top">git-rev-parse(1)</a> for explanations of commit-selecting
syntax such as <code class="literal">—not</code>.)</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="making-a-release"></a>Creating a changelog and tarball for a software release</h3></div></div></div><p>The <a href="git-archive.html" target="_top">git-archive(1)</a> command can create a tar or zip archive from
any version of a project; for example:</p><div class="literallayout"><p>$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz</p></div><p>will use HEAD to produce a tar archive in which each filename is
-preceded by "pr
efix/".</p><p>If you're releasing a new version of a software project, you may want
+preceded by "pr
oject/".</p><p>If you're releasing a new version of a software project, you may want
to simultaneously make a changelog to include in the release
announcement.</p><p>Linus Torvalds, for example, makes new kernel releases by tagging them,
then running:</p><div class="literallayout"><p>$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7</p></div><p>where release-script is a shell script that looks like:</p><div class="literallayout"><p>#!/bin/sh<br>
dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085<br>
dangling tree b24c2473f1fd3d91352a624795be026d64c8841f<br>
...</p></div><p>Dangling objects are not a problem. At worst they may take up a little
-extra disk space. They can sometimes provide a last-resort method of
-recover
y lost work—see <a href="#dangling-objects" title="Dangling objects">the section called “Dangling objects”</a> for details. However, if
-you w
ant, you may remove them with <a href="git-prune.html" target="_top">git-prune(1)</a> or the —prune
+extra disk space. They can sometimes provide a last-resort method for
+recover
ing lost work—see <a href="#dangling-objects" title="Dangling objects">the section called “Dangling objects”</a> for details. However, if
+you w
ish, you can remove them with <a href="git-prune.html" target="_top">git-prune(1)</a> or the —prune
option to <a href="git-gc.html" target="_top">git-gc(1)</a>:</p><div class="literallayout"><p>$ git gc --prune</p></div><p>This may be time-consuming. Unlike most other git operations (including
git-gc when run without any options), it is not safe to prune while
other git operations are in progress in the same repository.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="recovering-lost-changes"></a>Recovering lost changes</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="reflogs"></a>Reflogs</h4></div></div></div><p>Say you modify a branch with <a href="git-reset.html" target="_top">git-reset(1)</a> —hard, and then
In the section "<a href="#getting-updates-with-git-pull" title="Getting updates with git pull">Getting updates with git pull</a>" we described this as a way to get updates from the "main"
repository, but it works just as well in the other direction.</p><p>If you and the maintainer both have accounts on the same machine, then
you can just pull changes from each other's repositories directly;
-commands that accepts repository URLs as arguments will also accept a
+commands that accept repository URLs as arguments will also accept a
local directory name:</p><div class="literallayout"><p>$ git clone /path/to/repository<br>
-$ git pull /path/to/other/repository</p></div><p>However, the more common way to do this is to maintain a separate public
+$ git pull /path/to/other/repository</p></div><p>or an ssh url:</p><div class="literallayout"><p>$ git clone ssh://yourhost/~you/repository</p></div><p>For projects with few developers, or for synchronizing a few private
+repositories, this may be all you need.</p><p>However, the more common way to do this is to maintain a separate public
repository (usually on a different host) for others to pull changes
from. This is usually more convenient, and allows you to cleanly
separate private work in progress from publicly visible work.</p><p>You will continue to do your day-to-day work in your personal
| |
| |
| they push V
-their public repo <------------------- their repo</pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="setting-up-a-public-repository"></a>Setting up a public repository</h3></div></div></div><p>Assume your personal repository is in the directory ~/proj. We
+their public repo <------------------- their repo</pre><
p>We explain how to do this in the following sections.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="setting-up-a-public-repository"></a>Setting up a public repository</h3></div></div></div><p>Assume your personal repository is in the directory ~/proj. We
first create a new clone of the repository and tell git-daemon that it
is meant to be public:</p><div class="literallayout"><p>$ git clone --bare ~/proj proj.git<br>
$ touch proj.git/git-daemon-export-ok</p></div><p>The resulting directory proj.git contains a "bare" git repository—it is
a <a href="#fast-forwards" title="Fast-forward merges">fast forward</a>. Normally this is a sign of
something wrong. However, if you are sure you know what you're
doing, you may force git-push to perform the update anyway by
-proceeding the branch name by a plus sign:</p><div class="literallayout"><p>$ git push ssh://yourserver.com/~you/proj.git +master</p></div><p>As with git-fetch, you may also set up configuration options to
+proceeding the branch name by a plus sign:</p><div class="literallayout"><p>$ git push ssh://yourserver.com/~you/proj.git +master</p></div><p>Note that the target of a "push" is normally a
+<a href="#def_bare_repository">bare</a> repository. You can also push to a
+repository that has a checked-out working tree, but the working tree
+will not be updated by the push. This may lead to unexpected results if
+the branch you push to is the currently checked-out branch!</p><p>As with git-fetch, you may also set up configuration options to
save typing; so, for example, after</p><div class="literallayout"><p>$ cat >>.git/config <<EOF<br>
[remote "public-repo"]<br>
url = ssh://yourserver.com/~you/proj.git<br>
-------------------------------------------------
will use HEAD to produce a tar archive in which each filename is
-preceded by "prefix/".
+preceded by "project/".
If you're releasing a new version of a software project, you may want
to simultaneously make a changelog to include in the release
-------------------------------------------------
Dangling objects are not a problem. At worst they may take up a little
-extra disk space. They can sometimes provide a last-resort method of
-recovery lost work--see <<dangling-objects>> for details. However, if
-you want, you may remove them with gitlink:git-prune[1] or the --prune
+extra disk space. They can sometimes provide a last-resort method for
+recovering lost work--see <<dangling-objects>> for details. However, if
+you wish, you can remove them with gitlink:git-prune[1] or the --prune
option to gitlink:git-gc[1]:
-------------------------------------------------
If you and the maintainer both have accounts on the same machine, then
you can just pull changes from each other's repositories directly;
-commands that accepts repository URLs as arguments will also accept a
+commands that accept repository URLs as arguments will also accept a
local directory name:
-------------------------------------------------
$ git pull /path/to/other/repository
-------------------------------------------------
+or an ssh url:
+
+-------------------------------------------------
+$ git clone ssh://yourhost/~you/repository
+-------------------------------------------------
+
+For projects with few developers, or for synchronizing a few private
+repositories, this may be all you need.
+
However, the more common way to do this is to maintain a separate public
repository (usually on a different host) for others to pull changes
from. This is usually more convenient, and allows you to cleanly
| they push V
their public repo <------------------- their repo
+We explain how to do this in the following sections.
+
[[setting-up-a-public-repository]]
Setting up a public repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ git push ssh://yourserver.com/~you/proj.git +master
-------------------------------------------------
+Note that the target of a "push" is normally a
+<<def_bare_repository,bare>> repository. You can also push to a
+repository that has a checked-out working tree, but the working tree
+will not be updated by the push. This may lead to unexpected results if
+the branch you push to is the currently checked-out branch!
+
As with git-fetch, you may also set up configuration options to
save typing; so, for example, after
projects / git.git / commitdiff