gitlink:git-add[1]::
- Add file contents to the changeset to be committed next.
+ Add file contents to the index.
gitlink:git-am[1]::
Apply a series of patches from a mailbox.
<h2>NAME</h2>\r
<div class="sectionbody">\r
<p>git-add -\r
- Add file contents to the changeset to be committed next\r
+ Add file contents to the index\r
</p>\r
</div>\r
</div>\r
</div>\r
<h2>DESCRIPTION</h2>\r
<div class="sectionbody">\r
-<p>All the changed file contents to be committed together in a single set\r
-of changes must be "added" with the <em>add</em> command before using the\r
-<em>commit</em> command. This is not only for adding new files. Even modified\r
-files must be added to the set of changes about to be committed.</p>\r
-<p>This command can be performed multiple times before a commit. The added\r
-content corresponds to the state of specified file(s) at the time the\r
-<em>add</em> command is used. This means the <em>commit</em> command will not consider\r
-subsequent changes to already added content if it is not added again before\r
-the commit.</p>\r
-<p>The <em>git status</em> command can be used to obtain a summary of what is included\r
-for the next commit.</p>\r
-<p>This command can be used to add ignored files with <tt>-f</tt> (force)\r
-option, but they have to be\r
-explicitly and exactly specified from the command line. File globbing\r
-and recursive behaviour do not add ignored files.</p>\r
+<p>This command adds the current content of new or modified files to the\r
+index, thus staging that content for inclusion in the next commit.</p>\r
+<p>The "index" holds a snapshot of the content of the working tree, and it\r
+is this snapshot that is taken as the contents of the next commit. Thus\r
+after making any changes to the working directory, and before running\r
+the commit command, you must use the <em>add</em> command to add any new or\r
+modified files to the index.</p>\r
+<p>This command can be performed multiple times before a commit. It only\r
+adds the content of the specified file(s) at the time the add command is\r
+run; if you want subsequent changes included in the next commit, then\r
+you must run <em>git add</em> again to add the new content to the index.</p>\r
+<p>The <em>git status</em> command can be used to obtain a summary of which\r
+files have changes that are staged for the next commit.</p>\r
+<p>The <em>add</em> command can be used to add ignored files with <tt>-f</tt> (force)\r
+option, but they have to be explicitly and exactly specified from the\r
+command line. File globbing and recursive behaviour do not add ignored\r
+files.</p>\r
<p>Please see <a href="git-commit.html">git-commit(1)</a> for alternative ways to add content to a\r
commit.</p>\r
</div>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 19-Jul-2007 02:09:30 UTC\r
+Last updated 06-Aug-2007 04:38:48 UTC\r
</div>\r
</div>\r
</body>\r
NAME
----
-git-add - Add file contents to the changeset to be committed next
+git-add - Add file contents to the index
SYNOPSIS
--------
DESCRIPTION
-----------
-All the changed file contents to be committed together in a single set
-of changes must be "added" with the 'add' command before using the
-'commit' command. This is not only for adding new files. Even modified
-files must be added to the set of changes about to be committed.
-
-This command can be performed multiple times before a commit. The added
-content corresponds to the state of specified file(s) at the time the
-'add' command is used. This means the 'commit' command will not consider
-subsequent changes to already added content if it is not added again before
-the commit.
-
-The 'git status' command can be used to obtain a summary of what is included
-for the next commit.
-
-This command can be used to add ignored files with `-f` (force)
-option, but they have to be
-explicitly and exactly specified from the command line. File globbing
-and recursive behaviour do not add ignored files.
+This command adds the current content of new or modified files to the
+index, thus staging that content for inclusion in the next commit.
+
+The "index" holds a snapshot of the content of the working tree, and it
+is this snapshot that is taken as the contents of the next commit. Thus
+after making any changes to the working directory, and before running
+the commit command, you must use the 'add' command to add any new or
+modified files to the index.
+
+This command can be performed multiple times before a commit. It only
+adds the content of the specified file(s) at the time the add command is
+run; if you want subsequent changes included in the next commit, then
+you must run 'git add' again to add the new content to the index.
+
+The 'git status' command can be used to obtain a summary of which
+files have changes that are staged for the next commit.
+
+The 'add' command can be used to add ignored files with `-f` (force)
+option, but they have to be explicitly and exactly specified from the
+command line. File globbing and recursive behaviour do not add ignored
+files.
Please see gitlink:git-commit[1] for alternative ways to add content to a
commit.
<dd>\r
<p>\r
Usually, the command refuses to update a remote ref that is\r
- not a descendant of the local ref used to overwrite it.\r
+ not an ancestor of the local ref used to overwrite it.\r
This flag disables the check. This can cause the\r
remote repository to lose commits; use it with care.\r
</p>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 19-Jul-2007 02:09:49 UTC\r
+Last updated 06-Aug-2007 04:38:48 UTC\r
</div>\r
</div>\r
</body>\r
-f, \--force::
Usually, the command refuses to update a remote ref that is
- not a descendant of the local ref used to overwrite it.
+ not an ancestor of the local ref used to overwrite it.
This flag disables the check. This can cause the
remote repository to lose commits; use it with care.
</dt>\r
<dd>\r
<p>\r
- Add file contents to the changeset to be committed next.\r
+ Add file contents to the index.\r
</p>\r
</dd>\r
<dt>\r
</p>\r
</dd>\r
<dt>\r
+<em>GIT_SSH</em>\r
+</dt>\r
+<dd>\r
+<p>\r
+ If this environment variable is set then <a href="git-fetch.html">git-fetch(1)</a>\r
+ and <a href="git-push.html">git-push(1)</a> will use this command instead\r
+ of <tt>ssh</tt> when they need to connect to a remote system.\r
+ The <em>GIT_SSH</em> command will be given exactly two arguments:\r
+ the <em>username@host</em> (or just <em>host</em>) from the URL and the\r
+ shell command to execute on that remote system.\r
+</p>\r
+<p>To pass options to the program that you want to list in GIT_SSH\r
+you will need to wrap the program and options into a shell script,\r
+then set GIT_SSH to refer to the shell script.</p>\r
+<p>Usually it is easier to configure any desired options through your\r
+personal <tt>.ssh/config</tt> file. Please consult your ssh documentation\r
+for further details.</p>\r
+</dd>\r
+<dt>\r
<em>GIT_FLUSH</em>\r
</dt>\r
<dd>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 20-Jul-2007 10:27:39 UTC\r
+Last updated 06-Aug-2007 04:38:49 UTC\r
</div>\r
</div>\r
</body>\r
to an empty string or to the value "cat", git will not launch
a pager.
+'GIT_SSH'::
+ If this environment variable is set then gitlink:git-fetch[1]
+ and gitlink:git-push[1] will use this command instead
+ of `ssh` when they need to connect to a remote system.
+ The 'GIT_SSH' command will be given exactly two arguments:
+ the 'username@host' (or just 'host') from the URL and the
+ shell command to execute on that remote system.
++
+To pass options to the program that you want to list in GIT_SSH
+you will need to wrap the program and options into a shell script,
+then set GIT_SSH to refer to the shell script.
++
+Usually it is easier to configure any desired options through your
+personal `.ssh/config` file. Please consult your ssh documentation
+for further details.
+
'GIT_FLUSH'::
If this environment variable is set to "1", then commands such
as git-blame (in incremental mode), git-rev-list, git-log,
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><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="id189136"></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="#id264725">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="#Finding-comments-with-given-content">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 Reference</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="id264725"></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=UTF-8"><title>Git User's Manual (for version 1.5.
3 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="id189136"></a>Git User's Manual (for version 1.5.3 or newer)</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#id264725">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="#Finding-comments-with-given-content">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><dt><span class="section"><a href="#interrupted-work">Temporarily setting aside work in progress</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 Reference</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="id264725"></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
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
+<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><
dt><span class="section"><a href="#interrupted-work">Temporarily setting aside work in progress</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>
# be included if you ran "commit" now.<br>
$ git diff HEAD # difference between HEAD and working tree; what<br>
# would be committed if you ran "commit -a" now.<br>
-$ git status # a brief per-file summary of the above.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="creating-good-commit-messages"></a>Creating good commit messages</h2></div></div></div><p>Though not required, it's a good idea to begin the commit message
+$ git status # a brief per-file summary of the above.</p></div><p>You can also use <a href="git-gui.html" target="_top">git-gui(1)</a> to create commits, view changes in
+the index and the working tree files, and individually select diff hunks
+for inclusion in the index (by right-clicking on the diff hunk and
+choosing "Stage Hunk For Commit").</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="creating-good-commit-messages"></a>Creating good commit messages</h2></div></div></div><p>Though not required, it's a good idea to begin the commit message
with a single short (less than 50 character) line summarizing the
change, followed by a blank line and then a more thorough
description. Tools that turn commits into email, for example, use
name: the command</p><div class="literallayout"><p>$ git checkout HEAD^ path/to/file</p></div><p>replaces path/to/file by the contents it had in the commit HEAD^, and
also updates the index to match. It does not change branches.</p><p>If you just want to look at an old version of the file, without
modifying the working directory, you can do that with
-<a href="git-show.html" target="_top">git-show(1)</a>:</p><div class="literallayout"><p>$ git show HEAD^:path/to/file</p></div><p>which will display the given version of the file.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ensuring-good-performance"></a>Ensuring good performance</h2></div></div></div><p>On large repositories, git depends on compression to keep the history
+<a href="git-show.html" target="_top">git-show(1)</a>:</p><div class="literallayout"><p>$ git show HEAD^:path/to/file</p></div><p>which will display the given version of the file.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="interrupted-work"></a>Temporarily setting aside work in progress</h3></div></div></div><p>While you are in the middle of working on something complicated, you
+find an unrelated but obvious and trivial bug. You would like to fix it
+before continuing. You can use <a href="git-stash.html" target="_top">git-stash(1)</a> to save the current
+state of your work, and after fixing the bug (or, optionally after doing
+so on a different branch and then coming back), unstash the
+work-in-progress changes.</p><div class="literallayout"><p>$ git stash "work in progress for foo feature"</p></div><p>This command will save your changes away to the <code class="literal">stash</code>, and
+reset your working tree and the index to match the tip of your
+current branch. Then you can make your fix as usual.</p><div class="literallayout"><p>... edit and test ...<br>
+$ git commit -a -m "blorpl: typofix"</p></div><p>After that, you can go back to what you were working on with
+<code class="literal">git stash apply</code>:</p><div class="literallayout"><p>$ git stash apply</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ensuring-good-performance"></a>Ensuring good performance</h2></div></div></div><p>On large repositories, git depends on compression to keep the history
information from taking up to much space on disk or in memory.</p><p>This compression is not performed automatically. Therefore you
should occasionally run <a href="git-gc.html" target="_top">git-gc(1)</a>:</p><div class="literallayout"><p>$ git gc</p></div><p>to recompress the archive. This can be very time-consuming, so
you may prefer to run git-gc when you are not doing other work.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ensuring-reliability"></a>Ensuring reliability</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="checking-for-corruption"></a>Checking the repository for corruption</h3></div></div></div><p>The <a href="git-fsck.html" target="_top">git-fsck(1)</a> command runs a number of self-consistency checks
and how to merge two branches. So you can merge in changes from the
original repository's master branch with:</p><div class="literallayout"><p>$ git fetch<br>
$ git merge origin/master</p></div><p>However, the <a href="git-pull.html" target="_top">git-pull(1)</a> command provides a way to do this in
-one step:</p><div class="literallayout"><p>$ git pull origin master</p></div><p>In fact, "origin" is normally the default repository to pull from,
-and the default branch is normally the HEAD of the remote repository,
-so often you can accomplish the above with just</p><div class="literallayout"><p>$ git pull</p></div><p>See the descriptions of the branch.<name>.remote and branch.<name>.merge
-options in <a href="git-config.html" target="_top">git-config(1)</a> to learn how to control these defaults
-depending on the current branch. Also note that the —track option to
-<a href="git-branch.html" target="_top">git-branch(1)</a> and <a href="git-checkout.html" target="_top">git-checkout(1)</a> can be used to
-automatically set the default remote branch to pull from at the time
-that a branch is created:</p><div class="literallayout"><p>$ git checkout --track -b maint origin/maint</p></div><p>In addition to saving you keystrokes, "git pull" also helps you by
+one step:</p><div class="literallayout"><p>$ git pull origin master</p></div><p>In fact, if you have "master" checked out, then by default "git pull"
+merges from the HEAD branch of the origin repository. So often you can
+accomplish the above with just a simple</p><div class="literallayout"><p>$ git pull</p></div><p>More generally, a branch that is created from a remote branch will pull
+by default from that branch. See the descriptions of the
+branch.<name>.remote and branch.<name>.merge options in
+<a href="git-config.html" target="_top">git-config(1)</a>, and the discussion of the —track option in
+<a href="git-checkout.html" target="_top">git-checkout(1)</a>, to learn how to control these defaults.</p><p>In addition to saving you keystrokes, "git pull" also helps you by
producing a default commit message documenting the branch and
repository that you pulled from.</p><p>(But note that no such commit will be created in the case of a
<a href="#fast-forwards" title="Fast-forward merges">fast forward</a>; instead, your branch will just be
series of patches on top of "origin", you might do something like:</p><div class="literallayout"><p>$ git checkout -b mywork-new origin<br>
$ gitk origin..mywork &</p></div><p>And browse through the list of patches in the mywork branch using gitk,
applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using commit
-—amend.</p><p>Another technique is to use git-format-patch to create a series of
+cherry-pick, and possibly modifying them as you go using commit —amend.
+The git-gui[1] command may also help as it allows you to individually
+select diff hunks for inclusion in the index (by right-clicking on the
+diff hunk and choosing "Stage Hunk for Commit").</p><p>Another technique is to use git-format-patch to create a series of
patches, then reset the state to before the patches:</p><div class="literallayout"><p>$ git format-patch origin<br>
$ git reset --hard origin</p></div><p>Then modify, reorder, or eliminate patches as preferred before applying
them again with <a href="git-am.html" target="_top">git-am(1)</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="patch-series-tools"></a>Other tools</h2></div></div></div><p>There are numerous other tools, such as stgit, which exist for the
-Git User's Manual (for version 1.5.1 or newer)
+Git User's Manual (for version 1.5.3 or newer)
______________________________________________
$ git status # a brief per-file summary of the above.
-------------------------------------------------
+You can also use gitlink:git-gui[1] to create commits, view changes in
+the index and the working tree files, and individually select diff hunks
+for inclusion in the index (by right-clicking on the diff hunk and
+choosing "Stage Hunk For Commit").
+
[[creating-good-commit-messages]]
Creating good commit messages
-----------------------------
which will display the given version of the file.
+[[interrupted-work]]
+Temporarily setting aside work in progress
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While you are in the middle of working on something complicated, you
+find an unrelated but obvious and trivial bug. You would like to fix it
+before continuing. You can use gitlink:git-stash[1] to save the current
+state of your work, and after fixing the bug (or, optionally after doing
+so on a different branch and then coming back), unstash the
+work-in-progress changes.
+
+------------------------------------------------
+$ git stash "work in progress for foo feature"
+------------------------------------------------
+
+This command will save your changes away to the `stash`, and
+reset your working tree and the index to match the tip of your
+current branch. Then you can make your fix as usual.
+
+------------------------------------------------
+... edit and test ...
+$ git commit -a -m "blorpl: typofix"
+------------------------------------------------
+
+After that, you can go back to what you were working on with
+`git stash apply`:
+
+------------------------------------------------
+$ git stash apply
+------------------------------------------------
+
+
[[ensuring-good-performance]]
Ensuring good performance
-------------------------
$ git pull origin master
-------------------------------------------------
-In fact, "origin" is normally the default repository to pull from,
-and the default branch is normally the HEAD of the remote repository,
-so often you can accomplish the above with just
+In fact, if you have "master" checked out, then by default "git pull"
+merges from the HEAD branch of the origin repository. So often you can
+accomplish the above with just a simple
-------------------------------------------------
$ git pull
-------------------------------------------------
-See the descriptions of the branch.<name>.remote and branch.<name>.merge
-options in gitlink:git-config[1] to learn how to control these defaults
-depending on the current branch. Also note that the --track option to
-gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to
-automatically set the default remote branch to pull from at the time
-that a branch is created:
-
--------------------------------------------------
-$ git checkout --track -b maint origin/maint
--------------------------------------------------
+More generally, a branch that is created from a remote branch will pull
+by default from that branch. See the descriptions of the
+branch.<name>.remote and branch.<name>.merge options in
+gitlink:git-config[1], and the discussion of the --track option in
+gitlink:git-checkout[1], to learn how to control these defaults.
In addition to saving you keystrokes, "git pull" also helps you by
producing a default commit message documenting the branch and
And browse through the list of patches in the mywork branch using gitk,
applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using commit
---amend.
+cherry-pick, and possibly modifying them as you go using commit --amend.
+The git-gui[1] command may also help as it allows you to individually
+select diff hunks for inclusion in the index (by right-clicking on the
+diff hunk and choosing "Stage Hunk for Commit").
Another technique is to use git-format-patch to create a series of
patches, then reset the state to before the patches:
projects / git.git / commitdiff