diff options
Diffstat (limited to 'Documentation')
67 files changed, 952 insertions, 266 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.4.txt b/Documentation/RelNotes-1.6.0.4.txt index fba3f30a89..d522661d31 100644 --- a/Documentation/RelNotes-1.6.0.4.txt +++ b/Documentation/RelNotes-1.6.0.4.txt @@ -30,7 +30,7 @@ Fixes since v1.6.0.3 * 'git status' incorrectly reported a submodule directory as an untracked directory. -* 'git svn' used deprecated 'git-foo' form of subcommand invocaition. +* 'git svn' used deprecated 'git-foo' form of subcommand invocation. * 'git update-ref -d' to remove a reference did not honor --no-deref option. diff --git a/Documentation/RelNotes-1.6.0.5.txt b/Documentation/RelNotes-1.6.0.5.txt index 62f95e6bad..a08bb96738 100644 --- a/Documentation/RelNotes-1.6.0.5.txt +++ b/Documentation/RelNotes-1.6.0.5.txt @@ -4,18 +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 pack-objects' did not make its best effort to honor --max-pack-size +* "git diff" always allowed GIT_EXTERNAL_DIFF and --no-ext-diff was no-op for + the command. + +* 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 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 option when a single first object already busted the given limit and placed many objects in a single pack. -* 'make check' cannot be run without sparse; people may have meant to say - 'make test' instead, so suggest that. +* "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 + behaves more like what cg-push from Cogito used to work. + +* when giving up resolving a conflicted merge, "git reset --hard" failed + to remove new paths from the working tree. + +* "git tag" did not complain when given mutually incompatible set of options. + +* 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. + +* "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. + +* "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 7fdf83f604..adb7ccab0a 100644 --- a/Documentation/RelNotes-1.6.1.txt +++ b/Documentation/RelNotes-1.6.1.txt @@ -20,6 +20,8 @@ on. * Various gitweb updates from repo.or.cz installation. +* Updates to emacs bindings. + (portability) * A few test scripts used nonportable "grep" that did not work well on @@ -31,6 +33,11 @@ on. (performance) +* Many operations that are lstat(3) heavy can be told to pre-execute + necessary lstat(3) in parallel before their main operations, which + potentially gives much improved performance for cold-cache cases or in + environments with weak metadata caching (e.g. NFS). + * The underlying diff machinery to produce textual output has been optimized, which would result in faster "git blame" processing. @@ -55,19 +62,25 @@ on. to a non-zero value to accept the suggestion when git can uniquely guess. -* The packfile machinery hopefully is more robust when dealilng with +* The packfile machinery hopefully is more robust when dealing with corrupt packs if redundant objects involved in the corruption are - available elsehwere. + available elsewhere. * "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. @@ -122,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. @@ -157,7 +164,7 @@ on. * "git log" learned "--source" to show what ref each commit was reached from. -* "git log" also learned "--simplify-by-decration" to show the +* "git log" also learned "--simplify-by-decoration" to show the birds-eye-view of the topology of the history. * "git log --pretty=format:" learned "%d" format element that inserts @@ -169,6 +176,9 @@ on. * "git merge -s $strategy" can use a custom built strategy if you have a command "git-merge-$strategy" on your $PATH. +* "git pull" (and "git fetch") can be told to operate "-v"erbosely or + "-q"uietly. + * "git push" can be told to reject deletion of refs with receive.denyDeletes configuration. @@ -181,8 +191,9 @@ 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. * "git submodule foreach" subcommand allows you to iterate over checked out submodules. @@ -219,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. @@ -245,15 +276,11 @@ release, unless otherwise noted. timestamp part, exposing internal implementation detail. Also these did not work with --fixed-strings match at all. -* "git tag" did not complain about incompatible combination of options - e.g. "tag -l -d" (fix scheduled to be further downmerged to maint). - -* 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-697-g168d5bd +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 3d5a8df0cf..7408bb2d34 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -413,6 +413,15 @@ data writes properly, but can be useful for filesystems that do not use journalling (traditional UNIX filesystems) or that only journal metadata and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback"). +core.preloadindex:: + Enable parallel index preload for operations like 'git diff' ++ +This can speed up operations like 'git diff' and 'git status' especially +on filesystems like NFS that have weak caching semantics and thus +relatively high IO latencies. With this set to 'true', git will do the +index comparison to the filesystem data in parallel, allowing +overlapping IO's. + alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation @@ -572,9 +581,6 @@ color.status.<slot>:: to red). The values of these variables may be specified as in color.branch.<slot>. -commit.template:: - Specify a file to use as the template for new commit messages. - color.ui:: When set to `always`, always use colors in all git commands which are capable of colored output. When false (or `never`), never. When @@ -582,6 +588,9 @@ color.ui:: terminal. When more specific variables of color.* are set, they always take precedence over this setting. Defaults to false. +commit.template:: + Specify a file to use as the template for new commit messages. + diff.autorefreshindex:: When using 'git-diff' to compare with work tree files, do not consider stat-only change as changed. @@ -592,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 @@ -630,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 @@ -714,18 +723,6 @@ gc.rerereunresolved:: kept for this many days when 'git-rerere gc' is run. The default is 15 days. See linkgit:git-rerere[1]. -rerere.autoupdate:: - When set to true, `git-rerere` updates the index with the - resulting contents after it cleanly resolves conflicts using - previously recorded resolution. Defaults to false. - -rerere.enabled:: - Activate recording of resolved conflicts, so that identical - conflict hunks can be resolved automatically, should they - be encountered again. linkgit:git-rerere[1] command is by - default enabled if you create `rr-cache` directory under - `$GIT_DIR`, but can be disabled by setting this option to false. - gitcvs.enabled:: Whether the CVS server interface is enabled for this repository. See linkgit:git-cvsserver[1]. @@ -796,6 +793,14 @@ gui.diffcontext:: Specifies how many context lines should be used in calls to diff made by the linkgit:git-gui[1]. The default is "5". +gui.encoding:: + Specifies the default encoding to use for displaying of + file contents in linkgit:git-gui[1] and linkgit:gitk[1]. + It can be overridden by setting the 'encoding' attribute + for relevant files (see linkgit:gitattributes[5]). + If this option is not set, the tools default to the + locale encoding. + gui.matchtrackingbranch:: Determines if new branches created with linkgit:git-gui[1] should default to tracking remote branches with matching names or @@ -818,6 +823,73 @@ gui.spellingdictionary:: the linkgit:git-gui[1]. When set to "none" spell checking is turned off. +gui.fastcopyblame:: + If true, 'git gui blame' uses '-C' instead of '-C -C' for original + location detection. It makes blame significantly faster on huge + repositories at the expense of less thorough copy detection. + +gui.copyblamethreshold:: + Specifies the threshold to use in 'git gui blame' original location + detection, measured in alphanumeric characters. See the + linkgit:git-blame[1] manual for more information on copy detection. + +gui.blamehistoryctx:: + Specifies the radius of history context in days to show in + linkgit:gitk[1] for the selected commit, when the `Show History + 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]. @@ -893,6 +965,10 @@ i18n.logOutputEncoding:: Character encoding the commit messages are converted to when running 'git-log' and friends. +imap:: + The configuration variables in the 'imap' section are described + in linkgit:git-imap-send[1]. + instaweb.browser:: Specify the program that will be used to browse your working repository in gitweb. See linkgit:git-instaweb[1]. @@ -928,8 +1004,6 @@ man.viewer:: Specify the programs that may be used to display help in the 'man' format. See linkgit:git-help[1]. -include::merge-config.txt[] - man.<tool>.cmd:: Specify the command to invoke the specified man viewer. The specified command is evaluated in shell with the man page @@ -939,13 +1013,7 @@ man.<tool>.path:: Override the path for the given tool that may be used to display help in the 'man' format. See linkgit:git-help[1]. -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. +include::merge-config.txt[] mergetool.<tool>.path:: Override the path for the given tool. This is useful in case @@ -1065,6 +1133,41 @@ pull.octopus:: pull.twohead:: The default merge strategy to use when pulling a single branch. +receive.fsckObjects:: + If it is set to true, git-receive-pack will check all received + objects. It will abort in the case of a malformed object or a + broken link. The result of an abort are only dangling objects. + Defaults to false. + +receive.unpackLimit:: + If the number of objects received in a push is below this + limit then the objects will be unpacked into loose object + files. However if the number of received objects equals or + exceeds this limit then the received pack will be stored as + a pack, after adding any missing delta bases. Storing the + pack from a push can make the push operation complete faster, + especially on slow filesystems. If not set, the value of + `transfer.unpackLimit` is used instead. + +receive.denyDeletes:: + If set to true, git-receive-pack will deny a ref update that deletes + the ref. Use this to prevent such a ref deletion via a push. + +receive.denyCurrentBranch:: + If set to true or "refuse", receive-pack will deny a ref update + to the currently checked out branch of a non-bare repository. + Such a push is potentially dangerous because it brings the HEAD + out of sync with the index and working tree. If set to "warn", + print a warning of such a push to stderr, but allow the push to + proceed. If set to false or "ignore", allow such pushes with no + message. Defaults to "warn". + +receive.denyNonFastForwards:: + If set to true, git-receive-pack will deny a ref update which is + not a fast forward. Use this to prevent such an update via a push, + even if that push is forced. This configuration variable is + set when initializing a shared repository. + remote.<name>.url:: The URL of a remote repository. See linkgit:git-fetch[1] or linkgit:git-push[1]. @@ -1114,6 +1217,18 @@ repack.usedeltabaseoffset:: "false" and repack. Access from old git versions over the native protocol are unaffected by this option. +rerere.autoupdate:: + When set to true, `git-rerere` updates the index with the + resulting contents after it cleanly resolves conflicts using + previously recorded resolution. Defaults to false. + +rerere.enabled:: + Activate recording of resolved conflicts, so that identical + conflict hunks can be resolved automatically, should they + be encountered again. linkgit:git-rerere[1] command is by + default enabled if you create `rr-cache` directory under + `$GIT_DIR`, but can be disabled by setting this option to false. + showbranch.default:: The default set of branches for linkgit:git-show-branch[1]. See linkgit:git-show-branch[1]. @@ -1150,6 +1265,11 @@ tar.umask:: archiving user's umask will be used instead. See umask(2) and linkgit:git-archive[1]. +transfer.unpackLimit:: + When `fetch.unpackLimit` or `receive.unpackLimit` are + not set, the value of this variable is used instead. + The default value is 100. + url.<base>.insteadOf:: Any URL that starts with this value will be rewritten to start, instead, with <base>. In cases where some site serves a @@ -1178,50 +1298,6 @@ user.signingkey:: unchanged to gpg's --local-user parameter, so you may specify a key using any method that gpg supports. -imap:: - The configuration variables in the 'imap' section are described - in linkgit:git-imap-send[1]. - -receive.fsckObjects:: - If it is set to true, git-receive-pack will check all received - objects. It will abort in the case of a malformed object or a - broken link. The result of an abort are only dangling objects. - Defaults to false. - -receive.unpackLimit:: - If the number of objects received in a push is below this - limit then the objects will be unpacked into loose object - files. However if the number of received objects equals or - exceeds this limit then the received pack will be stored as - a pack, after adding any missing delta bases. Storing the - pack from a push can make the push operation complete faster, - especially on slow filesystems. If not set, the value of - `transfer.unpackLimit` is used instead. - -receive.denyDeletes:: - If set to true, git-receive-pack will deny a ref update that deletes - the ref. Use this to prevent such a ref deletion via a push. - -receive.denyNonFastForwards:: - If set to true, git-receive-pack will deny a ref update which is - not a fast forward. Use this to prevent such an update via a push, - even if that push is forced. This configuration variable is - set when initializing a shared repository. - -receive.denyCurrentBranch:: - If set to true or "refuse", receive-pack will deny a ref update - to the currently checked out branch of a non-bare repository. - Such a push is potentially dangerous because it brings the HEAD - out of sync with the index and working tree. If set to "warn", - print a warning of such a push to stderr, but allow the push to - proceed. If set to false or "ignore", allow such pushes with no - message. Defaults to "warn". - -transfer.unpackLimit:: - When `fetch.unpackLimit` or `receive.unpackLimit` are - not set, the value of this variable is used instead. - The default value is 100. - web.browser:: Specify a web browser that may be used by some commands. Currently only linkgit:git-instaweb[1] and 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-add.txt b/Documentation/git-add.txt index 6fc20b0baf..7c129cb24f 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -98,7 +98,7 @@ OPTIONS Record only the fact that the path will be added later. An entry for the path is placed in the index with no content. This is useful for, among other things, showing the unstaged content of - such files with 'git diff' and commiting them with 'git commit + such files with 'git diff' and committing them with 'git commit -a'. --refresh:: 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-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 837fb08b79..b764130d26 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -55,13 +55,12 @@ OPTIONS -n:: --no-commit:: - Usually the command automatically creates a commit with - a commit log message stating which commit was - cherry-picked. This flag applies the change necessary - to cherry-pick the named commit to your working tree - and the index, but does not make the commit. In addition, - when this option is used, your index does not have to match - the HEAD commit. The cherry-pick is done against the + Usually the command automatically creates a commit. + This flag applies the change necessary to cherry-pick + the named commit to your working tree and the index, + but does not make the commit. In addition, when this + option is used, your index does not have to match the + HEAD commit. The cherry-pick is done against the beginning state of your index. + This is useful when cherry-picking more than one commits' diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 2e62165fa9..b5d81be7ec 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -29,7 +29,8 @@ The content to be added can be specified in several ways: 3. by listing files as arguments to the 'commit' command, in which case the commit will ignore changes staged in the index, and instead - record the current content of the listed files; + record the current content of the listed files (which must already + be known to git); 4. by using the -a switch with the 'commit' command to automatically "add" changes from all known files (i.e. all files that are already @@ -94,7 +95,7 @@ OPTIONS -s:: --signoff:: - Add Signed-off-by line by the commiter at the end of the commit + Add Signed-off-by line by the committer at the end of the commit log message. -n:: @@ -165,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-gui.txt b/Documentation/git-gui.txt index 0e650f497b..d0bc98b852 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -65,9 +65,28 @@ git gui blame v0.99.8 Makefile:: example the file is read from the object database and not the working directory. +git gui blame --line=100 Makefile:: + + Loads annotations as described above and automatically + scrolls the view to center on line '100'. + git gui citool:: Make one commit and return to the shell when it is complete. + This command returns a non-zero exit code if the window was + closed in any way other than by making a commit. + +git gui citool --amend:: + + Automatically enter the 'Amend Last Commit' mode of + the interface. + +git gui citool --nocommit:: + + Behave as normal citool, but instead of making a commit + simply terminate with a zero exit code. It still checks + that the index does not contain any unmerged entries, so + you can use it as a GUI version of linkgit:git-mergetool[1] git citool:: 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 176483a1ae..4c0ffec507 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-repack.txt b/Documentation/git-repack.txt index bbe1485a97..aaa8852629 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -38,12 +38,11 @@ OPTIONS dangling. -A:: - Same as `-a`, but any unreachable objects in a previous - pack become loose, unpacked objects, instead of being - left in the old pack. Unreachable objects are never - intentionally added to a pack, even when repacking. - When used with '-d', this option - prevents unreachable objects from being immediately + Same as `-a`, unless '-d' is used. Then any unreachable + objects in a previous pack become loose, unpacked objects, + instead of being left in the old pack. Unreachable objects + are never intentionally added to a pack, even when repacking. + This option prevents unreachable objects from being immediately deleted by way of being left in the old pack and then removed. Instead, the loose unreachable objects will be pruned according to normal expiry rules diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 52aab5e680..abb25d1c00 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,7 +8,7 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git reset' [--mixed | --soft | --hard] [-q] [<commit>] +'git reset' [--mixed | --soft | --hard | --merge] [-q] [<commit>] 'git reset' [-q] [<commit>] [--] <paths>... DESCRIPTION @@ -45,6 +45,11 @@ OPTIONS switched to. Any changes to tracked files in the working tree since <commit> are lost. +--merge:: + Resets the index to match the tree recorded by the named commit, + and updates the files that are different between the named commit + and the current commit in the working tree. + -q:: Be quiet, only report errors. @@ -130,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... @@ -152,6 +157,28 @@ tip of the current branch in ORIG_HEAD, so resetting hard to it brings your index file and the working tree back to that state, and resets the tip of the branch to that commit. +Undo a merge or pull inside a dirty work tree:: ++ +------------ +$ git pull <1> +Auto-merging nitfol +Merge made by recursive. + nitfol | 20 +++++---- + ... +$ git reset --merge ORIG_HEAD <2> +------------ ++ +<1> Even if you may have local modifications in your +working tree, you can safely say "git pull" when you know +that the change in the other branch does not overlap with +them. +<2> After inspecting the result of the merge, you may find +that the change in the other branch is unsatisfactory. Running +"git reset --hard ORIG_HEAD" will let you go back to where you +were, but it will discard your local changes, which you do not +want. "git reset --merge" keeps your local changes. + + Interrupted workflow:: + Suppose you are interrupted by an urgent fix request while you @@ -177,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 82f505686e..b69846e522 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -8,7 +8,7 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- -'git send-email' [options] <file|directory> [... file|directory] +'git send-email' [options] <file|directory|rev-list options>... DESCRIPTION @@ -37,9 +37,23 @@ The --bcc option must be repeated for each user you want on the bcc list. + The --cc option must be repeated for each user you want on the cc list. +--annotate:: + Review each patch you're about to send in an editor. The setting + 'sendemail.multiedit' defines if this will spawn one editor per patch + or one for all of them at once. + --compose:: Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an introductory message for the patch series. ++ +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 +Headers values if you don't removed them. ++ +If it wasn't able to see a header in the summary it will ask you about it +interactively after quitting your editor. --from:: Specify the sender of the emails. This will default to @@ -192,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 ------------- @@ -204,6 +224,12 @@ sendemail.aliasfiletype:: Format of the file(s) specified in sendemail.aliasesfile. Must be one of 'mutt', 'mailrc', 'pine', or 'gnus'. +sendemail.multiedit:: + If true (default), a single editor instance will be spawned to edit + files you have to edit (patches when '--annotate' is used, and the + summary when '--compose' is used). If false, files will be edited one + after the other, spawning a new editor each time. + Author ------ 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-svn.txt b/Documentation/git-svn.txt index 84c8f3cde0..8d0c421b80 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -109,7 +109,7 @@ COMMANDS This works similarly to `svn update` or 'git-pull' except that it preserves linear history with 'git-rebase' instead of -'git-merge' for ease of dcommiting with 'git-svn'. +'git-merge' for ease of dcommitting with 'git-svn'. This accepts all options that 'git-svn fetch' and 'git-rebase' accept. However, '--fetch-all' only fetches from the current @@ -544,6 +544,8 @@ have each person clone that repository with 'git-clone': git remote add origin server:/pub/project git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' git fetch +# Create a local branch from one of the branches just fetched + git checkout -b master FETCH_HEAD # Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) git svn init http://svn.example.com/project # Pull the latest changes from Subversion diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 046ab3542b..e44f543025 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -70,7 +70,7 @@ OPTIONS -m <msg>:: Use the given tag message (instead of prompting). - If multiple `-m` options are given, there values are + If multiple `-m` options are given, their values are concatenated as separate paragraphs. Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. @@ -207,7 +207,7 @@ determines who are interested in whose tags. A one-shot pull is a sign that a commit history is now crossing the boundary between one circle of people (e.g. "people who are -primarily interested in networking part of the kernel") who may +primarily interested in the networking part of the kernel") who may have their own set of tags (e.g. "this is the third release candidate from the networking group to be proposed for general consumption with 2.6.21 release") to another circle of people 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/gitattributes.txt b/Documentation/gitattributes.txt index a172baf993..8af22eccac 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -535,6 +535,23 @@ in the file. E.g. the string `$Format:%H$` will be replaced by the commit hash. +Viewing files in GUI tools +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`encoding` +^^^^^^^^^^ + +The value of this attribute specifies the character encoding that should +be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to +display the contents of the relevant file. Note that due to performance +considerations linkgit:gitk[1] does not use this attribute unless you +manually enable per-file encodings in its options. + +If this attribute is not set or has an invalid value, the value of the +`gui.encoding` configuration variable is used instead +(See linkgit:git-config[1]). + + USING ATTRIBUTE MACROS ---------------------- diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index a417e592ac..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. @@ -1690,8 +1689,11 @@ to follow, not easier. SEE ALSO -------- -linkgit:gittutorial[7], linkgit:gittutorial-2[7], -linkgit:everyday[7], linkgit:gitcvs-migration[7], +linkgit:gittutorial[7], +linkgit:gittutorial-2[7], +linkgit:gitcvs-migration[7], +linkgit:git-help[1], +link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] GIT diff --git a/Documentation/gitglossary.txt b/Documentation/gitglossary.txt index 565719ed5f..d77a45aed6 100644 --- a/Documentation/gitglossary.txt +++ b/Documentation/gitglossary.txt @@ -16,8 +16,10 @@ include::glossary-content.txt[] SEE ALSO -------- -linkgit:gittutorial[7], linkgit:gittutorial-2[7], -linkgit:everyday[7], linkgit:gitcvs-migration[7], +linkgit:gittutorial[7], +linkgit:gittutorial-2[7], +linkgit:gitcvs-migration[7], +link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] GIT 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 ae29a00d59..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. @@ -56,6 +56,11 @@ frequently used options. Use this instead of explicitly specifying <revs> if the set of commits to show may vary between refreshes. +--select-commit=<ref>:: + + Automatically select the specified commit after loading the graph. + Default behavior is equivalent to specifying '--select-commit=HEAD'. + <revs>:: Limit the revisions to show. This can be either a single revision @@ -75,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/gittutorial-2.txt b/Documentation/gittutorial-2.txt index bab0f34b45..a057b50b2b 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -425,6 +425,7 @@ linkgit:gittutorial[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], +linkgit:git-help[1], link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 384972cb9b..7892244ef1 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -26,6 +26,15 @@ First, note that you can get documentation for a command such as $ man git-log ------------------------------------------------ +or: + +------------------------------------------------ +$ git help log +------------------------------------------------ + +With the latter, you can use the manual viewer of your choice; see +linkgit:git-help[1] for more information. + It is a good idea to introduce yourself to git with your name and public email address before doing any operation. The easiest way to do so is: @@ -653,6 +662,7 @@ linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], +linkgit:git-help[1], link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] 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 c735788b0f..1ff08ff2cc 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -1,6 +1,10 @@ -merge.stat:: - Whether to print the diffstat between ORIG_HEAD and the merge result - at the end of the merge. True by default. +merge.conflictstyle:: + Specify the style in which conflicted hunks are written out to + working tree files upon merge. The default is "merge", which + 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 @@ -11,6 +15,10 @@ merge.renameLimit:: during a merge; if not specified, defaults to the value of diff.renameLimit. +merge.stat:: + Whether to print the diffstat between ORIG_HEAD and the merge result + at the end of the merge. True by default. + merge.tool:: Controls which merge resolution program is used by linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", @@ -24,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 007909a82f..637b53f898 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -1,10 +1,18 @@ +-q:: +--quiet:: + Operate quietly. + +-v:: +--verbose:: + Be verbose. + --stat:: Show a diffstat at the end of the merge. The diffstat is also controlled by the configuration option merge.stat. -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/rev-list-options.txt b/Documentation/rev-list-options.txt index 6d7cf6d51f..b9f6e4d1b7 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -222,6 +222,21 @@ endif::git-rev-list[] Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the command line as '<commit>'. +--branches:: + + Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed + on the command line as '<commit>'. + +--tags:: + + Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed + on the command line as '<commit>'. + +--remotes:: + + Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed + on the command line as '<commit>'. + ifdef::git-rev-list[] --stdin:: diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index a9668e5f2d..a8ee2fe6a1 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -205,6 +205,13 @@ In order to facilitate caching and to make it possible to give parameters to the callback, `strbuf_expand()` passes a context pointer, which can be used by the programmer of the callback as she sees fit. +`strbuf_expand_dict_cb`:: + + Used as callback for `strbuf_expand()`, expects an array of + struct strbuf_expand_dict_entry as context, i.e. pairs of + placeholder and replacement string. The array needs to be + terminated by an entry with placeholder set to NULL. + `strbuf_addf`:: Add a formatted string to the buffer. 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 645d752c5c..d4b1e90f94 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -13,17 +13,27 @@ 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. Comprehensive reference documentation is available through the man -pages. For a command such as "git clone <repo>", just use +pages, or linkgit:git-help[1] command. For example, for the command +"git clone <repo>", you can either use: ------------------------------------------------ $ man git-clone ------------------------------------------------ +or: + +------------------------------------------------ +$ git help clone +------------------------------------------------ + +With the latter, you can use the manual viewer of your choice; see +linkgit:git-help[1] for more information. + See also <<git-quick-start>> for a brief overview of git commands, without any explanation. @@ -389,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 ------------------------------------ @@ -536,7 +546,7 @@ $ git bisect skip ------------------------------------------------- In this case, though, git may not eventually be able to tell the first -bad one between some first skipped commits and a latter bad commit. +bad one between some first skipped commits and a later bad commit. There are also ways to automate the bisecting process if you have a test script that can tell a good from a bad commit. See @@ -945,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -962,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 =================== @@ -1665,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 ----------------------------- @@ -1673,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: @@ -1784,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. @@ -1994,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 @@ -2563,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 ------------------------------- @@ -4562,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 |