diff options
Diffstat (limited to 'Documentation')
36 files changed, 571 insertions, 101 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index f628c1f3b7..0d7fa9cca9 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -21,8 +21,13 @@ code. For git in general, three rough rules are: As for more concrete guidelines, just imitate the existing code (this is a good guideline, no matter which project you are -contributing to). But if you must have a list of rules, -here they are. +contributing to). It is always preferable to match the _local_ +convention. New code added to git suite is expected to match +the overall style of existing code. Modifications to existing +code is expected to match the style the surrounding code already +uses (even if it doesn't match the overall style of existing code). + +But if you must have a list of rules, here they are. For shell scripts specifically (not exhaustive): diff --git a/Documentation/Makefile b/Documentation/Makefile index c34c1cae20..144ec32f12 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -32,6 +32,7 @@ DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) prefix?=$(HOME) bindir?=$(prefix)/bin htmldir?=$(prefix)/share/doc/git-doc +pdfdir?=$(prefix)/share/doc/git-doc mandir?=$(prefix)/share/man man1dir=$(mandir)/man1 man5dir=$(mandir)/man5 @@ -50,6 +51,7 @@ infodir?=$(prefix)/share/info MAKEINFO=makeinfo INSTALL_INFO=install-info DOCBOOK2X_TEXI=docbook2x-texi +DBLATEX=dblatex ifndef PERL_PATH PERL_PATH = /usr/bin/perl endif @@ -87,6 +89,8 @@ man7: $(DOC_MAN7) info: git.info gitman.info +pdf: user-manual.pdf + install: install-man install-man: man @@ -107,6 +111,10 @@ install-info: info echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \ fi +install-pdf: pdf + $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir) + $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir) + install-html: html sh ./install-webdoc.sh $(DESTDIR)$(htmldir) @@ -187,17 +195,23 @@ 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 $@+ $@ + +user-manual.pdf: user-manual.xml + $(RM) $@+ $@ + $(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $< 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.6.2.txt b/Documentation/RelNotes-1.6.2.txt new file mode 100644 index 0000000000..f1bfa82749 --- /dev/null +++ b/Documentation/RelNotes-1.6.2.txt @@ -0,0 +1,146 @@ +GIT v1.6.2 Release Notes +======================== + +With the next major release, "git push" into a branch that is +currently checked out will be refused by default. You can choose +what should happen upon such a push by setting the configuration +variable receive.denyCurrentBranch in the receiving repository. + +To ease the transition plan, the receiving repository of such a +push running this release will issue a big warning when the +configuration variable is missing. Please refer to: + + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + +for more details on the transition plan. + + +Updates since v1.6.1 +-------------------- + +(subsystems) + +* git-svn updates. + +* gitweb updates, including a new patch view and RSS/Atom feed + improvements. + +* (contrib) git.el updates for better XEmacs compatibility; vc-git.el + is not shiped with git anymore (it is part of official Emacs) + +(performance) + +* pack-objects autodetects the number of CPUs available and uses threaded + version. + +(usability, bells and whistles) + +* automatic typo correction works on aliases as well + +* Initial support for "git notes" implemented. + +* @{-1} is a way to refer to the last branch you were on. This is + accepted not only where an object name is expected, but anywhere + a branch name is expected. E.g. "git branch --track mybranch @{-1}" + "git rev-parse --symbolic-full-name @{-1}". + +* "git add -p" learned 'g'oto action to jump directly to a hunk. + +* "git add -p" learned to find a hunk with given text with '/'. + +* "git add -p" optionally can be told to work with just the command letter + without Enter. + +* when "git am" stops upon a patch that does not apply, it shows the + title of the offending patch. + +* "git am --directory=<dir>" and "git am --reject" passes these options + to underlying "git apply". + +* "git am" learned --ignore-date option. + +* "git blame" aligns author names better when they are spelled in + non US-ASCII encoding. + +* "git clone" now makes its best effort when cloning from an empty + repository to set up configuration variables to refer to the remote + repository. + +* "git checkout -" is a shorthand for "git checkout @{-1}". + +* "git cherry" defaults to whatever the current branch is tracking (if + exists) when the <upstream> argument is not given. + +* "git cvsserver" can be told not to add extra "via git-CVS emulator" to + the commit log message it serves via gitcvs.commitmsgannotation + configuration. + +* "git cvsserver" learned to handle 'noop' command some CVS clients seem + to expect to work. + +* "git diff" learned a new option --inter-hunk-context to coalesce close + hunks together and show context between them. + +* The definition of what constitutes a word for "git diff --color-words" + can be customized via gitattributes, command line or a configuration. + +* "git diff" learned --patience to run "patience diff" algorithm. + +* "git filter-branch" learned --prune-empty option that discards commits + that do not change the contents. + +* "git fsck" now checks loose objects in alternate object stores, instead + of misreporting them as missing. + +* "git grep -w" and "git grep" for fixed strings have been optimized. + +* "git mergetool" learned -y(--no-prompt) option to disable prompting. + +* "git rebase -i" can transplant a history down to root to elsewhere + with --root option. + +* "git reset --merge" is a new mode that works similar to the way + "git checkout" switches branches, taking the local changes while + switching to another commit. + +* "git tag" learned --contains that works the same way as the same option + from "git branch". + + +Fixes since v1.6.1 +------------------ + +All of the fixes in v1.6.1.X maintenance series are included in this +release, unless otherwise noted. + +Here are fixes that this release has, but have not been backported to +v1.6.1.X series. + +* "git-add sub/file" when sub is a submodule incorrectly added the path to + the superproject. + +* "git bundle" did not exclude annotated tags even when a range given + from the command line wanted to. + +* "git filter-branch" unnecessarily refused to work when you had + checked out a different commit from what is recorded in the superproject + index in a submodule. + +* "git filter-branch" incorrectly tried to update a nonexistent work tree + at the end when it is run in a bare repository. + +* "git mergetool" used to ignore autocrlf and other attributes + based content rewriting. + +* branch switching and merges had a silly bug that did not validate + the correct directory when making sure an existing subdirectory is + clean. + +* "git -p cmd" when cmd is not a built-in one left the display in funny state + when killed in the middle. + +-- +exec >/var/tmp/1 +O=v1.6.1.3-371-gc19923a +echo O=$(git describe master) +git shortlog --no-merges $O..master ^maint 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 2ed868c81a..1dd18c928d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -422,6 +422,19 @@ 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. +core.notesRef:: + When showing commit messages, also show notes which are stored in + the given ref. This ref is expected to contain files named + after the full SHA-1 of the commit they annotate. ++ +If such a file exists in the given ref, the referenced blob is read, and +appended to the commit message, separated by a "Notes:" line. If the +given ref itself does not exist, it is not an error, but means that no +notes should be printed. ++ +This setting defaults to "refs/notes/commits", and can be overridden by +the `GIT_NOTES_REF` environment variable. + alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation @@ -556,8 +569,8 @@ color.interactive:: color.interactive.<slot>:: Use customized color for 'git-add --interactive' - output. `<slot>` may be `prompt`, `header`, or `help`, for - three distinct types of normal output from interactive + output. `<slot>` may be `prompt`, `header`, `help` or `error`, for + four distinct types of normal output from interactive programs. The values of these variables may be specified as in color.branch.<slot>. @@ -639,6 +652,12 @@ diff.suppressBlankEmpty:: A boolean to inhibit the standard behavior of printing a space before each empty output line. Defaults to false. +diff.wordRegex:: + A POSIX Extended Regular Expression used to determine what is a "word" + when performing word-by-word difference calculations. Character + sequences that match the regular expression are "words", all other + characters are *ignorable* whitespace. + fetch.unpackLimit:: If the number of objects fetched over the git native transfer is below this @@ -725,6 +744,10 @@ gc.rerereunresolved:: kept for this many days when 'git-rerere gc' is run. The default is 15 days. See linkgit:git-rerere[1]. +gitcvs.commitmsgannotation:: + Append this string to each commit message. Set to empty string + to disable this feature. Defaults to "via git-CVS emulator". + gitcvs.enabled:: Whether the CVS server interface is enabled for this repository. See linkgit:git-cvsserver[1]. @@ -990,6 +1013,13 @@ instaweb.port:: The port number to bind the gitweb httpd to. See linkgit:git-instaweb[1]. +interactive.singlekey:: + In interactive programs, allow the user to provide one-letter + input with a single key (i.e., without hitting enter). + Currently this is used only by the `\--patch` mode of + linkgit:git-add[1]. Note that this setting is silently + ignored if portable keystroke input is not available. + log.date:: Set default date-time mode for the log command. Setting log.date value is similar to using 'git-log'\'s --date option. The value is one of the @@ -1046,6 +1076,16 @@ mergetool.keepBackup:: is set to `false` then this file is not preserved. Defaults to `true` (i.e. keep the backup files). +mergetool.keepTemporaries:: + When invoking a custom merge tool, git uses a set of temporary + files to pass to the tool. If the tool returns an error and this + variable is set to `true`, then these temporary files will be + preserved, otherwise they will be removed after the tool has + exited. Defaults to `false`. + +mergetool.prompt:: + Prompt before each invocation of the merge resolution program. + pack.window:: The size of the window used by linkgit:git-pack-objects[1] when no window size is given on the command line. Defaults to 10. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index b432d2518a..813a7b11b9 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -36,6 +36,9 @@ endif::git-format-patch[] --patch-with-raw:: Synonym for "-p --raw". +--patience:: + Generate a diff using the "patience diff" algorithm. + --stat[=width[,name-width]]:: Generate a diffstat. You can override the default output width for 80-column terminal by "--stat=width". @@ -91,8 +94,22 @@ endif::git-format-patch[] Turn off colored diff, even when the configuration file gives the default to color output. ---color-words:: - Show colored word diff, i.e. color words which have changed. +--color-words[=<regex>]:: + Show colored word diff, i.e., color words which have changed. + By default, words are separated by whitespace. ++ +When a <regex> is specified, every non-overlapping match of the +<regex> is considered a word. Anything between these matches is +considered whitespace and ignored(!) for the purposes of finding +differences. You may want to append `|[^[:space:]]` to your regular +expression to make sure that it matches all non-whitespace characters. +A match that contains a newline is silently truncated(!) at the +newline. ++ +The regex can also be set via a diff driver or configuration option, see +linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly +overrides any diff driver or configuration setting. Diff drivers +override configuration settings. --no-renames:: Turn off rename detection, even when the configuration @@ -116,7 +133,7 @@ endif::git-format-patch[] --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header - lines, show only handful hexdigits prefix. This is + lines, show only a partial prefix. This is independent of --full-index option above, which controls the diff-patch output format. Non default number of digits can be specified with --abbrev=<n>. @@ -205,6 +222,10 @@ endif::git-format-patch[] differences even if one line has whitespace where the other line has none. +--inter-hunk-context=<lines>:: + Show the context between diff hunks, up to the specified number + of lines, thereby fusing hunks that are close to each other. + --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-am.txt b/Documentation/git-am.txt index b9c6fac748..ff307eb270 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -10,8 +10,10 @@ SYNOPSIS -------- [verse] 'git am' [--signoff] [--keep] [--utf8 | --no-utf8] - [--3way] [--interactive] - [--whitespace=<option>] [-C<n>] [-p<n>] + [--3way] [--interactive] [--committer-date-is-author-date] + [--ignore-date] + [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] + [--reject] [<mbox> | <Maildir>...] 'git am' (--skip | --resolved | --abort) @@ -60,12 +62,10 @@ default. You could use `--no-utf8` to override this. available locally. --whitespace=<option>:: - This flag is passed to the 'git-apply' (see linkgit:git-apply[1]) - program that applies - the patch. - -C<n>:: -p<n>:: +--directory=<dir>:: +--reject:: These flags are passed to the 'git-apply' (see linkgit:git-apply[1]) program that applies the patch. @@ -74,6 +74,20 @@ default. You could use `--no-utf8` to override this. --interactive:: Run interactively. +--committer-date-is-author-date:: + By default the command records the date from the e-mail + message as the commit author date, and uses the time of + commit creation as the committer date. This allows the + user to lie about the committer date by using the same + timestamp as the author date. + +--ignore-date:: + By default the command records the date from the e-mail + message as the commit author date, and uses the time of + commit creation as the committer date. This allows the + user to lie about author timestamp by using the same + timestamp as the committer date. + --skip:: Skip the current patch. This is only meaningful when restarting an aborted patch. diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index e726510ab1..9400f6a5d0 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git apply' [--stat] [--numstat] [--summary] [--check] [--index] - [--apply] [--no-add] [--build-fake-ancestor <file>] [-R | --reverse] + [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached] [--whitespace=<nowarn|warn|fix|error|error-all>] @@ -64,7 +64,7 @@ OPTIONS cached data, apply the patch, and store the result in the index, without using the working tree. This implies '--index'. ---build-fake-ancestor <file>:: +--build-fake-ancestor=<file>:: Newer 'git-diff' output has embedded 'index information' for each blob to help identify the original version that the patch applies to. When this flag is given, and if diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 1b66ab743c..57590b1480 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -84,7 +84,7 @@ defining the basis. More than one reference may be packaged, and more than one basis can be specified. The objects packaged are those not contained in the union of the given bases. Each basis can be specified explicitly (e.g., ^master~10), or implicitly (e.g., -master~10..master, master --since=10.days.ago). +master~10..master, --since=10.days.ago master). It is very important that the basis used be held by the destination. It is okay to err on the side of conservatism, causing the bundle file @@ -94,75 +94,111 @@ when unpacking at the destination. EXAMPLE ------- -Assume two repositories exist as R1 on machine A, and R2 on machine B. +Assume you want to transfer the history from a repository R1 on machine A +to another repository R2 on machine B. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc). We want to update R2 with developments made on branch master in R1. -To create the bundle you have to specify the basis. You have some options: +To bootstrap the process, you can first create a bundle that doesn't have +any basis. You can use a tag to remember up to what commit you sent out +in order to make it easy to later update the other repository with +incremental bundle, -- Without basis. -+ -This is useful when sending the whole history. +---------------- +machineA$ cd R1 +machineA$ git bundle create file.bundle master +machineA$ git tag -f lastR2bundle master +---------------- ------------- -$ git bundle create mybundle master ------------- +Then you sneakernet file.bundle to the target machine B. Because you don't +have to have any object to extract objects from such a bundle, not only +you can fetch/pull from a bundle, you can clone from it as if it was a +remote repository. -- Using temporally tags. -+ -We set a tag in R1 (lastR2bundle) after the previous such transport, -and move it afterwards to help build the bundle. +---------------- +machineB$ git clone /home/me/tmp/file.bundle R2 +---------------- ------------- -$ git bundle create mybundle master ^lastR2bundle -$ git tag -f lastR2bundle master ------------- +This will define a remote called "origin" in the resulting repository that +lets you fetch and pull from the bundle. $GIT_DIR/config file in R2 may +have an entry like this: -- Using a tag present in both repositories +------------------------ +[remote "origin"] + url = /home/me/tmp/file.bundle + fetch = refs/heads/*:refs/remotes/origin/* +------------------------ + +You can fetch/pull to update the resulting mine.git repository after +replacing the bundle you store at /home/me/tmp/file.bundle with incremental +updates from here on. + +After working more in the original repository, you can create an +incremental bundle to update the other: + +---------------- +machineA$ cd R1 +machineA$ git bundle create file.bundle lastR2bundle..master +machineA$ git tag -f lastR2bundle master +---------------- + +and sneakernet it to the other machine to replace /home/me/tmp/file.bundle, +and pull from it. + +---------------- +machineB$ cd R2 +machineB$ git pull +---------------- ------------- -$ git bundle create mybundle master ^v1.0.0 ------------- +If you know up to what commit the intended recipient repository should +have the necessary objects for, you can use that knowledge to specify the +basis, giving a cut-off point to limit the revisions and objects that go +in the resulting bundle. The previous example used lastR2bundle tag +for this purpose, but you can use other options you would give to +the linkgit:git-log[1] command. Here are more examples: -- A basis based on time. +You can use a tag that is present in both. ------------- -$ git bundle create mybundle master --since=10.days.ago ------------- +---------------- +$ git bundle create mybundle v1.0.0..master +---------------- -- With a limit on the number of commits +You can use a basis based on time. ------------- -$ git bundle create mybundle master -n 10 ------------- +---------------- +$ git bundle create mybundle --since=10.days master +---------------- -Then you move mybundle from A to B, and in R2 on B: +Or you can use the number of commits. ------------- +---------------- +$ git bundle create mybundle -10 master +---------------- + +You can run `git-bundle verify` to see if you can extract from a bundle +that was created with a basis. + +---------------- $ git bundle verify mybundle -$ git fetch mybundle master:localRef ------------- +---------------- -With something like this in the config in R2: +This will list what commits you must have in order to extract from the +bundle and will error out if you don't have them. ------------------------- -[remote "bundle"] - url = /home/me/tmp/file.bdl - fetch = refs/heads/*:refs/remotes/origin/* ------------------------- +A bundle from a recipient repository's point of view is just like a +regular repository it fetches/pulls from. You can for example map +refs, like this example, when fetching: -You can first sneakernet the bundle file to ~/tmp/file.bdl and -then these commands on machine B: +---------------- +$ git fetch mybundle master:localRef +---------------- ------------- -$ git ls-remote bundle -$ git fetch bundle -$ git pull bundle ------------- +Or see what refs it offers. -would treat it as if it is talking with a remote side over the -network. +---------------- +$ git ls-remote mybundle +---------------- Author ------ diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 9cd51514db..3bccffae62 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -133,6 +133,10 @@ the conflicted merge in the specified paths. + When this parameter names a non-branch (but still a valid commit object), your HEAD becomes 'detached'. ++ +As a special case, the "`@\{-N\}`" syntax for the N-th last branch +checks out the branch (instead of detaching). You may also specify +"`-`" which is synonymous with "`@\{-1\}`". Detached HEAD diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 74d14c4e7f..7deefdae8f 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -7,7 +7,7 @@ git-cherry - Find commits not merged upstream SYNOPSIS -------- -'git cherry' [-v] <upstream> [<head>] [<limit>] +'git cherry' [-v] [<upstream> [<head> [<limit>]]] DESCRIPTION ----------- @@ -51,6 +51,7 @@ OPTIONS <upstream>:: Upstream branch to compare against. + Defaults to the first tracked remote branch, if available. <head>:: Working branch; defaults to HEAD. diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index a30c5ac966..b231dbb947 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -87,7 +87,7 @@ With something like git.git current tree, I get: v1.0.4-14-g2414721 i.e. the current head of my "parent" branch is based on v1.0.4, -but since it has a handful commits on top of that, +but since it has a few commits on top of that, describe has added the number of additional commits ("14") and an abbreviated object name for the commit itself ("2414721") at the end. diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index fed6de6a7f..451950bab6 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -122,6 +122,10 @@ You can use the 'map' convenience function in this filter, and other convenience functions, too. For example, calling 'skip_commit "$@"' will leave out the current commit (but not its changes! If you want that, use 'git-rebase' instead). ++ +You can also use the 'git_commit_non_empty_tree "$@"' instead of +'git commit-tree "$@"' if you don't wish to keep commits with a single parent +and that makes no change to the tree. --tag-name-filter <command>:: This is the filter for rewriting tag names. When passed, @@ -151,6 +155,16 @@ to other tags will be rewritten to point to the underlying commit. The result will contain that directory (and only that) as its project root. +--prune-empty:: + Some kind of filters will generate empty commits, that left the tree + untouched. This switch allow git-filter-branch to ignore such + commits. Though, this switch only applies for commits that have one + and only one parent, it will hence keep merges points. Also, this + option is not compatible with the use of '--commit-filter'. Though you + just need to use the function 'git_commit_non_empty_tree "$@"' instead + of the 'git commit-tree "$@"' idiom in your commit filter to make that + happen. + --original <namespace>:: Use this option to set the namespace where the original commits will be stored. The default value is 'refs/original'. diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 9f85d60b5f..057a021eb5 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -126,7 +126,7 @@ OPTIONS --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only handful hexdigits prefix. + lines, show only a partial prefix. Non default number of digits can be specified with --abbrev=<n>. \--:: diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index db6ebccd6d..f68e5c5c1a 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -61,7 +61,7 @@ OPTIONS --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only handful hexdigits prefix. + lines, show only a partial prefix. Non default number of digits can be specified with --abbrev=<n>. --full-name:: diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 602e7c6d3b..5d3c632872 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts SYNOPSIS -------- -'git mergetool' [--tool=<tool>] [<file>]... +'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]... DESCRIPTION ----------- @@ -22,7 +22,8 @@ with merge conflicts. OPTIONS ------- --t or --tool=<tool>:: +-t <tool>:: +--tool=<tool>:: Use the merge resolution program specified by <tool>. Valid merge tools are: kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, and opendiff @@ -60,6 +61,16 @@ 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. +-y:: +--no-prompt:: + Don't prompt before each invocation of the merge resolution + program. + +--prompt:: + Prompt before each invocation of the merge resolution program. + This is the default behaviour; the option is provided to + override any configuration settings. + Author ------ Written by Theodore Y Ts'o <tytso@mit.edu> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt new file mode 100644 index 0000000000..3d93625f9a --- /dev/null +++ b/Documentation/git-notes.txt @@ -0,0 +1,46 @@ +git-notes(1) +============ + +NAME +---- +git-notes - Add/inspect commit notes + +SYNOPSIS +-------- +[verse] +'git-notes' (edit | show) [commit] + +DESCRIPTION +----------- +This command allows you to add notes to commit messages, without +changing the commit. To discern these notes from the message stored +in the commit object, the notes are indented like the message, after +an unindented line saying "Notes:". + +To disable commit notes, you have to set the config variable +core.notesRef to the empty string. Alternatively, you can set it +to a different ref, something like "refs/notes/bugzilla". This setting +can be overridden by the environment variable "GIT_NOTES_REF". + + +SUBCOMMANDS +----------- + +edit:: + Edit the notes for a given commit (defaults to HEAD). + +show:: + Show the notes for a given commit (defaults to HEAD). + + +Author +------ +Written by Johannes Schindelin <johannes.schindelin@gmx.de> + +Documentation +------------- +Documentation by Johannes Schindelin + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index c8ad86a56f..3d6d429e5e 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,10 +8,11 @@ git-rebase - Forward-port local commits to the updated upstream head SYNOPSIS -------- [verse] -'git rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] - [-s <strategy> | --strategy=<strategy>] [--no-verify] - [-C<n>] [ --whitespace=<option>] [-p | --preserve-merges] - [--onto <newbase>] <upstream> [<branch>] +'git rebase' [-i | --interactive] [options] [--onto <newbase>] + <upstream> [<branch>] +'git rebase' [-i | --interactive] [options] --onto <newbase> + --root [<branch>] + 'git rebase' --continue | --skip | --abort DESCRIPTION @@ -22,7 +23,8 @@ it remains on the current branch. All changes made by commits in the current branch but that are not in <upstream> are saved to a temporary area. This is the same set -of commits that would be shown by `git log <upstream>..HEAD`. +of commits that would be shown by `git log <upstream>..HEAD` (or +`git log HEAD`, if --root is specified). The current branch is reset to <upstream>, or <newbase> if the --onto option was supplied. This has the exact same effect as @@ -255,6 +257,15 @@ OPTIONS --preserve-merges:: Instead of ignoring merges, try to recreate them. +--root:: + Rebase all commits reachable from <branch>, instead of + limiting them with an <upstream>. This allows you to rebase + the root commit(s) on a branch. Must be used with --onto, and + will skip changes already contained in <newbase> (instead of + <upstream>). When used together with --preserve-merges, 'all' + root commits will be rewritten to have <newbase> as parent + instead. + include::merge-strategies.txt[] NOTES diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 2049f3d97b..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. @@ -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 diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 2921da320d..3ccef2f2b3 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -212,6 +212,9 @@ when you run 'git-merge'. reflog of the current branch. For example, if you are on the branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'. +* The special construct '@\{-<n>\}' means the <n>th branch checked out + before the current one. + * A suffix '{caret}' to a revision parameter means the first parent of that commit object. '{caret}<n>' means the <n>th parent (i.e. 'rev{caret}' diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 8f7c0e226d..498bd28929 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -82,7 +82,7 @@ her family name fully spelled out, a proper `.mailmap` file would look like: # 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> +Joe R. Developer <joe@example.com> ------------ Author diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 8277577a6f..7e9ff3762b 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -99,12 +99,12 @@ OPTIONS will show the revisions given by "git rev-list {caret}master topic1 topic2" +-g:: --reflog[=<n>[,<base>]] [<ref>]:: Shows <n> most recent ref-log entries for the given ref. If <base> is given, <n> entries going back from that entry. <base> can be specified as count or date. - `-g` can be used as a short-hand for this option. When - no explicit <ref> parameter is given, it defaults to the + When no explicit <ref> parameter is given, it defaults to the current branch (or `HEAD` if it is detached). Note that --more, --list, --independent and --merge-base options diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 8d0c421b80..7b654f7928 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -92,6 +92,30 @@ COMMANDS .git/config file may be specified as an optional command-line argument. +--localtime;; + Store Git commit times in the local timezone instead of UTC. This + makes 'git-log' (even without --date=local) show the same times + that `svn log` would in the local timezone. + +This doesn't interfere with interoperating with the Subversion +repository you cloned from, but if you wish for your local Git +repository to be able to interoperate with someone else's local Git +repository, either don't use this option or you should both use it in +the same local timezone. + +--ignore-paths=<regex>;; + This allows one to specify Perl regular expression that will + cause skipping of all matching paths from checkout from SVN. + Examples: + + --ignore-paths="^doc" - skip "doc*" directory for every fetch. + + --ignore-paths="^[^/]+/(?:branches|tags)" - skip "branches" + and "tags" of first level directories. + + Regular expression is not persistent, you should specify + it every time when fetching. + 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index e44f543025..533d18bbd5 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <name> [<commit> | <object>] 'git tag' -d <name>... -'git tag' [-n[<num>]] -l [<pattern>] +'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>] 'git tag' -v <name>... DESCRIPTION @@ -68,6 +68,9 @@ OPTIONS List tags with names that match the given pattern (or all if no pattern is given). Typing "git tag" without arguments, also lists all tags. +--contains <commit>:: + Only list tags which contain the specified commit. + -m <msg>:: Use the given tag message (instead of prompting). If multiple `-m` options are given, their values are diff --git a/Documentation/git.txt b/Documentation/git.txt index 17dc8b2019..0c7bba3fa9 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,12 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.6.1/git.html[documentation for release 1.6.1] +* link:v1.6.1.3/git.html[documentation for release 1.6.1.3] * release notes for + link:RelNotes-1.6.1.3.txt[1.6.1.3], + link:RelNotes-1.6.1.2.txt[1.6.1.2], + link:RelNotes-1.6.1.1.txt[1.6.1.1], link:RelNotes-1.6.1.txt[1.6.1]. * link:v1.6.0.6/git.html[documentation for release 1.6.0.6] diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 8af22eccac..227934f59a 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -317,6 +317,8 @@ patterns are available: - `bibtex` suitable for files with BibTeX coded references. +- `cpp` suitable for source code in the C and C++ languages. + - `html` suitable for HTML/XHTML documents. - `java` suitable for source code in the Java language. @@ -334,6 +336,25 @@ patterns are available: - `tex` suitable for source code for LaTeX documents. +Customizing word diff +^^^^^^^^^^^^^^^^^^^^^ + +You can customize the rules that `git diff --color-words` uses to +split words in a line, by specifying an appropriate regular expression +in the "diff.*.wordRegex" configuration variable. For example, in TeX +a backslash followed by a sequence of letters forms a command, but +several such commands can be run together without intervening +whitespace. To separate them, use a regular expression such as + +------------------------ +[diff "tex"] + wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" +------------------------ + +A built-in pattern is provided for all languages listed in the +previous section. + + Performing text diffs of binary files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index e4dd5518c8..7ba5e589d7 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1243,10 +1243,10 @@ $ git ls-files --stage ------------ In our example of only two files, we did not have unchanged -files so only 'example' resulted in collapsing, but in real-life -large projects, only small number of files change in one commit, -and this 'collapsing' tends to trivially merge most of the paths -fairly quickly, leaving only a handful the real changes in non-zero +files so only 'example' resulted in collapsing. But in real-life +large projects, when only a small number of files change in one commit, +this 'collapsing' tends to trivially merge most of the paths +fairly quickly, leaving only a handful of real changes in non-zero stages. To look at only non-zero stages, use `\--unmerged` flag: diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 28a8abcf52..1fd512bca2 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -15,7 +15,7 @@ DESCRIPTION Hooks are little scripts you can place in `$GIT_DIR/hooks` directory to trigger action at certain points. When -'git-init' is run, a handful example hooks are copied in the +'git-init' is run, a handful of example hooks are copied into the `hooks` directory of the new repository, but by default they are all disabled. To enable a hook, rename it by removing its `.sample` suffix. diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 4673a75a98..bd005bc5c8 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -47,7 +47,8 @@ frequently used options. After an attempt to merge stops with conflicts, show the commits on the history between two branches (i.e. the HEAD and the MERGE_HEAD) - that modify the conflicted files. + that modify the conflicted files and do not exist on all the heads + being merged. --argscmd=<command>:: Command to be run each time gitk has to determine the list of diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index a057b50b2b..dc8fc3a18a 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -32,12 +32,12 @@ Initialized empty Git repository in .git/ $ echo 'hello world' > file.txt $ git add . $ git commit -a -m "initial commit" -[master (root-commit)] created 54196cc: "initial commit" +[master (root-commit) 54196cc] initial commit 1 files changed, 1 insertions(+), 0 deletions(-) create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" -[master] created c4d59f3: "add emphasis" +[master c4d59f3] add emphasis 1 files changed, 1 insertions(+), 1 deletions(-) ------------------------------------------------ diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 458fafdb2c..c5d5596d89 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -308,9 +308,7 @@ alice$ git pull /home/bob/myrepo master This merges the changes from Bob's "master" branch into Alice's current branch. If Alice has made her own changes in the meantime, -then she may need to manually fix any conflicts. (Note that the -"master" argument in the above command is actually unnecessary, as it -is the default.) +then she may need to manually fix any conflicts. The "pull" command thus performs two operations: it fetches changes from a remote branch, then merges them into the current branch. diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt index d214d4bf9d..74a1c0c4ba 100644 --- a/Documentation/howto/rebase-from-internal-branch.txt +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -27,7 +27,7 @@ the kind of task StGIT is designed to do. I just have done a simpler one, this time using only the core GIT tools. -I had a handful commits that were ahead of master in pu, and I +I had a handful of commits that were ahead of master in pu, and I wanted to add some documentation bypassing my usual habit of placing new things in pu first. At the beginning, the commit ancestry graph looked like this: diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 0a8a948e6f..3d87d3edd5 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -124,6 +124,7 @@ The placeholders are: - '%Cgreen': switch color to green - '%Cblue': switch color to blue - '%Creset': reset color +- '%C(...)': color specification, as described in color.branch.* config option - '%m': left, right or boundary mark - '%n': newline - '%x00': print a byte from a hex code diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 6d66c74cc1..5f21efe407 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -10,7 +10,7 @@ configuration (see linkgit:git-config[1]). --abbrev-commit:: Instead of showing the full 40-byte hexadecimal commit object - name, show only handful hexdigits prefix. Non default number of + name, show only a partial prefix. Non default number of digits can be specified with "--abbrev=<n>" (which also modifies diff output, if it is displayed). + diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 82e9e831b6..2efe7a40be 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -52,6 +52,21 @@ Functions Wait for the completion of an asynchronous function that was started with start_async(). +`run_hook`:: + + Run a hook. + The first argument is a pathname to an index file, or NULL + if the hook uses the default index file or no index is needed. + The second argument is the name of the hook. + The further arguments correspond to the hook arguments. + The last argument has to be NULL to terminate the arguments list. + If the hook does not exist or is not executable, the return + value will be zero. + If it is executable, the hook will be executed and the exit + status of the hook is returned. + On execution, .stdout_to_stderr and .no_stdin will be set. + (See below.) + Data structures --------------- diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index 985800e43a..ac56d1c477 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -133,8 +133,10 @@ Functions * Adding data to the buffer -NOTE: All of these functions in this section will grow the buffer as - necessary. +NOTE: All of the functions in this section will grow the buffer as necessary. +If they fail for some reason other than memory shortage and the buffer hadn't +been allocated before (i.e. the `struct strbuf` was set to `STRBUF_INIT`), +then they will free() it. `strbuf_addch`:: @@ -235,6 +237,11 @@ same behaviour as well. Read the contents of a file, specified by its path. The third argument can be used to give a hint about the file size, to avoid reallocs. +`strbuf_readlink`:: + + Read the target of a symbolic link, specified by its path. The third + argument can be used to give a hint about the size, to avoid reallocs. + `strbuf_getline`:: Read a line from a FILE* pointer. The second argument specifies the line |