-GIT v1.5.1.5 Release Notes (draft)
+GIT v1.5.1.5 Release Notes
==========================
Fixes since v1.5.1.4
compilers on Sun.
- Many many documentation fixes and updates.
-
---
-exec >/var/tmp/1
-O=v1.5.1.4-48-gcecb98a
-echo O=`git describe refs/heads/maint`
-git shortlog --no-merges $O..refs/heads/maint
--- /dev/null
+GIT v1.5.1.6 Release Notes
+==========================
+
+Fixes since v1.5.1.4
+--------------------
+
+* Bugfixes
+
+ - git-send-email did not understand aliases file for mutt, which
+ allows leading whitespaces.
+
+ - git-format-patch emitted Content-Type and Content-Transfer-Encoding
+ headers for non ASCII contents, but failed to add MIME-Version.
+
+ - git-name-rev had a buffer overrun with a deep history.
+
+ - contributed script import-tars did not get the directory in
+ tar archives interpreted correctly.
+
+ - git-svn was reported to segfault for many people on list and
+ #git; hopefully this has been fixed.
+
+ - git-svn also had a bug to crash svnserve by sending a bad
+ sequence of requests.
+
+ - "git-svn clone" does not try to minimize the URL
+ (i.e. connect to higher level hierarchy) by default, as this
+ can prevent clone to fail if only part of the repository
+ (e.g. 'trunk') is open to public.
+
+ - "git checkout branch^0" did not detach the head when you are
+ already on 'branch'; backported the fix from the 'master'.
+
+ - "git-config section.var" did not correctly work when
+ existing configuration file had both [section] and [section "name"]
+ next to each other.
+
+ - "git clone ../other-directory" was fooled if the current
+ directory $PWD points at is a symbolic link.
+
+ - (build) tree_entry_extract() function was both static inline
+ and extern, which caused trouble compiling with Forte12
+ compilers on Sun.
+
+ - Many many documentation fixes and updates.
-GIT v1.5.2 Release Notes (draft)
+GIT v1.5.2 Release Notes
========================
Updates since v1.5.1
--------------------
-* Plumbing level subproject support.
+* Plumbing level superproject support.
You can include a subdirectory that has an independent git
- repository in your index and tree objects as a
- "subproject". This plumbing (i.e. "core") level subproject
- support explicitly excludes recursive behaviour.
+ repository in your index and tree objects of your project
+ ("superproject"). This plumbing (i.e. "core") level
+ superproject support explicitly excludes recursive behaviour.
- The "subproject" entries in the index and trees are
- incompatible with older versions of git. Experimenting with
+ The "subproject" entries in the index and trees of a superproject
+ are incompatible with older versions of git. Experimenting with
the plumbing level support is encouraged, but be warned that
unless everybody in your project updates to this release or
later, using this feature would make your project
but this feature is an extremely sharp-edged razor and needs
to be handled with caution (do not use it unless you
understand the earlier mailing list discussion on keyword
- expansion).
+ expansion). These conversions apply when checking files in
+ or out, and exporting via git-archive.
* The packfile format now optionally suports 64-bit index.
needs more than 32-bit to express offsets of objects in the
pack.
-* Comes with an updated git-gui 0.7.0
+* Comes with an updated git-gui 0.7.1
* Updated gitweb:
- can show combined diff for merges;
- uses font size of user's preference, not hardcoded in pixels;
+ - can now 'grep';
* New commands and options.
- "git clean -d -X" now does not remove non-excluded directories.
-* Documentation updates
-
-* Performance Tweaks
-
---
-exec >/var/tmp/1
-O=v1.5.2-rc3
-echo O=`git describe refs/heads/master`
-git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint
+ - rebasing (without -m) a series that changes a symlink to a directory
+ in the middle of a path confused git-apply greatly and refused to
+ operate.
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 19-May-2007 04:51:28 UTC\r
+Last updated 20-May-2007 09:08:17 UTC\r
</div>\r
</div>\r
</body>\r
branch of the `git.git` repository.
Documentation for older releases are available here:
-* link:v1.5.1.5/git.html[documentation for release 1.5.1.5]
+* link:v1.5.2/git.html[documentation for release 1.5.2]
-* release notes for link:RelNotes-1.5.1.5.txt[1.5.1.5],
+* release notes for
+ link:RelNotes-1.5.2.txt[1.5.2].
+
+* link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
+
+* release notes for
+ link:RelNotes-1.5.1.6.txt[1.5.1.6],
+ link:RelNotes-1.5.1.5.txt[1.5.1.5],
link:RelNotes-1.5.1.4.txt[1.5.1.4],
link:RelNotes-1.5.1.3.txt[1.5.1.3],
link:RelNotes-1.5.1.2.txt[1.5.1.2],
* link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
-* release notes for link:RelNotes-1.5.0.7.txt[1.5.0.7],
+* release notes for
+ link:RelNotes-1.5.0.7.txt[1.5.0.7],
link:RelNotes-1.5.0.6.txt[1.5.0.6],
link:RelNotes-1.5.0.5.txt[1.5.0.5],
link:RelNotes-1.5.0.3.txt[1.5.0.3],
with the commands mentioned in <a href="everyday.html">Everyday git</a>. You\r
should be able to find any unknown jargon in the\r
<a href="glossary.html">Glossary</a>.</p>\r
+<p>The <a href="user-manual.html">Git User's Manual</a> provides a more\r
+comprehensive introduction to git.</p>\r
<p>The <a href="cvs-migration.html">CVS migration</a> document explains how to\r
import a CVS repository into git, and shows how to use git in a\r
CVS-like way.</p>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 04-Apr-2007 18:34:41 UTC\r
+Last updated 20-May-2007 09:08:18 UTC\r
</div>\r
</div>\r
</body>\r
should be able to find any unknown jargon in the
link:glossary.html[Glossary].
+The link:user-manual.html[Git User's Manual] provides a more
+comprehensive introduction to git.
+
The link:cvs-migration.html[CVS migration] document explains how to
import a CVS repository into git, and shows how to use git in a
CVS-like way.
<div class="sectionbody">\r
<p>This tutorial explains how to import a new project into git, make\r
changes to it, and share changes with other developers.</p>\r
+<p>If you are instead primarily interested in using git to fetch a project,\r
+for example, to test the latest version, you may prefer to start with\r
+the first two chapters of <a href="user-manual.html">The Git User's Manual</a>.</p>\r
<p>First, note that you can get documentation for a command such as "git\r
diff" with:</p>\r
<div class="listingblock">\r
<pre><tt>Initialized empty Git repository in .git/</tt></pre>\r
</div></div>\r
<p>You've now initialized the working directory—you may notice a new\r
-directory created, named ".git". Tell git that you want it to track\r
-every file under the current directory (note the <em>.</em>) with:</p>\r
+directory created, named ".git".</p>\r
+<p>Next, tell git to take a snapshot of the contents of all files under the\r
+current directory (note the <em>.</em>), with <a href="git-add.html">git-add(1)</a>:</p>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>$ git add .</tt></pre>\r
</div></div>\r
-<p>Finally,</p>\r
+<p>This snapshot is now stored in a temporary staging area which git calls\r
+the "index". You can permanently store the contents of the index in the\r
+repository with <a href="git-commit.html">git-commit(1)</a>:</p>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>$ git commit</tt></pre>\r
</div></div>\r
-<p>will prompt you for a commit message, then record the current state\r
-of all the files to the repository.</p>\r
+<p>This will prompt you for a commit message. You've now stored the first\r
+version of your project in git.</p>\r
</div>\r
<h2>Making changes</h2>\r
<div class="sectionbody">\r
-<p>Try modifying some files, then run</p>\r
+<p>Modify some files, then add their updated contents to the index:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git diff</tt></pre>\r
+<pre><tt>$ git add file1 file2 file3</tt></pre>\r
</div></div>\r
-<p>to review your changes. When you're done, tell git that you\r
-want the updated contents of these files in the commit and then\r
-make a commit, like this:</p>\r
+<p>You are now ready to commit. You can see what is about to be committed\r
+using <a href="git-diff.html">git-diff(1)</a> with the —cached option:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git add file1 file2 file3\r
-$ git commit</tt></pre>\r
+<pre><tt>$ git diff --cached</tt></pre>\r
+</div></div>\r
+<p>(Without —cached, <a href="git-diff.html">git-diff(1)</a> will show you any changes that\r
+you've made but not yet added to the index.) You can also get a brief\r
+summary of the situation with <a href="git-status.html">git-status(1)</a>:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git status\r
+# On branch master\r
+# Changes to be committed:\r
+# (use "git reset HEAD <file>..." to unstage)\r
+#\r
+# modified: file1\r
+# modified: file2\r
+# modified: file3\r
+#</tt></pre>\r
+</div></div>\r
+<p>If you need to make any further adjustments, do so now, and then add any\r
+newly modified content to the index. Finally, commit your changes with:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git commit</tt></pre>\r
</div></div>\r
<p>This will again prompt your for a message describing the change, and then\r
-record the new versions of the files you listed.</p>\r
+record a new version of the project.</p>\r
<p>Alternatively, instead of running <tt>git add</tt> beforehand, you can use</p>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>$ git commit -a</tt></pre>\r
</div></div>\r
-<p>which will automatically notice modified (but not new) files.</p>\r
+<p>which will automatically notice any modified (but not new) files, add\r
+them to the index, and commit, all in one step.</p>\r
<p>A note on commit messages: Though not required, it's a good idea to\r
begin the commit message with a single short (less than 50 character)\r
line summarizing the change, followed by a blank line and then a more\r
</div>\r
<h2>Git tracks content not files</h2>\r
<div class="sectionbody">\r
-<p>With git you have to explicitly "add" all the changed _content_ you\r
-want to commit together. This can be done in a few different ways:</p>\r
-<p>1) By using <em>git add <file_spec>…</em></p>\r
-<p>This can be performed multiple times before a commit. Note that this\r
-is not only for adding new files. Even modified files must be\r
-added to the set of changes about to be committed. The "git status"\r
-command gives you a summary of what is included so far for the\r
-next commit. When done you should use the <em>git commit</em> command to\r
-make it real.</p>\r
-<p>Note: don't forget to <em>add</em> a file again if you modified it after the\r
-first <em>add</em> and before <em>commit</em>. Otherwise only the previous added\r
-state of that file will be committed. This is because git tracks\r
-content, so what you're really <em>adding</em> to the commit is the <strong>content</strong>\r
-of the file in the state it is in when you <em>add</em> it.</p>\r
-<p>2) By using <em>git commit -a</em> directly</p>\r
-<p>This is a quick way to automatically <em>add</em> the content from all files\r
-that were modified since the previous commit, and perform the actual\r
-commit without having to separately <em>add</em> them beforehand. This will\r
-not add content from new files i.e. files that were never added before.\r
-Those files still have to be added explicitly before performing a\r
-commit.</p>\r
-<p>But here's a twist. If you do <em>git commit <file1> <file2> …</em> then only\r
-the changes belonging to those explicitly specified files will be\r
-committed, entirely bypassing the current "added" changes. Those "added"\r
-changes will still remain available for a subsequent commit though.</p>\r
-<p>However, for normal usage you only have to remember <em>git add</em> + <em>git commit</em>\r
-and/or <em>git commit -a</em>.</p>\r
+<p>Many revision control systems provide an "add" command that tells the\r
+system to start tracking changes to a new file. Git's "add" command\r
+does something simpler and more powerful: <tt>git add</tt> is used both for new\r
+and newly modified files, and in both cases it takes a snapshot of the\r
+given files and stages that content in the index, ready for inclusion in\r
+the next commit.</p>\r
</div>\r
<h2>Viewing the changelog</h2>\r
<div class="sectionbody">\r
<p><a href="tutorial-2.html">Part two of this tutorial</a> explains the object\r
database, the index file, and a few other odds and ends that you'll\r
need to make the most of git.</p>\r
-<p>If you don't want to consider with that right away, a few other\r
+<p>If you don't want to continue with that right away, a few other\r
digressions that may be interesting at this point are:</p>\r
<ul>\r
<li>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 06-May-2007 08:52:37 UTC\r
+Last updated 20-May-2007 09:08:17 UTC\r
</div>\r
</div>\r
</body>\r
This tutorial explains how to import a new project into git, make
changes to it, and share changes with other developers.
+If you are instead primarily interested in using git to fetch a project,
+for example, to test the latest version, you may prefer to start with
+the first two chapters of link:user-manual.html[The Git User's Manual].
+
First, note that you can get documentation for a command such as "git
diff" with:
------------------------------------------------
You've now initialized the working directory--you may notice a new
-directory created, named ".git". Tell git that you want it to track
-every file under the current directory (note the '.') with:
+directory created, named ".git".
+
+Next, tell git to take a snapshot of the contents of all files under the
+current directory (note the '.'), with gitlink:git-add[1]:
------------------------------------------------
$ git add .
------------------------------------------------
-Finally,
+This snapshot is now stored in a temporary staging area which git calls
+the "index". You can permanently store the contents of the index in the
+repository with gitlink:git-commit[1]:
------------------------------------------------
$ git commit
------------------------------------------------
-will prompt you for a commit message, then record the current state
-of all the files to the repository.
+This will prompt you for a commit message. You've now stored the first
+version of your project in git.
Making changes
--------------
-Try modifying some files, then run
+Modify some files, then add their updated contents to the index:
------------------------------------------------
-$ git diff
+$ git add file1 file2 file3
------------------------------------------------
-to review your changes. When you're done, tell git that you
-want the updated contents of these files in the commit and then
-make a commit, like this:
+You are now ready to commit. You can see what is about to be committed
+using gitlink:git-diff[1] with the --cached option:
+
+------------------------------------------------
+$ git diff --cached
+------------------------------------------------
+
+(Without --cached, gitlink:git-diff[1] will show you any changes that
+you've made but not yet added to the index.) You can also get a brief
+summary of the situation with gitlink:git-status[1]:
+
+------------------------------------------------
+$ git status
+# On branch master
+# Changes to be committed:
+# (use "git reset HEAD <file>..." to unstage)
+#
+# modified: file1
+# modified: file2
+# modified: file3
+#
+------------------------------------------------
+
+If you need to make any further adjustments, do so now, and then add any
+newly modified content to the index. Finally, commit your changes with:
------------------------------------------------
-$ git add file1 file2 file3
$ git commit
------------------------------------------------
This will again prompt your for a message describing the change, and then
-record the new versions of the files you listed.
+record a new version of the project.
Alternatively, instead of running `git add` beforehand, you can use
$ git commit -a
------------------------------------------------
-which will automatically notice modified (but not new) files.
+which will automatically notice any modified (but not new) files, add
+them to the index, and commit, all in one step.
A note on commit messages: Though not required, it's a good idea to
begin the commit message with a single short (less than 50 character)
example, use the first line on the Subject: line and the rest of the
commit in the body.
-
Git tracks content not files
----------------------------
-With git you have to explicitly "add" all the changed _content_ you
-want to commit together. This can be done in a few different ways:
-
-1) By using 'git add <file_spec>...'
-
-This can be performed multiple times before a commit. Note that this
-is not only for adding new files. Even modified files must be
-added to the set of changes about to be committed. The "git status"
-command gives you a summary of what is included so far for the
-next commit. When done you should use the 'git commit' command to
-make it real.
-
-Note: don't forget to 'add' a file again if you modified it after the
-first 'add' and before 'commit'. Otherwise only the previous added
-state of that file will be committed. This is because git tracks
-content, so what you're really 'adding' to the commit is the *content*
-of the file in the state it is in when you 'add' it.
-
-2) By using 'git commit -a' directly
-
-This is a quick way to automatically 'add' the content from all files
-that were modified since the previous commit, and perform the actual
-commit without having to separately 'add' them beforehand. This will
-not add content from new files i.e. files that were never added before.
-Those files still have to be added explicitly before performing a
-commit.
-
-But here's a twist. If you do 'git commit <file1> <file2> ...' then only
-the changes belonging to those explicitly specified files will be
-committed, entirely bypassing the current "added" changes. Those "added"
-changes will still remain available for a subsequent commit though.
-
-However, for normal usage you only have to remember 'git add' + 'git commit'
-and/or 'git commit -a'.
-
+Many revision control systems provide an "add" command that tells the
+system to start tracking changes to a new file. Git's "add" command
+does something simpler and more powerful: `git add` is used both for new
+and newly modified files, and in both cases it takes a snapshot of the
+given files and stages that content in the index, ready for inclusion in
+the next commit.
Viewing the changelog
---------------------
database, the index file, and a few other odds and ends that you'll
need to make the most of git.
-If you don't want to consider with that right away, a few other
+If you don't want to continue with that right away, a few other
digressions that may be interesting at this point are:
* gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Git User's Manual (for version 1.5.1 or newer)</title><link rel="stylesheet" href="docbook-xsl.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id232635"></a>Git User's Manual (for version 1.5.1 or newer)</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#id264704">Preface</a></span></dt><dt><span class="chapter"><a href="#repositories-and-branches">1. Repositories and Branches</a></span></dt><dd><dl><dt><span class="section"><a href="#how-to-get-a-git-repository">How to get a git repository</a></span></dt><dt><span class="section"><a href="#how-to-check-out">How to check out a different version of a project</a></span></dt><dt><span class="section"><a href="#understanding-commits">Understanding History: Commits</a></span></dt><dd><dl><dt><span class="section"><a href="#understanding-reachability">Understanding history: commits, parents, and reachability</a></span></dt><dt><span class="section"><a href="#history-diagrams">Understanding history: History diagrams</a></span></dt><dt><span class="section"><a href="#what-is-a-branch">Understanding history: What is a branch?</a></span></dt></dl></dd><dt><span class="section"><a href="#manipulating-branches">Manipulating branches</a></span></dt><dt><span class="section"><a href="#detached-head">Examining an old version without creating a new branch</a></span></dt><dt><span class="section"><a href="#examining-remote-branches">Examining branches from a remote repository</a></span></dt><dt><span class="section"><a href="#how-git-stores-references">Naming branches, tags, and other references</a></span></dt><dt><span class="section"><a href="#Updating-a-repository-with-git-fetch">Updating a repository with git fetch</a></span></dt><dt><span class="section"><a href="#fetching-branches">Fetching branches from other repositories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#exploring-git-history">2. Exploring git history</a></span></dt><dd><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#counting-commits-on-a-branch">Counting the number of commits on a branch</a></span></dt><dt><span class="section"><a href="#checking-for-equal-branches">Check whether two branches point at the same history</a></span></dt><dt><span class="section"><a href="#finding-tagged-descendants">Find first tagged version including a given fix</a></span></dt><dt><span class="section"><a href="#showing-commits-unique-to-a-branch">Showing commits unique to a given branch</a></span></dt><dt><span class="section"><a href="#making-a-release">Creating a changelog and tarball for a software release</a></span></dt></dl></dd><
/dl></dd><dt><span class="chapter"><a href="#Developing-with-git">3. Developing with git</a></span></dt><dd><dl><dt><span class="section"><a href="#telling-git-your-name">Telling git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dd><dl><dt><span class="section"><a href="#conflict-resolution">Getting conflict-resolution help during a merge</a></span></dt></dl></dd><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dd><dl><dt><span class="section"><a href="#reverting-a-commit">Fixing a mistake with a new commit</a></span></dt><dt><span class="section"><a href="#fixing-a-mistake-by-editing-history">Fixing a mistake by editing history</a></span></dt><dt><span class="section"><a href="#checkout-of-path">Checking out an old version of a file</a></span></dt></dl></dd><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt><dd><dl><dt><span class="section"><a href="#checking-for-corruption">Checking the repository for corruption</a></span></dt><dt><span class="section"><a href="#recovering-lost-changes">Recovering lost changes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#sharing-development">4. Sharing development with others</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-updates-with-git-pull">Getting updates with git pull</a></span></dt><dt><span class="section"><a href="#submitting-patches">Submitting patches to a project</a></span></dt><dt><span class="section"><a href="#importing-patches">Importing patches to a project</a></span></dt><dt><span class="section"><a href="#public-repositories">Public git repositories</a></span></dt><dd><dl><dt><span class="section"><a href="#setting-up-a-public-repository">Setting up a public repository</a></span></dt><dt><span class="section"><a href="#exporting-via-git">Exporting a git repository via the git protocol</a></span></dt><dt><span class="section"><a href="#exporting-via-http">Exporting a git repository via http</a></span></dt><dt><span class="section"><a href="#pushing-changes-to-a-public-repository">Pushing changes to a public repository</a></span></dt><dt><span class="section"><a href="#setting-up-a-shared-repository">Setting up a shared repository</a></span></dt><dt><span class="section"><a href="#setting-up-gitweb">Allowing web browsing of a repository</a></span></dt></dl></dd><dt><span class="section"><a href="#sharing-development-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#maintaining-topic-branches">Maintaining topic branches for a Linux subsystem maintainer</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#cleaning-up-history">5. Rewriting history and maintaining patch series</a></span></dt><dd><dl><dt><span class="section"><a href="#patch-series">Creating the perfect patch series</a></span></dt><dt><span class="section"><a href="#using-git-rebase">Keeping a patch series up to date using git-rebase</a></span></dt><dt><span class="section"><a href="#modifying-one-commit">Modifying a single commit</a></span></dt><dt><span class="section"><a href="#reordering-patch-series">Reordering or selecting from a patch series</a></span></dt><dt><span class="section"><a href="#patch-series-tools">Other tools</a></span></dt><dt><span class="section"><a href="#problems-with-rewriting-history">Problems with rewriting history</a></span></dt></dl></dd><dt><span class="chapter"><a href="#advanced-branch-management">6. Advanced branch management</a></span></dt><dd><dl><dt><span class="section"><a href="#fetching-individual-branches">Fetching individual branches</a></span></dt><dt><span class="section"><a href="#fetch-fast-forwards">git fetch and fast-forwards</a></span></dt><dt><span class="section"><a href="#forcing-fetch">Forcing git fetch to do non-fast-forward updates</a></span></dt><dt><span class="section"><a href="#remote-branch-configuration">Configuring remote branches</a></span></dt></dl></dd><dt><span class="chapter"><a href="#git-internals">7. Git internals</a></span></dt><dd><dl><dt><span class="section"><a href="#the-object-database">The Object Database</a></span></dt><dt><span class="section"><a href="#blob-object">Blob Object</a></span></dt><dt><span class="section"><a href="#tree-object">Tree Object</a></span></dt><dt><span class="section"><a href="#commit-object">Commit Object</a></span></dt><dt><span class="section"><a href="#trust">Trust</a></span></dt><dt><span class="section"><a href="#tag-object">Tag Object</a></span></dt><dt><span class="section"><a href="#the-index">The "index" aka "Current Directory Cache"</a></span></dt><dt><span class="section"><a href="#the-workflow">The Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#working-directory-to-index">working directory -> index</a></span></dt><dt><span class="section"><a href="#index-to-object-database">index -> object database</a></span></dt><dt><span class="section"><a href="#object-database-to-index">object database -> index</a></span></dt><dt><span class="section"><a href="#index-to-working-directory">index -> working directory</a></span></dt><dt><span class="section"><a href="#tying-it-all-together">Tying it all together</a></span></dt></dl></dd><dt><span class="section"><a href="#examining-the-data">Examining the data</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees">Merging multiple trees</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees-2">Merging multiple trees, continued</a></span></dt><dt><span class="section"><a href="#pack-files">How git stores objects efficiently: pack files</a></span></dt><dt><span class="section"><a href="#dangling-objects">Dangling objects</a></span></dt><dt><span class="section"><a href="#birdview-on-the-source-code">A birds-eye view of Git's source code</a></span></dt></dl></dd><dt><span class="chapter"><a href="#glossary">8. GIT Glossary</a></span></dt><dt><span class="appendix"><a href="#git-quick-start">A. Git Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#quick-creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#managing-branches">Managing branches</a></span></dt><dt><span class="section"><a href="#exploring-history">Exploring history</a></span></dt><dt><span class="section"><a href="#making-changes">Making changes</a></span></dt><dt><span class="section"><a href="#merging">Merging</a></span></dt><dt><span class="section"><a href="#sharing-your-changes">Sharing your changes</a></span></dt><dt><span class="section"><a href="#repository-maintenance">Repository maintenance</a></span></dt></dl></dd><dt><span class="appendix"><a href="#todo">B. Notes and todo list for this manual</a></span></dt></dl></div><div class="preface" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id264704"></a>Preface</h2></div></div></div><p>Git is a fast distributed revision control system.</p><p>This manual is designed to be readable by someone with basic unix
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Git User's Manual (for version 1.5.1 or newer)</title><link rel="stylesheet" href="docbook-xsl.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id232635"></a>Git User's Manual (for version 1.5.1 or newer)</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#id264704">Preface</a></span></dt><dt><span class="chapter"><a href="#repositories-and-branches">1. Repositories and Branches</a></span></dt><dd><dl><dt><span class="section"><a href="#how-to-get-a-git-repository">How to get a git repository</a></span></dt><dt><span class="section"><a href="#how-to-check-out">How to check out a different version of a project</a></span></dt><dt><span class="section"><a href="#understanding-commits">Understanding History: Commits</a></span></dt><dd><dl><dt><span class="section"><a href="#understanding-reachability">Understanding history: commits, parents, and reachability</a></span></dt><dt><span class="section"><a href="#history-diagrams">Understanding history: History diagrams</a></span></dt><dt><span class="section"><a href="#what-is-a-branch">Understanding history: What is a branch?</a></span></dt></dl></dd><dt><span class="section"><a href="#manipulating-branches">Manipulating branches</a></span></dt><dt><span class="section"><a href="#detached-head">Examining an old version without creating a new branch</a></span></dt><dt><span class="section"><a href="#examining-remote-branches">Examining branches from a remote repository</a></span></dt><dt><span class="section"><a href="#how-git-stores-references">Naming branches, tags, and other references</a></span></dt><dt><span class="section"><a href="#Updating-a-repository-with-git-fetch">Updating a repository with git fetch</a></span></dt><dt><span class="section"><a href="#fetching-branches">Fetching branches from other repositories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#exploring-git-history">2. Exploring git history</a></span></dt><dd><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#counting-commits-on-a-branch">Counting the number of commits on a branch</a></span></dt><dt><span class="section"><a href="#checking-for-equal-branches">Check whether two branches point at the same history</a></span></dt><dt><span class="section"><a href="#finding-tagged-descendants">Find first tagged version including a given fix</a></span></dt><dt><span class="section"><a href="#showing-commits-unique-to-a-branch">Showing commits unique to a given branch</a></span></dt><dt><span class="section"><a href="#making-a-release">Creating a changelog and tarball for a software release</a></span></dt></dl></dd><
dt><span class="section"><a href="#id274842">Finding commits referencing a file with given content</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Developing-with-git">3. Developing with git</a></span></dt><dd><dl><dt><span class="section"><a href="#telling-git-your-name">Telling git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#ignoring-files">Ignoring files</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dd><dl><dt><span class="section"><a href="#conflict-resolution">Getting conflict-resolution help during a merge</a></span></dt></dl></dd><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dd><dl><dt><span class="section"><a href="#reverting-a-commit">Fixing a mistake with a new commit</a></span></dt><dt><span class="section"><a href="#fixing-a-mistake-by-editing-history">Fixing a mistake by editing history</a></span></dt><dt><span class="section"><a href="#checkout-of-path">Checking out an old version of a file</a></span></dt></dl></dd><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt><dd><dl><dt><span class="section"><a href="#checking-for-corruption">Checking the repository for corruption</a></span></dt><dt><span class="section"><a href="#recovering-lost-changes">Recovering lost changes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#sharing-development">4. Sharing development with others</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-updates-with-git-pull">Getting updates with git pull</a></span></dt><dt><span class="section"><a href="#submitting-patches">Submitting patches to a project</a></span></dt><dt><span class="section"><a href="#importing-patches">Importing patches to a project</a></span></dt><dt><span class="section"><a href="#public-repositories">Public git repositories</a></span></dt><dd><dl><dt><span class="section"><a href="#setting-up-a-public-repository">Setting up a public repository</a></span></dt><dt><span class="section"><a href="#exporting-via-git">Exporting a git repository via the git protocol</a></span></dt><dt><span class="section"><a href="#exporting-via-http">Exporting a git repository via http</a></span></dt><dt><span class="section"><a href="#pushing-changes-to-a-public-repository">Pushing changes to a public repository</a></span></dt><dt><span class="section"><a href="#setting-up-a-shared-repository">Setting up a shared repository</a></span></dt><dt><span class="section"><a href="#setting-up-gitweb">Allowing web browsing of a repository</a></span></dt></dl></dd><dt><span class="section"><a href="#sharing-development-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#maintaining-topic-branches">Maintaining topic branches for a Linux subsystem maintainer</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#cleaning-up-history">5. Rewriting history and maintaining patch series</a></span></dt><dd><dl><dt><span class="section"><a href="#patch-series">Creating the perfect patch series</a></span></dt><dt><span class="section"><a href="#using-git-rebase">Keeping a patch series up to date using git-rebase</a></span></dt><dt><span class="section"><a href="#modifying-one-commit">Modifying a single commit</a></span></dt><dt><span class="section"><a href="#reordering-patch-series">Reordering or selecting from a patch series</a></span></dt><dt><span class="section"><a href="#patch-series-tools">Other tools</a></span></dt><dt><span class="section"><a href="#problems-with-rewriting-history">Problems with rewriting history</a></span></dt></dl></dd><dt><span class="chapter"><a href="#advanced-branch-management">6. Advanced branch management</a></span></dt><dd><dl><dt><span class="section"><a href="#fetching-individual-branches">Fetching individual branches</a></span></dt><dt><span class="section"><a href="#fetch-fast-forwards">git fetch and fast-forwards</a></span></dt><dt><span class="section"><a href="#forcing-fetch">Forcing git fetch to do non-fast-forward updates</a></span></dt><dt><span class="section"><a href="#remote-branch-configuration">Configuring remote branches</a></span></dt></dl></dd><dt><span class="chapter"><a href="#git-internals">7. Git internals</a></span></dt><dd><dl><dt><span class="section"><a href="#the-object-database">The Object Database</a></span></dt><dt><span class="section"><a href="#blob-object">Blob Object</a></span></dt><dt><span class="section"><a href="#tree-object">Tree Object</a></span></dt><dt><span class="section"><a href="#commit-object">Commit Object</a></span></dt><dt><span class="section"><a href="#trust">Trust</a></span></dt><dt><span class="section"><a href="#tag-object">Tag Object</a></span></dt><dt><span class="section"><a href="#the-index">The "index" aka "Current Directory Cache"</a></span></dt><dt><span class="section"><a href="#the-workflow">The Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#working-directory-to-index">working directory -> index</a></span></dt><dt><span class="section"><a href="#index-to-object-database">index -> object database</a></span></dt><dt><span class="section"><a href="#object-database-to-index">object database -> index</a></span></dt><dt><span class="section"><a href="#index-to-working-directory">index -> working directory</a></span></dt><dt><span class="section"><a href="#tying-it-all-together">Tying it all together</a></span></dt></dl></dd><dt><span class="section"><a href="#examining-the-data">Examining the data</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees">Merging multiple trees</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees-2">Merging multiple trees, continued</a></span></dt><dt><span class="section"><a href="#pack-files">How git stores objects efficiently: pack files</a></span></dt><dt><span class="section"><a href="#dangling-objects">Dangling objects</a></span></dt><dt><span class="section"><a href="#birdview-on-the-source-code">A birds-eye view of Git's source code</a></span></dt></dl></dd><dt><span class="chapter"><a href="#glossary">8. GIT Glossary</a></span></dt><dt><span class="appendix"><a href="#git-quick-start">A. Git Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#quick-creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#managing-branches">Managing branches</a></span></dt><dt><span class="section"><a href="#exploring-history">Exploring history</a></span></dt><dt><span class="section"><a href="#making-changes">Making changes</a></span></dt><dt><span class="section"><a href="#merging">Merging</a></span></dt><dt><span class="section"><a href="#sharing-your-changes">Sharing your changes</a></span></dt><dt><span class="section"><a href="#repository-maintenance">Repository maintenance</a></span></dt></dl></dd><dt><span class="appendix"><a href="#todo">B. Notes and todo list for this manual</a></span></dt></dl></div><div class="preface" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id264704"></a>Preface</h2></div></div></div><p>Git is a fast distributed revision control system.</p><p>This manual is designed to be readable by someone with basic unix
command-line skills, but no previous knowledge of git.</p><p><a href="#repositories-and-branches" title="Chapter 1. Repositories and Branches">Chapter 1, <i>Repositories and Branches</i></a> and <a href="#exploring-git-history" title="Chapter 2. Exploring git history">Chapter 2, <i>Exploring git history</i></a> explain how
to fetch and study a project using git—read these chapters to learn how
to build and test a particular version of a software project, search for
...</p></div><p>This is what causes git to track the remote's branches; you may modify
or delete these configuration options by editing .git/config with a
text editor. (See the "CONFIGURATION FILE" section of
-<a href="git-config.html" target="_top">git-config(1)</a> for details.)</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="exploring-git-history"></a>Chapter 2. Exploring git history</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#counting-commits-on-a-branch">Counting the number of commits on a branch</a></span></dt><dt><span class="section"><a href="#checking-for-equal-branches">Check whether two branches point at the same history</a></span></dt><dt><span class="section"><a href="#finding-tagged-descendants">Find first tagged version including a given fix</a></span></dt><dt><span class="section"><a href="#showing-commits-unique-to-a-branch">Showing commits unique to a given branch</a></span></dt><dt><span class="section"><a href="#making-a-release">Creating a changelog and tarball for a software release</a></span></dt></dl></dd></dl></div><p>Git is best thought of as a tool for storing the history of a
+<a href="git-config.html" target="_top">git-config(1)</a> for details.)</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="exploring-git-history"></a>Chapter 2. Exploring git history</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#counting-commits-on-a-branch">Counting the number of commits on a branch</a></span></dt><dt><span class="section"><a href="#checking-for-equal-branches">Check whether two branches point at the same history</a></span></dt><dt><span class="section"><a href="#finding-tagged-descendants">Find first tagged version including a given fix</a></span></dt><dt><span class="section"><a href="#showing-commits-unique-to-a-branch">Showing commits unique to a given branch</a></span></dt><dt><span class="section"><a href="#making-a-release">Creating a changelog and tarball for a software release</a></span></dt></dl></dd><
dt><span class="section"><a href="#id274842">Finding commits referencing a file with given content</a></span></dt></dl></div><p>Git is best thought of as a tool for storing the history of a
collection of files. It does this by storing compressed snapshots of
the contents of a file heirarchy, together with "commits" which show
the relationships between these snapshots.</p><p>Git provides extremely flexible and fast tools for exploring the
echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"<br>
echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"<br>
echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"</p></div><p>and then he just cut-and-pastes the output commands after verifying that
-they look OK.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Developing-with-git"></a>Chapter 3. Developing with git</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#telling-git-your-name">Telling git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dd><dl><dt><span class="section"><a href="#conflict-resolution">Getting conflict-resolution help during a merge</a></span></dt></dl></dd><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dd><dl><dt><span class="section"><a href="#reverting-a-commit">Fixing a mistake with a new commit</a></span></dt><dt><span class="section"><a href="#fixing-a-mistake-by-editing-history">Fixing a mistake by editing history</a></span></dt><dt><span class="section"><a href="#checkout-of-path">Checking out an old version of a file</a></span></dt></dl></dd><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt><dd><dl><dt><span class="section"><a href="#checking-for-corruption">Checking the repository for corruption</a></span></dt><dt><span class="section"><a href="#recovering-lost-changes">Recovering lost changes</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="telling-git-your-name"></a>Telling git your name</h2></div></div></div><p>Before creating any commits, you should introduce yourself to git. The
+they look OK.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id274842"></a>Finding commits referencing a file with given content</h2></div></div></div><p>Somebody hands you a copy of a file, and asks which commits modified a
+file such that it contained the given content either before or after the
+commit. You can find out with this:</p><div class="literallayout"><p>$ git log --raw -r --abbrev=40 --pretty=oneline -- filename |<br>
+ grep -B 1 `git hash-object filename`</p></div><p>Figuring out why this works is left as an exercise to the (advanced)
+student. The <a href="git-log.html" target="_top">git-log(1)</a>, <a href="git-diff-tree.html" target="_top">git-diff-tree(1)</a>, and
+<a href="git-hash-object.html" target="_top">git-hash-object(1)</a> man pages may prove helpful.</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Developing-with-git"></a>Chapter 3. Developing with git</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#telling-git-your-name">Telling git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#ignoring-files">Ignoring files</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dd><dl><dt><span class="section"><a href="#conflict-resolution">Getting conflict-resolution help during a merge</a></span></dt></dl></dd><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dd><dl><dt><span class="section"><a href="#reverting-a-commit">Fixing a mistake with a new commit</a></span></dt><dt><span class="section"><a href="#fixing-a-mistake-by-editing-history">Fixing a mistake by editing history</a></span></dt><dt><span class="section"><a href="#checkout-of-path">Checking out an old version of a file</a></span></dt></dl></dd><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt><dd><dl><dt><span class="section"><a href="#checking-for-corruption">Checking the repository for corruption</a></span></dt><dt><span class="section"><a href="#recovering-lost-changes">Recovering lost changes</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="telling-git-your-name"></a>Telling git your name</h2></div></div></div><p>Before creating any commits, you should introduce yourself to git. The
easiest way to do so is to make sure the following lines appear in a
file named .gitconfig in your home directory:</p><div class="literallayout"><p>[user]<br>
name = Your Name Comes Here<br>
change, followed by a blank line and then a more thorough
description. Tools that turn commits into email, for example, use
the first line on the Subject line and the rest of the commit in the
-body.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="how-to-merge"></a>How to merge</h2></div></div></div><p>You can rejoin two diverging branches of development using
+body.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ignoring-files"></a>Ignoring files</h2></div></div></div><p>A project will often generate files that you do <span class="emphasis"><em>not</em></span> want to track with git.
+This typically includes files generated by a build process or temporary
+backup files made by your editor. Of course, <span class="emphasis"><em>not</em></span> tracking files with git
+is just a matter of <span class="emphasis"><em>not</em></span> calling "<code class="literal">git add</code>" on them. But it quickly becomes
+annoying to have these untracked files lying around; e.g. they make
+"<code class="literal">git add .</code>" and "<code class="literal">git commit -a</code>" practically useless, and they keep
+showing up in the output of "<code class="literal">git status</code>", etc.</p><p>Git therefore provides "exclude patterns" for telling git which files to
+actively ignore. Exclude patterns are thoroughly explained in the
+"Exclude Patterns" section of the <a href="git-ls-files.html" target="_top">git-ls-files(1)</a> manual page,
+but the heart of the concept is simply a list of files which git should
+ignore. Entries in the list may contain globs to specify multiple files,
+or may be prefixed by "<code class="literal">!</code>" to explicitly include (un-ignore) a previously
+excluded (ignored) file (i.e. later exclude patterns override earlier ones).
+The following example should illustrate such patterns:</p><div class="literallayout"><p># Lines starting with '#' are considered comments.<br>
+# Ignore foo.txt.<br>
+foo.txt<br>
+# Ignore (generated) html files,<br>
+*.html<br>
+# except foo.html which is maintained by hand.<br>
+!foo.html<br>
+# Ignore objects and archives.<br>
+*.[oa]</p></div><p>The next question is where to put these exclude patterns so that git can
+find them. Git looks for exclude patterns in the following files:</p><div class="variablelist"><dl><dt><span class="term">
+<code class="literal">.gitignore</code> files in your working tree:
+</span></dt><dd>
+ You may store multiple <code class="literal">.gitignore</code> files at various locations in your
+ working tree. Each <code class="literal">.gitignore</code> file is applied to the directory where
+ it's located, including its subdirectories. Furthermore, the
+ <code class="literal">.gitignore</code> files can be tracked like any other files in your working
+ tree; just do a "<code class="literal">git add .gitignore</code>" and commit. <code class="literal">.gitignore</code> is
+ therefore the right place to put exclude patterns that are meant to
+ be shared between all project participants, such as build output files
+ (e.g. <code class="literal">*.o</code>), etc.
+</dd><dt><span class="term">
+<code class="literal">.git/info/exclude</code> in your repo:
+</span></dt><dd>
+ Exclude patterns in this file are applied to the working tree as a
+ whole. Since the file is not located in your working tree, it does
+ not follow push/pull/clone like <code class="literal">.gitignore</code> can do. This is therefore
+ the place to put exclude patterns that are local to your copy of the
+ repo (i.e. <span class="emphasis"><em>not</em></span> shared between project participants), such as
+ temporary backup files made by your editor (e.g. <code class="literal">*~</code>), etc.
+</dd><dt><span class="term">
+The file specified by the <code class="literal">core.excludesfile</code> config directive:
+</span></dt><dd>
+ By setting the <code class="literal">core.excludesfile</code> config directive you can tell git
+ where to find more exclude patterns (see <a href="git-config.html" target="_top">git-config(1)</a> for
+ more information on configuration options). This config directive
+ can be set in the per-repo <code class="literal">.git/config</code> file, in which case the
+ exclude patterns will apply to that repo only. Alternatively, you
+ can set the directive in the global <code class="literal">~/.gitconfig</code> file to apply
+ the exclude pattern to all your git repos. As with the above
+ <code class="literal">.git/info/exclude</code> (and, indeed, with git config directives in
+ general), this directive does not follow push/pull/clone, but remain
+ local to your repo(s).
+</dd></dl></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>In addition to the above alternatives, there are git commands that can take
+exclude patterns directly on the command line. See <a href="git-ls-files.html" target="_top">git-ls-files(1)</a>
+for an example of this.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="how-to-merge"></a>How to merge</h2></div></div></div><p>You can rejoin two diverging branches of development using
<a href="git-merge.html" target="_top">git-merge(1)</a>:</p><div class="literallayout"><p>$ git merge branchname</p></div><p>merges the development in the branch "branchname" into the current
branch. If there are conflicts—for example, if the same file is
modified in two different ways in the remote branch and the local
commonly used in CVS, where several developers with special rights
all push to and pull from a single shared repository. See
<a href="cvs-migration.html" target="_top">git for CVS users</a> for instructions on how to
-set this up.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="setting-up-gitweb"></a>Allowing web browsing of a repository</h3></div></div></div><p>The gitweb cgi script provides users an easy way to browse your
+set this up.</p><p>However, while there is nothing wrong with git's support for shared
+repositories, this mode of operation is not generally recommended,
+simply because the mode of collaboration that git supports—by
+exchanging patches and pulling from public repositories—has so many
+advantages over the central shared repository:</p><div class="itemizedlist"><ul type="disc"><li>
+Git's ability to quickly import and merge patches allows a
+ single maintainer to process incoming changes even at very
+ high rates. And when that becomes too much, git-pull provides
+ an easy way for that maintainer to delegate this job to other
+ maintainers while still allowing optional review of incoming
+ changes.
+</li><li>
+Since every developer's repository has the same complete copy
+ of the project history, no repository is special, and it is
+ trivial for another developer to take over maintenance of a
+ project, either by mutual agreement, or because a maintainer
+ becomes unresponsive or difficult to work with.
+</li><li>
+The lack of a central group of "committers" means there is
+ less need for formal decisions about who is "in" and who is
+ "out".
+</li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="setting-up-gitweb"></a>Allowing web browsing of a repository</h3></div></div></div><p>The gitweb cgi script provides users an easy way to browse your
project's files and history without having to install git; see the file
gitweb/INSTALL in the git source tree for instructions on setting it up.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sharing-development-examples"></a>Examples</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="maintaining-topic-branches"></a>Maintaining topic branches for a Linux subsystem maintainer</h3></div></div></div><p>This describes how Tony Luck uses git in his role as maintainer of the
IA64 architecture for the Linux kernel.</p><p>He uses two public branches:</p><div class="itemizedlist"><ul type="disc"><li>
no more knowledge than necessary: for example, "importing
patches into a project" rather than "the git-am command"</p><p>Think about how to create a clear chapter dependency graph that will
allow people to get to important topics without necessarily reading
-everything in between.</p><p>Say something about .gitignore.</p><p>Scan Documentation/ for other stuff left out; in particular:
+everything in between.</p><p>Scan Documentation/ for other stuff left out; in particular:
howto's
some of technical/?
hooks
and then he just cut-and-pastes the output commands after verifying that
they look OK.
+Finding commits referencing a file with given content
+-----------------------------------------------------
+
+Somebody hands you a copy of a file, and asks which commits modified a
+file such that it contained the given content either before or after the
+commit. You can find out with this:
+
+-------------------------------------------------
+$ git log --raw -r --abbrev=40 --pretty=oneline -- filename |
+ grep -B 1 `git hash-object filename`
+-------------------------------------------------
+
+Figuring out why this works is left as an exercise to the (advanced)
+student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and
+gitlink:git-hash-object[1] man pages may prove helpful.
+
[[Developing-with-git]]
Developing with git
===================
the first line on the Subject line and the rest of the commit in the
body.
+[[ignoring-files]]
+Ignoring files
+--------------
+
+A project will often generate files that you do 'not' want to track with git.
+This typically includes files generated by a build process or temporary
+backup files made by your editor. Of course, 'not' tracking files with git
+is just a matter of 'not' calling "`git add`" on them. But it quickly becomes
+annoying to have these untracked files lying around; e.g. they make
+"`git add .`" and "`git commit -a`" practically useless, and they keep
+showing up in the output of "`git status`", etc.
+
+Git therefore provides "exclude patterns" for telling git which files to
+actively ignore. Exclude patterns are thoroughly explained in the
+"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page,
+but the heart of the concept is simply a list of files which git should
+ignore. Entries in the list may contain globs to specify multiple files,
+or may be prefixed by "`!`" to explicitly include (un-ignore) a previously
+excluded (ignored) file (i.e. later exclude patterns override earlier ones).
+The following example should illustrate such patterns:
+
+-------------------------------------------------
+# Lines starting with '#' are considered comments.
+# Ignore foo.txt.
+foo.txt
+# Ignore (generated) html files,
+*.html
+# except foo.html which is maintained by hand.
+!foo.html
+# Ignore objects and archives.
+*.[oa]
+-------------------------------------------------
+
+The next question is where to put these exclude patterns so that git can
+find them. Git looks for exclude patterns in the following files:
+
+`.gitignore` files in your working tree:::
+ You may store multiple `.gitignore` files at various locations in your
+ working tree. Each `.gitignore` file is applied to the directory where
+ it's located, including its subdirectories. Furthermore, the
+ `.gitignore` files can be tracked like any other files in your working
+ tree; just do a "`git add .gitignore`" and commit. `.gitignore` is
+ therefore the right place to put exclude patterns that are meant to
+ be shared between all project participants, such as build output files
+ (e.g. `\*.o`), etc.
+`.git/info/exclude` in your repo:::
+ Exclude patterns in this file are applied to the working tree as a
+ whole. Since the file is not located in your working tree, it does
+ not follow push/pull/clone like `.gitignore` can do. This is therefore
+ the place to put exclude patterns that are local to your copy of the
+ repo (i.e. 'not' shared between project participants), such as
+ temporary backup files made by your editor (e.g. `\*~`), etc.
+The file specified by the `core.excludesfile` config directive:::
+ By setting the `core.excludesfile` config directive you can tell git
+ where to find more exclude patterns (see gitlink:git-config[1] for
+ more information on configuration options). This config directive
+ can be set in the per-repo `.git/config` file, in which case the
+ exclude patterns will apply to that repo only. Alternatively, you
+ can set the directive in the global `~/.gitconfig` file to apply
+ the exclude pattern to all your git repos. As with the above
+ `.git/info/exclude` (and, indeed, with git config directives in
+ general), this directive does not follow push/pull/clone, but remain
+ local to your repo(s).
+
+[NOTE]
+In addition to the above alternatives, there are git commands that can take
+exclude patterns directly on the command line. See gitlink:git-ls-files[1]
+for an example of this.
+
[[how-to-merge]]
How to merge
------------
link:cvs-migration.html[git for CVS users] for instructions on how to
set this up.
+However, while there is nothing wrong with git's support for shared
+repositories, this mode of operation is not generally recommended,
+simply because the mode of collaboration that git supports--by
+exchanging patches and pulling from public repositories--has so many
+advantages over the central shared repository:
+
+ - Git's ability to quickly import and merge patches allows a
+ single maintainer to process incoming changes even at very
+ high rates. And when that becomes too much, git-pull provides
+ an easy way for that maintainer to delegate this job to other
+ maintainers while still allowing optional review of incoming
+ changes.
+ - Since every developer's repository has the same complete copy
+ of the project history, no repository is special, and it is
+ trivial for another developer to take over maintenance of a
+ project, either by mutual agreement, or because a maintainer
+ becomes unresponsive or difficult to work with.
+ - The lack of a central group of "committers" means there is
+ less need for formal decisions about who is "in" and who is
+ "out".
+
[[setting-up-gitweb]]
Allowing web browsing of a repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
allow people to get to important topics without necessarily reading
everything in between.
-Say something about .gitignore.
-
Scan Documentation/ for other stuff left out; in particular:
howto's
some of technical/?
projects / git.git / commitdiff