diff options
Diffstat (limited to 'Documentation')
54 files changed, 652 insertions, 183 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index c34c1cae20..5cd8b63ac5 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -187,17 +187,18 @@ git.info: user-manual.texi user-manual.texi: user-manual.xml $(RM) $@+ $@ - $(DOCBOOK2X_TEXI) user-manual.xml --to-stdout | $(PERL_PATH) fix-texi.perl >$@+ + $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout | \ + $(PERL_PATH) fix-texi.perl >$@+ mv $@+ $@ gitman.texi: $(MAN_XML) cat-texi.perl $(RM) $@+ $@ - ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --to-stdout $(xml);)) | \ - $(PERL_PATH) cat-texi.perl $@ >$@+ + ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \ + --to-stdout $(xml);)) | $(PERL_PATH) cat-texi.perl $@ >$@+ mv $@+ $@ gitman.info: gitman.texi - $(MAKEINFO) --no-split $*.texi + $(MAKEINFO) --no-split --no-validate $*.texi $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml $(RM) $@+ $@ diff --git a/Documentation/RelNotes-1.5.4.7.txt b/Documentation/RelNotes-1.5.4.7.txt new file mode 100644 index 0000000000..9065a0e273 --- /dev/null +++ b/Documentation/RelNotes-1.5.4.7.txt @@ -0,0 +1,10 @@ +GIT v1.5.4.7 Release Notes +========================== + +Fixes since 1.5.4.7 +------------------- + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. diff --git a/Documentation/RelNotes-1.5.5.6.txt b/Documentation/RelNotes-1.5.5.6.txt new file mode 100644 index 0000000000..d5e85cb70e --- /dev/null +++ b/Documentation/RelNotes-1.5.5.6.txt @@ -0,0 +1,10 @@ +GIT v1.5.5.6 Release Notes +========================== + +Fixes since 1.5.5.5 +------------------- + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. diff --git a/Documentation/RelNotes-1.5.6.6.txt b/Documentation/RelNotes-1.5.6.6.txt new file mode 100644 index 0000000000..79da23db5a --- /dev/null +++ b/Documentation/RelNotes-1.5.6.6.txt @@ -0,0 +1,10 @@ +GIT v1.5.6.6 Release Notes +========================== + +Fixes since 1.5.6.5 +------------------- + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. diff --git a/Documentation/RelNotes-1.6.0.5.txt b/Documentation/RelNotes-1.6.0.5.txt index 1dc101c6a3..a08bb96738 100644 --- a/Documentation/RelNotes-1.6.0.5.txt +++ b/Documentation/RelNotes-1.6.0.5.txt @@ -4,40 +4,53 @@ GIT v1.6.0.5 Release Notes Fixes since v1.6.0.4 -------------------- -* 'git checkout' used to crash when your HEAD was pointing at a deleted +* "git checkout" used to crash when your HEAD was pointing at a deleted branch. -* 'git checkout' from an un-checked-out state did not allow switching out +* "git checkout" from an un-checked-out state did not allow switching out of the current branch. -* 'git diff' always allowed GIT_EXTERNAL_DIFF and --no-ext-diff was no-op for +* "git diff" always allowed GIT_EXTERNAL_DIFF and --no-ext-diff was no-op for the command. -* 'git fast-export' did not export all tags. +* Giving 3 or more tree-ish to "git diff" is supposed to show the combined + diff from second and subsequent trees to the first one, but the order was + screwed up. -* 'git ls-files --with-tree=<tree>' did not work with options other +* "git fast-export" did not export all tags. + +* "git ls-files --with-tree=<tree>" did not work with options other than -c, most notably with -m. -* 'git pack-objects' did not make its best effort to honor --max-pack-size +* "git pack-objects" did not make its best effort to honor --max-pack-size option when a single first object already busted the given limit and placed many objects in a single pack. -* 'git-p4' fast import frontend was too eager to trigger its keyword expansion +* "git-p4" fast import frontend was too eager to trigger its keyword expansion logic, even on a keyword-looking string that does not have closing '$' on the same line. -* 'git push $there' when the remote $there is defined in $GIT_DIR/branches/$there +* "git push $there" when the remote $there is defined in $GIT_DIR/branches/$there behaves more like what cg-push from Cogito used to work. -* 'git tag' did not complain when given mutually incompatible set of options. +* when giving up resolving a conflicted merge, "git reset --hard" failed + to remove new paths from the working tree. -* 'make check' cannot be run without sparse; people may have meant to say - 'make test' instead, so suggest that. +* "git tag" did not complain when given mutually incompatible set of options. -* Many unsafe call to sprintf() style varargs functions are corrected. +* The message constructed in the internal editor was discarded when "git + tag -s" failed to sign the message, which was often caused by the user + not configuring GPG correctly. -* Also contains quite a few documentation updates. +* "make check" cannot be run without sparse; people may have meant to say + "make test" instead, so suggest that. + +* Internal diff machinery had a corner case performance bug that choked on + a large file with many repeated contents. --- -O=v1.6.0.4-39-g27f6496 +* "git repack" used to grab objects out of packs marked with .keep + into a new pack. +* Many unsafe call to sprintf() style varargs functions are corrected. + +* Also contains quite a few documentation updates. diff --git a/Documentation/RelNotes-1.6.0.6.txt b/Documentation/RelNotes-1.6.0.6.txt new file mode 100644 index 0000000000..64ece1ffd5 --- /dev/null +++ b/Documentation/RelNotes-1.6.0.6.txt @@ -0,0 +1,33 @@ +GIT v1.6.0.6 Release Notes +========================== + +Fixes since 1.6.0.5 +------------------- + + * "git fsck" had a deep recursion that wasted stack space. + + * "git fast-export" and "git fast-import" choked on an old style + annotated tag that lack the tagger information. + + * "git mergetool -- file" did not correctly skip "--" marker that + signals the end of options list. + + * "git show $tag" segfaulted when an annotated $tag pointed at a + nonexistent object. + + * "git show 2>error" when the standard output is automatically redirected + to the pager redirected the standard error to the pager as well; there + was no need to. + + * "git send-email" did not correctly handle list of addresses when + they had quoted comma (e.g. "Lastname, Givenname" <mail@addre.ss>). + + * Logic to discover branch ancestry in "git svn" was unreliable when + the process to fetch history was interrupted. + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. + +Also contains numerous documentation typofixes. diff --git a/Documentation/RelNotes-1.6.1.1.txt b/Documentation/RelNotes-1.6.1.1.txt new file mode 100644 index 0000000000..10b38e6ec1 --- /dev/null +++ b/Documentation/RelNotes-1.6.1.1.txt @@ -0,0 +1,23 @@ +GIT v1.6.1.1 Release Notes +========================== + +Fixes since v1.6.1 +------------------ + +* "git describe --all" complained when a commit is described with a tag, + which was nonsense. + +* "git log --pretty=format:%s" did not handle a multi-line subject the + same way as built-in log listers (i.e. shortlog, --pretty=oneline, etc.) + +* "git daemon", and "git merge-file" are more careful when freopen fails + and barf, instead of going on and writing to unopened filehandle. + +Other documentation fixes. + +--- +exec >/var/tmp/1 +O=v1.6.1-15-ga9e67c8 +echo O=$(git describe maint) +git shortlog --no-merges $O..maint + diff --git a/Documentation/RelNotes-1.6.1.txt b/Documentation/RelNotes-1.6.1.txt index 698c1e0b77..adb7ccab0a 100644 --- a/Documentation/RelNotes-1.6.1.txt +++ b/Documentation/RelNotes-1.6.1.txt @@ -69,12 +69,18 @@ on. * "git add -N path..." adds the named paths as an empty blob, so that subsequent "git diff" will show a diff as if they are creation events. +* "git add" gained a built-in synonym for people who want to say "stage + changes" instead of "add contents to the staging area" which amounts + to the same thing. + * "git apply" learned --include=paths option, similar to the existing --exclude=paths option. * "git bisect" is careful about a user mistake and suggests testing of merge base first when good is not a strict ancestor of bad. +* "git bisect skip" can take a range of commits. + * "git blame" re-encodes the commit metainfo to UTF-8 from i18n.commitEncoding by default. @@ -129,16 +135,10 @@ on. cannot produce a patch that can be applied, so this is disabled in format-patch among other things). -* "git diff" hunk header pattern for ObjC has been added. - * "--cached" option to "git diff has an easier to remember synonym "--staged", to ask "what is the difference between the given commit and the contents staged in the index?" -* a "textconv" filter that makes binary files textual form for human - consumption can be specified as an attribute for paths; "git diff" - learnt to make use of it. - * "git for-each-ref" learned "refname:short" token that gives an unambiguously abbreviated refname. @@ -191,9 +191,6 @@ on. * "git remote show $remote" lists remote branches one-per-line now. -* when giving up resolving a conflicted merge, "git reset --hard" failed - to remove new paths from the working tree. [cherry-pick to 'maint'?] - * "git send-email" can be given revision range instead of files and maildirs on the command line, and automatically runs format-patch to generate patches for the given revision range. @@ -233,24 +230,44 @@ Fixes since v1.6.0 All of the fixes in v1.6.0.X maintenance series are included in this release, unless otherwise noted. +* Porcelains implemented as shell scripts were utterly confused when you + entered to a subdirectory of a work tree from sideways, following a + symbolic link (this may need to be backported to older releases later). + +* Tracking symbolic links would work better on filesystems whose lstat() + returns incorrect st_size value for them. + * "git add" and "git update-index" incorrectly allowed adding S/F when S is a tracked symlink that points at a directory D that has a path F in it (we still need to fix a similar nonsense when S is a submodule and F is a path in it). +* "git am" after stopping at a broken patch lost --whitespace, -C, -p and + --3way options given from the command line initially. + * "git diff --stdin" used to take two trees on a line and compared them, but we dropped support for such a use case long time ago. This has been resurrected. -* Giving 3 or more tree-ish to "git diff" is supposed to show the combined - diff from second and subsequent trees to the first one. b75271d ("git - diff <tree>{3,}": do not reverse order of arguments, 2008-10-10) needs - to be cherry-picked to 'maint'. - * "git filter-branch" failed to rewrite a tag name with slashes in it. -* "git repack" used to grab objects out of packs marked with .keep - into a new pack (fix scheduled to be further downmerged to maint). +* "git http-push" did not understand URI scheme other than opaquelocktoken + when acquiring a lock from the server (this may need to be backported to + older releases later). + +* After "git rebase -p" stopped with conflicts while replaying a merge, + "git rebase --continue" did not work (may need to be backported to older + releases). + +* "git revert" records relative to which parent a revert was made when + reverting a merge. Together with new documentation that explains issues + around reverting a merge and merging from the updated branch later, this + hopefully will reduce user confusion (this may need to be backported to + older releases later). + +* "git rm --cached" used to allow an empty blob that was added earlier to + be removed without --force, even when the file in the work tree has + since been modified. * "git push --tags --all $there" failed with generic usage message without telling saying these two options are incompatible. @@ -259,12 +276,11 @@ release, unless otherwise noted. timestamp part, exposing internal implementation detail. Also these did not work with --fixed-strings match at all. -* Internal diff machinery had a corner case performance bug that choked on a - large file with many repeated contents (fix scheduled to be further cherry- - picked to maint). +* "gitweb" did not mark non-ASCII characters imported from external HTML fragments + correctly. -- exec >/var/tmp/1 -O=v1.6.0.4-854-gaaab7ea +O=v1.6.1-rc3-74-gf66bc5f echo O=$(git describe master) git shortlog --no-merges $O..master ^maint diff --git a/Documentation/RelNotes-1.6.2.txt b/Documentation/RelNotes-1.6.2.txt new file mode 100644 index 0000000000..1a80626781 --- /dev/null +++ b/Documentation/RelNotes-1.6.2.txt @@ -0,0 +1,28 @@ +GIT v1.6.2 Release Notes +======================== + +Updates since v1.6.1 +-------------------- + +(subsystems) + +(portability) + +(performance) + +(usability, bells and whistles) + +(internal) + + +Fixes since v1.6.1 +------------------ + +All of the fixes in v1.6.1.X maintenance series are included in this +release, unless otherwise noted. + +-- +exec >/var/tmp/1 +O=v1.6.1 +echo O=$(git describe master) +git shortlog --no-merges $O..master ^maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f0295c60f5..ba07c8c571 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -222,6 +222,9 @@ D-C-O. Indeed you are encouraged to do so. Do not forget to place an in-body "From: " line at the beginning to properly attribute the change to its true author (see (2) above). +Also notice that a real name is used in the Signed-off-by: line. Please +don't hide your real name. + Some people also put extra tags at the end. "Acked-by:" says that the patch was reviewed by the person who diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 2da867d2f8..1e735df3bb 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -7,6 +7,9 @@ # Show GIT link as: <command>(<section>); if section is defined, else just show # the command. +[macros] +(?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= + [attributes] asterisk=* plus=+ diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl index dbc133cd3c..828ec62554 100755 --- a/Documentation/cat-texi.perl +++ b/Documentation/cat-texi.perl @@ -18,8 +18,12 @@ close TMP; printf '\input texinfo @setfilename gitman.info -@documentencoding us-ascii -@node Top,,%s +@documentencoding UTF-8 +@dircategory Development +@direntry +* Git Man Pages: (gitman). Manual pages for Git revision control system +@end direntry +@node Top,,, (dir) @top Git Manual Pages @documentlanguage en @menu diff --git a/Documentation/config.txt b/Documentation/config.txt index b233fe5352..52786c7df5 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -601,10 +601,6 @@ 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 @@ -639,6 +635,10 @@ diff.renames:: will enable basic rename detection. If set to "copies" or "copy", it will detect copies, as well. +diff.suppress-blank-empty:: + A boolean to inhibit the standard behavior of printing a space + before each empty output line. Defaults to false. + fetch.unpackLimit:: If the number of objects fetched over the git native transfer is below this @@ -839,6 +839,57 @@ gui.blamehistoryctx:: Context` menu item is invoked from 'git gui blame'. If this variable is set to zero, the whole history is shown. +guitool.<name>.cmd:: + Specifies the shell command line to execute when the corresponding item + of the linkgit:git-gui[1] `Tools` menu is invoked. This option is + mandatory for every tool. The command is executed from the root of + the working directory, and in the environment it receives the name of + the tool as 'GIT_GUITOOL', the name of the currently selected file as + 'FILENAME', and the name of the current branch as 'CUR_BRANCH' (if + the head is detached, 'CUR_BRANCH' is empty). + +guitool.<name>.needsfile:: + Run the tool only if a diff is selected in the GUI. It guarantees + that 'FILENAME' is not empty. + +guitool.<name>.noconsole:: + Run the command silently, without creating a window to display its + output. + +guitool.<name>.norescan:: + Don't rescan the working directory for changes after the tool + finishes execution. + +guitool.<name>.confirm:: + Show a confirmation dialog before actually running the tool. + +guitool.<name>.argprompt:: + Request a string argument from the user, and pass it to the tool + through the 'ARGS' environment variable. Since requesting an + argument implies confirmation, the 'confirm' option has no effect + if this is enabled. If the option is set to 'true', 'yes', or '1', + the dialog uses a built-in generic prompt; otherwise the exact + value of the variable is used. + +guitool.<name>.revprompt:: + Request a single valid revision from the user, and set the + 'REVISION' environment variable. In other aspects this option + is similar to 'argprompt', and can be used together with it. + +guitool.<name>.revunmerged:: + Show only unmerged branches in the 'revprompt' subdialog. + This is useful for tools similar to merge or rebase, but not + for things like checkout or reset. + +guitool.<name>.title:: + Specifies the title to use for the prompt dialog. The default + is the tool name. + +guitool.<name>.prompt:: + Specifies the general prompt string to display at the top of + the dialog, before subsections for 'argprompt' and 'revprompt'. + The default value includes the actual command. + help.browser:: Specify the browser that will be used to display help in the 'web' format. See linkgit:git-help[1]. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index aafd3a3941..1eeb1c7683 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -58,7 +58,7 @@ Possible status letters are: be committed) - X: "unknown" change type (most probably a bug, please report it) -Status letters C and M are always followed by a score (denoting the +Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or copy), and are the only ones to be so. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 517e1eba3c..0f25ba7e38 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -143,15 +143,15 @@ different from it. A `-` character in the column N means that the line appears in fileN but it does not appear in the result. A `+` character -in the column N means that the line appears in the last file, +in the column N means that the line appears in the result, and fileN does not have that line (in other words, the line was added, from the point of view of that parent). In the above example output, the function signature was changed from both files (hence two `-` removals from both file1 and file2, plus `++` to mean one line that was added does not appear -in either file1 nor file2). Also two other lines are the same -from file1 but do not appear in file2 (hence prefixed with ` +`). +in either file1 nor file2). Also eight other lines are the same +from file1 but do not appear in file2 (hence prefixed with `{plus}`). When shown by `git diff-tree -c`, it compares the parents of a merge commit with the merge result (i.e. file1..fileN are the diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index c62b45cdba..b432d2518a 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -19,16 +19,12 @@ endif::git-format-patch[] ifndef::git-format-patch[] -p:: +-u:: Generate patch (see section on generating patches). {git-diff? This is the default.} endif::git-format-patch[] --u:: - Synonym for "-p". - -U<n>:: - Shorthand for "--unified=<n>". - --unified=<n>:: Generate diffs with <n> lines of context instead of the usual three. Implies "-p". @@ -190,31 +186,25 @@ endif::git-format-patch[] can name which subdirectory to make the output relative to by giving a <path> as an argument. +-a:: --text:: Treat all files as text. --a:: - Shorthand for "--text". - --ignore-space-at-eol:: Ignore changes in whitespace at EOL. +-b:: --ignore-space-change:: Ignore changes in amount of whitespace. This ignores whitespace at line end, and considers all other sequences of one or more whitespace characters to be equivalent. --b:: - Shorthand for "--ignore-space-change". - +-w:: --ignore-all-space:: Ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none. --w:: - Shorthand for "--ignore-all-space". - --exit-code:: Make the program exit with codes similar to diff(1). That is, it exits with 1 if there were differences and diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 39034ec7d6..147ea38197 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -19,7 +19,7 @@ on the subcommand: git bisect start [<bad> [<good>...]] [--] [<paths>...] git bisect bad [<rev>] git bisect good [<rev>...] - git bisect skip [<rev>...] + git bisect skip [(<rev>|<range>)...] git bisect reset [<branch>] git bisect visualize git bisect replay <logfile> @@ -164,6 +164,25 @@ But computing the commit to test may be slower afterwards and git may eventually not be able to tell the first bad among a bad and one or more "skip"ped commits. +You can even skip a range of commits, instead of just one commit, +using the "'<commit1>'..'<commit2>'" notation. For example: + +------------ +$ git bisect skip v2.5..v2.6 +------------ + +would mean that no commit between `v2.5` excluded and `v2.6` included +can be tested. + +Note that if you want to also skip the first commit of a range you can +use something like: + +------------ +$ git bisect skip v2.5 v2.5..v2.6 +------------ + +and the commit pointed to by `v2.5` will be skipped too. + Cutting down bisection by giving more parameters to bisect start ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 168333a588..9cd51514db 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -27,7 +27,7 @@ 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, or from a named commit. In +the index file, or from a named <tree-ish> (most often a commit). In this case, the `-b` options is meaningless and giving either of them results in an error. <tree-ish> argument can be used to specify a specific tree-ish (i.e. commit, tag or tree) @@ -232,7 +232,6 @@ the `-m` option, you would see something like this: ------------ $ git checkout -m mytopic Auto-merging frotz -merge: warning: conflicts during merge ERROR: Merge conflict in frotz fatal: merge program failed ------------ diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 6203461f41..b5d81be7ec 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -166,7 +166,7 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) 'git-commit' if any paths are given on the command line, in which case this option can be omitted. If this option is specified together with '--amend', then - no paths need be specified, which can be used to amend + no paths need to be specified, which can be used to amend the last commit without committing changes that have already been staged. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 28e1861094..19a8917b83 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -279,7 +279,7 @@ If you want to know all the values for a multivar, do: % git config --get-all core.gitproxy ------------ -If you like to live dangerous, you can replace *all* core.gitproxy by a +If you like to live dangerously, you can replace *all* core.gitproxy by a new one with ------------ diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index f1a570a874..36f00aed67 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -110,9 +110,9 @@ OPTIONS --user-path:: --user-path=path:: - Allow ~user notation to be used in requests. When + Allow {tilde}user notation to be used in requests. When specified with no parameter, requests to - git://host/~alice/foo is taken as a request to access + git://host/{tilde}alice/foo is taken as a request to access 'foo' repository in the home directory of user `alice`. If `--user-path=path` is specified, the same request is taken as a request to access `path/foo` repository in diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 5d48664e62..23b7abd3c6 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -43,7 +43,7 @@ include::diff-options.txt[] show tree entry itself as well as subtrees. Implies -r. --root:: - When '--root' is specified the initial commit will be showed as a big + When '--root' is specified the initial commit will be shown as a big creation event. This is equivalent to a diff against the NULL tree. --stdin:: @@ -63,7 +63,7 @@ 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 +The following flags further affect the behavior when comparing commits (but not trees). -m:: diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index b974e2115b..0c9eb567cb 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -15,7 +15,7 @@ DESCRIPTION This program dumps the given revisions in a form suitable to be piped into 'git-fast-import'. -You can use it as a human readable bundle replacement (see +You can use it as a human-readable bundle replacement (see linkgit:git-bundle[1]), or as a kind of an interactive 'git-filter-branch'. @@ -65,6 +65,12 @@ If the backend uses a similar \--import-marks file, this allows for incremental bidirectional exporting of the repository by keeping the marks the same across runs. +--fake-missing-tagger:: + Some old repositories have tags without a tagger. The + fast-import protocol was pretty strict about that, and did not + allow that. So fake a tagger to be able to fast-import the + output. + EXAMPLES -------- diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index d5a7647219..287c4fc5e0 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -79,7 +79,8 @@ that aren't readable from any of the specified head nodes. So for example - git fsck --unreachable HEAD $(cat .git/refs/heads/*) + git fsck --unreachable HEAD \ + $(git for-each-ref --format="%(objectname)" refs/heads) will do quite a _lot_ of verification on the tree. There are a few extra validity tests to be added (make sure that tree objects are diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 31eccea5bc..8d95aaa304 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- -Reading a single e-mail message from the standard input, and +Reads a single e-mail message from the standard input, and writes the commit log message in <msg> file, and the patches in <patch> file. The author name, e-mail and e-mail subject are written out to the standard output to be used by 'git-am' diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 2f0c5259e0..767486c770 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -16,15 +16,15 @@ DESCRIPTION '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 +that does not have any better common ancestor is a 'best common ancestor', i.e. a 'merge base'. Note that there can be more than one -merge bases between two commits. +merge base for a pair of commits. -Among the two commits to compute their merge bases, one is specified by +Among the two commits to compute the merge base from, 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 +commits on the command line. As the most common special case, specifying only +two commits on the command line means computing the merge base between the given two commits. OPTIONS @@ -47,7 +47,7 @@ For example, with this topology: 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 +merge base between 'A' and a hypothetical commit 'M', which is a merge between 'B' and 'C'. For example, with this topology: o---o---o---o---C @@ -71,8 +71,7 @@ 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: +'best' common ancestor for two commits. For example, with this topology: ---1---o---A \ / @@ -80,8 +79,8 @@ topology: / \ ---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, +both '1' and '2' are merge-bases of A and B. Neither one is better than +the other (both are 'best' merge bases). When the `--all` option is not given, it is unspecified which best one is output. Author diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 024ec015a3..303537357b 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -15,17 +15,17 @@ SYNOPSIS DESCRIPTION ----------- -'git-file-merge' incorporates all changes that lead from the `<base-file>` +'git-merge-file' incorporates all changes that lead from the `<base-file>` to `<other-file>` into `<current-file>`. The result ordinarily goes into `<current-file>`. 'git-merge-file' is useful for combining separate changes to an original. Suppose `<base-file>` is the original, and both -`<current-file>` and `<other-file>` are modifications of `<base-file>`. -Then 'git-merge-file' combines both changes. +`<current-file>` and `<other-file>` are modifications of `<base-file>`, +then 'git-merge-file' combines both changes. A conflict occurs if both `<current-file>` and `<other-file>` have changes in a common segment of lines. If a conflict is found, 'git-merge-file' -normally outputs a warning and brackets the conflict with <<<<<<< and ->>>>>>> lines. A typical conflict will look like this: +normally outputs a warning and brackets the conflict with lines containing +<<<<<<< and >>>>>>> markers. A typical conflict will look like this: <<<<<<< A lines in file A @@ -60,7 +60,7 @@ OPTIONS `<current-file>`. -q:: - Quiet; do not warn about conflicts. + Quiet; do not warn about conflicts. EXAMPLES diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index ff088c5c29..123e6d024a 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -29,11 +29,11 @@ OPTIONS Instead of stopping at the first failed merge, do all of them in one shot - continue with merging even when previous merges returned errors, and only return the error code after all the - merges are over. + merges. -q:: - Do not complain about failed merge program (the merge program - failure usually indicates conflicts during merge). This is for + Do not complain about a failed merge program (a merge program + failure usually indicates conflicts during the merge). This is for porcelains which might want to emit custom messages. If 'git-merge-index' is called with multiple <file>s (or -a) then it diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index dbb0c18668..f869a7f00f 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -14,14 +14,14 @@ DESCRIPTION ----------- Reads three treeish, and output trivial merge results and conflicting stages to the standard output. This is similar to -what three-way read-tree -m does, but instead of storing the +what three-way 'git read-tree -m' does, but instead of storing the results in the index, the command outputs the entries to the standard output. This is meant to be used by higher level scripts to compute -merge results outside index, and stuff the results back into the +merge results outside of the index, and stuff the results back into the index. For this reason, the output from the command omits -entries that match <branch1> tree. +entries that match the <branch1> tree. Author ------ diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 1f30830d46..f7be5846a6 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -69,20 +69,20 @@ Three kinds of merge can happen: simplest case, called "Already up-to-date." * `HEAD` is already contained in the merged commit. This is the - most common case especially when involved through 'git pull': - you are tracking an upstream repository, committed no local + most common case especially when invoked from 'git pull': + you are tracking an upstream repository, have committed no local changes and now you want to update to a newer upstream revision. - Your `HEAD` (and the index) is updated to at point the merged + Your `HEAD` (and the index) is updated to point at the merged commit, without creating an extra merge commit. This is called "Fast-forward". * Both the merged commit and `HEAD` are independent and must be - tied together by a merge commit that has them both as its parents. + tied together by a merge commit that has both of them as its parents. The rest of this section describes this "True merge" case. The chosen merge strategy merges the two commits into a single new source tree. -When things cleanly merge, these things happen: +When things merge cleanly, this is what happens: 1. The results are updated both in the index file and in your working tree; @@ -91,16 +91,16 @@ When things cleanly merge, these things happen: 4. The `HEAD` pointer gets advanced. Because of 2., we require that the original state of the index -file to match exactly the current `HEAD` commit; otherwise we +file matches exactly the current `HEAD` commit; otherwise we will write out your local changes already registered in your index file along with the merge result, which is not good. -Because 1. involves only the paths different between your +Because 1. involves only those paths differing between your branch and the remote branch you are pulling from during the merge (which is typically a fraction of the whole tree), you can have local modifications in your working tree as long as they do not overlap with what the merge updates. -When there are conflicts, these things happen: +When there are conflicts, the following happens: 1. `HEAD` stays the same. @@ -111,8 +111,8 @@ When there are conflicts, these things happen: versions; stage1 stores the version from the common ancestor, stage2 from `HEAD`, and stage3 from the remote branch (you can inspect the stages with `git ls-files -u`). The working - tree files have the result of "merge" program; i.e. 3-way - merge result with familiar conflict markers `<<< === >>>`. + tree files contain the result of the "merge" program; i.e. 3-way + merge results with familiar conflict markers `<<< === >>>`. 4. No other changes are done. In particular, the local modifications you had before you started merge will stay the @@ -145,13 +145,13 @@ Git makes conflict resolution easy. And here is another line that is cleanly resolved or unmodified. ------------ -The area a pair of conflicting changes happened is marked with markers +The area where a pair of conflicting changes happened is marked with markers "`<<<<<<<`", "`=======`", and "`>>>>>>>`". The part before the "`=======`" -is typically your side, and the part after it is typically their side. +is typically your side, and the part afterwards is typically their side. -The default format does not show what the original said in the conflicted -area. You cannot tell how many lines are deleted and replaced with the -Barbie's remark by your side. The only thing you can tell is that your +The default format does not show what the original said in the conflicting +area. You cannot tell how many lines are deleted and replaced with +Barbie's remark on your side. The only thing you can tell is that your side wants to say it is hard and you'd prefer to go shopping, while the other side wants to claim it is easy. @@ -186,14 +186,14 @@ HOW TO RESOLVE CONFLICTS After seeing a conflict, you can do two things: - * Decide not to merge. The only clean-up you need are to reset + * Decide not to merge. The only clean-ups you need are to reset the index file to the `HEAD` commit to reverse 2. and to clean up working tree changes made by 2. and 3.; 'git-reset --hard' can be used for this. * 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. + 'git-add' them to the index. Use 'git-commit' to seal the deal. You can work through the conflict with a number of tools: diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index e0b2703b38..602e7c6d3b 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -38,7 +38,7 @@ can configure the absolute path to kdiff3 by setting `mergetool.kdiff3.path`. Otherwise, 'git-mergetool' assumes the tool is available in PATH. + -Instead of running one of the known merge tool programs +Instead of running one of the known merge tool programs, 'git-mergetool' can be customized to run an alternative program by specifying the command line to invoke in a configuration variable `mergetool.<tool>.cmd`. @@ -55,7 +55,7 @@ of the file to which the merge tool should write the result of the merge resolution. + If the custom merge tool correctly indicates the success of a -merge resolution with its exit code then the configuration +merge resolution with its exit code, then the configuration variable `mergetool.<tool>.trustExitCode` can be set to `true`. Otherwise, 'git-mergetool' will prompt the user to indicate the success of the resolution after the custom tool has exited. diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 6b2f8c4de7..514f03c979 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -86,7 +86,7 @@ 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 no +file exists and is executable, it will be invoked once with no parameters. The standard input of the hook will be one line for each successfully updated ref: @@ -133,7 +133,7 @@ post-update Hook ---------------- After all other processing, if at least one ref was updated, and if $GIT_DIR/hooks/post-update file exists and is executable, then -post-update will called with the list of refs that have been updated. +post-update will be called with the list of refs that have been updated. This can be used to implement any repository wide cleanup tasks. The exit code from this hook invocation is ignored; the only thing diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index d99236e14d..7f7a5445c7 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -28,7 +28,7 @@ updated. This command is to manage the information recorded in it. The subcommand "expire" is used to prune older reflog entries. Entries older than `expire` time, or entries older than -`expire-unreachable` time and are not reachable from the current +`expire-unreachable` time and not reachable from the current tip, are removed from the reflog. This is typically not used directly by the end users -- instead, see linkgit:git-gc[1]. @@ -71,7 +71,7 @@ them. which in turn defaults to 90 days. --expire-unreachable=<time>:: - Entries older than this time and are not reachable from + Entries older than this time and not reachable from the current tip of the branch are pruned. Without the option it is taken from configuration `gc.reflogExpireUnreachable`, which in turn defaults to diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index c542b0caf7..abb25d1c00 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -135,7 +135,7 @@ Undo a merge or pull:: $ git pull <1> Auto-merging nitfol CONFLICT (content): Merge conflict in nitfol -Automatic merge failed/prevented; fix up by hand +Automatic merge failed; fix conflicts and then commit the result. $ git reset --hard <2> $ git pull . topic/branch <3> Updating from 41223... to 13134... @@ -204,6 +204,8 @@ $ git reset <3> <3> At this point the index file still has all the WIP changes you committed as 'snapshot WIP'. This updates the index to show your WIP files as uncommitted. ++ +See also linkgit:git-stash[1]. Reset a single file in the index:: + diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index caa07298a6..5e1175800a 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -44,6 +44,14 @@ OPTIONS option specifies the parent number (starting from 1) of the mainline and allows revert to reverse the change relative to the specified parent. ++ +Reverting a merge commit declares that you will never want the tree changes +brought in by the merge. As a result, later merges will only bring in tree +changes introduced by commits that are not ancestors of the previously +reverted merge. This may or may not be what you want. ++ +See the link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for +more details. --no-edit:: With this option, 'git-revert' will not start the commit diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index acf8bf41d6..b69846e522 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -46,7 +46,7 @@ The --cc option must be repeated for each user you want on the cc list. Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an introductory message for the patch series. + -When compose is in used, git send-email gets less interactive will use the +When '--compose' is used, git send-email gets less interactive will use the values of the headers you set there. If the body of the email (what you type after the headers and a blank line) only contains blank (or GIT: prefixed) lines, the summary won't be sent, but git-send-email will still use the @@ -197,12 +197,6 @@ Administering --[no-]validate:: Perform sanity checks on patches. Currently, validation means the following: - ---[no-]format-patch:: - When an argument may be understood either as a reference or as a file name, - choose to understand it as a format-patch argument ('--format-patch') - or as a file name ('--no-format-patch'). By default, when such a conflict - occurs, git send-email will fail. + -- * Warn of patches that contain lines longer than 998 characters; this @@ -212,6 +206,12 @@ Administering Default is the value of 'sendemail.validate'; if this is not set, default to '--validate'. +--[no-]format-patch:: + When an argument may be understood either as a reference or as a file name, + choose to understand it as a format-patch argument ('--format-patch') + or as a file name ('--no-format-patch'). By default, when such a conflict + occurs, git send-email will fail. + CONFIGURATION ------------- diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 7ccf31ccc4..8f7c0e226d 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -48,15 +48,41 @@ OPTIONS FILES ----- -If the file `.mailmap` exists, it will be used for mapping author -email addresses to a real author name. One mapping per line, first -the author name followed by the email address enclosed by -'<' and '>'. Use hash '#' for comments. Example: +If a file `.mailmap` exists at the toplevel of the repository, +it is used to map an author email address to a canonical real name. This +can be used to coalesce together commits by the same person where their +name was spelled differently (whether with the same email address or +not). + +Each line in the file consists, in this order, of the canonical real name +of an author, whitespace, and an email address (enclosed by '<' and '>') +to map to the name. Use hash '#' for comments, either on their own line, +or after the email address. + +A canonical name may appear in more than one line, associated with +different email addresses, but it doesn't make sense for a given address +to appear more than once (if that happens, a later line overrides the +earlier ones). + +So, for example, if your history contains commits by two authors, Jane +and Joe, whose names appear in the repository under several forms: + +------------ +Joe Developer <joe@example.com> +Joe R. Developer <joe@example.com> +Jane Doe <jane@example.com> +Jane Doe <jane@laptop.(none)> +Jane D. <jane@desktop.(none)> +------------ + +Then, supposing Joe wants his middle name initial used, and Jane prefers +her family name fully spelled out, a proper `.mailmap` file would look like: ------------ -# Keep alphabetized -Adam Morrow <adam@localhost.localdomain> -Eve Jones <eve@laptop.(none)> +# Note how we don't need an entry for <jane@laptop.(none)>, because the +# real name of that author is correct already, and coalesced directly. +Jane Doe <jane@desktop.(none)> +Joe R. Developer <joe@random.com> ------------ Author diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index d3f258869f..8277577a6f 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -30,7 +30,7 @@ OPTIONS ------- <rev>:: Arbitrary extended SHA1 expression (see linkgit:git-rev-parse[1]) - that typically names a branch HEAD or a tag. + that typically names a branch head or a tag. <glob>:: A glob pattern that matches branch or tag names under @@ -172,7 +172,7 @@ only the primary branches. In addition, if you happen to be on your topic branch, it is shown as well. ------------ -$ git show-branch --reflog='10,1 hour ago' --list master +$ git show-branch --reflog="10,1 hour ago" --list master ------------ shows 10 reflog entries going back from the tip as of 1 hour ago. diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt new file mode 100644 index 0000000000..7f251a5865 --- /dev/null +++ b/Documentation/git-stage.txt @@ -0,0 +1,19 @@ +git-stage(1) +============== + +NAME +---- +git-stage - Add file contents to the staging area + + +SYNOPSIS +-------- +[verse] +'git stage' args... + + +DESCRIPTION +----------- + +This is a synonym for linkgit:git-add[1]. Please refer to the +documentation of that command. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index babaa9bc46..2f207fbbda 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -87,7 +87,7 @@ use by subsequent users cloning the superproject. If the URL is given relative to the superproject's repository, the presumption is the superproject and submodule repositories will be kept together in the same relative location, and only the -superproject's URL need be provided: git-submodule will correctly +superproject's URL needs to be provided: git-submodule will correctly locate the submodule using the relative URL in .gitmodules. status:: diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 1d9d81a702..25e0bbea86 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -55,7 +55,7 @@ OPTIONS default behavior is to error out. This option makes 'git-update-index' continue anyway. ---ignore-submodules: +--ignore-submodules:: Do not try to update submodules. This option is only respected when passed before --refresh. @@ -78,9 +78,9 @@ OPTIONS --assume-unchanged:: --no-assume-unchanged:: - When these flags are specified, the object name recorded + When these flags are specified, the object names recorded for the paths are not updated. Instead, these options - sets and unsets the "assume unchanged" bit for the + set and unset the "assume unchanged" bit for the paths. When the "assume unchanged" bit is on, git stops checking the working tree files for possible modifications, so you need to manually unset the bit to @@ -122,7 +122,7 @@ you will need to handle the situation manually. 'git-update-index' refuses an attempt to add `path/file`. Similarly if a file `path/file` exists, a file `path` cannot be added. With --replace flag, existing entries - that conflicts with the entry being added are + that conflict with the entry being added are automatically removed with warning messages. --stdin:: diff --git a/Documentation/git.txt b/Documentation/git.txt index 7e0a041436..17dc8b2019 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,18 +43,26 @@ 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.0.4/git.html[documentation for release 1.6.0.4] +* 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:v1.6.0.6/git.html[documentation for release 1.6.0.6] + +* release notes for + link:RelNotes-1.6.0.6.txt[1.6.0.6], + link:RelNotes-1.6.0.5.txt[1.6.0.5], link:RelNotes-1.6.0.4.txt[1.6.0.4], link:RelNotes-1.6.0.3.txt[1.6.0.3], link:RelNotes-1.6.0.2.txt[1.6.0.2], link:RelNotes-1.6.0.1.txt[1.6.0.1], link:RelNotes-1.6.0.txt[1.6.0]. -* link:v1.5.6.5/git.html[documentation for release 1.5.6.5] +* link:v1.5.6.6/git.html[documentation for release 1.5.6.6] * release notes for + link:RelNotes-1.5.6.6.txt[1.5.6.6], link:RelNotes-1.5.6.5.txt[1.5.6.5], link:RelNotes-1.5.6.4.txt[1.5.6.4], link:RelNotes-1.5.6.3.txt[1.5.6.3], @@ -62,18 +70,22 @@ Documentation for older releases are available here: link:RelNotes-1.5.6.1.txt[1.5.6.1], link:RelNotes-1.5.6.txt[1.5.6]. -* link:v1.5.5.4/git.html[documentation for release 1.5.5.4] +* link:v1.5.5.6/git.html[documentation for release 1.5.5.6] * release notes for + link:RelNotes-1.5.5.6.txt[1.5.5.6], + link:RelNotes-1.5.5.5.txt[1.5.5.5], link:RelNotes-1.5.5.4.txt[1.5.5.4], link:RelNotes-1.5.5.3.txt[1.5.5.3], link:RelNotes-1.5.5.2.txt[1.5.5.2], link:RelNotes-1.5.5.1.txt[1.5.5.1], link:RelNotes-1.5.5.txt[1.5.5]. -* link:v1.5.4.5/git.html[documentation for release 1.5.4.5] +* link:v1.5.4.7/git.html[documentation for release 1.5.4.7] * release notes for + link:RelNotes-1.5.4.7.txt[1.5.4.7], + link:RelNotes-1.5.4.6.txt[1.5.4.6], link:RelNotes-1.5.4.5.txt[1.5.4.5], link:RelNotes-1.5.4.4.txt[1.5.4.4], link:RelNotes-1.5.4.3.txt[1.5.4.3], diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 96bf353d13..e4dd5518c8 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -899,7 +899,7 @@ file, which had no differences in the `mybranch` branch), and say: ---------------- Auto-merging hello CONFLICT (content): Merge conflict in hello - Automatic merge failed; fix up by hand + Automatic merge failed; fix conflicts and then commit the result. ---------------- It tells you that it did an "Automatic merge", which @@ -993,14 +993,14 @@ would be different) ---------------- Updating from ae3a2da... to a80b4aa.... -Fast forward +Fast forward (no commit created; -m option ignored) example | 1 + hello | 1 + 2 files changed, 2 insertions(+), 0 deletions(-) ---------------- -Because your branch did not contain anything more than what are -already merged into the `master` branch, the merge operation did +Because your branch did not contain anything more than what had +already been merged into the `master` branch, the merge operation did not actually do a merge. Instead, it just updated the top of the tree of your branch to that of the `master` branch. This is often called 'fast forward' merge. @@ -1265,9 +1265,8 @@ file, using 3-way merge. This is done by giving ------------ $ git merge-index git-merge-one-file hello -Auto-merging hello. -merge: warning: conflicts during merge -ERROR: Merge conflict in hello. +Auto-merging hello +ERROR: Merge conflict in hello fatal: merge program failed ------------ @@ -1353,7 +1352,7 @@ $ GIT_DIR=my-git.git git init ------------ Make sure this directory is available for others you want your -changes to be pulled by via the transport of your choice. Also +changes to be pulled via the transport of your choice. Also you need to make sure that you have the 'git-receive-pack' program on the `$PATH`. @@ -1447,7 +1446,7 @@ public repository you might want to repack & prune often, or never. If you run `git repack` again at this point, it will say -"Nothing to pack". Once you continue your development and +"Nothing new to pack.". Once you continue your development and accumulate the changes, running `git repack` again will create a new pack, that contains objects created since you packed your repository the last time. We recommend that you pack your project @@ -1512,7 +1511,7 @@ You can repack this private repository whenever you feel like. 6. Push your changes to the public repository, and announce it to the public. -7. Every once in a while, "git-repack" the public repository. +7. Every once in a while, 'git-repack' the public repository. Go back to step 5. and continue working. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 5faaaa5fed..cfdae1efa2 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -20,6 +20,10 @@ directory to trigger action at certain points. When all disabled. To enable a hook, rename it by removing its `.sample` suffix. +NOTE: It is also a requirement for a given hook to be executable. +However - in a freshly initialized repository - the `.sample` files are +executable by default. + This document describes the currently defined hooks. applypatch-msg diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 317f6317c2..4673a75a98 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -21,7 +21,7 @@ git repository. OPTIONS ------- -To control which revisions to shown, the command takes options applicable to +To control which revisions to show, the command takes options applicable to the 'git-rev-list' command (see linkgit:git-rev-list[1]). This manual page describes only the most frequently used options. @@ -80,7 +80,7 @@ Examples -------- gitk v2.6.12.. include/scsi drivers/scsi:: - Show as the changes since version 'v2.6.12' that changed any + Show the changes since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories gitk --since="2 weeks ago" \-- gitk:: diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index a969b3fbc3..1befca98d4 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -134,7 +134,8 @@ hooks:: Hooks are customization scripts used by various git commands. A handful of sample hooks are installed when 'git-init' is run, but all of them are disabled by - default. To enable, they need to be made executable. + default. To enable, the `.sample` suffix has to be + removed from the filename by renaming. Read linkgit:githooks[5] for more details about each hook. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 9b4a4f45e9..9afca755ed 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -183,7 +183,8 @@ to point at the new commit. and potentially aborted, and allow for a post-notification after the operation is done. The hook scripts are found in the `$GIT_DIR/hooks/` directory, and are enabled by simply - making them executable. + removing the `.sample` suffix from the filename. In earlier versions + of git you had to make them executable. [[def_index]]index:: A collection of files with stat information, whose contents are stored diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt new file mode 100644 index 0000000000..39b1da440a --- /dev/null +++ b/Documentation/howto/revert-a-faulty-merge.txt @@ -0,0 +1,179 @@ +Date: Fri, 19 Dec 2008 00:45:19 -0800 +From: Linus Torvalds <torvalds@linux-foundation.org>, Junio C Hamano <gitster@pobox.com> +Subject: Re: Odd merge behaviour involving reverts +Abstract: Sometimes a branch that was already merged to the mainline + is later found to be faulty. Linus and Junio give guidance on + recovering from such a premature merge and continuing development + after the offending branch is fixed. +Message-ID: <7vocz8a6zk.fsf@gitster.siamese.dyndns.org> +References: <alpine.LFD.2.00.0812181949450.14014@localhost.localdomain> + +Alan <alan@clueserver.org> said: + + I have a master branch. We have a branch off of that that some + developers are doing work on. They claim it is ready. We merge it + into the master branch. It breaks something so we revert the merge. + They make changes to the code. they get it to a point where they say + it is ok and we merge again. + + When examined, we find that code changes made before the revert are + not in the master branch, but code changes after are in the master + branch. + +and asked for help recovering from this situation. + +The history immediately after the "revert of the merge" would look like +this: + + ---o---o---o---M---x---x---W + / + ---A---B + +where A and B are on the side development that was not so good, M is the +merge that brings these premature changes into the mainline, x are changes +unrelated to what the side branch did and already made on the mainline, +and W is the "revert of the merge M" (doesn't W look M upside down?). +IOW, "diff W^..W" is similar to "diff -R M^..M". + +Such a "revert" of a merge can be made with: + + $ git revert -m 1 M + +After the develpers of the side branch fixes their mistakes, the history +may look like this: + + ---o---o---o---M---x---x---W---x + / + ---A---B-------------------C---D + +where C and D are to fix what was broken in A and B, and you may already +have some other changes on the mainline after W. + +If you merge the updated side branch (with D at its tip), none of the +changes made in A nor B will be in the result, because they were reverted +by W. That is what Alan saw. + +Linus explains the situation: + + Reverting a regular commit just effectively undoes what that commit + did, and is fairly straightforward. But reverting a merge commit also + undoes the _data_ that the commit changed, but it does absolutely + nothing to the effects on _history_ that the merge had. + + So the merge will still exist, and it will still be seen as joining + the two branches together, and future merges will see that merge as + the last shared state - and the revert that reverted the merge brought + in will not affect that at all. + + So a "revert" undoes the data changes, but it's very much _not_ an + "undo" in the sense that it doesn't undo the effects of a commit on + the repository history. + + So if you think of "revert" as "undo", then you're going to always + miss this part of reverts. Yes, it undoes the data, but no, it doesn't + undo history. + +In such a situation, you would want to first revert the previous revert, +which would make the history look like this: + + ---o---o---o---M---x---x---W---x---Y + / + ---A---B-------------------C---D + +where Y is the revert of W. Such a "revert of the revert" can be done +with: + + $ git revert W + +This history would (ignoring possible conflicts between what W and W..Y +changed) be equivalent to not having W nor Y at all in the history: + + ---o---o---o---M---x---x-------x---- + / + ---A---B-------------------C---D + +and merging the side branch again will not have conflict arising from an +earlier revert and revert of the revert. + + ---o---o---o---M---x---x-------x-------* + / / + ---A---B-------------------C---D + +Of course the changes made in C and D still can conflict with what was +done by any of the x, but that is just a normal merge conflict. + +On the other hand, if the developers of the side branch discarded their +faulty A and B, and redone the changes on top of the updated mainline +after the revert, the history would have looked like this: + + ---o---o---o---M---x---x---W---x---x + / \ + ---A---B A'--B'--C' + +If you reverted the revert in such a case as in the previous example: + + ---o---o---o---M---x---x---W---x---x---Y---* + / \ / + ---A---B A'--B'--C' + +where Y is the revert of W, A' and B'are rerolled A and B, and there may +also be a further fix-up C' on the side branch. "diff Y^..Y" is similar +to "diff -R W^..W" (which in turn means it is similar to "diff M^..M"), +and "diff A'^..C'" by definition would be similar but different from that, +because it is a rerolled series of the earlier change. There will be a +lot of overlapping changes that result in conflicts. So do not do "revert +of revert" blindly without thinking.. + + ---o---o---o---M---x---x---W---x---x + / \ + ---A---B A'--B'--C' + +In the history with rebased side branch, W (and M) are behind the merge +base of the updated branch and the tip of the mainline, and they should +merge without the past faulty merge and its revert getting in the way. + +To recap, these are two very different scenarios, and they want two very +different resolution strategies: + + - If the faulty side branch was fixed by adding corrections on top, then + doing a revert of the previous revert would be the right thing to do. + + - If the faulty side branch whose effects were discarded by an earlier + revert of a merge was rebuilt from scratch (i.e. rebasing and fixing, + as you seem to have interpreted), then re-merging the result without + doing anything else fancy would be the right thing to do. + +However, there are things to keep in mind when reverting a merge (and +reverting such a revert). + +For example, think about what reverting a merge (and then reverting the +revert) does to bisectability. Ignore the fact that the revert of a revert +is undoing it - just think of it as a "single commit that does a lot". +Because that is what it does. + +When you have a problem you are chasing down, and you hit a "revert this +merge", what you're hitting is essentially a single commit that contains +all the changes (but obviously in reverse) of all the commits that got +merged. So it's debugging hell, because now you don't have lots of small +changes that you can try to pinpoint which _part_ of it changes. + +But does it all work? Sure it does. You can revert a merge, and from a +purely technical angle, git did it very naturally and had no real +troubles. It just considered it a change from "state before merge" to +"state after merge", and that was it. Nothing complicated, nothing odd, +nothing really dangerous. Git will do it without even thinking about it. + +So from a technical angle, there's nothing wrong with reverting a merge, +but from a workflow angle it's something that you generally should try to +avoid. + +If at all possible, for example, if you find a problem that got merged +into the main tree, rather than revert the merge, try _really_ hard to +bisect the problem down into the branch you merged, and just fix it, or +try to revert the individual commit that caused it. + +Yes, it's more complex, and no, it's not always going to work (sometimes +the answer is: "oops, I really shouldn't have merged it, because it wasn't +ready yet, and I really need to undo _all_ of the merge"). So then you +really should revert the merge, but when you want to re-do the merge, you +now need to do it by reverting the revert. diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index 2cdacd94cd..708da6ca31 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -7,11 +7,11 @@ At the core level, git is character encoding agnostic. to be what lstat(2) and creat(2) accepts. There is no such thing as pathname encoding translation. - - The contents of the blob objects are uninterpreted sequence + - The contents of the blob objects are uninterpreted sequences of bytes. There is no encoding translation at the core level. - - The commit log messages are uninterpreted sequence of non-NUL + - The commit log messages are uninterpreted sequences of non-NUL bytes. Although we encourage that the commit log messages are encoded diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 86d5b26ab2..1ff08ff2cc 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -1,10 +1,10 @@ merge.conflictstyle:: Specify the style in which conflicted hunks are written out to working tree files upon merge. The default is "merge", which - shows `<<<<<<<` conflict marker, change made by one side, - `=======` marker, change made by the other side, and then - `>>>>>>>` marker. An alternate style, "diff3", adds `|||||||` - marker and the original text before `=======` marker. + shows a `<<<<<<<` conflict marker, changes made by one side, + a `=======` marker, changes made by the other side, and then + a `>>>>>>>` marker. An alternate style, "diff3", adds a `|||||||` + marker and the original text before the `=======` marker. merge.log:: Whether to include summaries of merged commits in newly created @@ -32,10 +32,10 @@ merge.verbosity:: message if conflicts were detected. Level 1 outputs only conflicts, 2 outputs conflicts and file changes. Level 5 and above outputs debugging information. The default is level 2. - Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. + Can be overridden by the 'GIT_MERGE_VERBOSITY' environment variable. merge.<driver>.name:: - Defines a human readable name for a custom low-level + Defines a human-readable name for a custom low-level merge driver. See linkgit:gitattributes[5] for details. merge.<driver>.driver:: diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 427cdefd01..637b53f898 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -12,7 +12,7 @@ -n:: --no-stat:: - Do not show diffstat at the end of the merge. + Do not show a diffstat at the end of the merge. --summary:: --no-summary:: diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index f18d33e00b..0a8a948e6f 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -30,7 +30,7 @@ This is designed to be as compact as possible. commit <sha1> Author: <author> - Date: <author date> + Date: <author date> <title line> @@ -49,9 +49,9 @@ This is designed to be as compact as possible. * 'fuller' commit <sha1> - Author: <author> + Author: <author> AuthorDate: <author date> - Commit: <committer> + Commit: <committer> CommitDate: <committer date> <title line> diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 6bdf034b3a..48bb97f0b1 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -135,7 +135,7 @@ them, and give the same timestamp to the index file: This will make all index entries racily clean. The linux-2.6 project, for example, there are over 20,000 files in the working -tree. On my Athron 64X2 3800+, after the above: +tree. On my Athlon 64 X2 3800+, after the above: $ /usr/bin/time git diff-files 1.68user 0.54system 0:02.22elapsed 100%CPU (0avgtext+0avgdata 0maxresident)k diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index da9c6b2999..d4b1e90f94 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -13,7 +13,7 @@ to build and test a particular version of a software project, search for regressions, and so on. People needing to do actual development will also want to read -<<Developing-with-git>> and <<sharing-development>>. +<<Developing-With-git>> and <<sharing-development>>. Further chapters cover more specialized topics. @@ -399,7 +399,7 @@ the order it uses to decide which to choose when there are multiple references with the same shorthand name, see the "SPECIFYING REVISIONS" section of linkgit:git-rev-parse[1]. -[[Updating-a-repository-with-git-fetch]] +[[Updating-a-repository-With-git-fetch]] Updating a repository with git-fetch ------------------------------------ @@ -955,7 +955,7 @@ echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new" and then he just cut-and-pastes the output commands after verifying that they look OK. -[[Finding-comments-with-given-content]] +[[Finding-comments-With-given-Content]] Finding commits referencing a file with given content ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -972,7 +972,7 @@ Figuring out why this works is left as an exercise to the (advanced) student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and linkgit:git-hash-object[1] man pages may prove helpful. -[[Developing-with-git]] +[[Developing-With-git]] Developing with git =================== @@ -1675,7 +1675,7 @@ dangling objects can arise in other situations. Sharing development with others =============================== -[[getting-updates-with-git-pull]] +[[getting-updates-With-git-pull]] Getting updates with git-pull ----------------------------- @@ -1683,7 +1683,7 @@ 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 <<Updating-a-repository-with-git-fetch,how to +We have already seen <<Updating-a-repository-With-git-fetch,how to keep remote tracking branches up to date>> with linkgit:git-fetch[1], and how to merge two branches. So you can merge in changes from the original repository's master branch with: @@ -1794,7 +1794,7 @@ Public git repositories Another way to submit changes to a project is to tell the maintainer of that project to pull the changes from your repository using -linkgit:git-pull[1]. In the section "<<getting-updates-with-git-pull, +linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull, Getting updates with git-pull>>" we described this as a way to get updates from the "main" repository, but it works just as well in the other direction. @@ -2004,7 +2004,7 @@ $ git push ssh://yourserver.com/~you/proj.git +master Normally whenever a branch head in a public repository is modified, it is modified to point to a descendant of the commit that it pointed to before. By forcing a push in this situation, you break that convention. -(See <<problems-with-rewriting-history>>.) +(See <<problems-With-rewriting-history>>.) Nevertheless, this is a common practice for people that need a simple way to publish a work-in-progress patch series, and it is an acceptable @@ -2573,7 +2573,7 @@ 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]] +[[problems-With-rewriting-history]] Problems with rewriting history ------------------------------- @@ -4572,4 +4572,3 @@ Alternates, clone -reference, etc. More on recovery from repository corruption. See: http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2 http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 - http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 |