From c51fede9f2fdd66e06416d7865b023924b52e659 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 12 Mar 2007 07:29:20 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.0.3-382-g34572 --- docbook-xsl.css | 286 ++++++++++++++++++++++++++++++++++++++++++ git-commit.html | 14 ++- git-commit.txt | 9 +- git-fast-import.html | 8 +- git-fast-import.txt | 6 +- git-format-patch.html | 23 +++- git-format-patch.txt | 16 ++- git-receive-pack.html | 34 ++--- git-receive-pack.txt | 32 ++--- git-send-email.html | 53 +++++++- git-send-email.txt | 23 +++- git.html | 2 +- glossary.html | 22 ++-- user-manual.html | 167 ++++++++++++------------ user-manual.txt | 45 ++++--- 15 files changed, 570 insertions(+), 170 deletions(-) create mode 100644 docbook-xsl.css diff --git a/docbook-xsl.css b/docbook-xsl.css new file mode 100644 index 000000000..8821e305d --- /dev/null +++ b/docbook-xsl.css @@ -0,0 +1,286 @@ +/* + CSS stylesheet for XHTML produced by DocBook XSL stylesheets. + Tested with XSL stylesheets 1.61.2, 1.67.2 +*/ + +span.strong { + font-weight: bold; +} + +body blockquote { + margin-top: .75em; + line-height: 1.5; + margin-bottom: .75em; +} + +html body { + margin: 1em 5% 1em 5%; + line-height: 1.2; +} + +body div { + margin: 0; +} + +h1, h2, h3, h4, h5, h6, +div.toc p b, +div.list-of-figures p b, +div.list-of-tables p b, +div.abstract p.title +{ + color: #527bbd; + font-family: tahoma, verdana, sans-serif; +} + +div.toc p:first-child, +div.list-of-figures p:first-child, +div.list-of-tables p:first-child, +div.example p.title +{ + margin-bottom: 0.2em; +} + +body h1 { + margin: .0em 0 0 -4%; + line-height: 1.3; + border-bottom: 2px solid silver; +} + +body h2 { + margin: 0.5em 0 0 -4%; + line-height: 1.3; + border-bottom: 2px solid silver; +} + +body h3 { + margin: .8em 0 0 -3%; + line-height: 1.3; +} + +body h4 { + margin: .8em 0 0 -3%; + line-height: 1.3; +} + +body h5 { + margin: .8em 0 0 -2%; + line-height: 1.3; +} + +body h6 { + margin: .8em 0 0 -1%; + line-height: 1.3; +} + +body hr { + border: none; /* Broken on IE6 */ +} +div.footnotes hr { + border: 1px solid silver; +} + +div.navheader th, div.navheader td, div.navfooter td { + font-family: sans-serif; + font-size: 0.9em; + font-weight: bold; + color: #527bbd; +} +div.navheader img, div.navfooter img { + border-style: none; +} +div.navheader a, div.navfooter a { + font-weight: normal; +} +div.navfooter hr { + border: 1px solid silver; +} + +body td { + line-height: 1.2 +} + +body th { + line-height: 1.2; +} + +ol { + line-height: 1.2; +} + +ul, body dir, body menu { + line-height: 1.2; +} + +html { + margin: 0; + padding: 0; +} + +body h1, body h2, body h3, body h4, body h5, body h6 { + margin-left: 0 +} + +body pre { + margin: 0.5em 10% 0.5em 1em; + line-height: 1.0; + color: navy; +} + +tt.literal, code.literal { + color: navy; +} + +div.literallayout p { + padding: 0em; + margin: 0em; +} + +div.literallayout { + font-family: monospace; +# margin: 0.5em 10% 0.5em 1em; + margin: 0em; + color: navy; + border: 1px solid silver; + background: #f4f4f4; + padding: 0.5em; +} + +.programlisting, .screen { + border: 1px solid silver; + background: #f4f4f4; + margin: 0.5em 10% 0.5em 0; + padding: 0.5em 1em; +} + +div.sidebar { + background: #ffffee; + margin: 1.0em 10% 0.5em 0; + padding: 0.5em 1em; + border: 1px solid silver; +} +div.sidebar * { padding: 0; } +div.sidebar div { margin: 0; } +div.sidebar p.title { + font-family: sans-serif; + margin-top: 0.5em; + margin-bottom: 0.2em; +} + +div.bibliomixed { + margin: 0.5em 5% 0.5em 1em; +} + +div.glossary dt { + font-weight: bold; +} +div.glossary dd p { + margin-top: 0.2em; +} + +dl { + margin: .8em 0; + line-height: 1.2; +} + +dt { + margin-top: 0.5em; +} + +dt span.term { + font-style: italic; +} + +div.variablelist dd p { + margin-top: 0; +} + +div.itemizedlist li, div.orderedlist li { + margin-left: -0.8em; + margin-top: 0.5em; +} + +ul, ol { + list-style-position: outside; +} + +div.sidebar ul, div.sidebar ol { + margin-left: 2.8em; +} + +div.itemizedlist p.title, +div.orderedlist p.title, +div.variablelist p.title +{ + margin-bottom: -0.8em; +} + +div.revhistory table { + border-collapse: collapse; + border: none; +} +div.revhistory th { + border: none; + color: #527bbd; + font-family: tahoma, verdana, sans-serif; +} +div.revhistory td { + border: 1px solid silver; +} + +/* Keep TOC and index lines close together. */ +div.toc dl, div.toc dt, +div.list-of-figures dl, div.list-of-figures dt, +div.list-of-tables dl, div.list-of-tables dt, +div.indexdiv dl, div.indexdiv dt +{ + line-height: normal; + margin-top: 0; + margin-bottom: 0; +} + +/* + Table styling does not work because of overriding attributes in + generated HTML. +*/ +div.table table, +div.informaltable table +{ + margin-left: 0; + margin-right: 5%; + margin-bottom: 0.8em; +} +div.informaltable table +{ + margin-top: 0.4em +} +div.table thead, +div.table tfoot, +div.table tbody, +div.informaltable thead, +div.informaltable tfoot, +div.informaltable tbody +{ + /* No effect in IE6. */ + border-top: 2px solid #527bbd; + border-bottom: 2px solid #527bbd; +} +div.table thead, div.table tfoot, +div.informaltable thead, div.informaltable tfoot +{ + font-weight: bold; +} + +div.mediaobject img { + border: 1px solid silver; + margin-bottom: 0.8em; +} +div.figure p.title, +div.table p.title +{ + margin-top: 1em; + margin-bottom: 0.4em; +} + +@media print { + div.navheader, div.navfooter { display: none; } +} diff --git a/git-commit.html b/git-commit.html index 757de8dbc..125b1f697 100644 --- a/git-commit.html +++ b/git-commit.html @@ -273,8 +273,9 @@ git-commit(1) Manual Page

SYNOPSIS

-
git-commit [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg> | - --amend] [--no-verify] [-e] [--author <author>] +
git-commit [-a | --interactive] [-s] [-v] + [(-c | -C) <commit> | -F <file> | -m <msg> | --amend] + [--no-verify] [-e] [--author <author>] [--] [[-i | -o ]<file>…]

DESCRIPTION

@@ -312,6 +313,13 @@ by using the -a switch with the commit command to automatically "add" removed from the working tree, and perform the actual commit.

+
  • +

    +by using the --interactive switch with the commit command to decide one + by one which files should be part of the commit, before finalizing the + operation. Currently, this is done by invoking git-add --interactive. +

    +

    • The git-status(1) command can be used to obtain a summary of what is included by any of the above for the next @@ -656,7 +664,7 @@ Junio C Hamano <junkio@cox.net>

    diff --git a/git-commit.txt b/git-commit.txt index 2187eee41..53a7bb089 100644 --- a/git-commit.txt +++ b/git-commit.txt @@ -8,8 +8,9 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git-commit' [-a] [-s] [-v] [(-c | -C) | -F | -m | - --amend] [--no-verify] [-e] [--author ] +'git-commit' [-a | --interactive] [-s] [-v] + [(-c | -C) | -F | -m | --amend] + [--no-verify] [-e] [--author ] [--] [[-i | -o ]...] DESCRIPTION @@ -35,6 +36,10 @@ methods: before, and to automatically "rm" files that have been removed from the working tree, and perform the actual commit. +5. by using the --interactive switch with the 'commit' command to decide one + by one which files should be part of the commit, before finalizing the + operation. Currently, this is done by invoking `git-add --interactive`. + The gitlink:git-status[1] command can be used to obtain a summary of what is included by any of the above for the next commit by giving the same set of parameters you would give to diff --git a/git-fast-import.html b/git-fast-import.html index 6ff782cf3..0fb105083 100644 --- a/git-fast-import.html +++ b/git-fast-import.html @@ -805,7 +805,7 @@ in octal. Git only supports the following modes:

    In both formats <path> is the complete path of the file to be added (if not already existing) or modified (if already existing).

    -

    A <path> string must use UNIX-style directory seperators (forward +

    A <path> string must use UNIX-style directory separators (forward slash /), may contain any byte other than LF, and must not start with double quote (").

    If an LF or double quote must be encoded into <path> shell-style @@ -819,12 +819,12 @@ contain an empty directory component (e.g. foo//bar is invalid),

  • -end with a directory seperator (e.g. foo/ is invalid), +end with a directory separator (e.g. foo/ is invalid),

  • -start with a directory seperator (e.g. /foo is invalid), +start with a directory separator (e.g. /foo is invalid),

  • @@ -1204,7 +1204,7 @@ memory footprint (less than 2.7 MiB per active branch).

    diff --git a/git-fast-import.txt b/git-fast-import.txt index 7e3d2b1a9..eaba6fd4c 100644 --- a/git-fast-import.txt +++ b/git-fast-import.txt @@ -462,7 +462,7 @@ in octal. Git only supports the following modes: In both formats `` is the complete path of the file to be added (if not already existing) or modified (if already existing). -A `` string must use UNIX-style directory seperators (forward +A `` string must use UNIX-style directory separators (forward slash `/`), may contain any byte other than `LF`, and must not start with double quote (`"`). @@ -472,8 +472,8 @@ quoting should be used, e.g. `"path/with\n and \" in it"`. The value of `` must be in canoncial form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), -* end with a directory seperator (e.g. `foo/` is invalid), -* start with a directory seperator (e.g. `/foo` is invalid), +* end with a directory separator (e.g. `foo/` is invalid), +* start with a directory separator (e.g. `/foo` is invalid), * contain the special component `.` or `..` (e.g. `foo/./bar` and `foo/../bar` are invalid). diff --git a/git-format-patch.html b/git-format-patch.html index f1bdd8d4f..65d18d047 100644 --- a/git-format-patch.html +++ b/git-format-patch.html @@ -273,8 +273,9 @@ git-format-patch(1) Manual Page

    SYNOPSIS

    -
    git-format-patch [<common diff options>] [-n | -k] [-o <dir> | --stdout] - [--attach] [--thread] [-s | --signoff] [--start-number <n>] +
    git-format-patch [-n | -k] [-o <dir> | --stdout] [--thread] + [--attach[=<boundary>] | --inline[=<boundary>]] + [-s | --signoff] [<common diff options>] [--start-number <n>] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] <since>[..<until>]
    @@ -713,11 +714,23 @@ reference.

    ---attach +--attach[=<boundary>]

    - Create attachments instead of inlining patches. + Create multipart/mixed attachment, the first part of + which is the commit message and the patch itself in the + second part, with "Content-Disposition: attachment". +

    +
    +
    +--inline[=<boundary>] +
    +
    +

    + Create multipart/mixed attachment, the first part of + which is the commit message and the patch itself in the + second part, with "Content-Disposition: inline".

    @@ -846,7 +859,7 @@ git-format-patch -3
    diff --git a/git-format-patch.txt b/git-format-patch.txt index 84eabebe0..111d7c60b 100644 --- a/git-format-patch.txt +++ b/git-format-patch.txt @@ -9,8 +9,9 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git-format-patch' [] [-n | -k] [-o | --stdout] - [--attach] [--thread] [-s | --signoff] [--start-number ] +'git-format-patch' [-n | -k] [-o | --stdout] [--thread] + [--attach[=] | --inline[=]] + [-s | --signoff] [] [--start-number ] [--in-reply-to=Message-Id] [--suffix=.] [--ignore-if-in-upstream] [..] @@ -70,8 +71,15 @@ include::diff-options.txt[] Print all commits to the standard output in mbox format, instead of creating a file for each one. ---attach:: - Create attachments instead of inlining patches. +--attach[=]:: + Create multipart/mixed attachment, the first part of + which is the commit message and the patch itself in the + second part, with "Content-Disposition: attachment". + +--inline[=]:: + Create multipart/mixed attachment, the first part of + which is the commit message and the patch itself in the + second part, with "Content-Disposition: inline". --thread:: Add In-Reply-To and References headers to make the second and diff --git a/git-receive-pack.html b/git-receive-pack.html index d02c4acfb..d3ef3237e 100644 --- a/git-receive-pack.html +++ b/git-receive-pack.html @@ -308,14 +308,14 @@ are not fast-forwards.

    pre-receive Hook

    Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists -and is executable, it will be invoked once, with three parameters -per ref to be updated:

    +and is executable, it will be invoked once with no parameters. The +standard input of the hook will be one line per ref to be updated:

    -
    $GIT_DIR/hooks/pre-receive (refname sha1-old sha1-new)+
    +
    sha1-old SP sha1-new SP refname LF
    -

    The refname parameter is relative to $GIT_DIR; e.g. for the master -head this is "refs/heads/master". The two sha1 arguments after +

    The refname value is relative to $GIT_DIR; e.g. for the master +head this is "refs/heads/master". The two sha1 values before each refname are the object names for the refname before and after sha1-old and sha1-new should be valid objects in the repository.

    This hook is called before any refname is updated and before any @@ -349,14 +349,15 @@ this hook. Consider using the post-receive hook instead.

    After all refs were updated (or attempted to be updated), if any ref update was successful, and if $GIT_DIR/hooks/post-receive -file exists and is executable, it will be invoke once with three -parameters for each successfully updated ref:

    +file exists and is executable, it will be invoke once with no +parameters. The standard input of the hook will be one line +for each successfully updated ref:

    -
    $GIT_DIR/hooks/post-receive (refname sha1-old sha1-new)+
    +
    sha1-old SP sha1-new SP refname LF
    -

    The refname parameter is relative to $GIT_DIR; e.g. for the master -head this is "refs/heads/master". The two sha1 arguments after +

    The refname value is relative to $GIT_DIR; e.g. for the master +head this is "refs/heads/master". The two sha1 values before each refname are the object names for the refname before and after the update. Refs that were created will have sha1-old equal to the repository.

    @@ -367,18 +368,17 @@ ref listing the commits pushed to the repository:

    #!/bin/sh
 # mail out commit update information.
-while test $# -gt 0
+while read oval nval ref
 do
-        if expr "$2" : '0*$' >/dev/null
+        if expr "$oval" : '0*$' >/dev/null
         then
                 echo "Created a new ref, with the following commits:"
-                git-rev-list --pretty "$2"
+                git-rev-list --pretty "$nval"
         else
                 echo "New commits:"
-                git-rev-list --pretty "$3" "^$2"
+                git-rev-list --pretty "$nval" "^$oval"
         fi |
-        mail -s "Changes to ref $1" commit-list@mydomain
-        shift; shift; shift; # discard this ref's args
+        mail -s "Changes to ref $ref" commit-list@mydomain
 done
 exit 0
    @@ -425,7 +425,7 @@ exec git-update-server-info
    diff --git a/git-receive-pack.txt b/git-receive-pack.txt index 3cf55111c..6914aa59c 100644 --- a/git-receive-pack.txt +++ b/git-receive-pack.txt @@ -40,13 +40,13 @@ OPTIONS pre-receive Hook ---------------- Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists -and is executable, it will be invoked once, with three parameters -per ref to be updated: +and is executable, it will be invoked once with no parameters. The +standard input of the hook will be one line per ref to be updated: - $GIT_DIR/hooks/pre-receive (refname sha1-old sha1-new)+ + sha1-old SP sha1-new SP refname LF -The refname parameter is relative to $GIT_DIR; e.g. for the master -head this is "refs/heads/master". The two sha1 arguments after +The refname value is relative to $GIT_DIR; e.g. for the master +head this is "refs/heads/master". The two sha1 values before each refname are the object names for the refname before and after the update. Refs to be created will have sha1-old equal to 0{40}, while refs to be deleted will have sha1-new equal to 0{40}, otherwise @@ -86,13 +86,14 @@ post-receive Hook ----------------- After all refs were updated (or attempted to be updated), if any ref update was successful, and if $GIT_DIR/hooks/post-receive -file exists and is executable, it will be invoke once with three -parameters for each successfully updated ref: +file exists and is executable, it will be invoke once with no +parameters. The standard input of the hook will be one line +for each successfully updated ref: - $GIT_DIR/hooks/post-receive (refname sha1-old sha1-new)+ + sha1-old SP sha1-new SP refname LF -The refname parameter is relative to $GIT_DIR; e.g. for the master -head this is "refs/heads/master". The two sha1 arguments after +The refname value is relative to $GIT_DIR; e.g. for the master +head this is "refs/heads/master". The two sha1 values before each refname are the object names for the refname before and after the update. Refs that were created will have sha1-old equal to 0{40}, while refs that were deleted will have sha1-new equal to @@ -105,18 +106,17 @@ ref listing the commits pushed to the repository: #!/bin/sh # mail out commit update information. - while test $# -gt 0 + while read oval nval ref do - if expr "$2" : '0*$' >/dev/null + if expr "$oval" : '0*$' >/dev/null then echo "Created a new ref, with the following commits:" - git-rev-list --pretty "$2" + git-rev-list --pretty "$nval" else echo "New commits:" - git-rev-list --pretty "$3" "^$2" + git-rev-list --pretty "$nval" "^$oval" fi | - mail -s "Changes to ref $1" commit-list@mydomain - shift; shift; shift; # discard this ref's args + mail -s "Changes to ref $ref" commit-list@mydomain done exit 0 diff --git a/git-send-email.html b/git-send-email.html index 6a6e9aa29..e05b0b9d0 100644 --- a/git-send-email.html +++ b/git-send-email.html @@ -313,7 +313,8 @@ enabled interface to provide the necessary information.

    the first will be sent as replies to the first email sent. When using this, it is recommended that the first file given be an overview of the entire patch series. - Default is --chain-reply-to + Default is the value of the sendemail.chainreplyto configuration + value; if that is unspecified, default to --chain-reply-to.

    @@ -410,6 +411,54 @@ enabled interface to provide the necessary information.

    +

    CONFIGURATION

    +
    +
    +
    +sendemail.aliasesfile +
    +
    +

    + To avoid typing long email addresses, point this to one or more + email aliases files. You must also supply sendemail.aliasfiletype. +

    +
    +
    +sendemail.aliasfiletype +
    +
    +

    + Format of the file(s) specified in sendemail.aliasesfile. Must be + one of mutt, mailrc, pine, or gnus. +

    +
    +
    +sendemail.bcc +
    +
    +

    + Email address (or alias) to always bcc. +

    +
    +
    +sendemail.chainreplyto +
    +
    +

    + Boolean value specifying the default to the --chain_reply_to + parameter. +

    +
    +
    +sendemail.smtpserver +
    +
    +

    + Default smtp server to use. +

    +
    +
    +

    Author

    Written by Ryan Anderson <ryan@michonline.com>

    @@ -426,7 +475,7 @@ send_lots_of_email.pl by Greg Kroah-Hartman.

    diff --git a/git-send-email.txt b/git-send-email.txt index 35b0104e4..9b3aabb6f 100644 --- a/git-send-email.txt +++ b/git-send-email.txt @@ -40,7 +40,8 @@ The --cc option must be repeated for each user you want on the cc list. the first will be sent as replies to the first email sent. When using this, it is recommended that the first file given be an overview of the entire patch series. - Default is --chain-reply-to + Default is the value of the 'sendemail.chainreplyto' configuration + value; if that is unspecified, default to --chain-reply-to. --compose:: Use $EDITOR to edit an introductory message for the @@ -91,6 +92,26 @@ The --cc option must be repeated for each user you want on the cc list. The --to option must be repeated for each user you want on the to list. +CONFIGURATION +------------- +sendemail.aliasesfile:: + To avoid typing long email addresses, point this to one or more + email aliases files. You must also supply 'sendemail.aliasfiletype'. + +sendemail.aliasfiletype:: + Format of the file(s) specified in sendemail.aliasesfile. Must be + one of 'mutt', 'mailrc', 'pine', or 'gnus'. + +sendemail.bcc:: + Email address (or alias) to always bcc. + +sendemail.chainreplyto:: + Boolean value specifying the default to the '--chain_reply_to' + parameter. + +sendemail.smtpserver:: + Default smtp server to use. + Author ------ Written by Ryan Anderson diff --git a/git.html b/git.html index dfa720750..12b59118e 100644 --- a/git.html +++ b/git.html @@ -2309,7 +2309,7 @@ contributors on the git-list <git@vger.kernel.org>.

    diff --git a/glossary.html b/glossary.html index 6e32f6e49..7c7a06458 100644 --- a/glossary.html +++ b/glossary.html @@ -285,10 +285,10 @@ div.exampleblock-content { have a locally checked-out copy of any of the files under revision control. That is, all of the git administrative and control files that would normally be present in the - hidden .git sub-directory are directly present in - the repository.git directory - instead, and no other files are present and checked out. Usually - publishers of public repositories make bare repositories available. + hidden .git sub-directory are directly present in the + repository.git directory instead, + and no other files are present and checked out. Usually publishers of + public repositories make bare repositories available.

    @@ -675,8 +675,8 @@ div.exampleblock-content { at least one upstream project which they track. By default origin is used for that purpose. New upstream updates will be fetched into remote tracking branches named - origin/name-of-upstream-branch, which you - can see using "git branch -r". + origin/name-of-upstream-branch, which you can see using + "git branch -r".

    @@ -715,9 +715,9 @@ div.exampleblock-content {

    The term pickaxe refers to an option to the diffcore routines that help select changes that add or delete a given text - string. With the —pickaxe-all option, it can be used to - view the full changeset that introduced or removed, - say, a particular line of text. See git-diff(1). + string. With the —pickaxe-all option, it can be used to view the full + changeset that introduced or removed, say, a + particular line of text. See git-diff(1).

    @@ -898,7 +898,7 @@ div.exampleblock-content { itself, it is of the format ref: refs/some/thing and when referenced, it recursively dereferences to this reference. HEAD is a prime example of a symref. Symbolic references are - manipulated with the ref.html">git-symbolic-ref(1) command. + manipulated with the git-symbolic-ref(1) command.

    @@ -1019,7 +1019,7 @@ the git-list <git@vger.kernel.org>.

    diff --git a/user-manual.html b/user-manual.html index 7892b10c8..2caf56d1a 100644 --- a/user-manual.html +++ b/user-manual.html @@ -1,4 +1,4 @@ -Git User's Manual

    Git User's Manual

    Table of Contents

    Preface
    1. Git Quick Start
    Creating a new repository
    Managing branches
    Exploring history
    Making changes
    Merging
    Sharing your changes
    Repository maintenance
    2. Repositories and Branches
    How to get a git repository
    How to check out a different version of a project
    Understanding History: Commits
    Understanding history: commits, parents, and reachability
    Understanding history: History diagrams
    Understanding history: What is a branch?
    Manipulating branches
    Examining branches from a remote repository
    Naming branches, tags, and other references
    Updating a repository with git fetch
    Fetching branches from other repositories
    3. Exploring git history
    How to use bisect to find a regression
    Naming commits
    Creating tags
    Browsing revisions
    Generating diffs
    Viewing old file versions
    Examples
    Check whether two branches point at the same history
    Find first tagged version including a given fix
    4. Developing with git
    Telling git your name
    Creating a new repository
    how to make a commit
    creating good commit messages
    how to merge
    Resolving a merge
    Getting conflict-resolution help during a merge
    undoing a merge
    Fast-forward merges
    Fixing mistakes
    Fixing a mistake with a new commit
    Fixing a mistake by editing history
    Checking out an old version of a file
    Ensuring good performance
    Ensuring reliability
    Checking the repository for corruption
    Recovering lost changes
    5. Sharing development with others
    Getting updates with git pull
    Submitting patches to a project
    Importing patches to a project
    Setting up a public repository
    Exporting a git repository via http
    Exporting a git repository via the git protocol
    Pushing changes to a public repository
    Setting up a shared repository
    Allow web browsing of a repository
    Examples
    6. Rewriting history and maintaining patch series
    Creating the perfect patch series
    Keeping a patch series up to date using git-rebase
    Modifying a single commit
    Reordering or selecting from a patch series
    Other tools
    Problems with rewriting history
    7. Advanced branch management
    Fetching individual branches
    Understanding git history: fast-forwards
    Forcing git fetch to do non-fast-forward updates
    Configuring remote branches
    8. Git internals
    The Object Database
    Blob Object
    Tree Object
    Commit Object
    Trust
    Tag Object
    The "index" aka "Current Directory Cache"
    The Workflow
    working directory -> index
    index -> object database
    object database -> index
    index -> working directory
    Tying it all together
    Examining the data
    Merging multiple trees
    Merging multiple trees, continued
    How git stores objects efficiently: pack files
    Dangling objects
    9. Glossary of git terms
    10. Notes and todo list for this manual

    Preface

    This manual is designed to be readable by someone with basic unix +Git User's Manual

    Git User's Manual

    Table of Contents

    Preface
    1. Git Quick Start
    Creating a new repository
    Managing branches
    Exploring history
    Making changes
    Merging
    Sharing your changes
    Repository maintenance
    2. Repositories and Branches
    How to get a git repository
    How to check out a different version of a project
    Understanding History: Commits
    Understanding history: commits, parents, and reachability
    Understanding history: History diagrams
    Understanding history: What is a branch?
    Manipulating branches
    Examining branches from a remote repository
    Naming branches, tags, and other references
    Updating a repository with git fetch
    Fetching branches from other repositories
    3. Exploring git history
    How to use bisect to find a regression
    Naming commits
    Creating tags
    Browsing revisions
    Generating diffs
    Viewing old file versions
    Examples
    Check whether two branches point at the same history
    Find first tagged version including a given fix
    4. Developing with git
    Telling git your name
    Creating a new repository
    how to make a commit
    creating good commit messages
    how to merge
    Resolving a merge
    Getting conflict-resolution help during a merge
    undoing a merge
    Fast-forward merges
    Fixing mistakes
    Fixing a mistake with a new commit
    Fixing a mistake by editing history
    Checking out an old version of a file
    Ensuring good performance
    Ensuring reliability
    Checking the repository for corruption
    Recovering lost changes
    5. Sharing development with others
    Getting updates with git pull
    Submitting patches to a project
    Importing patches to a project
    Setting up a public repository
    Exporting a git repository via http
    Exporting a git repository via the git protocol
    Pushing changes to a public repository
    Setting up a shared repository
    Allow web browsing of a repository
    Examples
    6. Rewriting history and maintaining patch series
    Creating the perfect patch series
    Keeping a patch series up to date using git-rebase
    Modifying a single commit
    Reordering or selecting from a patch series
    Other tools
    Problems with rewriting history
    7. Advanced branch management
    Fetching individual branches
    Understanding git history: fast-forwards
    Forcing git fetch to do non-fast-forward updates
    Configuring remote branches
    8. Git internals
    The Object Database
    Blob Object
    Tree Object
    Commit Object
    Trust
    Tag Object
    The "index" aka "Current Directory Cache"
    The Workflow
    working directory -> index
    index -> object database
    object database -> index
    index -> working directory
    Tying it all together
    Examining the data
    Merging multiple trees
    Merging multiple trees, continued
    How git stores objects efficiently: pack files
    Dangling objects
    9. Glossary of git terms
    10. Notes and todo list for this manual

    Preface

    This manual is designed to be readable by someone with basic unix command-line skills, but no previous knowledge of git.

    Chapter 1 gives a brief overview of git commands, without any explanation; you may prefer to skip to chapter 2 on a first reading.

    Chapters 2 and 3 explain how to fetch and study a project using git—the tools you'd need to build and test a particular version of a @@ -173,10 +173,11 @@ if commit X is an ancestor of commit Y. Equivalently, you could say that Y is a descendent of X, or that there is a chain of parents leading from commit Y to commit X.

    Understanding history: History diagrams

    We will sometimes represent git history using diagrams like the one below. Commits are shown as "o", and the links between them with -lines drawn with - / and \. Time goes left to right:

            o--o--o <-- Branch A
-       /
-o--o--o <-- master
-                o--o--o <-- Branch B

    If we need to talk about a particular commit, the character "o" may +lines drawn with - / and \. Time goes left to right:

             o--o--o <-- Branch A
+        /
+ o--o--o <-- master
+        \
+         o--o--o <-- Branch B

    If we need to talk about a particular commit, the character "o" may be replaced with another letter or number.

    Understanding history: What is a branch?

    Though we've been using the word "branch" to mean a kind of reference to a particular commit, the word branch is also commonly used to refer to the line of commits leading up to that point. In the @@ -274,8 +275,8 @@ named <remote> will be updated.

    If you examine the file .git/config, a new stanza:

    $ cat .git/config
    ...
    [remote "linux-nfs"]
    -        url = git://linux-nfs.org/~bfields/git.git
    -        fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
    +        url = git://linux-nfs.org/pub/nfs-2.6.git
    +        fetch = +refs/heads/*:refs/remotes/linux-nfs/*
    ...

    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 @@ -406,7 +407,7 @@ available
       ! [v1.5.0-rc2] GIT v1.5.0-rc2
    ...

    then search for a line that looks like

    + ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
    available

    Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and -from v1.5.0-rc2, but not from v1.5.0-rc0.

    Chapter 4. Developing with git

    Table of Contents

    Telling git your name
    Creating a new repository
    how to make a commit
    creating good commit messages
    how to merge
    Resolving a merge
    Getting conflict-resolution help during a merge
    undoing a merge
    Fast-forward merges
    Fixing mistakes
    Fixing a mistake with a new commit
    Fixing a mistake by editing history
    Checking out an old version of a file
    Ensuring good performance
    Ensuring reliability
    Checking the repository for corruption
    Recovering lost changes

    Telling git your name

    Before creating any commits, you should introduce yourself to git. The +from v1.5.0-rc2, but not from v1.5.0-rc0.

    Chapter 4. Developing with git

    Table of Contents

    Telling git your name
    Creating a new repository
    how to make a commit
    creating good commit messages
    how to merge
    Resolving a merge
    Getting conflict-resolution help during a merge
    undoing a merge
    Fast-forward merges
    Fixing mistakes
    Fixing a mistake with a new commit
    Fixing a mistake by editing history
    Checking out an old version of a file
    Ensuring good performance
    Ensuring reliability
    Checking the repository for corruption
    Recovering lost changes

    Telling git your name

    Before creating any commits, you should introduce yourself to git. The easiest way to do so is:

    $ cat >~/.gitconfig <<\EOF
    [user]
            name = Your Name Comes Here
    @@ -452,17 +453,9 @@ body.

    < git-merge(1):

    $ git merge branchname

    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 -branch—then you are warned; the output may look something like this:

    $ git pull . next
    -Trying really trivial in-index merge...
    -fatal: Merge requires file-level merging
    -Nope.
    -Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
    -Merging:
    -15e2162 world
    -77976da goodbye
    -found 1 common ancestor(s):
    -d122ed4 initial
    -Auto-merging file.txt
    +branch—then you are warned; the output may look something like this:

    $ git merge next
    + 100% (4/4) done
    +Auto-merged file.txt
    CONFLICT (content): Merge conflict in file.txt
    Automatic merge failed; fix conflicts and then commit the result.

    Conflict markers are left in the problematic files, and after you resolve the conflicts manually, you can update the index @@ -484,7 +477,7 @@ $ some information about the merge. Normally you can just use this default message unchanged, but you may add additional commentary of your own if desired.

    The above is all you need to know to resolve a simple merge. But git -also provides more information to help resolve conflicts:

    Getting conflict-resolution help during a merge

    All of the changes that git was able to merge automatically are +also provides more information to help resolve conflicts:

    Getting conflict-resolution help during a merge

    All of the changes that git was able to merge automatically are already added to the index file, so git-diff(1) shows only the conflicts. It uses an unusual syntax:

    $ git diff
    diff --cc file.txt
    @@ -538,7 +531,7 @@ git-diff will (by default) no longer show diffs for that file.

    $ git reset --hard HEAD

    Or, if you've already commited the merge that you want to throw away,

    $ git reset --hard ORIG_HEAD

    However, this last command can be dangerous in some cases—never throw away a commit you have already committed if that commit may itself have been merged into another branch, as doing so may confuse -further merges.

    Fast-forward merges

    There is one special case not mentioned above, which is treated +further merges.

    Fast-forward merges

    There is one special case not mentioned above, which is treated differently. Normally, a merge results in a merge commit, with two parents, one pointing at each of the two lines of development that were merged.

    However, if one of the two lines of development is completely @@ -546,7 +539,7 @@ contained within the other—so every commit present in the one is already contained in the other—then git just performs a fast forward; the head of the current branch is moved forward to point at the head of the merged-in branch, without -any new commits being created.

    Fixing mistakes

    If you've messed up the working tree, but haven't yet committed your +any new commits being created.

    Fixing mistakes

    If you've messed up the working tree, but haven't yet committed your mistake, you can return the entire working tree to the last committed state with

    $ git reset --hard HEAD

    If you make a commit that you later wish you hadn't, there are two fundamentally different ways to fix the problem:

    1. @@ -559,7 +552,7 @@ You can go back and modify the old commit. You should git does not normally expect the "history" of a project to change, and cannot correctly perform repeated merges from a branch that has had its history changed. -

    Fixing a mistake with a new commit

    Creating a new commit that reverts an earlier change is very easy; +

    • Fixing a mistake with a new commit

    Creating a new commit that reverts an earlier change is very easy; just pass the git-revert(1) command a reference to the bad commit; for example, to revert the most recent commit:

    $ git revert HEAD

    This will create a new commit which undoes the change in HEAD. You will be given a chance to edit the commit message for the new commit.

    You can also revert an earlier change, for example, the next-to-last:

    $ git revert HEAD^

    In this case git will attempt to undo the old change while leaving @@ -574,17 +567,17 @@ changes, giving you a chance to edit the old commit message first.

    Again, been merged into another branch; use git-revert(1) instead in that case.

    It is also possible to edit commits further back in the history, but this is an advanced topic to be left for -another chapter.

    Checking out an old version of a file

    In the process of undoing a previous bad change, you may find it +another chapter.

    Checking out an old version of a file

    In the process of undoing a previous bad change, you may find it useful to check out an older version of a particular file using git-checkout(1). We've used git checkout before to switch branches, but it has quite different behavior if it is given a path name: the command

    $ git checkout HEAD^ path/to/file

    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.

    If you just want to look at an old version of the file, without modifying the working directory, you can do that with -git-show(1):

    $ git show HEAD^ path/to/file

    which will display the given version of the file.

    Ensuring good performance

    On large repositories, git depends on compression to keep the history +git-show(1):

    $ git show HEAD^:path/to/file

    which will display the given version of the file.

    Ensuring good performance

    On large repositories, git depends on compression to keep the history information from taking up to much space on disk or in memory.

    This compression is not performed automatically. Therefore you should occasionally run git-gc(1):

    $ git gc

    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.

    Ensuring reliability

    Checking the repository for corruption

    The git-fsck(1) command runs a number of self-consistency checks +you may prefer to run git-gc when you are not doing other work.

    Ensuring reliability

    Checking the repository for corruption

    The git-fsck(1) command runs a number of self-consistency checks on the repository, and reports on any problems. This may take some time. The most common warning by far is about "dangling" objects:

    $ git fsck
    dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
    @@ -599,7 +592,7 @@ dangling you can remove them at any time with git-prune(1) or the —prune option to git-gc(1):

    $ git gc --prune

    This may be time-consuming. Unlike most other git operations (including git-gc when run without any options), it is not safe to prune while -other git operations are in progress in the same repository.

    For more about dangling objects, see the section called “Dangling objects”.

    Recovering lost changes

    Reflogs

    Say you modify a branch with git-reset(1) —hard, and then +other git operations are in progress in the same repository.

    For more about dangling objects, see the section called “Dangling objects”.

    Recovering lost changes

    Reflogs

    Say you modify a branch with git-reset(1) —hard, and then realize that the branch was the only reference you had to that point in history.

    Fortunately, git also keeps a log, called a "reflog", of all the previous values of each branch. So in this case you can still find the @@ -614,7 +607,7 @@ how to control this pruning, and see the "SPECIFYING REVISIONS" section of git-rev-parse(1) for details.

    Note that the reflog history is very different from normal git history. While normal history is shared by every repository that works on the same project, the reflog history is not shared: it tells you only about -how the branches in your local repository have changed over time.

    Examining dangling objects

    In some situations the reflog may not be able to save you. For +how the branches in your local repository have changed over time.

    Examining dangling objects

    In some situations the reflog may not be able to save you. For example, suppose you delete a branch, then realize you need the history it contained. The reflog is also deleted; however, if you have not yet pruned the repository, then you may still be able to find @@ -631,7 +624,7 @@ you get exactly the history reachable from that commit that is lost. (And notice that it might not be just one commit: we only report the "tip of the line" as being dangling, but there might be a whole deep and complex commit history that was dropped.)

    If you decide you want the history back, you can always create a new -reference pointing to it, for example, a new branch:

    $ git branch recovered-branch 7281251ddd

    Chapter 5. Sharing development with others

    Table of Contents

    Getting updates with git pull
    Submitting patches to a project
    Importing patches to a project
    Setting up a public repository
    Exporting a git repository via http
    Exporting a git repository via the git protocol
    Pushing changes to a public repository
    Setting up a shared repository
    Allow web browsing of a repository
    Examples

    Getting updates with git pull

    After you clone a repository and make a few changes of your own, you +reference pointing to it, for example, a new branch:

    $ git branch recovered-branch 7281251ddd

    Chapter 5. Sharing development with others

    Table of Contents

    Getting updates with git pull
    Submitting patches to a project
    Importing patches to a project
    Setting up a public repository
    Exporting a git repository via http
    Exporting a git repository via the git protocol
    Pushing changes to a public repository
    Setting up a shared repository
    Allow web browsing of a repository
    Examples

    Getting updates with git pull

    After you clone a repository and make a few changes of your own, you may wish to check the original repository for updates and merge them into your own work.

    We have already seen how to keep remote tracking branches up to date with git-fetch(1), and how to merge two branches. So you can merge in changes from the @@ -648,13 +641,13 @@ repository that you pulled from.

    (But note that no such commit will be cre updated to point to the latest commit from the upstream branch.)

    The git-pull command can also be given "." as the "remote" repository, in which case it just merges in a branch from the current repository; so the commands

    $ git pull . branch
    -$ git merge branch

    are roughly equivalent. The former is actually very commonly used.

    Submitting patches to a project

    If you just have a few changes, the simplest way to submit them may +$ git merge branch

    are roughly equivalent. The former is actually very commonly used.

    Submitting patches to a project

    If you just have a few changes, the simplest way to submit them may just be to send them as patches in email:

    First, use git-format-patch(1); for example:

    $ git format-patch origin

    will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD.

    You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the git-send-email(1) script to automate the process. Consult the mailing list for your project first to determine how they -prefer such patches be handled.

    Importing patches to a project

    Git also provides a tool called git-am(1) (am stands for +prefer such patches be handled.

    Importing patches to a project

    Git also provides a tool called git-am(1) (am stands for "apply mailbox"), for importing such an emailed series of patches. Just save all of the patch-containing messages, in order, into a single mailbox file, say "patches.mbox", then run

    $ git am -3 patches.mbox

    Git will apply each patch in order; if any conflicts are found, it @@ -726,16 +719,16 @@ save typing; so, for example, after

    $         url = ssh://yourserver.com/~you/proj.git
    EOF

    you should be able to perform the above push with just

    $ git push public-repo master

    See the explanations of the remote.<name>.url, branch.<name>.remote, and remote.<name>.push options in git-config(1) for -details.

    Setting up a shared repository

    Another way to collaborate is by using a model similar to that +details.

    Setting up a shared repository

    Another way to collaborate is by using a model similar to that commonly used in CVS, where several developers with special rights all push to and pull from a single shared repository. See git for CVS users for instructions on how to -set this up.

    Allow web browsing of a repository

    The gitweb cgi script provides users an easy way to browse your +set this up.

    Allow web browsing of a repository

    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/README in the git source tree for instructions on setting it up.

    Examples

    TODO: topic branches, typical roles as in everyday.txt, ?

    Chapter 6. Rewriting history and maintaining patch series

    Table of Contents

    Creating the perfect patch series
    Keeping a patch series up to date using git-rebase
    Modifying a single commit
    Reordering or selecting from a patch series
    Other tools
    Problems with rewriting history

    Normally commits are only added to a project, never taken away or +gitweb/README in the git source tree for instructions on setting it up.

    Examples

    TODO: topic branches, typical roles as in everyday.txt, ?

    Chapter 6. Rewriting history and maintaining patch series

    Table of Contents

    Creating the perfect patch series
    Keeping a patch series up to date using git-rebase
    Modifying a single commit
    Reordering or selecting from a patch series
    Other tools
    Problems with rewriting history

    Normally commits are only added to a project, never taken away or replaced. Git is designed with this assumption, and violating it will cause git's merge machinery (for example) to do the wrong thing.

    However, there is a situation in which it can be useful to violate this -assumption.

    Creating the perfect patch series

    Suppose you are a contributor to a large project, and you want to add a +assumption.

    Creating the perfect patch series

    Suppose you are a contributor to a large project, and you want to add a complicated feature, and to present it to the other developers in a way that makes it easy for them to read your changes, verify that they are correct, and understand why you made each change.

    If you present all of your changes as a single patch (or commit), they @@ -754,30 +747,34 @@ The complete series produces the same end result as your own (probably much messier!) development process did.

    We will introduce some tools that can help you do this, explain how to use them, and then explain some of the problems that can arise because -you are rewriting history.

    Keeping a patch series up to date using git-rebase

    Suppose that you create a branch "mywork" on a remote-tracking branch +you are rewriting history.

    Keeping a patch series up to date using git-rebase

    Suppose that you create a branch "mywork" on a remote-tracking branch "origin", and create some commits on top of it:

    $ git checkout -b mywork origin
    $ vi file.txt
    $ git commit
    $ vi otherfile.txt
    $ git commit
    ...

    You have performed no merges into mywork, so it is just a simple linear -sequence of patches on top of "origin":

    o--o--o <-- origin
-                o--o--o <-- mywork

    Some more interesting work has been done in the upstream project, and -"origin" has advanced:

    o--o--O--o--o--o <-- origin
-                a--b--c <-- mywork

    At this point, you could use "pull" to merge your changes back in; -the result would create a new merge commit, like this:

    o--o--O--o--o--o <-- origin
-       \                 a--b--c--m <-- mywork

    However, if you prefer to keep the history in mywork a simple series of +sequence of patches on top of "origin":

     o--o--o <-- origin
+        \
+         o--o--o <-- mywork

    Some more interesting work has been done in the upstream project, and +"origin" has advanced:

     o--o--O--o--o--o <-- origin
+        \
+         a--b--c <-- mywork

    At this point, you could use "pull" to merge your changes back in; +the result would create a new merge commit, like this:

     o--o--O--o--o--o <-- origin
+        \        \
+         a--b--c--m <-- mywork

    However, if you prefer to keep the history in mywork a simple series of commits without any merges, you may instead choose to use git-rebase(1):

    $ git checkout mywork
    $ git rebase origin

    This will remove each of your commits from mywork, temporarily saving them as patches (in a directory named ".dotest"), update mywork to point at the latest version of origin, then apply each of the saved -patches to the new mywork. The result will look like:

    o--o--O--o--o--o <-- origin
-                                  a'--b'--c' <-- mywork

    In the process, it may discover conflicts. In that case it will stop +patches to the new mywork. The result will look like:

     o--o--O--o--o--o <-- origin
+                 \
+                  a'--b'--c' <-- mywork

    In the process, it may discover conflicts. In that case it will stop and allow you to fix the conflicts; after fixing conflicts, use "git add" to update the index with those contents, and then, instead of running git-commit, just run

    $ git rebase --continue

    and git will continue applying the rest of the patches.

    At any point you may use the —abort option to abort this process and -return mywork to the state it had before you started the rebase:

    $ git rebase --abort

    Modifying a single commit

    We saw in the section called “Fixing a mistake by editing history” that you can replace the +return mywork to the state it had before you started the rebase:

    $ git rebase --abort

    Modifying a single commit

    We saw in the section called “Fixing a mistake by editing history” that you can replace the most recent commit using

    $ git commit --amend

    which will replace the old commit by a new commit incorporating your changes, giving you a chance to edit the old commit message first.

    You can also use a combination of this and git-rebase(1) to edit commits further back in your history. First, tag the problematic commit with

    $ git tag bad mywork~5

    (Either gitk or git-log may be useful for finding the commit.)

    Then check out a new branch at that commit, edit it, and rebase the rest of @@ -789,7 +786,7 @@ on mywork reapplied on top of the modified commit you created in TMP. You can then clean up with

    $ git branch -d TMP
    $ git tag -d bad

    Note that the immutable nature of git history means that you haven't really "modified" existing commits; instead, you have replaced the old commits with -new commits having new object names.

    Reordering or selecting from a patch series

    Given one existing commit, the git-cherry-pick(1) command +new commits having new object names.

    Reordering or selecting from a patch series

    Given one existing commit, the git-cherry-pick(1) command allows you to apply the change introduced by that commit and create a new commit that records it. So, for example, if "mywork" points to a series of patches on top of "origin", you might do something like:

    $ git checkout -b mywork-new origin
    @@ -799,18 +796,20 @@ cherry-pick, and possibly modifying them as you go using commit —amend.

    Another technique is to use git-format-patch to create a series of patches, then reset the state to before the patches:

    $ git format-patch origin
    $ git reset --hard origin

    Then modify, reorder, or eliminate patches as preferred before applying -them again with git-am(1).

    Other tools

    There are numerous other tools, such as stgit, which exist for the +them again with git-am(1).

    Other tools

    There are numerous other tools, such as stgit, which exist for the purpose of maintaining a patch series. These are outside of the scope of -this manual.

    Problems with rewriting history

    The primary problem with rewriting the history of a branch has to do +this manual.

    Problems with rewriting history

    The primary problem with rewriting the history of a branch has to do with merging. Suppose somebody fetches your branch and merges it into -their branch, with a result something like this:

    o--o--O--o--o--o <-- origin
-       \                 t--t--t--m <-- their branch:

    Then suppose you modify the last three commits:

            o--o--o <-- new head of origin
-       /
-o--o--O--o--o--o <-- old head of origin

    If we examined all this history together in one repository, it will -look like:

            o--o--o <-- new head of origin
-       /
-o--o--O--o--o--o <-- old head of origin
-       \                 t--t--t--m <-- their branch:

    Git has no way of knowing that the new head is an updated version of +their branch, with a result something like this:

     o--o--O--o--o--o <-- origin
+        \        \
+         t--t--t--m <-- their branch:

    Then suppose you modify the last three commits:

             o--o--o <-- new head of origin
+        /
+ o--o--O--o--o--o <-- old head of origin

    If we examined all this history together in one repository, it will +look like:

             o--o--o <-- new head of origin
+        /
+ o--o--O--o--o--o <-- old head of origin
+        \        \
+         t--t--t--m <-- their branch:

    Git has no way of knowing that the new head is an updated version of the old head; it treats this situation exactly the same as it would if two developers had independently done the work on the old and new heads in parallel. At this point, if someone attempts to merge the new head @@ -820,7 +819,7 @@ new. The results are likely to be unexpected.

    You may still choose to pub and it may be useful for others to be able to fetch those branches in order to examine or test them, but they should not attempt to pull such branches into their own work.

    For true distributed development that supports proper merging, -published branches should never be rewritten.

    Chapter 7. Advanced branch management

    Table of Contents

    Fetching individual branches
    Understanding git history: fast-forwards
    Forcing git fetch to do non-fast-forward updates
    Configuring remote branches

    Fetching individual branches

    Instead of using git-remote(1), you can also choose just +published branches should never be rewritten.

    Chapter 7. Advanced branch management

    Table of Contents

    Fetching individual branches
    Understanding git history: fast-forwards
    Forcing git fetch to do non-fast-forward updates
    Configuring remote branches

    Fetching individual branches

    Instead of using git-remote(1), you can also choose just to update one branch at a time, and to store it locally under an arbitrary name:

    $ git fetch origin todo:my-todo-work

    The first argument, "origin", just tells git to fetch from the repository you originally cloned from. The second argument tells git @@ -833,19 +832,21 @@ next we explain what a fast-forward is:

    fetch" checks to make sure that the most recent commit on the remote branch is a descendant of the most recent commit on your copy of the branch before updating your copy of the branch to point at the new -commit. Git calls this process a "fast forward".

    A fast forward looks something like this:

    o--o--o--o <-- old head of the branch
-                      o--o--o <-- new head of the branch

    In some cases it is possible that the new head will not actually be +commit. Git calls this process a "fast forward".

    A fast forward looks something like this:

     o--o--o--o <-- old head of the branch
+           \
+            o--o--o <-- new head of the branch

    In some cases it is possible that the new head will not actually be a descendant of the old head. For example, the developer may have realized she made a serious mistake, and decided to backtrack, -resulting in a situation like:

    o--o--o--o--a--b <-- old head of the branch
-                      o--o--o <-- new head of the branch

    In this case, "git fetch" will fail, and print out a warning.

    In that case, you can still force git to update to the new head, as +resulting in a situation like:

     o--o--o--o--a--b <-- old head of the branch
+           \
+            o--o--o <-- new head of the branch

    In this case, "git fetch" will fail, and print out a warning.

    In that case, you can still force git to update to the new head, as described in the following section. However, note that in the situation above this may mean losing the commits labeled "a" and "b", unless you've already created a reference of your own pointing to -them.

    Forcing git fetch to do non-fast-forward updates

    If git fetch fails because the new head of a branch is not a +them.

    Forcing git fetch to do non-fast-forward updates

    If git fetch fails because the new head of a branch is not a descendant of the old head, you may force the update with:

    $ git fetch git://example.com/proj.git +master:refs/remotes/example/master

    Note the addition of the "+" sign. Be aware that commits that the old version of example/master pointed at may be lost, as we saw in -the previous section.

    Configuring remote branches

    We saw above that "origin" is just a shortcut to refer to the +the previous section.

    Configuring remote branches

    We saw above that "origin" is just a shortcut to refer to the repository that you originally cloned from. This information is stored in git configuration variables, which you can see using git-config(1):

    $ git config -l
    @@ -865,8 +866,8 @@ $ throwing away commits on mybranch.

    Also note that all of the above configuration can be performed by directly editing the file .git/config instead of using git-config(1).

    See git-config(1) for more details on the configuration -options mentioned above.

    Chapter 8. Git internals

    Table of Contents

    The Object Database
    Blob Object
    Tree Object
    Commit Object
    Trust
    Tag Object
    The "index" aka "Current Directory Cache"
    The Workflow
    working directory -> index
    index -> object database
    object database -> index
    index -> working directory
    Tying it all together
    Examining the data
    Merging multiple trees
    Merging multiple trees, continued
    How git stores objects efficiently: pack files
    Dangling objects

    There are two object abstractions: the "object database", and the -"current directory cache" aka "index".

    The Object Database

    The object database is literally just a content-addressable collection +options mentioned above.

    Chapter 8. Git internals

    Table of Contents

    The Object Database
    Blob Object
    Tree Object
    Commit Object
    Trust
    Tag Object
    The "index" aka "Current Directory Cache"
    The Workflow
    working directory -> index
    index -> object database
    object database -> index
    index -> working directory
    Tying it all together
    Examining the data
    Merging multiple trees
    Merging multiple trees, continued
    How git stores objects efficiently: pack files
    Dangling objects

    There are two object abstractions: the "object database", and the +"current directory cache" aka "index".

    The Object Database

    The object database is literally just a content-addressable collection of objects. All objects are named by their content, which is approximated by the SHA1 hash of the object itself. Objects may refer to other objects (by referencing their SHA1 hash), and so you can @@ -908,7 +909,7 @@ size> + <byte\0> + <binary object data>.

    The structured obj connectivity to other objects verified. This is generally done with the git-fsck program, which generates a full dependency graph of all objects, and verifies their internal consistency (in addition -to just verifying their superficial consistency through the hash).

    The object types in some more detail:

    Blob Object

    A "blob" object is nothing but a binary blob of data, and doesn't +to just verifying their superficial consistency through the hash).

    The object types in some more detail:

    Blob Object

    A "blob" object is nothing but a binary blob of data, and doesn't refer to anything else. There is no signature or any other verification of the data, so while the object is consistent (it is indexed by its sha1 hash, so the data itself is certainly correct), it @@ -920,7 +921,7 @@ repository) have the same contents, they will share the same blob object. The object is totally independent of its location in the directory tree, and renaming a file does not change the object that file is associated with in any way.

    A blob is typically created when git-update-index(1) -is run, and its data can be accessed by git-cat-file(1).

    Tree Object

    The next hierarchical object type is the "tree" object. A tree object +is run, and its data can be accessed by git-cat-file(1).

    Tree Object

    The next hierarchical object type is the "tree" object. A tree object is a list of mode/name/blob data, sorted by name. Alternatively, the mode data may specify a directory mode, in which case instead of naming a blob, that name is associated with another TREE object.

    Like the "blob" object, a tree object is uniquely determined by the @@ -944,7 +945,7 @@ involved), you can see trivial renames or permission changes by noticing that the blob stayed the same. However, renames with data changes need a smarter "diff" implementation.

    A tree is created with git-write-tree(1) and its data can be accessed by git-ls-tree(1). -Two trees can be compared with git-diff-tree(1).

    Commit Object

    The "commit" object is an object that introduces the notion of +Two trees can be compared with git-diff-tree(1).

    Commit Object

    The "commit" object is an object that introduces the notion of history into the picture. In contrast to the other objects, it doesn't just describe the physical state of a tree, it describes how we got there, and why.

    A "commit" is defined by the tree-object that it results in, the @@ -959,7 +960,7 @@ rename information or file mode change information. All of that is implicit in the trees involved (the result tree, and the result trees of the parents), and describing that makes no sense in this idiotic file manager.

    A commit is created with git-commit-tree(1) and -its data can be accessed by git-cat-file(1).

    Trust

    An aside on the notion of "trust". Trust is really outside the scope +its data can be accessed by git-cat-file(1).

    Trust

    An aside on the notion of "trust". Trust is really outside the scope of "git", but it's worth noting a few things. First off, since everything is hashed with SHA1, you can trust that an object is intact and has not been messed with by external sources. So the name @@ -975,7 +976,7 @@ that you trust that commit, and the immutability of the history of commits tells others that they can trust the whole history.

    In other words, you can easily validate a whole archive by just sending out a single email that tells the people the name (SHA1 hash) of the top commit, and digitally sign that email using something -like GPG/PGP.

    To assist in this, git also provides the tag object…

    Tag Object

    Git provides the "tag" object to simplify creating, managing and +like GPG/PGP.

    To assist in this, git also provides the tag object…

    Tag Object

    Git provides the "tag" object to simplify creating, managing and exchanging symbolic and signed tokens. The "tag" object at its simplest simply symbolically identifies another object by containing the sha1, type and symbolic name.

    However it can optionally contain additional signature information @@ -985,7 +986,7 @@ integrity; the trust framework (and signature provision and verification) has to come from outside.

    A tag is created with git-mktag(1), its data can be accessed by git-cat-file(1), and the signature can be verified by -git-verify-tag(1).

    The "index" aka "Current Directory Cache"

    The index is a simple binary file, which contains an efficient +git-verify-tag(1).

    The "index" aka "Current Directory Cache"

    The index is a simple binary file, which contains an efficient representation of a virtual directory content at some random time. It does so by a simple array that associates a set of names, dates, permissions and content (aka "blob") objects together. The cache is @@ -1018,11 +1019,11 @@ involves a controlled modification of the index file. In particular, the index file can have the representation of an intermediate tree that has not yet been instantiated. So the index can be thought of as a write-back cache, which can contain dirty information that has not yet -been written back to the backing store.

    The Workflow

    Generally, all "git" operations work on the index file. Some operations +been written back to the backing store.

    The Workflow

    Generally, all "git" operations work on the index file. Some operations work purely on the index file (showing the current state of the index), but most operations move data to and from the index file. Either from the database or from the working directory. Thus there are four -main combinations:

    working directory -> index

    You update the index with information from the working directory with +main combinations:

    working directory -> index

    You update the index with information from the working directory with the git-update-index(1) command. You generally update the index information by just specifying the filename you want to update, like so:

    $ git-update-index filename

    but to avoid common mistakes with filename globbing etc, the command @@ -1038,16 +1039,16 @@ does not exist any more, it will update the index accordingly.

    As a specia will refresh the "stat" information of each index to match the current stat information. It will not update the object status itself, and it will only update the fields that are used to quickly test whether -an object still matches its old backing store object.

    index -> object database

    You write your current index file to a "tree" object with the program

    $ git-write-tree

    that doesn't come with any options - it will just write out the +an object still matches its old backing store object.

    index -> object database

    You write your current index file to a "tree" object with the program

    $ git-write-tree

    that doesn't come with any options - it will just write out the current index into the set of tree objects that describe that state, and it will return the name of the resulting top-level tree. You can use that tree to re-generate the index at any time by going in the -other direction:

    object database -> index

    You read a "tree" file from the object database, and use that to +other direction:

    object database -> index

    You read a "tree" file from the object database, and use that to populate (and overwrite - don't do this if your index contains any unsaved state that you might want to restore later!) your current index. Normal operation is just

    $ git-read-tree <sha1 of tree>

    and your index file will now be equivalent to the tree that you saved earlier. However, that is only your index file: your working -directory contents have not been modified.

    index -> working directory

    You update your working directory from the index by "checking out" +directory contents have not been modified.

    index -> working directory

    You update your working directory from the index by "checking out" files. This is not a very common operation, since normally you'd just keep your files updated, and rather than write to your working directory, you'd tell the index files about the changes in your @@ -1058,7 +1059,7 @@ with

    $ if you have an old version of the tree already checked out, you will need to use the "-f" flag (before the "-a" flag or the filename) to force the checkout.

    Finally, there are a few odds and ends which are not purely moving -from one representation to the other:

    Tying it all together

    To commit a tree you have instantiated with "git-write-tree", you'd +from one representation to the other:

    Tying it all together

    To commit a tree you have instantiated with "git-write-tree", you'd create a "commit" object that refers to that tree and the history behind it - most notably the "parent" commits that preceded it in history.

    Normally a "commit" has one parent: the previous state of the tree @@ -1107,7 +1108,7 @@ various pieces fit together.


                        |  Working  |
                        | Directory |
                        +-----------+
    -

    Examining the data

    You can examine the data represented in the object database and the +

    Examining the data

    You can examine the data represented in the object database and the index with various helper tools. For every object, you can use git-cat-file(1) to examine details about the object:

    $ git-cat-file -t <objectname>

    shows the type of the object, and once you have the type (which is @@ -1117,7 +1118,7 @@ there is a special helper for showing that content, called readable form.

    It's especially instructive to look at "commit" objects, since those tend to be small and fairly self-explanatory. In particular, if you follow the convention of having the top commit name in .git/HEAD, -you can do

    $ git-cat-file commit HEAD

    to see what the top commit was.

    Merging multiple trees

    Git helps you do a three-way merge, which you can expand to n-way by +you can do

    $ git-cat-file commit HEAD

    to see what the top commit was.

    Merging multiple trees

    Git helps you do a three-way merge, which you can expand to n-way by repeating the merge procedure arbitrary times until you finally "commit" the state. The normal situation is that you'd only do one three-way merge (two parents), and commit it, but if you like to, you @@ -1136,7 +1137,7 @@ make sure that you've committed those - in fact you would normally always do a merge against your last commit (which should thus match what you have in your current index anyway).

    To do the merge, do

    $ git-read-tree -m -u <origtree> <yourtree> <targettree>

    which will do all trivial merge operations for you directly in the index file, and you can just write the result out with -git-write-tree.

    Merging multiple trees, continued

    Sadly, many merges aren't trivial. If there are files that have +git-write-tree.

    Merging multiple trees, continued

    Sadly, many merges aren't trivial. If there are files that have been added.moved or removed, or if both branches have modified the same file, you will be left with an index tree that contains "merge entries" in it. Such an index tree can NOT be written out to a tree @@ -1171,7 +1172,7 @@ that path tells git to mark the path resolved.

    The above is the descriptio to help you understand what conceptually happens under the hood. In practice, nobody, not even git itself, uses three git-cat-file for this. There is git-merge-index program that extracts the -stages to temporary files and calls a "merge" script on it:

    $ git-merge-index git-merge-one-file hello.c

    and that is what higher level git merge -s resolve is implemented with.

    How git stores objects efficiently: pack files

    We've seen how git stores each object in a file named after the +stages to temporary files and calls a "merge" script on it:

    $ git-merge-index git-merge-one-file hello.c

    and that is what higher level git merge -s resolve is implemented with.

    How git stores objects efficiently: pack files

    We've seen how git stores each object in a file named after the object's SHA1 hash.

    Unfortunately this system becomes inefficient once a project has a lot of objects. Try this on an old project:

    $ git count-objects
    6930 objects, 47620 kilobytes

    The first number is the number of objects which are kept in @@ -1235,7 +1236,7 @@ on what it found, git-fsck itself is never "dangerous" to run. Running it while somebody is actually changing the repository can cause confusing and scary messages, but it won't actually do anything bad. In contrast, running "git prune" while somebody is actively changing the -repository is a BAD idea).

    Chapter 9. Glossary of git terms

    +repository is a BAD idea).

    Chapter 9. Glossary of git terms

    alternate object database
    Via the alternates mechanism, a repository can inherit part of its @@ -1669,7 +1670,7 @@ working tree
    The set of files and directories currently being worked on, i.e. you can work in your working tree without using git at all. -

    Chapter 10. Notes and todo list for this manual

    This is a work in progress.

    The basic requirements: +

    Chapter 10. Notes and todo list for this manual

    This is a work in progress.

    The basic requirements: - It must be readable in order, from beginning to end, by someone intelligent with a basic grasp of the unix commandline, but without any special knowledge of git. If diff --git a/user-manual.txt b/user-manual.txt index ffd673ec3..d7b227e64 100644 --- a/user-manual.txt +++ b/user-manual.txt @@ -437,11 +437,14 @@ We will sometimes represent git history using diagrams like the one below. Commits are shown as "o", and the links between them with lines drawn with - / and \. Time goes left to right: + +................................................ o--o--o <-- Branch A / o--o--o <-- master \ o--o--o <-- Branch B +................................................ If we need to talk about a particular commit, the character "o" may be replaced with another letter or number. @@ -601,8 +604,8 @@ a new stanza: $ cat .git/config ... [remote "linux-nfs"] - url = git://linux-nfs.org/~bfields/git.git - fetch = +refs/heads/*:refs/remotes/linux-nfs-read/* + url = git://linux-nfs.org/pub/nfs-2.6.git + fetch = +refs/heads/*:refs/remotes/linux-nfs/* ... ------------------------------------------------- @@ -1133,17 +1136,9 @@ modified in two different ways in the remote branch and the local branch--then you are warned; the output may look something like this: ------------------------------------------------- -$ git pull . next -Trying really trivial in-index merge... -fatal: Merge requires file-level merging -Nope. -Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086 -Merging: -15e2162 world -77976da goodbye -found 1 common ancestor(s): -d122ed4 initial -Auto-merging file.txt +$ git merge next + 100% (4/4) done +Auto-merged file.txt CONFLICT (content): Merge conflict in file.txt Automatic merge failed; fix conflicts and then commit the result. ------------------------------------------------- @@ -1439,7 +1434,7 @@ modifying the working directory, you can do that with gitlink:git-show[1]: ------------------------------------------------- -$ git show HEAD^ path/to/file +$ git show HEAD^:path/to/file ------------------------------------------------- which will display the given version of the file. @@ -1936,25 +1931,29 @@ $ git commit You have performed no merges into mywork, so it is just a simple linear sequence of patches on top of "origin": - +................................................ o--o--o <-- origin \ o--o--o <-- mywork +................................................ Some more interesting work has been done in the upstream project, and "origin" has advanced: +................................................ o--o--O--o--o--o <-- origin \ a--b--c <-- mywork +................................................ At this point, you could use "pull" to merge your changes back in; the result would create a new merge commit, like this: - +................................................ o--o--O--o--o--o <-- origin \ \ a--b--c--m <-- mywork +................................................ However, if you prefer to keep the history in mywork a simple series of commits without any merges, you may instead choose to use @@ -1971,9 +1970,11 @@ point at the latest version of origin, then apply each of the saved patches to the new mywork. The result will look like: +................................................ o--o--O--o--o--o <-- origin \ a'--b'--c' <-- mywork +................................................ In the process, it may discover conflicts. In that case it will stop and allow you to fix the conflicts; after fixing conflicts, use "git @@ -2081,24 +2082,30 @@ The primary problem with rewriting the history of a branch has to do with merging. Suppose somebody fetches your branch and merges it into their branch, with a result something like this: +................................................ o--o--O--o--o--o <-- origin \ \ t--t--t--m <-- their branch: +................................................ Then suppose you modify the last three commits: +................................................ o--o--o <-- new head of origin / o--o--O--o--o--o <-- old head of origin +................................................ If we examined all this history together in one repository, it will look like: +................................................ o--o--o <-- new head of origin / o--o--O--o--o--o <-- old head of origin \ \ t--t--t--m <-- their branch: +................................................ Git has no way of knowing that the new head is an updated version of the old head; it treats this situation exactly the same as it would if @@ -2159,9 +2166,11 @@ commit. Git calls this process a "fast forward". A fast forward looks something like this: +................................................ o--o--o--o <-- old head of the branch \ o--o--o <-- new head of the branch +................................................ In some cases it is possible that the new head will *not* actually be @@ -2169,11 +2178,11 @@ a descendant of the old head. For example, the developer may have realized she made a serious mistake, and decided to backtrack, resulting in a situation like: +................................................ o--o--o--o--a--b <-- old head of the branch \ o--o--o <-- new head of the branch - - +................................................ In this case, "git fetch" will fail, and print out a warning. -- 2.26.2