diff options
Diffstat (limited to 'Documentation')
24 files changed, 564 insertions, 106 deletions
diff --git a/Documentation/RelNotes-1.6.0.1.txt b/Documentation/RelNotes-1.6.0.1.txt new file mode 100644 index 0000000000..49d7a1cafa --- /dev/null +++ b/Documentation/RelNotes-1.6.0.1.txt @@ -0,0 +1,36 @@ +GIT v1.6.0.1 Release Notes +========================== + +Fixes since v1.6.0 +------------------ + +* "git diff --cc" did not honor content mangling specified by + gitattributes and core.autocrlf when reading from the work tree. + +* "git diff --check" incorrectly detected new trailing blank lines when + whitespace check was in effect. + +* "git for-each-ref" tried to dereference NULL when asked for '%(body)" on + a tag with a single incomplete line as its payload. + +* "git format-patch" peeked before the beginning of a string when + "format.headers" variable is empty (a misconfiguration). + +* "git help help" did not work correctly. + +* "git mailinfo" (hence "git am") was unhappy when MIME multipart message + contained garbage after the finishing boundary. + +* "git mailinfo" also was unhappy when the "From: " line only had a bare + e-mail address. + +* "git merge" did not refresh the index correctly when a merge resulted in + a fast-forward. + +* "git merge" did not resolve a truly trivial merges that can be done + without content level merges. + +* "git svn dcommit" to a repository with URL that has embedded usernames + did not work correctly. + +Contains other various documentation fixes. diff --git a/Documentation/RelNotes-1.6.0.txt b/Documentation/RelNotes-1.6.0.txt index 8afb5b2531..de7ef166b6 100644 --- a/Documentation/RelNotes-1.6.0.txt +++ b/Documentation/RelNotes-1.6.0.txt @@ -28,6 +28,16 @@ introduced in v1.5.2 and v1.4.4.5. If you want to keep your repositories backwards compatible past these versions, set repack.useDeltaBaseOffset to false or pack.indexVersion to 1, respectively. +We used to prevent sample hook scripts shipped in templates/ from +triggering by default by relying on the fact that we install them as +unexecutable, but on some filesystems, this approach does not work. +They are now shipped with ".sample" suffix. If you want to activate +any of these samples as-is, rename them to drop the ".sample" suffix, +instead of running "chmod +x" on them. For example, you can rename +hooks/post-update.sample to hooks/post-update to enable the sample +hook that runs update-server-info, in order to make repositories +friendly to dumb protocols (i.e. HTTP). + GIT_CONFIG, which was only documented as affecting "git config", but actually affected all git commands, now only affects "git config". GIT_LOCAL_CONFIG, also only documented as affecting "git config" and @@ -56,11 +66,7 @@ Updates since v1.5.6 gangs. * Sample hook scripts shipped in templates/ are now suffixed with - *.sample. We used to prevent them from triggering by default by - relying on the fact that we install them as unexecutable, but on - some filesystems this approach does not work. Instead of running - "chmod +x" on them, the users who want to activate these samples - as-is can now rename them dropping *.sample suffix. + *.sample. * perl's in-place edit (-i) does not work well without backup files on Windows; some tests are rewritten to cope with this. @@ -172,7 +178,7 @@ Updates since v1.5.6 * git-diff --check now checks leftover merge conflict markers. * "git-diff -p" learned to grab a better hunk header lines in - Pascal/Delphi and Ruby source files, and also pays attention to + BibTex, Pascal/Delphi, and Ruby files and also pays attention to chapter and part boundary in TeX documents. * When remote side used to have branch 'foo' and git-fetch finds that now @@ -239,15 +245,14 @@ Fixes since v1.5.6 All of the fixes in v1.5.6 maintenance series are included in this release, unless otherwise noted. -* git-clone ignored its -u option; the fix needs to be backported to - 'maint'; + * git-clone ignored its -u option; the fix needs to be backported to + 'maint'; + + * git-mv used to lose the distinction between changes that are staged + and that are only in the working tree, by staging both in the index + after moving such a path. -* git-mv used to lose the distinction between changes that are staged - and that are only in the working tree, by staging both in the index - after moving such a path. + * "git-rebase -i -p" rewrote the parents to wrong ones when amending + (either edit or squash) was involved, and did not work correctly + when fast forwarding. ---- -exec >/var/tmp/1 -O=v1.6.0-rc2-21-g0bb3a0b -echo O=$(git describe refs/heads/master) -git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/RelNotes-1.6.1.txt b/Documentation/RelNotes-1.6.1.txt new file mode 100644 index 0000000000..d37da039f6 --- /dev/null +++ b/Documentation/RelNotes-1.6.1.txt @@ -0,0 +1,58 @@ +GIT v1.6.1 Release Notes +======================== + +Updates since v1.6.0 +-------------------- + +When some commands (e.g. "git log", "git diff") spawn pager internally, we +used to make the pager the parent process of the git command that produces +output. This meant that the exit status of the whole thing comes from the +pager, not the underlying git command. We swapped the order of the +processes around and you will see the exit code from the command from now +on. + +(subsystems) + +* ... + +(portability) + +* ... + +(documentation) + +* ... + +(performance) + +* The underlying diff machinery to produce textual output has been + optimized, which would result in faster "git blame" processing. + +(usability, bells and whistles) + +* "git checkout --track origin/hack" used to be a syntax error. It now + DWIMs to create a corresponding local branch "hack", i.e. acts as if you + said "git checkout --track -b hack origin/hack". + +* "git diff" learned to mimick --suppress-blank-empty from GNU diff via a + configuration option. + +* "git imap-send" can optionally talk SSL. + +(internal) + +* "git hash-object" learned to lie about the path being hashed, so that + correct gitattributes processing can be done while hashing contents + stored in a temporary file. + +Fixes since v1.6.0 +------------------ + +All of the fixes in v1.6.0.X maintenance series are included in this +release, unless otherwise noted. + +-- +exec >/var/tmp/1 +O=v1.6.0-48-ge28a867 +echo O=$(git describe master) +git shortlog --no-merges $O..master ^maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 841bead9db..a1e9100f9e 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -71,7 +71,7 @@ run git diff --check on your changes before you commit. (1a) Try to be nice to older C compilers -We try to support wide range of C compilers to compile +We try to support a wide range of C compilers to compile git with. That means that you should not use C99 initializers, even if a lot of compilers grok it. diff --git a/Documentation/config.txt b/Documentation/config.txt index b8ec01c923..af57d94304 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -358,8 +358,13 @@ core.editor:: `EDITOR` environment variables and then finally `vi`. core.pager:: - The command that git will use to paginate output. Can be overridden - with the `GIT_PAGER` environment variable. + The command that git will use to paginate output. Can + be overridden with the `GIT_PAGER` environment + variable. Note that git sets the `LESS` environment + variable to `FRSX` if it is unset when it runs the + pager. One can change these settings by setting the + `LESS` variable to some other value or by giving the + `core.pager` option a value such as "`less -+FRSX`". core.whitespace:: A comma separated list of common whitespace problems to @@ -567,6 +572,10 @@ diff.autorefreshindex:: affects only 'git-diff' Porcelain, and not lower level 'diff' commands, such as 'git-diff-files'. +diff.suppress-blank-empty:: + A boolean to inhibit the standard behavior of printing a space + before each empty output line. Defaults to false. + diff.external:: If this config variable is set, diff generation is not performed using the internal diff machinery, but using the @@ -978,6 +987,13 @@ pack.packSizeLimit:: can be overridden by the `\--max-pack-size` option of linkgit:git-repack[1]. +pager.<cmd>:: + Allows turning on or off pagination of the output of a + particular git subcommand when writing to a tty. If + `\--paginate` or `\--no-pager` is specified on the command line, + it takes precedence over this option. To disable pagination for + all commands, set `core.pager` or 'GIT_PAGER' to "`cat`". + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index cba90fd27c..1759386404 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -107,9 +107,9 @@ endif::git-format-patch[] --exit-code. --full-index:: - Instead of the first handful characters, show full - object name of pre- and post-image blob on the "index" - line when generating a patch format output. + Instead of the first handful of characters, show the full + pre- and post-image blob object names on the "index" + line when generating patch format output. --binary:: In addition to --full-index, output "binary diff" that diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index c45c53ec24..b9c6fac748 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git am' [--signoff] [--keep] [--utf8 | --no-utf8] - [--3way] [--interactive] [--binary] + [--3way] [--interactive] [--whitespace=<option>] [-C<n>] [-p<n>] [<mbox> | <Maildir>...] 'git am' (--skip | --resolved | --abort) @@ -59,11 +59,6 @@ default. You could use `--no-utf8` to override this. it is supposed to apply to, and we have those blobs available locally. --b:: ---binary:: - Pass `--allow-binary-replacement` flag to 'git-apply' - (see linkgit:git-apply[1]). - --whitespace=<option>:: This flag is passed to the 'git-apply' (see linkgit:git-apply[1]) program that applies diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 5aa69c0e12..be54a0299f 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -8,7 +8,7 @@ git-checkout - Checkout a branch or paths to the working tree SYNOPSIS -------- [verse] -'git checkout' [-q] [-f] [[--track | --no-track] -b <new_branch> [-l]] [-m] [<branch>] +'git checkout' [-q] [-f] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>] 'git checkout' [<tree-ish>] [--] <paths>... DESCRIPTION @@ -21,6 +21,10 @@ specified, <new_branch>. Using -b will cause <new_branch> to be created; in this case you can use the --track or --no-track options, which will be passed to `git branch`. +As a convenience, --track will default to create a branch whose +name is constructed from the specified branch name by stripping +the first namespace level. + When <paths> are given, this command does *not* switch branches. It updates the named paths in the working tree from the index file (i.e. it runs `git checkout-index -f -u`), or @@ -59,6 +63,17 @@ OPTIONS 'git-checkout' and 'git-branch' to always behave as if '--no-track' were given. Set it to `always` if you want this behavior when the start-point is either a local or remote branch. ++ +If no '-b' option was given, the name of the new branch will be +derived from the remote branch, by attempting to guess the name +of the branch on remote system. If "remotes/" or "refs/remotes/" +are prefixed, it is stripped away, and then the part up to the +next slash (which would be the nickname of the remote) is removed. +This would tell us to use "hack" as the local branch when branching +off of "origin/hack" (or "remotes/origin/hack", or even +"refs/remotes/origin/hack"). If the given name has no slash, or the above +guessing results in an empty name, the guessing is aborted. You can +exlicitly give a name with '-b' in such a case. --no-track:: Ignore the branch.autosetupmerge configuration variable. diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 75a8da1ca9..6bc1c21e62 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -21,8 +21,9 @@ OPTIONS --verbose:: In addition to the number of loose objects and disk space consumed, it reports the number of in-pack - objects, number of packs, and number of objects that can be - removed by running `git prune-packed`. + objects, number of packs, disk space consumed by those packs, + and number of objects that can be removed by running + `git prune-packed`. Author diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index c2d3c90d27..785779e221 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -11,7 +11,7 @@ SYNOPSIS SSH: [verse] -export CVS_SERVER=git-cvsserver +export CVS_SERVER="git cvsserver" 'cvs' -d :ext:user@server/path/repo.git co <HEAD_name> pserver (/etc/inetd.conf): @@ -109,7 +109,7 @@ Note: Newer CVS versions (>= 1.12.11) also support specifying CVS_SERVER directly in CVSROOT like ------ -cvs -d ":ext;CVS_SERVER=git-cvsserver:user@server/path/repo.git" co <HEAD_name> +cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name> ------ This has the advantage that it will be saved in your 'CVS/Root' files and you don't need to worry about always setting the correct environment @@ -158,7 +158,7 @@ allowing access over SSH. -- ------ export CVSROOT=:ext:user@server:/var/git/project.git - export CVS_SERVER=git-cvsserver + export CVS_SERVER="git cvsserver" ------ -- 4. For SSH clients that will make commits, make sure their server-side @@ -283,7 +283,7 @@ To get a checkout with the Eclipse CVS client: Protocol notes: If you are using anonymous access via pserver, just select that. Those using SSH access should choose the 'ext' protocol, and configure 'ext' access on the Preferences->Team->CVS->ExtConnection pane. Set CVS_SERVER to -'git-cvsserver'. Note that password support is not good when using 'ext', +"'git cvsserver'". Note that password support is not good when using 'ext', you will definitely want to have SSH keys setup. Alternatively, you can just use the non-standard extssh protocol that Eclipse diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 1fdf20dcc9..5d48664e62 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -49,13 +49,22 @@ include::diff-options.txt[] --stdin:: When '--stdin' is specified, the command does not take <tree-ish> arguments from the command line. Instead, it - reads either one <commit> or a list of <commit> - separated with a single space from its standard input. + reads lines containing either two <tree>, one <commit>, or a + list of <commit> from its standard input. (Use a single space + as separator.) + -When a single commit is given on one line of such input, it compares -the commit with its parents. The following flags further affects its -behavior. The remaining commits, when given, are used as if they are +When two trees are given, it compares the first tree with the second. +When a single commit is given, it compares the commit with its +parents. The remaining commits, when given, are used as if they are parents of the first commit. ++ +When comparing two trees, the ID of both trees (separated by a space +and terminated by a newline) is printed before the difference. When +comparing commits, the ID of the first (or only) commit, followed by a +newline, is printed. ++ +The following flags further affects the behavior when comparing +commits (but not trees). -m:: By default, 'git-diff-tree --stdin' does not show diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 010d9e4322..adb4ea7b1b 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -147,9 +147,9 @@ include::diff-options.txt[] to any configured headers, and may be used multiple times. --cover-letter:: - Generate a cover letter template. You still have to fill in - a description, but the shortlog and the diffstat will be - generated for you. + In addition to the patches, generate a cover letter file + containing the shortlog and the overall diffstat. You can + fill in a description in the file before sending it out. --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index ac928e198e..0af40cfb85 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -8,7 +8,9 @@ git-hash-object - Compute object ID and optionally creates a blob from a file SYNOPSIS -------- -'git hash-object' [-t <type>] [-w] [--stdin | --stdin-paths] [--] <file>... +[verse] +'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>... +'git hash-object' [-t <type>] [-w] --stdin-paths < <list-of-paths> DESCRIPTION ----------- @@ -35,6 +37,22 @@ OPTIONS --stdin-paths:: Read file names from stdin instead of from the command-line. +--path:: + Hash object as it were located at the given path. The location of + file does not directly influence on the hash value, but path is + used to determine what git filters should be applied to the object + before it can be placed to the object database, and, as result of + applying filters, the actual blob put into the object database may + differ from the given file. This option is mainly useful for hashing + temporary files located outside of the working directory or files + read from stdin. + +--no-filters:: + Hash the contents as is, ignoring any input filter that would + have been chosen by the attributes mechanism, including crlf + conversion. If the file is read from standard input then this + is always implied, unless the --path option is given. + Author ------ Written by Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index b3d8da33ee..bd49a0aee8 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -3,7 +3,7 @@ git-imap-send(1) NAME ---- -git-imap-send - Dump a mailbox from stdin into an imap folder +git-imap-send - Send a collection of patches from stdin to an IMAP folder SYNOPSIS @@ -13,9 +13,9 @@ SYNOPSIS DESCRIPTION ----------- -This command uploads a mailbox generated with git-format-patch -into an imap drafts folder. This allows patches to be sent as -other email is sent with mail clients that cannot read mailbox +This command uploads a mailbox generated with 'git-format-patch' +into an IMAP drafts folder. This allows patches to be sent as +other email is when using mail clients that cannot read mailbox files directly. Typical usage is something like: @@ -26,21 +26,75 @@ git format-patch --signoff --stdout --attach origin | git imap-send CONFIGURATION ------------- -'git-imap-send' requires the following values in the repository -configuration file (shown with examples): +To use the tool, imap.folder and either imap.tunnel or imap.host must be set +to appropriate values. + +Variables +~~~~~~~~~ + +imap.folder:: + The folder to drop the mails into, which is typically the Drafts + folder. For example: "INBOX.Drafts", "INBOX/Drafts" or + "[Gmail]/Drafts". Required to use imap-send. + +imap.tunnel:: + Command used to setup a tunnel to the IMAP server through which + commands will be piped instead of using a direct network connection + to the server. Required when imap.host is not set to use imap-send. + +imap.host:: + A URL identifying the server. Use a `imap://` prefix for non-secure + connections and a `imaps://` prefix for secure connections. + Ignored when imap.tunnel is set, but required to use imap-send + otherwise. + +imap.user:: + The username to use when logging in to the server. + +imap.password:: + The password to use when logging in to the server. + +imap.port:: + An integer port number to connect to on the server. + Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. + Ignored when imap.tunnel is set. + +imap.sslverify:: + A boolean to enable/disable verification of the server certificate + used by the SSL/TLS connection. Default is `true`. Ignored when + imap.tunnel is set. + +Examples +~~~~~~~~ + +Using tunnel mode: .......................... [imap] - Folder = "INBOX.Drafts" + folder = "INBOX.Drafts" + tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null" +.......................... +Using direct mode: + +......................... [imap] - Tunnel = "ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null" + folder = "INBOX.Drafts" + host = imap://imap.example.com + user = bob + pass = p4ssw0rd +.......................... + +Using direct mode with SSL: +......................... [imap] - Host = imap.server.com - User = bob - Pass = pwd - Port = 143 + folder = "INBOX.Drafts" + host = imaps://imap.example.com + user = bob + pass = p4ssw0rd + port = 123 + sslverify = false .......................... diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 1a7ecbf8f3..2f0c5259e0 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -8,26 +8,81 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- -'git merge-base' [--all] <commit> <commit> +'git merge-base' [--all] <commit> <commit>... DESCRIPTION ----------- -'git-merge-base' finds as good a common ancestor as possible between -the two commits. That is, given two commits A and B, `git merge-base A -B` will output a commit which is reachable from both A and B through -the parent relationship. +'git-merge-base' finds best common ancestor(s) between two commits to use +in a three-way merge. One common ancestor is 'better' than another common +ancestor if the latter is an ancestor of the former. A common ancestor +that does not have any better common ancestor than it is a 'best common +ancestor', i.e. a 'merge base'. Note that there can be more than one +merge bases between two commits. -Given a selection of equally good common ancestors it should not be -relied on to decide in any particular way. - -The 'git-merge-base' algorithm is still in flux - use the source... +Among the two commits to compute their merge bases, one is specified by +the first commit argument on the command line; the other commit is a +(possibly hypothetical) commit that is a merge across all the remaining +commits on the command line. As the most common special case, giving only +two commits from the command line means computing the merge base between +the given two commits. OPTIONS ------- --all:: - Output all common ancestors for the two commits instead of - just one. + Output all merge bases for the commits, instead of just one. + +DISCUSSION +---------- + +Given two commits 'A' and 'B', `git merge-base A B` will output a commit +which is reachable from both 'A' and 'B' through the parent relationship. + +For example, with this topology: + + o---o---o---B + / + ---o---1---o---o---o---A + +the merge base between 'A' and 'B' is '1'. + +Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the +merge base between 'A' and an hypothetical commit 'M', which is a merge +between 'B' and 'C'. For example, with this topology: + + o---o---o---o---C + / + / o---o---o---B + / / + ---2---1---o---o---o---A + +the result of `git merge-base A B C` is '1'. This is because the +equivalent topology with a merge commit 'M' between 'B' and 'C' is: + + + o---o---o---o---o + / \ + / o---o---o---o---M + / / + ---2---1---o---o---o---A + +and the result of `git merge-base A M` is '1'. Commit '2' is also a +common ancestor between 'A' and 'M', but '1' is a better common ancestor, +because '2' is an ancestor of '1'. Hence, '2' is not a merge base. + +When the history involves criss-cross merges, there can be more than one +'best' common ancestors between two commits. For example, with this +topology: + + ---1---o---A + \ / + X + / \ + ---2---o---o---B + +both '1' and '2' are merge-base of A and B. Neither one is better than +the other (both are 'best' merge base). When `--all` option is not given, +it is unspecified which best one is output. Author ------ diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 17a15acb07..685e1fed58 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -126,13 +126,25 @@ After seeing a conflict, you can do two things: up working tree changes made by 2. and 3.; 'git-reset --hard' can be used for this. - * Resolve the conflicts. `git diff` would report only the - conflicting paths because of the above 2. and 3. - Edit the working tree files into a desirable shape - ('git mergetool' can ease this task), 'git-add' or 'git-rm' - them, to make the index file contain what the merge result - should be, and run 'git-commit' to commit the result. + * Resolve the conflicts. Git will mark the conflicts in + the working tree. Edit the files into shape and + 'git-add' to the index. 'git-commit' to seal the deal. +You can work through the conflict with a number of tools: + + * Use a mergetool. 'git mergetool' to launch a graphical + mergetool which will work you through the merge. + + * Look at the diffs. 'git diff' will show a three-way diff, + highlighting changes from both the HEAD and remote versions. + + * Look at the diffs on their own. 'git log --merge -p <path>' + will show diffs first for the HEAD version and then the + remote version. + + * Look at the originals. 'git show :1:filename' shows the + common ancestor, 'git show :2:filename' shows the HEAD + version and 'git show :3:filename' shows the remote version. SEE ALSO -------- diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 98cfa3c0d0..caa07298a6 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -15,6 +15,15 @@ Given one existing commit, revert the change the patch introduces, and record a new commit that records it. This requires your working tree to be clean (no modifications from the HEAD commit). +Note: 'git revert' is used to record a new commit to reverse the +effect of an earlier commit (often a faulty one). If you want to +throw away all uncommitted changes in your working directory, you +should see linkgit:git-reset[1], particularly the '--hard' option. If +you want to extract specific files as they were in another commit, you +should see linkgit:git-checkout[1], specifically the 'git checkout +<commit> -- <filename>' syntax. Take care with these alternatives as +both will discard uncommitted changes in your working directory. + OPTIONS ------- <commit>:: diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 7d50d74cc9..49e2296a24 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -8,11 +8,13 @@ git-stash - Stash the changes in a dirty working directory away SYNOPSIS -------- [verse] -'git stash' list -'git stash' (show | apply | drop | pop ) [<stash>] +'git stash' list [<options>] +'git stash' (show | drop | pop ) [<stash>] +'git stash' apply [--index] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [<message>]] +'git stash' [save [--keep-index] [<message>]] 'git stash' clear +'git stash' create DESCRIPTION ----------- @@ -116,6 +118,11 @@ pop [<stash>]:: of the current working tree state. When no `<stash>` is given, `stash@\{0}` is assumed. See also `apply`. +create:: + + Create a stash (which is a regular commit object) and return its + object name, without storing it anywhere in the ref namespace. + DISCUSSION ---------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index bf33b0cba0..babaa9bc46 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -14,6 +14,8 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] update [--init] [--] [<path>...] 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] +'git submodule' [--quiet] foreach <command> +'git submodule' [--quiet] sync [--] [<path>...] DESCRIPTION @@ -123,6 +125,30 @@ summary:: in the submodule between the given super project commit and the index or working tree (switched by --cached) are shown. +foreach:: + Evaluates an arbitrary shell command in each checked out submodule. + The command has access to the variables $path and $sha1: + $path is the name of the submodule directory relative to the + superproject, and $sha1 is the commit as recorded in the superproject. + Any submodules defined in the superproject but not checked out are + ignored by this command. Unless given --quiet, foreach prints the name + of each submodule before evaluating the command. + A non-zero return from the command in any submodule causes + the processing to terminate. This can be overridden by adding '|| :' + to the end of the command. ++ +As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will +show the path and currently checked out commit for each submodule. + +sync:: + Synchronizes submodules' remote URL configuration setting + to the value specified in .gitmodules. This is useful when + submodule URLs change upstream and you need to update your local + repositories accordingly. ++ +"git submodule sync" synchronizes all submodules while +"git submodule sync -- A" synchronizes submodule "A" only. + OPTIONS ------- -q:: diff --git a/Documentation/git.txt b/Documentation/git.txt index b1cb972369..e178fb5813 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,6 +43,12 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: +* link:v1.6.1/git.html[documentation for release 1.6.1] + +* release notes for + link:RelNotes-1.6.1.txt[1.6.1], + link:RelNotes-1.6.0.txt[1.6.0]. + * link:v1.5.6.5/git.html[documentation for release 1.5.6.5] * release notes for @@ -492,7 +498,8 @@ other 'GIT_PAGER':: This environment variable overrides `$PAGER`. If it is set to an empty string or to the value "cat", git will not launch - a pager. + a pager. See also the `core.pager` option in + linkgit:git-config[1]. 'GIT_SSH':: If this environment variable is set then 'git-fetch' diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index d7b41142d2..5495d695c6 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -307,9 +307,22 @@ backslash, and zero or more occurrences of `sub` followed by There are a few built-in patterns to make this easier, and `tex` is one of them, so you do not have to write the above in your configuration file (you still need to enable this with the -attribute mechanism, via `.gitattributes`). Another built-in -pattern is defined for `java` that defines a pattern suitable -for program text in Java language. +attribute mechanism, via `.gitattributes`). The following built in +patterns are available: + +- `bibtex` suitable for files with BibTeX coded references. + +- `java` suitable for source code in the Java lanugage. + +- `pascal` suitable for source code in the Pascal/Delphi language. + +- `python` suitable for source code in the Python language. + +- `ruby` suitable for source code in the Ruby language. + +- `tex` suitable for source code for LaTeX documents. + +- `html` suitable for HTML/XHTML documents. Performing a three-way merge diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 49179b0a00..a417e592ac 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1366,8 +1366,9 @@ your login shell is 'bash', only `.bashrc` is read and not [NOTE] If you plan to publish this repository to be accessed over http, -you should do `chmod +x my-git.git/hooks/post-update` at this -point. This makes sure that every time you push into this +you should do `mv my-git.git/hooks/post-update.sample +my-git.git/hooks/post-update` at this point. +This makes sure that every time you push into this repository, `git update-server-info` is run. Your "public repository" is now ready to accept your changes. @@ -1486,11 +1487,11 @@ A recommended workflow for a "project lead" goes like this: If other people are pulling from your repository over dumb transport protocols (HTTP), you need to keep this repository 'dumb transport friendly'. After `git init`, -`$GIT_DIR/hooks/post-update` copied from the standard templates -would contain a call to 'git-update-server-info' but the -`post-update` hook itself is disabled by default -- enable it -with `chmod +x post-update`. This makes sure 'git-update-server-info' -keeps the necessary files up-to-date. +`$GIT_DIR/hooks/post-update.sample` copied from the standard templates +would contain a call to 'git-update-server-info' +but you need to manually enable the hook with +`mv post-update.sample post-update`. This makes sure +'git-update-server-info' keeps the necessary files up-to-date. 3. Push into the public repository from your primary repository. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index be84721781..735cf07b20 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -43,11 +43,13 @@ endif::git-rev-list[] --parents:: - Print the parents of the commit. + Print the parents of the commit. Also enables parent + rewriting, see 'History Simplification' below. --children:: - Print the children of the commit. + Print the children of the commit. Also enables parent + rewriting, see 'History Simplification' below. ifdef::git-rev-list[] --timestamp:: @@ -71,7 +73,7 @@ For example, if you have this topology: o---x---a---a branch A ----------------------------------------------------------------------- + -you would get an output line this: +you would get an output like this: + ----------------------------------------------------------------------- $ git rev-list --left-right --boundary --pretty=oneline A...B @@ -94,6 +96,7 @@ you would get an output line this: This implies the '--topo-order' option by default, but the '--date-order' option may also be specified. +ifndef::git-rev-list[] Diff Formatting ~~~~~~~~~~~~~~~ @@ -123,6 +126,7 @@ options may be given. See linkgit:git-diff-files[1] for more options. -t:: Show the tree objects in the diff output. This implies '-r'. +endif::git-rev-list[] Commit Limiting ~~~~~~~~~~~~~~~ @@ -191,14 +195,6 @@ endif::git-rev-list[] Stop when a given path disappears from the tree. ---full-history:: - - Show also parts of history irrelevant to current state of a given - path. This turns off history simplification, which removed merges - which didn't change anything at all at some child. It will still actually - simplify away merges that didn't change anything at all into either - child. - --no-merges:: Do not print commits with more than one parent. @@ -280,18 +276,144 @@ See also linkgit:git-reflog[1]. Output uninteresting commits at the boundary, which are usually not shown. +-- + +History Simplification +~~~~~~~~~~~~~~~~~~~~~~ + +When optional paths are given, 'git-rev-list' simplifies commits with +various strategies, according to the options you have selected. + +Suppose you specified `foo` as the <paths>. We shall call commits +that modify `foo` !TREESAME, and the rest TREESAME. (In a diff +filtered for `foo`, they look different and equal, respectively.) + +In the following, we will always refer to the same example history to +illustrate the differences between simplification settings. We assume +that you are filtering for a file `foo` in this commit graph: +----------------------------------------------------------------------- + .-A---M---N---O---P + / / / / / + I B C D E + \ / / / / + `-------------' +----------------------------------------------------------------------- +The horizontal line of history A--P is taken to be the first parent of +each merge. The commits are: + +* `I` is the initial commit, in which `foo` exists with contents + "asdf", and a file `quux` exists with contents "quux". Initial + commits are compared to an empty tree, so `I` is !TREESAME. + +* In `A`, `foo` contains just "foo". + +* `B` contains the same change as `A`. Its merge `M` is trivial and + hence TREESAME to all parents. + +* `C` does not change `foo`, but its merge `N` changes it to "foobar", + so it is not TREESAME to any parent. + +* `D` sets `foo` to "baz". Its merge `O` combines the strings from + `N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent. + +* `E` changes `quux` to "xyzzy", and its merge `P` combines the + strings to "quux xyzzy". Despite appearing interesting, `P` is + TREESAME to all parents. + +'rev-list' walks backwards through history, including or excluding +commits based on whether '\--full-history' and/or parent rewriting +(via '\--parents' or '\--children') are used. The following settings +are available. + +Default mode:: + + Commits are included if they are not TREESAME to any parent + (though this can be changed, see '\--sparse' below). If the + commit was a merge, and it was TREESAME to one parent, follow + only that parent. (Even if there are several TREESAME + parents, follow only one of them.) Otherwise, follow all + parents. ++ +This results in: ++ +----------------------------------------------------------------------- + .-A---N---O + / / + I---------D +----------------------------------------------------------------------- ++ +Note how the rule to only follow the TREESAME parent, if one is +available, removed `B` from consideration entirely. `C` was +considered via `N`, but is TREESAME. Root commits are compared to an +empty tree, so `I` is !TREESAME. ++ +Parent/child relations are only visible with --parents, but that does +not affect the commits selected in default mode, so we have shown the +parent lines. + +--full-history without parent rewriting:: + + This mode differs from the default in one point: always follow + all parents of a merge, even if it is TREESAME to one of them. + Even if more than one side of the merge has commits that are + included, this does not imply that the merge itself is! In + the example, we get ++ +----------------------------------------------------------------------- + I A B N D O +----------------------------------------------------------------------- ++ +`P` and `M` were excluded because they are TREESAME to a parent. `E`, +`C` and `B` were all walked, but only `B` was !TREESAME, so the others +do not appear. ++ +Note that without parent rewriting, it is not really possible to talk +about the parent/child relationships between the commits, so we show +them disconnected. + +--full-history with parent rewriting:: + + Ordinary commits are only included if they are !TREESAME + (though this can be changed, see '\--sparse' below). ++ +Merges are always included. However, their parent list is rewritten: +Along each parent, prune away commits that are not included +themselves. This results in ++ +----------------------------------------------------------------------- + .-A---M---N---O---P + / / / / / + I B / D / + \ / / / / + `-------------' +----------------------------------------------------------------------- ++ +Compare to '\--full-history' without rewriting above. Note that `E` +was pruned away because it is TREESAME, but the parent list of P was +rewritten to contain `E`'s parent `I`. The same happened for `C` and +`N`. Note also that `P` was included despite being TREESAME. + +In addition to the above settings, you can change whether TREESAME +affects inclusion: + --dense:: + + Commits that are walked are included if they are not TREESAME + to any parent. + --sparse:: -When optional paths are given, the default behaviour ('--dense') is to -only output commits that changes at least one of them, and also ignore -merges that do not touch the given paths. + All commits that are walked are included. ++ +Note that without '\--full-history', this still simplifies merges: if +one of the parents is TREESAME, we follow only that one, so the other +sides of the merge are never walked. -Use the '--sparse' flag to makes the command output all eligible commits -(still subject to count and age limitation), but apply merge -simplification nevertheless. ifdef::git-rev-list[] +Bisection Helpers +~~~~~~~~~~~~~~~~~ + --bisect:: Limit output to the one commit object which is roughly halfway between @@ -341,7 +463,6 @@ after all the sorted commit objects, there will be the same text as if `--bisect-vars` had been used alone. endif::git-rev-list[] --- Commit Ordering ~~~~~~~~~~~~~~~ diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index e99921108e..08d1310bf5 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1890,7 +1890,7 @@ adjustments to give web clients some extra information they need: $ mv proj.git /home/you/public_html/proj.git $ cd proj.git $ git --bare update-server-info -$ chmod a+x hooks/post-update +$ mv hooks/post-update.sample hooks/post-update ------------------------------------------------- (For an explanation of the last two lines, see |