diff options
Diffstat (limited to 'Documentation')
78 files changed, 1175 insertions, 529 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 04f69cf64e..a4c4063e50 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -6,7 +6,7 @@ MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ gitrepository-layout.txt MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \ gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \ - gitdiffcore.txt gitworkflows.txt + gitdiffcore.txt gitrevisions.txt gitworkflows.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) diff --git a/Documentation/RelNotes-1.5.6.3.txt b/Documentation/RelNotes-1.5.6.3.txt index 942611299d..f61dd3504a 100644 --- a/Documentation/RelNotes-1.5.6.3.txt +++ b/Documentation/RelNotes-1.5.6.3.txt @@ -4,7 +4,7 @@ GIT v1.5.6.3 Release Notes Fixes since v1.5.6.2 -------------------- -* Setting core.sharerepository to traditional "true" value was supposed to make +* Setting core.sharedrepository to traditional "true" value was supposed to make the repository group writable but should not affect permission for others. However, since 1.5.6, it was broken to drop permission for others when umask is 022, making the repository unreadable by others. diff --git a/Documentation/RelNotes-1.6.0.2.txt b/Documentation/RelNotes-1.6.0.2.txt index 51b32f5d94..e1e24b3295 100644 --- a/Documentation/RelNotes-1.6.0.2.txt +++ b/Documentation/RelNotes-1.6.0.2.txt @@ -17,7 +17,7 @@ Fixes since v1.6.0.1 * Many commands did not use the correct working tree location when used with GIT_WORK_TREE environment settings. -* Some systems needs to use compatibility fnmach and regex libraries +* Some systems need to use compatibility fnmatch and regex libraries independent from each other; the compat/ area has been reorganized to allow this. diff --git a/Documentation/RelNotes-1.6.4.3.txt b/Documentation/RelNotes-1.6.4.3.txt index 4f29babdeb..5643e6537d 100644 --- a/Documentation/RelNotes-1.6.4.3.txt +++ b/Documentation/RelNotes-1.6.4.3.txt @@ -11,7 +11,7 @@ Fixes since v1.6.4.2 been deprecated. * "git fetch" and "git clone" had an extra sanity check to verify the - presense of the corresponding *.pack file before downloading *.idx + presence of the corresponding *.pack file before downloading *.idx file by issuing a HEAD request. Github server however sometimes gave 500 (Internal server error) response to HEAD even if a GET request for *.pack file to the same URL would have succeeded, and broke diff --git a/Documentation/RelNotes-1.6.5.4.txt b/Documentation/RelNotes-1.6.5.4.txt index e42f8b2397..d3a2a3e712 100644 --- a/Documentation/RelNotes-1.6.5.4.txt +++ b/Documentation/RelNotes-1.6.5.4.txt @@ -26,7 +26,7 @@ Fixes since v1.6.5.3 future versions, but not in this release, * "git merge -m <message> <branch>..." added the standard merge message - on its own after user-supplied message, which should have overrided the + on its own after user-supplied message, which should have overridden the standard one. Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.5.7.txt b/Documentation/RelNotes-1.6.5.7.txt index 5b49ea53be..dc5302c21c 100644 --- a/Documentation/RelNotes-1.6.5.7.txt +++ b/Documentation/RelNotes-1.6.5.7.txt @@ -10,7 +10,7 @@ Fixes since v1.6.5.6 an older version of git should just ignore them. Instead we diagnosed it as an error. -* With help.autocorrect set to non-zero value, the logic to guess typoes +* With help.autocorrect set to non-zero value, the logic to guess typos in the subcommand name misfired and ran a random nonsense command. * If a command is run with an absolute path as a pathspec inside a bare diff --git a/Documentation/RelNotes-1.6.6.txt b/Documentation/RelNotes-1.6.6.txt index 04e205c457..c50b59c495 100644 --- a/Documentation/RelNotes-1.6.6.txt +++ b/Documentation/RelNotes-1.6.6.txt @@ -29,7 +29,7 @@ or adjust to the new behaviour, on the day their sysadmin decides to install the new version of git. When we switched from "git-foo" to "git foo" in 1.6.0, even though the change had been advertised and the transition guide had been provided for a very long time, the users procrastinated -during the entire transtion period, and ended up panicking on the day +during the entire transition period, and ended up panicking on the day their sysadmins updated their git installation. We are trying to avoid repeating that unpleasantness in the 1.7.0 release. @@ -94,7 +94,7 @@ users will fare this time. * "git diff" traditionally treated various "ignore whitespace" options only as a way to filter the patch output. "git diff --exit-code -b" exited with non-zero status even if all changes were about changing the - ammount of whitespace and nothing else. and "git diff -b" showed the + amount of whitespace and nothing else. and "git diff -b" showed the "diff --git" header line for such a change without patch text. In 1.7.0, the "ignore whitespaces" will affect the semantics of the diff --git a/Documentation/RelNotes-1.7.0.7.txt b/Documentation/RelNotes-1.7.0.7.txt new file mode 100644 index 0000000000..d0cb7ca7e2 --- /dev/null +++ b/Documentation/RelNotes-1.7.0.7.txt @@ -0,0 +1,16 @@ +Git v1.7.0.7 Release Notes +========================== + +Fixes since v1.7.0.6 +-------------------- + + * "make NO_CURL=NoThanks install" was broken. + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git config --path conf.var" to attempt to expand a variable conf.var + that uses "~/" short-hand segfaulted when $HOME environment variable + was not set. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.0.txt b/Documentation/RelNotes-1.7.0.txt index 43e3f33615..0bb8c0b2a2 100644 --- a/Documentation/RelNotes-1.7.0.txt +++ b/Documentation/RelNotes-1.7.0.txt @@ -202,7 +202,7 @@ release, unless otherwise noted. the branch is fully merged to its upstream branch if it is not merged to the current branch. It now deletes it in such a case. - * "fiter-branch" command incorrectly said --prune-empty and --filter-commit + * "filter-branch" command incorrectly said --prune-empty and --filter-commit were incompatible; the latter should be read as --commit-filter. * When using "git status" or asking "git diff" to compare the work tree diff --git a/Documentation/RelNotes-1.7.1.1.txt b/Documentation/RelNotes-1.7.1.1.txt index bfdb5ba064..3f6b3148a3 100644 --- a/Documentation/RelNotes-1.7.1.1.txt +++ b/Documentation/RelNotes-1.7.1.1.txt @@ -1,5 +1,5 @@ -Git v1.7.1.1 Release Notes (draft) -================================== +Git v1.7.1.1 Release Notes +========================== Fixes since v1.7.1 ------------------ @@ -17,11 +17,18 @@ Fixes since v1.7.1 * We didn't recognize timezone "Z" as a synonym for "UTC" (75b37e70). + * In 1.7.0, read-tree and user commands that use the mechanism such as + checkout and merge were fixed to handle switching between branches one + of which has a file while the other has a directory at the same path + correctly even when there are some "confusing" pathnames in them. But + the algorithm used for this fix was suboptimal and had a terrible + performance degradation especially in larger trees. + * "git am -3" did not show diagnosis when the patch in the message was corrupt. * After "git apply --whitespace=fix" removed trailing blank lines in an patch in a patch series, it failed to apply later patches that depend - on the presense of such blank lines. + on the presence of such blank lines. * "git bundle --stdin" segfaulted. @@ -57,10 +64,15 @@ Fixes since v1.7.1 * "git merge --log" used to replace the custom message given by "-m" with the shortlog, instead of appending to it. + * "git notes copy" without any other argument segfaulted. + * "git pull" accepted "--dry-run", gave it to underlying "git fetch" but ignored the option itself, resulting in a bogus attempt to merge unrelated commit. + * "git rebase" did not faithfully reproduce a malformed author ident, that + is often seen in a repository converted from foreign SCMs. + * "git reset --hard" started from a wrong directory and a working tree in a nonstandard location is in use got confused. @@ -68,6 +80,9 @@ Fixes since v1.7.1 EHLO/HELO exchange, causing rejected connection from picky servers. It learned --smtp-domain option to solve this issue. + * "git send-email" did not declare a content-transfer-encoding and + content-type even when its payload needs to be sent in 8-bit. + * "git show -C -C" and other corner cases lost diff metainfo output in 1.7.0. @@ -79,10 +94,3 @@ Fixes since v1.7.1 * "git status" showed excess "hints" even when advice.statusHints is set to false. And other minor fixes and documentation updates. - - --- -exec >/var/tmp/1 -O=v1.7.1-195-gb2ebbd8 -echo O=$(git describe HEAD) -git shortlog --no-merges HEAD ^$O diff --git a/Documentation/RelNotes-1.7.1.2.txt b/Documentation/RelNotes-1.7.1.2.txt new file mode 100644 index 0000000000..61ba14e262 --- /dev/null +++ b/Documentation/RelNotes-1.7.1.2.txt @@ -0,0 +1,28 @@ +Git v1.7.1.2 Release Notes +========================== + +Fixes since v1.7.1.1 +-------------------- + + * "git commit" did not honor GIT_REFLOG_ACTION environment variable, resulting + reflog messages for cherry-pick and revert actions to be recorded as "commit". + + * "git clone/fetch/pull" issued an incorrect error message when a ref and + a symref that points to the ref were updated at the same time. This + obviously would update them to the same value, and should not result in + an error condition. + + * "git diff" inside a tree with many pathnames that have certain + characters has become very slow in 1.7.0 by mistake. + + * "git rev-parse --parseopt --stop-at-non-option" did not stop at non option + when --keep-dashdash was in effect. + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git config --path conf.var" to attempt to expand a variable conf.var + that uses "~/" short-hand segfaulted when $HOME environment variable + was not set. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.2.1.txt b/Documentation/RelNotes-1.7.2.1.txt new file mode 100644 index 0000000000..1103c47a4f --- /dev/null +++ b/Documentation/RelNotes-1.7.2.1.txt @@ -0,0 +1,25 @@ +Git v1.7.2.1 Release Notes +========================== + +Fixes since v1.7.2 +------------------ + + * "git instaweb" wasn't useful when your Apache was installed under a + name other than apache2 (e.g. "httpd"). + + * Similarly, "git web--browse" (invoked by "git help -w") learned that + chrome browser is sometimes called google-chrome. + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git config --path conf.var" to attempt to expand a variable conf.var + that uses "~/" short-hand segfaulted when $HOME environment variable + was not set. + + * Documentation on Cygwin failed to build. + + * The error message from "git pull blarg" when 'blarg' is an unknown + remote name has been improved. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.2.2.txt b/Documentation/RelNotes-1.7.2.2.txt new file mode 100644 index 0000000000..71eb6a8b0a --- /dev/null +++ b/Documentation/RelNotes-1.7.2.2.txt @@ -0,0 +1,22 @@ +Git v1.7.2.2 Release Notes +========================== + +Fixes since v1.7.2.1 +-------------------- + + * Object transfer over smart http transport deadlocked the client when + the remote HTTP server returned a failure, instead of erroring it out. + + * git-gui honors custom textconv filters when showing diff and blame; + + * git diff --relative=subdir (without the necessary trailing /) did not + work well; + + * "git diff-files -p --submodule" was recently broken; + + * "git checkout -b n ':/token'" did not work; + + * "git index-pack" (hence "git fetch/clone/pull/push") enabled the object + replacement machinery by mistake (it never should have); + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.2.3.txt b/Documentation/RelNotes-1.7.2.3.txt new file mode 100644 index 0000000000..610960cfe1 --- /dev/null +++ b/Documentation/RelNotes-1.7.2.3.txt @@ -0,0 +1,39 @@ +Git v1.7.2.3 Release Notes +========================== + +Fixes since v1.7.2.2 +-------------------- + + * When people try insane things such as delta-compressing 4GiB files, we + threw an assertion failure. + + * "git archive" gave the full commit ID for "$Format:%h$". + + * "git fetch --tags" did not fetch tags when remote.<nick>.tagopt was set + to --no-tags. The command line option now overrides the configuration + setting. + + * "git for-each-ref --format='%(objectname:short)'" has been completely + broken for a long time. + + * "git gc" incorrectly pruned a rerere record that was created long + time ago but still is actively and repeatedly used. + + * "git log --follow -M -p" was seriously broken in 1.7.2, reporting + assertion failure. + + * Running "git log" with an incorrect option started pager nevertheless, + forcing the user to dismiss it. + + * "git rebase" did not work well when the user has diff.renames + configuration variable set. + + * An earlier (and rather old) fix to "git rebase" against a rebased + upstream broke a more normal, non rebased upstream case rather badly, + attempting to re-apply patches that are already accepted upstream. + + * "git submodule sync" forgot to update the superproject's config file + when submodule URL changed. + + * "git pack-refs --all --prune" did not remove a directory that has + become empty. diff --git a/Documentation/RelNotes-1.7.2.txt b/Documentation/RelNotes-1.7.2.txt index 8ed7406266..15cf01178c 100644 --- a/Documentation/RelNotes-1.7.2.txt +++ b/Documentation/RelNotes-1.7.2.txt @@ -1,13 +1,16 @@ -Git v1.7.2 Release Notes (draft) -================================ +Git v1.7.2 Release Notes +======================== Updates since v1.7.1 -------------------- - * core.eol configuration and eol attribute are the new way to control - the end of line conventions for files in the working tree; - core.autocrlf overrides it, keeping the traditional behaviour by - default. + * core.eol configuration and text/eol attributes are the new way to control + the end of line conventions for files in the working tree. + + * core.autocrlf has been made safer - it will now only handle line + endings for new files and files that are LF-only in the + repository. To normalize content that has been checked in with + CRLF, use the new eol/text attributes. * The whitespace rules used in "git apply --whitespace" and "git diff" gained a new member in the family (tab-in-indent) to help projects with @@ -44,9 +47,13 @@ Updates since v1.7.1 prepares to create a root commit that is not connected to any existing commit. - * "git cherry-pick" learned to pick a range of commits (e.g. "cherry-pick - A..B"); this does not have nicer sequencing control "rebase [-i]" has, - though. + * "git cherry-pick" learned to pick a range of commits + (e.g. "cherry-pick A..B" and "cherry-pick --stdin"), so did "git + revert"; these do not support the nicer sequencing control "rebase + [-i]" has, though. + + * "git cherry-pick" and "git revert" learned --strategy option to specify + the merge strategy to be used when performing three-way merges. * "git cvsserver" can be told to use pserver; its password file can be stored outside the repository. @@ -74,8 +81,12 @@ Updates since v1.7.1 * Various options to "git grep" (e.g. --count, --name-only) work better with binary files. + * "git grep" learned "-Ovi" to open the files with hits in your editor. + * "git help -w" learned "chrome" and "chromium" browsers. + * "git log --decorate" shows commit decorations in various colours. + * "git log --follow <path>" follows across copies (it used to only follow renames). This may make the processing more expensive. @@ -92,8 +103,6 @@ Updates since v1.7.1 * "git remote" learned "set-branches" subcommand. - * "git revert" learned --strategy option to specify the merge strategy. - * "git rev-list A..B" learned --ancestry-path option to further limit the result to the commits that are on the ancestry chain between A and B (i.e. commits that are not descendants of A are excluded). @@ -106,10 +115,16 @@ Updates since v1.7.1 * "git status -s -b" shows the current branch in the output. + * "git status" learned "--ignore-submodules" option. + * Various "gitweb" enhancements and clean-ups, including syntax highlighting, "plackup" support for instaweb, .fcgi suffix to run it as FastCGI script, etc. + * The test harness has been updated to produce TAP-friendly output. + + * Many documentation improvement patches are also included. + Fixes since v1.7.1 ------------------ @@ -118,37 +133,19 @@ All of the fixes in v1.7.1.X maintenance series are included in this release, unless otherwise noted. * We didn't URL decode "file:///path/to/repo" correctly when path/to/repo - had percent-encoded characters (638794c, 9d2e942). - - * "git commit" did not honor GIT_REFLOG_ACTION environment variable, resulting - reflog messages for cherry-pick and revert actions to be recorded as "commit". - - * "git clone/fetch/pull" issued an incorrect error message when a ref and - a symref that points to the ref were updated at the same time. This - obviously would update them to the same value, and should not result in - an error condition (0e71bc3). + had percent-encoded characters (638794c, 9d2e942, ce83eda, 3c73a1d). * "git clone" did not configure remote.origin.url correctly for bare clones (df61c889). - * "git diff" inside a tree with many pathnames that have certain - characters has become very slow in 1.7.0 by mistake (will merge - e53e6b443 to 'maint'). - * "git diff --graph" works better with "--color-words" and other options (81fa024..4297c0a). * "git diff" could show ambiguous abbreviation of blob object names on its "index" line (3e5a188). - * "git rebase" did not faithfully reproduce a malformed author ident, that - is often seen in a repository converted from foreign SCMs (43c23251). - * "git reset --hard" started from a wrong directory and a working tree in a nonstandard location is in use got confused (560fb6a1). --- -exec >/var/tmp/1 -O=v1.7.1-592-gcf4403a -echo O=$(git describe HEAD) -git shortlog --no-merges HEAD ^maint ^$O + * "git read-tree -m A B" used to switch to branch B while retaining + local changes added an incorrect cache-tree information (b1f47514). diff --git a/Documentation/RelNotes-1.7.3.txt b/Documentation/RelNotes-1.7.3.txt new file mode 100644 index 0000000000..3512bbb238 --- /dev/null +++ b/Documentation/RelNotes-1.7.3.txt @@ -0,0 +1,73 @@ +Git v1.7.3 Release Notes (draft) +================================ + +Updates since v1.7.2 +-------------------- + + * git-gui got various updates and a new maintainer, Pat Thoyts. + + * Gitweb allows its configuration to change per each request; it used to + read the configuration once upon startup. + + * When git finds a corrupt object, it now reports the file that contains + it. + + * "git checkout -B <it>" is a shorter way to say "git branch -f <it>" + followed by "git checkout <it>". + + * When "git checkout" or "git merge" refuse to proceed in order to + protect local modification to your working tree, they used to stop + after showing just one path that might be lost. They now show all, + in a format that is easier to read. + + * "git clean" learned "-e" ("--exclude") option. + + * Hunk headers produced for C# files by "git diff" and friends show more + relevant context than before. + + * diff.ignoresubmodules configuration variable can be used to squelch the + differences in submodules reported when running commands (e.g. "diff", + "status", etc.) at the superproject level. + + * http.useragent configuration can be used to lie who you are to your + restrictive firewall. + + * "git rebase --strategy <s>" learned "-X" option to pass extra options + that are understood by the chosen merge strategy. + + * "git rebase -i" learned "exec" that you can insert into the insn sheet + to run a command between its steps. + + * "git rebase" between branches that have many binary changes that do + not conflict should be faster. + + * "git rebase -i" peeks into rebase.autosquash configuration and acts as + if you gave --autosquash from the command line. + + +Also contains various documentation updates. + + +Fixes since v1.7.2 +------------------ + +All of the fixes in v1.7.2.X maintenance series are included in this +release, unless otherwise noted. + + * "git merge -s recursive" (which is the default) did not handle cases + where a directory becomes a file (or vice versa) very well. + + * "git fetch" and friends were accidentally broken for url with "+" in + its path, e.g. "git://git.gnome.org/gtk+". + +--- +exec >/var/tmp/1 +echo O=$(git describe master) +O=v1.7.2.2-268-g7e42332 +O=v1.7.2 +git shortlog --no-merges $O..master ^maint +exit 0 + +What did we want to do with... + +1e3d411 (Enable custom schemes for column colors in the graph API, 2010-07-13) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index eb53e0636e..ece3c77482 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -7,17 +7,16 @@ Checklist (and a short version for the impatient): before committing - do not check in commented out code or unneeded files - the first line of the commit message should be a short - description and should skip the full stop + description (50 characters is the soft limit, see DISCUSSION + in git-commit(1)), and should skip the full stop - the body should provide a meaningful commit message, which: - uses the imperative, present tense: "change", not "changed" or "changes". - includes motivation for the change, and contrasts its implementation with previous behaviour - - if you want your work included in git.git, add a - "Signed-off-by: Your Name <you@example.com>" line to the - commit message (or just use the option "-s" when - committing) to confirm that you agree to the Developer's - Certificate of Origin + - add a "Signed-off-by: Your Name <you@example.com>" line to the + commit message (or just use the option "-s" when committing) + to confirm that you agree to the Developer's Certificate of Origin - make sure that you have tests for the bug you are fixing - make sure that the test suite passes after your commit diff --git a/Documentation/config.txt b/Documentation/config.txt index 4c491045c9..61831f60ce 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -128,7 +128,7 @@ advice.*:: when writing commit messages. Default: true. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to - merge to avoid overwritting local changes. + merge to avoid overwriting local changes. Default: true. resolveConflict:: Advices shown by various commands when conflicts @@ -418,7 +418,7 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. core.deltaBaseCacheLimit:: Maximum number of bytes to reserve for caching base objects - that multiple deltafied objects reference. By storing the + that may be referenced by multiple deltified objects. By storing the entire decompressed base objects in a cache Git is able to avoid unpacking and decompressing frequently used base objects multiple times. @@ -563,7 +563,7 @@ not necessarily be the current directory. am.keepcr:: If true, git-am will call git-mailsplit for patches in mbox format with parameter '--keep-cr'. In this case git-mailsplit will - not remove `\r` from lines ending with `\r\n`. Can be overrriden + not remove `\r` from lines ending with `\r\n`. Can be overridden by giving '--no-keep-cr' from the command line. See linkgit:git-am[1], linkgit:git-mailsplit[1]. @@ -690,6 +690,11 @@ color.diff.<slot>:: (highlighting whitespace errors). The values of these variables may be specified as in color.branch.<slot>. +color.decorate.<slot>:: + Use customized color for 'git log --decorate' output. `<slot>` is one + of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local + branches, remote tracking branches, tags, stash and HEAD, respectively. + color.grep:: When set to `always`, always highlight matches. When `false` (or `never`), never. When set to `true` or `auto`, use color only @@ -821,6 +826,11 @@ diff.renames:: will enable basic rename detection. If set to "copies" or "copy", it will detect copies, as well. +diff.ignoreSubmodules:: + Sets the default value of --ignore-submodules. Note that this + affects only 'git diff' Porcelain, and not lower level 'diff' + commands such as 'git diff-files'. + diff.suppressBlankEmpty:: A boolean to inhibit the standard behavior of printing a space before each empty output line. Defaults to false. @@ -881,9 +891,11 @@ format.headers:: Additional email headers to include in a patch to be submitted by mail. See linkgit:git-format-patch[1]. +format.to:: format.cc:: - Additional "Cc:" headers to include in a patch to be submitted - by mail. See the --cc option in linkgit:git-format-patch[1]. + Additional recipients to include in a patch to be submitted + by mail. See the --to and --cc options in + linkgit:git-format-patch[1]. format.subjectprefix:: The default for format-patch is to output files with the '[PATCH]' @@ -995,7 +1007,7 @@ gitcvs.usecrlfattr:: If true, the server will look up the end-of-line conversion attributes for files to determine the '-k' modes to use. If the attributes force git to treat a file as text, - the '-k' mode will be left blank so cvs clients will + the '-k' mode will be left blank so CVS clients will treat it as text. If they suppress text conversion, the file will be set with '-kb' mode, which suppresses any newline munging the client might otherwise do. If the attributes do not allow @@ -1236,6 +1248,15 @@ http.noEPSV:: support EPSV mode. Can be overridden by the 'GIT_CURL_FTP_NO_EPSV' environment variable. Default is false (curl will use EPSV). +http.useragent:: + The HTTP USER_AGENT string presented to an HTTP server. The default + value represents the version of the client git such as git/1.7.1. + This option allows you to override this value to a more common value + such as Mozilla/4.0. This may be necessary, for instance, if + connecting through a firewall that restricts HTTP connections to a set + of common USER_AGENT strings (but not including those like git/1.7.1). + Can be overridden by the 'GIT_HTTP_USER_AGENT' environment variable. + i18n.commitEncoding:: Character encoding the commit messages are stored in; git itself does not care per se, but this information is necessary e.g. when @@ -1268,7 +1289,9 @@ instaweb.local:: be bound to the local IP (127.0.0.1). instaweb.modulepath:: - The module path for an apache httpd used by linkgit:git-instaweb[1]. + The default module path for linkgit:git-instaweb[1] to use + instead of /usr/lib/apache2/modules. Only used if httpd + is Apache. instaweb.port:: The port number to bind the gitweb httpd to. See @@ -1526,6 +1549,9 @@ rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. +rebase.autosquash:: + If set to true enable '--autosquash' option by default. + receive.autogc:: By default, git-receive-pack will run "git-gc --auto" after receiving data from git-push and updating refs. You can stop @@ -1551,6 +1577,10 @@ 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.denyDeleteCurrent:: + If set to true, git-receive-pack will deny a ref update that + deletes the currently checked out branch of a non-bare repository. + receive.denyCurrentBranch:: If set to true or "refuse", git-receive-pack will deny a ref update to the currently checked out branch of a non-bare repository. @@ -1616,7 +1646,9 @@ remote.<name>.tagopt:: Setting this value to \--no-tags disables automatic tag following when fetching from remote <name>. Setting it to \--tags will fetch every tag from remote <name>, even if they are not reachable from remote - branch heads. + branch heads. Passing these flags directly to linkgit:git-fetch[1] can + override this setting. See options \--tags and \--no-tags of + linkgit:git-fetch[1]. remote.<name>.vcs:: Setting this to a value <vcs> will cause git to interact with @@ -1727,6 +1759,28 @@ status.submodulesummary:: summary of commits for modified submodules will be shown (see --summary-limit option of linkgit:git-submodule[1]). +submodule.<name>.path:: +submodule.<name>.url:: +submodule.<name>.update:: + The path within this project, URL, and the updating strategy + for a submodule. These variables are initially populated + by 'git submodule init'; edit them to override the + URL and other values found in the `.gitmodules` file. See + linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. + +submodule.<name>.ignore:: + Defines under what circumstances "git status" and the diff family show + a submodule as modified. When set to "all", it will never be considered + modified, "dirty" will ignore all changes to the submodules work tree and + takes only differences between the HEAD of the submodule and the commit + recorded in the superproject into account. "untracked" will additionally + let submodules with modified tracked files in their work tree show up. + Using "none" (the default when this option is not set) also shows + submodules that have untracked files in their work tree as changed. + This setting overrides any setting made in .gitmodules for this submodule, + both settings can be overridden on the command line by using the + "--ignore-submodules" option. + tar.umask:: This variable can be used to restrict the permission bits of tar archive entries. The default is 0002, which turns off the diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index e745a3ccdc..4656a97e60 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -206,10 +206,29 @@ endif::git-format-patch[] the diff-patch output format. Non default number of digits can be specified with `--abbrev=<n>`. --B:: - Break complete rewrite changes into pairs of delete and create. - --M:: +-B[<n>][/<m>]:: + Break complete rewrite changes into pairs of delete and + create. This serves two purposes: ++ +It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number `m` controls this aspect of the -B +option (defaults to 60%). `-B/70%` specifies that less than 30% of the +original should remain in the result for git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines). ++ +When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number `n` controls this aspect of +the -B option (defaults to 50%). `-B20%` specifies that a change with +addition and deletion compared to 20% or more of the file's size are +eligible for being picked up as a possible source of a rename to +another file. + +-M[<n>]:: ifndef::git-log[] Detect renames. endif::git-log[] @@ -218,9 +237,15 @@ ifdef::git-log[] For following files across renames while traversing history, see `--follow`. endif::git-log[] + If `n` is specified, it is a is a threshold on the similarity + index (i.e. amount of addition/deletions compared to the + file's size). For example, `-M90%` means git should consider a + delete/add pair to be a rename if more than 90% of the file + hasn't changed. --C:: +-C[<n>]:: Detect copies as well as renames. See also `--find-copies-harder`. + If `n` is specified, it has the same meaning as for `-M<n>`. ifndef::git-format-patch[] --diff-filter=[ACDMRTUXB*]:: @@ -328,8 +353,18 @@ endif::git-format-patch[] --no-ext-diff:: Disallow external diff drivers. ---ignore-submodules:: - Ignore changes to submodules in the diff generation. +--ignore-submodules[=<when>]:: + Ignore changes to submodules in the diff generation. <when> can be + either "none", "untracked", "dirty" or "all", which is the default + Using "none" will consider the submodule modified when it either contains + untracked or modified files or its HEAD differs from the commit recorded + in the superproject and can be used to override any settings of the + 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When + "untracked" is used submodules are not considered dirty when they only + contain untracked content (but they are still scanned for modified + content). Using "dirty" ignores all changes to the work tree of submodules, + only changes to the commits stored in the superproject are shown (this was + the behavior until 1.7.0). Using "all" hides all changes to submodules. --src-prefix=<prefix>:: Show the given source prefix instead of "a/". diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 044ec882cc..470ac31396 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -34,6 +34,7 @@ ifndef::git-pull[] Allow several <repository> and <group> arguments to be specified. No <refspec>s may be specified. +-p:: --prune:: After fetching, remove any remote tracking branches which no longer exist on the remote. @@ -48,7 +49,9 @@ ifndef::git-pull[] endif::git-pull[] By default, tags that point at objects that are downloaded from the remote repository are fetched and stored locally. - This option disables this automatic tag following. + This option disables this automatic tag following. The default + behavior for a remote may be specified with the remote.<name>.tagopt + setting. See linkgit:git-config[1]. -t:: --tags:: @@ -57,7 +60,9 @@ endif::git-pull[] objects reachable from the branch heads that are being tracked will not be fetched by this mechanism. This flag lets all tags and their associated objects be - downloaded. + downloaded. The default behavior for a remote may be + specified with the remote.<name>.tagopt setting. See + linkgit:git-config[1]. -u:: --update-head-ok:: diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 74741a42f4..e22a62f065 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -10,7 +10,8 @@ SYNOPSIS [verse] 'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N] - [--refresh] [--ignore-errors] [--] [<filepattern>...] + [--refresh] [--ignore-errors] [--ignore-missing] [--] + [<filepattern>...] DESCRIPTION ----------- @@ -57,7 +58,8 @@ OPTIONS -n:: --dry-run:: - Don't actually add the file(s), just show if they exist. + Don't actually add the file(s), just show if they exist and/or will + be ignored. -v:: --verbose:: @@ -131,6 +133,12 @@ subdirectories. them, do not abort the operation, but continue adding the others. The command shall still exit with non-zero status. +--ignore-missing:: + This option can only be used together with --dry-run. By using + this option the user can check if any of the given files would + be ignored, no matter if they are already present in the work + tree or not. + \--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 8463439ac5..4a74b23d40 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -26,6 +26,10 @@ with the `--cache` option the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a git repository. +This command applies the patch but does not create a commit. Use +linkgit:git-am[1] to create commits from patches generated by +linkgit:git-format-patch[1] and/or received by email. + OPTIONS ------- <patch>...:: @@ -242,6 +246,12 @@ If `--index` is not specified, then the submodule commits in the patch are ignored and only the absence or presence of the corresponding subdirectory is checked and (if possible) updated. + +SEE ALSO +-------- +linkgit:git-am[1]. + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 86b3015c13..efbe3790bb 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -971,7 +971,7 @@ logical change in each commit. The smaller the changes in your commit, the most effective "git bisect" will be. And you will probably need "git bisect" less in the first place, as small changes are easier to review even if they are -only reviewed by the commiter. +only reviewed by the committer. Another good idea is to have good commit messages. They can be very helpful to understand why some changes were made. diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 9ebbe9402b..a3f56b07fd 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -27,7 +27,7 @@ OPTIONS <object>:: The name of the object to show. For a more complete list of ways to spell object names, see - the "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + the "SPECIFYING REVISIONS" section in linkgit:gitrevisions[1]. -t:: Instead of the content, show the object type identified by diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 379eee6734..f5c2e0601d 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -49,7 +49,7 @@ git imposes the following rules on how references are named: These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoids ambiguities in certain -reference name expressions (see linkgit:git-rev-parse[1]): +reference name expressions (see linkgit:gitrevisions[1]): . A double-dot `..` is often used as in `ref1..ref2`, and in some contexts this notation means `{caret}ref1 ref2` (i.e. not in diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 261dd90c38..66e570113a 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git checkout' [-q] [-f] [-m] [<branch>] -'git checkout' [-q] [-f] [-m] [[-b|--orphan] <new_branch>] [<start_point>] +'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... 'git checkout' --patch [<tree-ish>] [--] [<paths>...] @@ -21,7 +21,7 @@ also update `HEAD` to set the specified branch as the current branch. 'git checkout' [<branch>]:: -'git checkout' -b <new branch> [<start point>]:: +'git checkout' -b|-B <new_branch> [<start point>]:: This form switches branches by updating the index, working tree, and HEAD to reflect the specified branch. @@ -31,6 +31,17 @@ were called and then checked out; in this case you can use the `--track` or `--no-track` options, which will be passed to 'git branch'. As a convenience, `--track` without `-b` implies branch creation; see the description of `--track` below. ++ +If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it +is reset. This is the transactional equivalent of ++ +------------ +$ git branch -f <branch> [<start point>] +$ git checkout <branch> +------------ ++ +that is to say, the branch is not reset/created unless "git checkout" is +successful. 'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...:: @@ -75,6 +86,12 @@ entries; instead, unmerged entries are ignored. Create a new branch named <new_branch> and start it at <start_point>; see linkgit:git-branch[1] for details. +-B:: + Creates the branch <new_branch> and start it at <start_point>; + if it already exists, then reset it to <start_point>. This is + equivalent to running "git branch" with "-f"; see + linkgit:git-branch[1] for details. + -t:: --track:: When creating a new branch, set up "upstream" configuration. See @@ -263,7 +280,7 @@ the above checkout would fail like this: + ------------ $ git checkout mytopic -fatal: Entry 'frotz' not uptodate. Cannot merge. +error: You have local changes to 'frotz'; not switching branches. ------------ + You can give the `-m` flag to the command, which would try a diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index bcb4c758b7..2cef579316 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -20,8 +20,8 @@ OPTIONS ------- <commit>...:: Commits to cherry-pick. - For a more complete list of ways to spell commits, see the - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + For a more complete list of ways to spell commits, see + linkgit:gitrevisions[1]. Sets of commits can be passed but no traversal is done by default, as if the '--no-walk' option was specified, see linkgit:git-rev-list[1]. @@ -113,6 +113,13 @@ git cherry-pick --ff ..next:: are in next but not HEAD to the current branch, creating a new commit for each new change. +git rev-list --reverse master \-- README | git cherry-pick -n --stdin:: + + Apply the changes introduced by all commits on the master + branch that touched README to the working tree and index, + so the result can be inspected and made into a single new + commit if suitable. + Author ------ Written by Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index a81cb6c280..60e38e6e27 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git clean' [-d] [-f] [-n] [-q] [-x | -X] [--] <path>... +'git clean' [-d] [-f] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... DESCRIPTION ----------- @@ -45,6 +45,12 @@ OPTIONS Be quiet, only report errors, but not the files that are successfully removed. +-e <pattern>:: +--exclude=<pattern>:: + Specify special exceptions to not be cleaned. Each <pattern> is + the same form as in $GIT_DIR/info/excludes and this option can be + given multiple times. + -x:: Don't use the ignore rules. This allows removing all untracked files, including build products. This can be used (possibly in diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index c28603ecf5..42fb1f57b2 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -130,11 +130,11 @@ OPTIONS Usually recording a commit that has the exact same tree as its sole parent commit is a mistake, and the command prevents you from making such a commit. This option bypasses the safety, and - is primarily for use by foreign scm interface scripts. + is primarily for use by foreign SCM interface scripts. --allow-empty-message:: Like --allow-empty this command is primarily for use by foreign - scm interface scripts. It allows you to create a commit with an + SCM interface scripts. It allows you to create a commit with an empty commit message without using plumbing commands like linkgit:git-commit-tree[1]. diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 8bcd875a67..608cd63fc3 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -188,7 +188,7 @@ ISSUES ------ Problems related to timestamps: - * If timestamps of commits in the cvs repository are not stable enough + * If timestamps of commits in the CVS repository are not stable enough to be used for ordering commits changes may show up in the wrong order. * If any files were ever "cvs import"ed more than once (e.g., import of @@ -201,7 +201,7 @@ Problems related to branches: * Branches on which no commits have been made are not imported. * All files from the branching point are added to a branch even if - never added in cvs. + never added in CVS. * This applies to files added to the source branch *after* a daughter branch was created: if previously no commit was made on the daughter branch they will erroneously be added to the daughter branch in git. diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 7004dd2dec..f4472c61db 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -366,8 +366,8 @@ CRLF Line Ending Conversions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default the server leaves the '-k' mode blank for all files, -which causes the cvs client to treat them as a text files, subject -to crlf conversion on some platforms. +which causes the CVS client to treat them as a text files, subject +to end-of-line conversion on some platforms. You can make the server use the end-of-line conversion attributes to set the '-k' modes for files by setting the `gitcvs.usecrlfattr` diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 723a64872f..08fd4099ad 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -68,11 +68,11 @@ for the last two forms that use ".." notations, can be any <tree-ish>. For a more complete list of ways to spell <commit>, see -"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. +"SPECIFYING REVISIONS" section in linkgit:gitrevisions[1]. However, "diff" is about comparing two _endpoints_, not ranges, and the range notations ("<commit>..<commit>" and "<commit>\...<commit>") do not mean a range as defined in the -"SPECIFYING RANGES" section in linkgit:git-rev-parse[1]. +"SPECIFYING RANGES" section in linkgit:gitrevisions[1]. OPTIONS ------- diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 98ec6b5871..8a6a3cb255 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -90,6 +90,12 @@ marks the same across runs. resulting stream can only be used by a repository which already contains the necessary objects. +--full-tree:: + This option will cause fast-export to issue a "deleteall" + directive for each commit followed by a full list of all files + in the commit (as opposed to just listing the files which are + different from the commit's first parent). + [git-rev-list-args...]:: A list of arguments, acceptable to 'git rev-parse' and 'git rev-list', that specifies the specific objects and references diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 19082b04eb..966ba4f213 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -439,7 +439,7 @@ Marks must be declared (via `mark`) before they can be used. * A complete 40 byte or abbreviated commit SHA-1 in hex. * Any valid Git SHA-1 expression that resolves to a commit. See - ``SPECIFYING REVISIONS'' in linkgit:git-rev-parse[1] for details. + ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[1] for details. The special case of restarting an incremental import from the current branch value should be written as: @@ -482,9 +482,11 @@ External data format:: 'M' SP <mode> SP <dataref> SP <path> LF .... + -Here `<dataref>` can be either a mark reference (`:<idnum>`) +Here usually `<dataref>` must be either a mark reference (`:<idnum>`) set by a prior `blob` command, or a full 40-byte SHA-1 of an -existing Git blob object. +existing Git blob object. If `<mode>` is `040000`` then +`<dataref>` must be the full 40-byte SHA-1 of an existing +Git tree object or a mark reference set with `--import-marks`. Inline data format:: The data content for the file has not been supplied yet. @@ -509,6 +511,8 @@ in octal. Git only supports the following modes: * `160000`: A gitlink, SHA-1 of the object refers to a commit in another repository. Git links can only be specified by SHA or through a commit mark. They are used to implement submodules. +* `040000`: A subdirectory. Subdirectories can only be specified by + SHA or through a tree mark set with `--import-marks`. In both formats `<path>` is the complete path of the file to be added (if not already existing) or modified (if already existing). diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index c8c81e8437..4b3f5ba535 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -39,7 +39,7 @@ There are two ways to specify which commits to operate on. that leads to the <since> to be output. 2. Generic <revision range> expression (see "SPECIFYING - REVISIONS" section in linkgit:git-rev-parse[1]) means the + REVISIONS" section in linkgit:gitrevisions[1]) means the commits in the specified range. The first rule takes precedence in the case of a single <commit>. To diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index a9e0882e9b..315f07ef1c 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -137,6 +137,13 @@ If you are expecting some objects to be collected and they aren't, check all of those locations and decide whether it makes sense in your case to remove those references. +HOOKS +----- + +The 'git gc --auto' command will run the 'pre-auto-gc' hook. See +linkgit:githooks[5] for more information. + + SEE ALSO -------- linkgit:git-prune[1] diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 912bddd7b6..5474dd7f94 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -14,6 +14,7 @@ SYNOPSIS [-E | --extended-regexp] [-G | --basic-regexp] [-F | --fixed-strings] [-n] [-l | --files-with-matches] [-L | --files-without-match] + [(-O | --open-files-in-pager) [<pager>]] [-z | --null] [-c | --count] [--all-match] [-q | --quiet] [--max-depth <depth>] @@ -104,6 +105,13 @@ OPTIONS For better compatibility with 'git diff', `--name-only` is a synonym for `--files-with-matches`. +-O [<pager>]:: +--open-files-in-pager [<pager>]:: + Open the matching files in the pager (not the output of 'grep'). + If the pager happens to be "less" or "vi", and the user + specified only one pattern, the first file is positioned at + the first match automatically. + -z:: --null:: Output \0 instead of the character that normally follows a diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 6904739a48..51edeecbe5 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -49,7 +49,7 @@ OPTIONS --no-filters:: Hash the contents as is, ignoring any input filter that would - have been chosen by the attributes mechanism, including crlf + have been chosen by the attributes mechanism, including the end-of-line conversion. If the file is read from standard input then this is always implied, unless the --path option is given. diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 2c3c4d2994..e70cea9320 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -49,15 +49,18 @@ OPTIONS linkgit:git-web--browse[1] for more information about this. If the script fails, the URL will be printed to stdout. +start:: --start:: Start the httpd instance and exit. This does not generate any of the configuration files for spawning a new instance. +stop:: --stop:: Stop the httpd instance and exit. This does not generate any of the configuration files for spawning a new instance, nor does it close the browser. +restart:: --restart:: Restart the httpd instance and exit. This does not generate any of the configuration files for spawning a new instance. diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 0e6ff31823..c213bdbdc5 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -23,9 +23,6 @@ each commit introduces are shown. OPTIONS ------- -:git-log: 1 -include::diff-options.txt[] - -<n>:: Limits the number of commits to show. @@ -34,8 +31,11 @@ include::diff-options.txt[] either <since> or <until> is omitted, it defaults to `HEAD`, i.e. the tip of the current branch. For a more complete list of ways to spell <since> - and <until>, see "SPECIFYING REVISIONS" section in - linkgit:git-rev-parse[1]. + and <until>, see linkgit:gitrevisions[1]. + +--follow:: + Continue listing the history of a file beyond renames + (works only for a single file). --no-decorate:: --decorate[=short|full|no]:: @@ -55,9 +55,9 @@ include::diff-options.txt[] paths. With this, the full diff is shown for commits that touch the specified paths; this means that "<path>..." limits only commits, and doesn't limit diff for those commits. - ---follow:: - Continue listing the history of a file beyond renames/copies. ++ +Note that this affects all diff-based output types, e.g. those +produced by --stat etc. --log-size:: Before the log message print out its size in bytes. Intended @@ -72,6 +72,11 @@ include::diff-options.txt[] to be prefixed with "\-- " to separate them from options or refnames. +Common diff options +~~~~~~~~~~~~~~~~~~~ + +:git-log: 1 +include::diff-options.txt[] include::rev-list-options.txt[] diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 3521637b58..a7c8174d01 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -106,8 +106,16 @@ OPTIONS with `-s` or `-u` options does not make any sense. -t:: - Identify the file status with the following tags (followed by - a space) at the start of each line: + This feature is semi-deprecated. For scripting purpose, + linkgit:git-status[1] `--porcelain` and + linkgit:git-diff-files[1] `--name-status` are almost always + superior alternatives, and users should look at + linkgit:git-status[1] `--short` or linkgit:git-diff[1] + `--name-status` for more user-friendly alternatives. ++ +This option identifies the file status with the following tags (followed by +a space) at the start of each line: + H:: cached S:: skip-worktree M:: unmerged @@ -132,6 +140,12 @@ OPTIONS lines, show only a partial prefix. Non default number of digits can be specified with --abbrev=<n>. +--debug:: + After each line that describes a file, add more data about its + cache entry. This is intended to show as much information as + possible for manual inspection; the exact format may change at + any time. + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 55735faf7b..e4ed016146 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -72,6 +72,16 @@ success of the resolution after the custom tool has exited. This is the default behaviour; the option is provided to override any configuration settings. +TEMPORARY FILES +--------------- +`git mergetool` creates `*.orig` backup files while resolving merges. +These are safe to remove once a file has been merged and its +`git mergetool` session has completed. + +Setting the `mergetool.keepBackup` configuration variable to `false` +causes `git mergetool` to automatically remove the backup as files +are successfully merged. + Author ------ Written by Theodore Y Ts'o <tytso@mit.edu> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 5540af5d16..2981d8c5ef 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -129,10 +129,12 @@ OPTIONS is taken to be in `refs/notes/` if it is not qualified. -n:: +--dry-run:: Do not remove anything; just report the object names whose notes would be removed. -v:: +--verbose:: Report all object names whose notes are removed. diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 15cfb7a8dc..4d673a5686 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -31,10 +31,12 @@ OPTIONS ------- -n:: +--dry-run:: Do not remove anything; just report what it would remove. -v:: +--verbose:: Report all removed objects. \--:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index ab4de10358..c50f7dcb89 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -8,29 +8,72 @@ git-pull - Fetch from and merge with another repository or a local branch SYNOPSIS -------- -'git pull' <options> <repository> <refspec>... +'git pull' [options] [<repository> [<refspec>...]] DESCRIPTION ----------- -Runs 'git fetch' with the given parameters, and calls 'git merge' -to merge the retrieved head(s) into the current branch. -With `--rebase`, calls 'git rebase' instead of 'git merge'. -Note that you can use `.` (current directory) as the -<repository> to pull from the local repository -- this is useful -when merging local branches into the current branch. +Incorporates changes from a remote repository into the current +branch. In its default mode, `git pull` is shorthand for +`git fetch` followed by `git merge FETCH_HEAD`. -Also note that options meant for 'git pull' itself and underlying -'git merge' must be given before the options meant for 'git fetch'. +More precisely, 'git pull' runs 'git fetch' with the given +parameters and calls 'git merge' to merge the retrieved branch +heads into the current branch. +With `--rebase`, it runs 'git rebase' instead of 'git merge'. -*Warning*: Running 'git pull' (actually, the underlying 'git merge') +<repository> should be the name of a remote repository as +passed to linkgit:git-fetch[1]. <refspec> can name an +arbitrary remote ref (for example, the name of a tag) or even +a collection of refs with corresponding remote tracking branches +(e.g., refs/heads/*:refs/remotes/origin/*), but usually it is +the name of a branch in the remote repository. + +Default values for <repository> and <branch> are read from the +"remote" and "merge" configuration for the current branch +as set by linkgit:git-branch[1] `--track`. + +Assume the following history exists and the current branch is +"`master`": + +------------ + A---B---C master on origin + / + D---E---F---G master +------------ + +Then "`git pull`" will fetch and replay the changes from the remote +`master` branch since it diverged from the local `master` (i.e., `E`) +until its current commit (`C`) on top of `master` and record the +result in a new commit along with the names of the two parent commits +and a log message from the user describing the changes. + +------------ + A---B---C remotes/origin/master + / \ + D---E---F---G---H master +------------ + +See linkgit:git-merge[1] for details, including how conflicts +are presented and handled. + +In git 1.7.0 or later, to cancel a conflicting merge, use +`git reset --merge`. *Warning*: In older versions of git, running 'git pull' with uncommitted changes is discouraged: while possible, it leaves you -in a state that is hard to back out of in the case of a conflict. +in a state that may be hard to back out of in the case of a conflict. + +If any of the remote changes overlap with local uncommitted changes, +the merge will be automatically cancelled and the work tree untouched. +It is generally best to get any local changes in working order before +pulling or stash them away with linkgit:git-stash[1]. OPTIONS ------- +Options meant for 'git pull' itself and the underlying 'git merge' +must be given before the options meant for 'git fetch'. + -q:: --quiet:: This is passed to both underlying git-fetch to squelch reporting of diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 48570242fb..658ff2ff67 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -41,7 +41,7 @@ OPTIONS[[OPTIONS]] + The <src> is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as `master~4` or -`HEAD` (see linkgit:git-rev-parse[1]). +`HEAD` (see linkgit:gitrevisions[1]). + The <dst> tells which ref on the remote side is updated with this push. Arbitrary expressions cannot be used here, an actual ref must @@ -200,16 +200,29 @@ summary:: For a successfully pushed ref, the summary shows the old and new values of the ref in a form suitable for using as an argument to `git log` (this is `<old>..<new>` in most cases, and - `<old>...<new>` for forced non-fast-forward updates). For a - failed update, more details are given for the failure. - The string `rejected` indicates that git did not try to send the - ref at all (typically because it is not a fast-forward). The - string `remote rejected` indicates that the remote end refused - the update; this rejection is typically caused by a hook on the - remote side. The string `remote failure` indicates that the - remote end did not report the successful update of the ref - (perhaps because of a temporary error on the remote side, a - break in the network connection, or other transient error). + `<old>...<new>` for forced non-fast-forward updates). ++ +For a failed update, more details are given: ++ +-- +rejected:: + Git did not try to send the ref at all, typically because it + is not a fast-forward and you did not force the update. + +remote rejected:: + The remote end refused the update. Usually caused by a hook + on the remote side, or because the remote repository has one + of the following safety options in effect: + `receive.denyCurrentBranch` (for pushes to the checked out + branch), `receive.denyNonFastForwards` (for forced + non-fast-forward updates), `receive.denyDeletes` or + `receive.denyDeleteCurrent`. See linkgit:git-config[1]. + +remote failure:: + The remote end did not report the successful update of the ref, + perhaps because of a temporary error on the remote side, a + break in the network connection, or other transient error. +-- from:: The name of the local ref being pushed, minus its diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index f6037c4f6a..2e78da448f 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -412,6 +412,13 @@ turn `core.sparseCheckout` on in order to have sparse checkout support. +BUGS +---- +In order to match a directory with $GIT_DIR/info/sparse-checkout, +trailing slash must be used. The form without trailing slash, while +works with .gitignore, does not work with sparse checkout. + + SEE ALSO -------- linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index be23ad2359..45c52d2e57 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -199,6 +199,9 @@ rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. +rebase.autosquash:: + If set to true enable '--autosquash' option by default. + OPTIONS ------- <newbase>:: @@ -250,6 +253,13 @@ on top of the <upstream> branch using the given strategy, using the 'ours' strategy simply discards all patches from the <branch>, which makes little sense. +-X <strategy-option>:: +--strategy-option=<strategy-option>:: + Pass the <strategy-option> through to the merge strategy. + This implies `\--merge` and, if no strategy has been + specified, `-s recursive`. Note the reversal of 'ours' and + 'theirs' as noted in above for the `-m` option. + -q:: --quiet:: Be quiet. Implies --no-stat. @@ -326,6 +336,7 @@ idea unless you know what you are doing (see BUGS below). instead. --autosquash:: +--no-autosquash:: When the commit log message begins with "squash! ..." (or "fixup! ..."), and there is a commit whose title begins with the same ..., automatically modify the todo list of rebase -i @@ -334,6 +345,10 @@ idea unless you know what you are doing (see BUGS below). commit from `pick` to `squash` (or `fixup`). + This option is only valid when the '--interactive' option is used. ++ +If the '--autosquash' option is enabled by default using the +configuration variable `rebase.autosquash`, this option can be +used to override and disable this setting. --no-ff:: With --interactive, cherry-pick all rebased commits instead of @@ -459,6 +474,30 @@ sure that the current HEAD is "B", and call $ git rebase -i -p --onto Q O ----------------------------- +Reordering and editing commits usually creates untested intermediate +steps. You may want to check that your history editing did not break +anything by running a test, or at least recompiling at intermediate +points in history by using the "exec" command (shortcut "x"). You may +do so by creating a todo list like this one: + +------------------------------------------- +pick deadbee Implement feature XXX +fixup f1a5c00 Fix to feature XXX +exec make +pick c0ffeee The oneline of the next commit +edit deadbab The oneline of the commit after +exec cd subdir; make test +... +------------------------------------------- + +The interactive rebase will stop when a command fails (i.e. exits with +non-0 status) to give you an opportunity to fix the problem. You can +continue with `git rebase --continue`. + +The "exec" command launches the command in a shell (the one specified +in `$SHELL`, or the default shell if `$SHELL` is not set), so you can +use shell features (like "cd", ">", ";" ...). The command is run from +the root of the working tree. SPLITTING COMMITS ----------------- diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 4eaa62b691..5a0451aaf3 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -40,7 +40,7 @@ see linkgit:git-log[1]. The reflog is useful in various git commands, to specify the old value of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be two moves ago", `master@\{one.week.ago\}` means "where master used to -point to one week ago", and so on. See linkgit:git-rev-parse[1] for +point to one week ago", and so on. See linkgit:gitrevisions[1] for more details. To delete single entries from the reflog, use the subcommand "delete" diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 19335fddae..400f61f6e2 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -7,7 +7,7 @@ git-request-pull - Generates a summary of pending changes SYNOPSIS -------- -'git request-pull' <start> <url> [<end>] +'git request-pull' [-p] <start> <url> [<end>] DESCRIPTION ----------- @@ -17,6 +17,9 @@ the given URL in the generated summary. OPTIONS ------- +-p:: + Show patch text + <start>:: Commit to start at. diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index acc220a00f..db99d4786e 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -7,7 +7,7 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- -'git rerere' ['clear'|'diff'|'status'|'gc'] +'git rerere' ['clear'|'forget' [<pathspec>]|'diff'|'status'|'gc'] DESCRIPTION ----------- @@ -40,6 +40,11 @@ This resets the metadata used by rerere if a merge resolution is to be aborted. Calling 'git am [--skip|--abort]' or 'git rebase [--skip|--abort]' will automatically invoke this command. +'forget' <pathspec>:: + +This resets the conflict resolutions which rerere has recorded for the current +conflict in <pathspec>. The <pathspec> is optional. + 'diff':: This displays diffs for the current state of the resolution. It is diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 645f0c1748..9cf31485fe 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,40 +8,50 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git reset' [--mixed | --soft | --hard | --merge | --keep] [-q] [<commit>] 'git reset' [-q] [<commit>] [--] <paths>... 'git reset' --patch [<commit>] [--] [<paths>...] +'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- -Sets the current head to the specified commit and optionally resets the -index and working tree to match. - -This command is useful if you notice some small error in a recent -commit (or set of commits) and want to redo that part without showing -the undo in the history. - -If you want to undo a commit other than the latest on a branch, -linkgit:git-revert[1] is your friend. - -The second and third forms with 'paths' and/or --patch are used to -revert selected paths in the index from a given commit, without moving -HEAD. - +In the first and second form, copy entries from <commit> to the index. +In the third form, set the current branch to <commit>, optionally +modifying index and worktree to match. The <commit> defaults to HEAD +in all forms. + +'git reset' [-q] [<commit>] [--] <paths>...:: + This form resets the index entries for all <paths> to their + state at the <commit>. (It does not affect the worktree, nor + the current branch.) ++ +This means that `git reset <paths>` is the opposite of `git add +<paths>`. -OPTIONS -------- ---mixed:: - Resets the index but not the working tree (i.e., the changed files - are preserved but not marked for commit) and reports what has not - been updated. This is the default action. +'git reset' --patch|-p [<commit>] [--] [<paths>...]:: + Interactively select hunks in the difference between the index + and <commit> (defaults to HEAD). The chosen hunks are applied + in reverse to the index. ++ +This means that `git reset -p` is the opposite of `git add -p` (see +linkgit:git-add[1]). +'git reset' [--<mode>] [<commit>]:: + This form points the current branch to <commit> and then + updates index and working tree according to <mode>, which must + be one of the following: ++ +-- --soft:: Does not touch the index file nor the working tree at all, but requires them to be in a good order. This leaves all your changed files "Changes to be committed", as 'git status' would put it. +--mixed:: + Resets the index but not the working tree (i.e., the changed files + are preserved but not marked for commit) and reports what has not + been updated. This is the default action. + --hard:: Matches the working tree and index to that of the tree being switched to. Any changes to tracked files in the working tree @@ -59,132 +69,46 @@ OPTIONS the given commit. If a file that is different between the current commit and the given commit has local changes, reset is aborted. +-- --p:: ---patch:: - Interactively select hunks in the difference between the index - and <commit> (defaults to HEAD). The chosen hunks are applied - in reverse to the index. -+ -This means that `git reset -p` is the opposite of `git add -p` (see -linkgit:git-add[1]). +If you want to undo a commit other than the latest on a branch, +linkgit:git-revert[1] is your friend. + + +OPTIONS +------- -q:: --quiet:: Be quiet, only report errors. -<commit>:: - Commit to make the current HEAD. If not given defaults to HEAD. - -DISCUSSION ----------- -The tables below show what happens when running: - ----------- -git reset --option target ----------- - -to reset the HEAD to another commit (`target`) with the different -reset options depending on the state of the files. - -In these tables, A, B, C and D are some different states of a -file. For example, the first line of the first table means that if a -file is in state A in the working tree, in state B in the index, in -state C in HEAD and in state D in the target, then "git reset --soft -target" will put the file in state A in the working tree, in state B -in the index and in state D in HEAD. - - working index HEAD target working index HEAD - ---------------------------------------------------- - A B C D --soft A B D - --mixed A D D - --hard D D D - --merge (disallowed) - --keep (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - A B C C --soft A B C - --mixed A C C - --hard C C C - --merge (disallowed) - --keep A C C - - working index HEAD target working index HEAD - ---------------------------------------------------- - B B C D --soft B B D - --mixed B D D - --hard D D D - --merge D D D - --keep (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - B B C C --soft B B C - --mixed B C C - --hard C C C - --merge C C C - --keep B C C - - working index HEAD target working index HEAD - ---------------------------------------------------- - B C C D --soft B C D - --mixed B D D - --hard D D D - --merge (disallowed) - --keep (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - B C C C --soft B C C - --mixed B C C - --hard C C C - --merge B C C - --keep B C C - -"reset --merge" is meant to be used when resetting out of a conflicted -merge. Any mergy operation guarantees that the work tree file that is -involved in the merge does not have local change wrt the index before -it starts, and that it writes the result out to the work tree. So if -we see some difference between the index and the target and also -between the index and the work tree, then it means that we are not -resetting out from a state that a mergy operation left after failing -with a conflict. That is why we disallow --merge option in this case. - -"reset --keep" is meant to be used when removing some of the last -commits in the current branch while keeping changes in the working -tree. If there could be conflicts between the changes in the commit we -want to remove and the changes in the working tree we want to keep, -the reset is disallowed. That's why it is disallowed if there are both -changes between the working tree and HEAD, and between HEAD and the -target. To be safe, it is also disallowed when there are unmerged -entries. - -The following tables show what happens when there are unmerged -entries: - - working index HEAD target working index HEAD - ---------------------------------------------------- - X U A B --soft (disallowed) - --mixed X B B - --hard B B B - --merge B B B - --keep (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - X U A A --soft (disallowed) - --mixed X A A - --hard A A A - --merge A A A - --keep (disallowed) - -X means any state and U means an unmerged index. - -Examples +EXAMPLES -------- +Undo add:: ++ +------------ +$ edit <1> +$ git add frotz.c filfre.c +$ mailx <2> +$ git reset <3> +$ git pull git://info.example.com/ nitfol <4> +------------ ++ +<1> You are happily working on something, and find the changes +in these files are in good order. You do not want to see them +when you run "git diff", because you plan to work on other files +and changes with these files are distracting. +<2> Somebody asks you to pull, and the changes sounds worthy of merging. +<3> However, you already dirtied the index (i.e. your index does +not match the HEAD commit). But you know the pull you are going +to make does not affect frotz.c nor filfre.c, so you revert the +index changes for these two files. Your changes in working tree +remain there. +<4> Then you can pull and merge, leaving frotz.c and filfre.c +changes still in the working tree. + Undo a commit and redo:: + ------------ @@ -204,19 +128,6 @@ edit the message further, you can give -C option instead. + See also the --amend option to linkgit:git-commit[1]. -Undo commits permanently:: -+ ------------- -$ git commit ... -$ git reset --hard HEAD~3 <1> ------------- -+ -<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad -and you do not want to ever see them again. Do *not* do this if -you have already given these commits to somebody else. (See the -"RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for -the implications of doing so.) - Undo a commit, making it a topic branch:: + ------------ @@ -232,28 +143,18 @@ current HEAD. <2> Rewind the master branch to get rid of those three commits. <3> Switch to "topic/wip" branch and keep working. -Undo add:: +Undo commits permanently:: + ------------ -$ edit <1> -$ git add frotz.c filfre.c -$ mailx <2> -$ git reset <3> -$ git pull git://info.example.com/ nitfol <4> +$ git commit ... +$ git reset --hard HEAD~3 <1> ------------ + -<1> You are happily working on something, and find the changes -in these files are in good order. You do not want to see them -when you run "git diff", because you plan to work on other files -and changes with these files are distracting. -<2> Somebody asks you to pull, and the changes sounds worthy of merging. -<3> However, you already dirtied the index (i.e. your index does -not match the HEAD commit). But you know the pull you are going -to make does not affect frotz.c nor filfre.c, so you revert the -index changes for these two files. Your changes in working tree -remain there. -<4> Then you can pull and merge, leaving frotz.c and filfre.c -changes still in the working tree. +<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +and you do not want to ever see them again. Do *not* do this if +you have already given these commits to somebody else. (See the +"RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for +the implications of doing so.) Undo a merge or pull:: + @@ -355,7 +256,7 @@ Keep changes in working tree while discarding some previous commits:: Suppose you are working on something and you commit it, and then you continue working a bit more, but now you think that what you have in your working tree should be in another branch that has nothing to do -with what you commited previously. You can start a new branch and +with what you committed previously. You can start a new branch and reset it while keeping the changes in your work tree. + ------------ @@ -376,6 +277,114 @@ $ git reset --keep start <3> <3> But you can use "reset --keep" to remove the unwanted commit after you switched to "branch2". + +DISCUSSION +---------- + +The tables below show what happens when running: + +---------- +git reset --option target +---------- + +to reset the HEAD to another commit (`target`) with the different +reset options depending on the state of the files. + +In these tables, A, B, C and D are some different states of a +file. For example, the first line of the first table means that if a +file is in state A in the working tree, in state B in the index, in +state C in HEAD and in state D in the target, then "git reset --soft +target" will put the file in state A in the working tree, in state B +in the index and in state D in HEAD. + + working index HEAD target working index HEAD + ---------------------------------------------------- + A B C D --soft A B D + --mixed A D D + --hard D D D + --merge (disallowed) + --keep (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + A B C C --soft A B C + --mixed A C C + --hard C C C + --merge (disallowed) + --keep A C C + + working index HEAD target working index HEAD + ---------------------------------------------------- + B B C D --soft B B D + --mixed B D D + --hard D D D + --merge D D D + --keep (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + B B C C --soft B B C + --mixed B C C + --hard C C C + --merge C C C + --keep B C C + + working index HEAD target working index HEAD + ---------------------------------------------------- + B C C D --soft B C D + --mixed B D D + --hard D D D + --merge (disallowed) + --keep (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + B C C C --soft B C C + --mixed B C C + --hard C C C + --merge B C C + --keep B C C + +"reset --merge" is meant to be used when resetting out of a conflicted +merge. Any mergy operation guarantees that the work tree file that is +involved in the merge does not have local change wrt the index before +it starts, and that it writes the result out to the work tree. So if +we see some difference between the index and the target and also +between the index and the work tree, then it means that we are not +resetting out from a state that a mergy operation left after failing +with a conflict. That is why we disallow --merge option in this case. + +"reset --keep" is meant to be used when removing some of the last +commits in the current branch while keeping changes in the working +tree. If there could be conflicts between the changes in the commit we +want to remove and the changes in the working tree we want to keep, +the reset is disallowed. That's why it is disallowed if there are both +changes between the working tree and HEAD, and between HEAD and the +target. To be safe, it is also disallowed when there are unmerged +entries. + +The following tables show what happens when there are unmerged +entries: + + working index HEAD target working index HEAD + ---------------------------------------------------- + X U A B --soft (disallowed) + --mixed X B B + --hard B B B + --merge B B B + --keep (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + X U A A --soft (disallowed) + --mixed X A A + --hard A A A + --merge A A A + --keep (disallowed) + +X means any state and U means an unmerged index. + + Author ------ Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 8db600f6ba..be4c053360 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -174,202 +174,7 @@ shown. If the pattern does not contain a globbing character (`?`, Flags and parameters to be parsed. -SPECIFYING REVISIONS --------------------- - -A revision parameter typically, but not necessarily, names a -commit object. They use what is called an 'extended SHA1' -syntax. Here are various ways to spell object names. The -ones listed near the end of this list are to name trees and -blobs contained in a commit. - -* The full SHA1 object name (40-byte hexadecimal string), or - a substring of such that is unique within the repository. - E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both - name the same commit object if there are no other object in - your repository whose object name starts with dae86e. - -* An output from 'git describe'; i.e. a closest tag, optionally - followed by a dash and a number of commits, followed by a dash, a - `g`, and an abbreviated object name. - -* A symbolic ref name. E.g. 'master' typically means the commit - object referenced by refs/heads/master. If you - happen to have both heads/master and tags/master, you can - explicitly say 'heads/master' to tell git which one you mean. - When ambiguous, a `<name>` is disambiguated by taking the - first match in the following rules: - - . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`); - - . otherwise, `refs/<name>` if exists; - - . otherwise, `refs/tags/<name>` if exists; - - . otherwise, `refs/heads/<name>` if exists; - - . otherwise, `refs/remotes/<name>` if exists; - - . otherwise, `refs/remotes/<name>/HEAD` if exists. -+ -HEAD names the commit your changes in the working tree is based on. -FETCH_HEAD records the branch you fetched from a remote repository -with your last 'git fetch' invocation. -ORIG_HEAD is created by commands that moves your HEAD in a drastic -way, to record the position of the HEAD before their operation, so that -you can change the tip of the branch back to the state before you ran -them easily. -MERGE_HEAD records the commit(s) you are merging into your branch -when you run 'git merge'. -+ -Note that any of the `refs/*` cases above may come either from -the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. - -* A ref followed by the suffix '@' with a date specification - enclosed in a brace - pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 - second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value - of the ref at a prior point in time. This suffix may only be - used immediately following a ref name and the ref must have an - existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state - of your *local* ref at a given time; e.g., what was in your local - `master` branch last week. If you want to look at commits made during - certain times, see `--since` and `--until`. - -* A ref followed by the suffix '@' with an ordinal specification - enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify - the n-th prior value of that ref. For example 'master@\{1\}' - is the immediate prior value of 'master' while 'master@\{5\}' - is the 5th prior value of 'master'. This suffix may only be used - immediately following a ref name and the ref must have an existing - log ($GIT_DIR/logs/<ref>). - -* You can use the '@' construct with an empty ref part to get at a - 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. - -* The suffix '@\{upstream\}' to a ref (short form 'ref@\{u\}') refers to - the branch the ref is set to build on top of. Missing ref defaults - to the current branch. - -* 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}' - is equivalent to 'rev{caret}1'). As a special rule, - 'rev{caret}0' means the commit itself and is used when 'rev' is the - object name of a tag object that refers to a commit object. - -* A suffix '{tilde}<n>' to a revision parameter means the commit - object that is the <n>th generation grand-parent of the named - commit object, following only the first parent. I.e. rev~3 is - equivalent to rev{caret}{caret}{caret} which is equivalent to - rev{caret}1{caret}1{caret}1. See below for a illustration of - the usage of this form. - -* A suffix '{caret}' followed by an object type name enclosed in - brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object - could be a tag, and dereference the tag recursively until an - object of that type is found or the object cannot be - dereferenced anymore (in which case, barf). `rev{caret}0` - introduced earlier is a short-hand for `rev{caret}\{commit\}`. - -* A suffix '{caret}' followed by an empty brace pair - (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag, - and dereference the tag recursively until a non-tag object is - found. - -* A colon, followed by a slash, followed by a text: this names - a commit whose commit message starts with the specified text. - This name returns the youngest matching commit which is - reachable from any ref. If the commit message starts with a - '!', you have to repeat that; the special sequence ':/!', - followed by something else than '!' is reserved for now. - -* A suffix ':' followed by a path; this names the blob or tree - at the given path in the tree-ish object named by the part - before the colon. - -* A colon, optionally followed by a stage number (0 to 3) and a - colon, followed by a path; this names a blob object in the - index at the given path. Missing stage number (and the colon - that follows it) names a stage 0 entry. During a merge, stage - 1 is the common ancestor, stage 2 is the target branch's version - (typically the current branch), and stage 3 is the version from - the branch being merged. - -Here is an illustration, by Jon Loeliger. Both commit nodes B -and C are parents of commit node A. Parent commits are ordered -left-to-right. - -........................................ -G H I J - \ / \ / - D E F - \ | / \ - \ | / | - \|/ | - B C - \ / - \ / - A -........................................ - - A = = A^0 - B = A^ = A^1 = A~1 - C = A^2 = A^2 - D = A^^ = A^1^1 = A~2 - E = B^2 = A^^2 - F = B^3 = A^^3 - G = A^^^ = A^1^1^1 = A~3 - H = D^2 = B^^2 = A^^^2 = A~2^2 - I = F^ = B^3^ = A^^3^ - J = F^2 = B^3^2 = A^^3^2 - - -SPECIFYING RANGES ------------------ - -History traversing commands such as 'git log' operate on a set -of commits, not just a single commit. To these commands, -specifying a single revision with the notation described in the -previous section means the set of commits reachable from that -commit, following the commit ancestry chain. - -To exclude commits reachable from a commit, a prefix `{caret}` -notation is used. E.g. `{caret}r1 r2` means commits reachable -from `r2` but exclude the ones reachable from `r1`. - -This set operation appears so often that there is a shorthand -for it. When you have two commits `r1` and `r2` (named according -to the syntax explained in SPECIFYING REVISIONS above), you can ask -for commits that are reachable from r2 excluding those that are reachable -from r1 by `{caret}r1 r2` and it can be written as `r1..r2`. - -A similar notation `r1\...r2` is called symmetric difference -of `r1` and `r2` and is defined as -`r1 r2 --not $(git merge-base --all r1 r2)`. -It is the set of commits that are reachable from either one of -`r1` or `r2` but not from both. - -Two other shorthands for naming a set that is formed by a commit -and its parent commits exist. The `r1{caret}@` notation means all -parents of `r1`. `r1{caret}!` includes commit `r1` but excludes -all of its parents. - -Here are a handful of examples: - - D G H D - D F G H I J D F - ^G D H D - ^D B E I J F B - B...C G H D E B C - ^D B C E I J F B C - C^@ I J F - F^! D G H D F +include::revisions.txt[] PARSEOPT -------- @@ -379,10 +184,13 @@ scripts the same facilities C builtins have. It works as an option normalizer (e.g. splits single switches aggregate values), a bit like `getopt(1)` does. It takes on the standard input the specification of the options to parse and -understand, and echoes on the standard output a line suitable for `sh(1)` `eval` +understand, and echoes on the standard output a string suitable for `sh(1)` `eval` to replace the arguments with normalized ones. In case of error, it outputs usage on the standard error stream, and exits with code 129. +Note: Make sure you quote the result when passing it to `eval`. See +below for an example. + Input Format ~~~~~~~~~~~~ @@ -439,7 +247,7 @@ bar= some cool option --bar with an argument An option group Header C? option C with an optional argument" -eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?` +eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" ------------ SQ-QUOTE diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index dea4f53522..b7d9ef7e47 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -31,7 +31,7 @@ OPTIONS <commit>...:: Commits to revert. For a more complete list of ways to spell commit names, see - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + linkgit:gitrevisions[1]. Sets of commits can also be given but no traversal is done by default, see linkgit:git-rev-list[1] and its '--no-walk' option. diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index f1499bba88..81ba29669c 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -32,7 +32,7 @@ no <rev> nor <glob> is given on the command line. OPTIONS ------- <rev>:: - Arbitrary extended SHA1 expression (see linkgit:git-rev-parse[1]) + Arbitrary extended SHA1 expression (see linkgit:gitrevisions[1]) that typically names a branch head or a tag. <glob>:: diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 3f9d9c6db3..75780d7d63 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -163,9 +163,15 @@ flag, so you can do to get a listing of all tags together with what they dereference. +FILES +----- +`.git/refs/*`, `.git/packed-refs` + SEE ALSO -------- -linkgit:git-ls-remote[1] +linkgit:git-ls-remote[1], +linkgit:git-update-ref[1], +linkgit:gitrepository-layout[5] AUTHORS ------- diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 55e687a7c7..0002bfb045 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -36,7 +36,7 @@ OPTIONS <object>...:: The names of objects to show. For a more complete list of ways to spell object names, see - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + "SPECIFYING REVISIONS" section in linkgit:gitrevisions[1]. include::pretty-options.txt[] diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index fd0fe7cb56..dae190a5f2 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -53,6 +53,21 @@ See linkgit:git-config[1] for configuration variable used to change the default for when the option is not specified. +--ignore-submodules[=<when>]:: + Ignore changes to submodules when looking for changes. <when> can be + either "none", "untracked", "dirty" or "all", which is the default. + Using "none" will consider the submodule modified when it either contains + untracked or modified files or its HEAD differs from the commit recorded + in the superproject and can be used to override any settings of the + 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When + "untracked" is used submodules are not considered dirty when they only + contain untracked content (but they are still scanned for modified + content). Using "dirty" ignores all changes to the work tree of submodules, + only changes to the commits stored in the superproject are shown (this was + the behavior before 1.7.0). Using "all" hides all changes to submodules + (and suppresses the output of submodule summaries when the config option + `status.submodulesummary` is set). + -z:: Terminate entries with NUL, instead of LF. This implies the `--porcelain` output format if no other format is given. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index cdabfd29ad..1ed331c599 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,7 +9,7 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b branch] +'git submodule' [--quiet] add [-b branch] [-f|--force] [--reference <repository>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] @@ -183,6 +183,11 @@ OPTIONS --branch:: Branch of repository to add as submodule. +-f:: +--force:: + This option is only valid for the add command. + Allow adding an otherwise ignored submodule path. + --cached:: This option is only valid for status and summary commands. These commands typically use the commit found in the submodule HEAD, but diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index b09bd9761f..4b84d08fc8 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -646,6 +646,12 @@ svn.brokenSymlinkWorkaround:: revision fetched. If unset, 'git svn' assumes this option to be "true". +svn.pathnameencoding:: + This instructs git svn to recode pathnames to a given encoding. + It can be used by windows users and by those who work in non-utf8 + locales to avoid corrupted file names with non-ASCII characters. + Valid encodings are the ones supported by Perl's Encode module. + Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps options all affect the metadata generated and used by 'git svn'; they *must* be set in the configuration file before any history is imported diff --git a/Documentation/git.txt b/Documentation/git.txt index bec6348dab..93e3b07c6c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,14 +44,25 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.7.1/git.html[documentation for release 1.7.1] +* link:v1.7.2.3/git.html[documentation for release 1.7.2.3] * release notes for + link:RelNotes-1.7.2.3.txt[1.7.2.3], + link:RelNotes-1.7.2.2.txt[1.7.2.2], + link:RelNotes-1.7.2.1.txt[1.7.2.1], + link:RelNotes-1.7.2.txt[1.7.2]. + +* link:v1.7.1.2/git.html[documentation for release 1.7.1.2] + +* release notes for + link:RelNotes-1.7.1.2.txt[1.7.1.2], + link:RelNotes-1.7.1.1.txt[1.7.1.1], link:RelNotes-1.7.1.txt[1.7.1]. -* link:v1.7.0.6/git.html[documentation for release 1.7.0.6] +* link:v1.7.0.7/git.html[documentation for release 1.7.0.7] * release notes for + link:RelNotes-1.7.0.7.txt[1.7.0.7], link:RelNotes-1.7.0.6.txt[1.7.0.6], link:RelNotes-1.7.0.5.txt[1.7.0.5], link:RelNotes-1.7.0.4.txt[1.7.0.4], @@ -478,7 +489,7 @@ HEAD:: (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). For a more complete list of ways to spell object names, see -"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. +"SPECIFYING REVISIONS" section in linkgit:gitrevisions[1]. File/Directory Structure @@ -718,6 +729,13 @@ The documentation for git suite was started by David Greaves <david@dgreaves.com>, and later enhanced greatly by the contributors on the git-list <git@vger.kernel.org>. +Reporting Bugs +-------------- + +Report bugs to the Git mailing list <git@vger.kernel.org> where the +development and maintenance is primarily done. You do not have to be +subscribed to the list to send a message there. + SEE ALSO -------- linkgit:gittutorial[7], linkgit:gittutorial-2[7], diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index da553ff006..e5a27d875e 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -475,6 +475,8 @@ patterns are available: - `cpp` suitable for source code in the C and C++ languages. +- `csharp` suitable for source code in the C# language. + - `html` suitable for HTML/XHTML documents. - `java` suitable for source code in the Java language. diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f7815e96a2..ed3ddc92cb 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -971,7 +971,7 @@ commits from the master branch. The string inside brackets before the commit log message is a short name you can use to name the commit. In the above example, 'master' and 'mybranch' are branch heads. 'master^' is the first parent of 'master' -branch head. Please see linkgit:git-rev-parse[1] if you want to +branch head. Please see linkgit:gitrevisions[1] if you want to see more complex cases. [NOTE] diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 99baa24a2d..05ac1c79f7 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -69,7 +69,7 @@ frequently used options. the form "'<from>'..'<to>'" to show all revisions between '<from>' and back to '<to>'. Note, more advanced revision selection can be applied. For a more complete list of ways to spell object names, see - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + linkgit:gitrevisions[1]. <path>...:: diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 5daf750d19..bcffd95ada 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -29,6 +29,9 @@ submodule.<name>.path:: submodule.<name>.url:: Defines an url from where the submodule repository can be cloned. + This may be either an absolute URL ready to be passed to + linkgit:git-clone[1] or (if it begins with ./ or ../) a location + relative to the superproject's origin repository. submodule.<name>.update:: Defines what to do when the submodule is updated by the superproject. @@ -41,6 +44,21 @@ submodule.<name>.update:: This config option is overridden if 'git submodule update' is given the '--merge' or '--rebase' options. +submodule.<name>.ignore:: + Defines under what circumstances "git status" and the diff family show + a submodule as modified. When set to "all", it will never be considered + modified, "dirty" will ignore all changes to the submodules work tree and + takes only differences between the HEAD of the submodule and the commit + recorded in the superproject into account. "untracked" will additionally + let submodules with modified tracked files in their work tree show up. + Using "none" (the default when this option is not set) also shows + submodules that have untracked files in their work tree as changed. + If this option is also present in the submodules entry in .git/config of + the superproject, the setting there will override the one found in + .gitmodules. + Both settings can be overridden on the command line by using the + "--ignore-submodule" option. + EXAMPLES -------- diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 3cd32d6803..eb3d040783 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -16,7 +16,7 @@ You may find these things in your git repository (`.git` directory for a repository associated with your working tree, or `<project>.git` directory for a public 'bare' repository. It is also possible to have a working tree where `.git` is a plain -ascii file containing `gitdir: <path>`, i.e. the path to the +ASCII file containing `gitdir: <path>`, i.e. the path to the real git repository). objects:: diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt new file mode 100644 index 0000000000..fc4789f98e --- /dev/null +++ b/Documentation/gitrevisions.txt @@ -0,0 +1,35 @@ +gitrevisions(7) +================ + +NAME +---- +gitrevisions - specifying revisions and ranges for git + +SYNOPSIS +-------- +gitrevisions + + +DESCRIPTION +----------- + +Many Git commands take revision parameters as arguments. Depending on +the command, they denote a specific commit or, for commands which +walk the revision graph (such as linkgit:git-log[1]), all commits which can +be reached from that commit. In the latter case one can also specify a +range of revisions explicitly. + +In addition, some Git commands (such as linkgit:git-show[1]) also take +revision parameters which denote other objects than commits, e.g. blobs +("files") or trees ("directories of files"). + +include::revisions.txt[] + + +SEE ALSO +-------- +linkgit:git-rev-parse[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt index ff5c0bc27a..6fd711996a 100644 --- a/Documentation/howto/revert-a-faulty-merge.txt +++ b/Documentation/howto/revert-a-faulty-merge.txt @@ -229,7 +229,7 @@ reverting W. Mainline's history would look like this: A---B---C But if you don't actually need to change commit A, then you need some way to -recreate it as a new commit with the same changes in it. The rebase commmand's +recreate it as a new commit with the same changes in it. The rebase command's --no-ff option provides a way to do this: $ git rebase [-i] --no-ff P diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt index 8c32da6deb..093c656048 100644 --- a/Documentation/howto/revert-branch-rebase.txt +++ b/Documentation/howto/revert-branch-rebase.txt @@ -112,25 +112,19 @@ $ git tag pu-anchor pu $ git rebase master * Applying: Redo "revert" using three-way merge machinery. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: Remove git-apply-patch-script. First trying simple merge strategy to cherry-pick. Simple cherry-pick fails; trying Automatic cherry-pick. Removing Documentation/git-apply-patch-script.txt Removing git-apply-patch-script -Finished one cherry-pick. * Applying: Document "git cherry-pick" and "git revert" First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: mailinfo and applymbox updates First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: Show commits in topo order and name all commits. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: More documentation updates. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. ------------------------------------------------ The temporary tag 'pu-anchor' is me just being careful, in case 'git diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh index 34d02a2418..37e67d1a14 100755 --- a/Documentation/install-webdoc.sh +++ b/Documentation/install-webdoc.sh @@ -12,7 +12,7 @@ do then : did not match elif test -f "$T/$h" && - $DIFF -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h" + $DIFF -u -I'^Last updated ' "$T/$h" "$h" then :; # up to date else diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index d78e121c76..9b6f3899ec 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -1,5 +1,5 @@ --pretty[='<format>']:: ---format[='<format>']:: +--format='<format>':: Pretty-print the contents of the commit logs in a given format, where '<format>' can be one of 'oneline', 'short', 'medium', diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 73569c073e..cc562a057a 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -98,6 +98,15 @@ you would get an output like this: This implies the '--topo-order' option by default, but the '--date-order' option may also be specified. +ifdef::git-rev-list[] +--count:: + Print a number stating how many commits would have been + listed, and suppress all other output. When used together + with '--left-right', instead print the counts for left and + right commits, separated by a tab. +endif::git-rev-list[] + + ifndef::git-rev-list[] Diff Formatting ~~~~~~~~~~~~~~~ diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt new file mode 100644 index 0000000000..fe846f043c --- /dev/null +++ b/Documentation/revisions.txt @@ -0,0 +1,199 @@ +SPECIFYING REVISIONS +-------------------- + +A revision parameter typically, but not necessarily, names a +commit object. They use what is called an 'extended SHA1' +syntax. Here are various ways to spell object names. The +ones listed near the end of this list are to name trees and +blobs contained in a commit. + +* The full SHA1 object name (40-byte hexadecimal string), or + a substring of such that is unique within the repository. + E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both + name the same commit object if there are no other object in + your repository whose object name starts with dae86e. + +* An output from 'git describe'; i.e. a closest tag, optionally + followed by a dash and a number of commits, followed by a dash, a + `g`, and an abbreviated object name. + +* A symbolic ref name. E.g. 'master' typically means the commit + object referenced by refs/heads/master. If you + happen to have both heads/master and tags/master, you can + explicitly say 'heads/master' to tell git which one you mean. + When ambiguous, a `<name>` is disambiguated by taking the + first match in the following rules: + + . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`); + + . otherwise, `refs/<name>` if exists; + + . otherwise, `refs/tags/<name>` if exists; + + . otherwise, `refs/heads/<name>` if exists; + + . otherwise, `refs/remotes/<name>` if exists; + + . otherwise, `refs/remotes/<name>/HEAD` if exists. ++ +HEAD names the commit your changes in the working tree is based on. +FETCH_HEAD records the branch you fetched from a remote repository +with your last 'git fetch' invocation. +ORIG_HEAD is created by commands that moves your HEAD in a drastic +way, to record the position of the HEAD before their operation, so that +you can change the tip of the branch back to the state before you ran +them easily. +MERGE_HEAD records the commit(s) you are merging into your branch +when you run 'git merge'. ++ +Note that any of the `refs/*` cases above may come either from +the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. + +* A ref followed by the suffix '@' with a date specification + enclosed in a brace + pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 + second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value + of the ref at a prior point in time. This suffix may only be + used immediately following a ref name and the ref must have an + existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state + of your *local* ref at a given time; e.g., what was in your local + `master` branch last week. If you want to look at commits made during + certain times, see `--since` and `--until`. + +* A ref followed by the suffix '@' with an ordinal specification + enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify + the n-th prior value of that ref. For example 'master@\{1\}' + is the immediate prior value of 'master' while 'master@\{5\}' + is the 5th prior value of 'master'. This suffix may only be used + immediately following a ref name and the ref must have an existing + log ($GIT_DIR/logs/<ref>). + +* You can use the '@' construct with an empty ref part to get at a + 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. + +* The suffix '@\{upstream\}' to a ref (short form 'ref@\{u\}') refers to + the branch the ref is set to build on top of. Missing ref defaults + to the current branch. + +* A suffix '{caret}' to a revision parameter (e.g. 'HEAD{caret}') means the first parent of + that commit object. '{caret}<n>' means the <n>th parent (i.e. + 'rev{caret}' + is equivalent to 'rev{caret}1'). As a special rule, + 'rev{caret}0' means the commit itself and is used when 'rev' is the + object name of a tag object that refers to a commit object. + +* A suffix '{tilde}<n>' to a revision parameter means the commit + object that is the <n>th generation grand-parent of the named + commit object, following only the first parent. I.e. rev~3 is + equivalent to rev{caret}{caret}{caret} which is equivalent to + rev{caret}1{caret}1{caret}1. See below for a illustration of + the usage of this form. + +* A suffix '{caret}' followed by an object type name enclosed in + brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object + could be a tag, and dereference the tag recursively until an + object of that type is found or the object cannot be + dereferenced anymore (in which case, barf). `rev{caret}0` + introduced earlier is a short-hand for `rev{caret}\{commit\}`. + +* A suffix '{caret}' followed by an empty brace pair + (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag, + and dereference the tag recursively until a non-tag object is + found. + +* A colon, followed by a slash, followed by a text (e.g. `:/fix nasty bug`): this names + a commit whose commit message starts with the specified text. + This name returns the youngest matching commit which is + reachable from any ref. If the commit message starts with a + '!', you have to repeat that; the special sequence ':/!', + followed by something else than '!' is reserved for now. + +* A suffix ':' followed by a path (e.g. `HEAD:README`); this names the blob or tree + at the given path in the tree-ish object named by the part + before the colon. + ':path' (with an empty part before the colon, e.g. `:README`) + is a special case of the syntax described next: content + recorded in the index at the given path. + +* A colon, optionally followed by a stage number (0 to 3) and a + colon, followed by a path (e.g. `:0:README`); this names a blob object in the + index at the given path. Missing stage number (and the colon + that follows it, e.g. `:README`) names a stage 0 entry. During a merge, stage + 1 is the common ancestor, stage 2 is the target branch's version + (typically the current branch), and stage 3 is the version from + the branch being merged. + +Here is an illustration, by Jon Loeliger. Both commit nodes B +and C are parents of commit node A. Parent commits are ordered +left-to-right. + +........................................ +G H I J + \ / \ / + D E F + \ | / \ + \ | / | + \|/ | + B C + \ / + \ / + A +........................................ + + A = = A^0 + B = A^ = A^1 = A~1 + C = A^2 = A^2 + D = A^^ = A^1^1 = A~2 + E = B^2 = A^^2 + F = B^3 = A^^3 + G = A^^^ = A^1^1^1 = A~3 + H = D^2 = B^^2 = A^^^2 = A~2^2 + I = F^ = B^3^ = A^^3^ + J = F^2 = B^3^2 = A^^3^2 + + +SPECIFYING RANGES +----------------- + +History traversing commands such as 'git log' operate on a set +of commits, not just a single commit. To these commands, +specifying a single revision with the notation described in the +previous section means the set of commits reachable from that +commit, following the commit ancestry chain. + +To exclude commits reachable from a commit, a prefix `{caret}` +notation is used. E.g. `{caret}r1 r2` means commits reachable +from `r2` but exclude the ones reachable from `r1`. + +This set operation appears so often that there is a shorthand +for it. When you have two commits `r1` and `r2` (named according +to the syntax explained in SPECIFYING REVISIONS above), you can ask +for commits that are reachable from r2 excluding those that are reachable +from r1 by `{caret}r1 r2` and it can be written as `r1..r2`. + +A similar notation `r1\...r2` is called symmetric difference +of `r1` and `r2` and is defined as +`r1 r2 --not $(git merge-base --all r1 r2)`. +It is the set of commits that are reachable from either one of +`r1` or `r2` but not from both. + +Two other shorthands for naming a set that is formed by a commit +and its parent commits exist. The `r1{caret}@` notation means all +parents of `r1`. `r1{caret}!` includes commit `r1` but excludes +all of its parents. + +Here are a handful of examples: + + D G H D + D F G H I J D F + ^G D H D + ^D B E I J F B + B...C G H D E B C + ^D B C E I J F B C + C^@ I J F + F^! D G H D F diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 6d8c24bb1e..3f575bdcff 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -38,8 +38,8 @@ struct string_list list; int i; memset(&list, 0, sizeof(struct string_list)); -string_list_append("foo", &list); -string_list_append("bar", &list); +string_list_append(&list, "foo"); +string_list_append(&list, "bar"); for (i = 0; i < list.nr; i++) printf("%s\n", list.items[i].string) ---- diff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt index 55b728632c..14af37c3f1 100644 --- a/Documentation/technical/api-tree-walking.txt +++ b/Documentation/technical/api-tree-walking.txt @@ -42,6 +42,8 @@ information. * `data` can be anything the `fn` callback would want to use. +* `show_all_errors` tells whether to stop at the first error or not. + Initializing ------------ diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index fd1a593149..b15517fa06 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -119,7 +119,7 @@ both. ofs-delta --------- -Server can send, and client understand PACKv2 with delta refering to +Server can send, and client understand PACKv2 with delta referring to its base by position in pack rather than by an obj-id. That is, they can send/read OBJ_OFS_DELTA (aka type 6) in a packfile. diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 1dcd1e7f1e..289019478d 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -25,7 +25,7 @@ The ssh and git protocols additionally support ~username expansion: - git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ - {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/ -For local respositories, also supported by git natively, the following +For local repositories, also supported by git natively, the following syntaxes may be used: - /path/to/repo.git/ diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index fe6fb722da..22aee34d4a 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -397,7 +397,7 @@ is usually a shortcut for the HEAD branch in the repository "origin". For the complete list of paths which git checks for references, and 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]. +REVISIONS" section of linkgit:gitrevisions[1]. [[Updating-a-repository-With-git-fetch]] Updating a repository with git fetch @@ -568,7 +568,7 @@ We have seen several ways of naming commits already: - HEAD: refers to the head of the current branch There are many more; see the "SPECIFYING REVISIONS" section of the -linkgit:git-rev-parse[1] man page for the complete list of ways to +linkgit:gitrevisions[1] man page for the complete list of ways to name revisions. Some examples: ------------------------------------------------- @@ -909,7 +909,7 @@ commits reachable from some head but not from any tag in the repository: $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) ------------------------------------------------- -(See linkgit:git-rev-parse[1] for explanations of commit-selecting +(See linkgit:gitrevisions[1] for explanations of commit-selecting syntax such as `--not`.) [[making-a-release]] @@ -1635,7 +1635,7 @@ you've checked out. The reflogs are kept by default for 30 days, after which they may be pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn how to control this pruning, and see the "SPECIFYING REVISIONS" -section of linkgit:git-rev-parse[1] for details. +section of linkgit:gitrevisions[1] for details. Note that the reflog history is very different from normal git history. While normal history is shared by every repository that works on the |