diff options
Diffstat (limited to 'Documentation')
107 files changed, 1706 insertions, 287 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 45577117c2..57da6aadeb 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -76,11 +76,19 @@ For shell scripts specifically (not exhaustive): - We do not use Process Substitution <(list) or >(list). + - Do not write control structures on a single line with semicolon. + "then" should be on the next line for if statements, and "do" + should be on the next line for "while" and "for". + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell functions. + - We prefer a space between the function name and the parentheses. The + opening "{" should also be on the same line. + E.g.: my_function () { + - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, [::], [==], nor [..]) for portability. diff --git a/Documentation/Makefile b/Documentation/Makefile index 063fa696c9..361550422a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -24,8 +24,30 @@ SP_ARTICLES = user-manual SP_ARTICLES += howto/revert-branch-rebase SP_ARTICLES += howto/using-merge-subtree SP_ARTICLES += howto/using-signed-tag-in-pull-request +SP_ARTICLES += howto/use-git-daemon +SP_ARTICLES += howto/update-hook-example +SP_ARTICLES += howto/setup-git-server-over-http +SP_ARTICLES += howto/separating-topic-branches +SP_ARTICLES += howto/revert-a-faulty-merge +SP_ARTICLES += howto/recover-corrupted-blob-object +SP_ARTICLES += howto/rebuild-from-update-hook +SP_ARTICLES += howto/rebuild-from-update-hook +SP_ARTICLES += howto/rebase-from-internal-branch +SP_ARTICLES += howto/maintain-git API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) + +TECH_DOCS = technical/index-format +TECH_DOCS += technical/pack-format +TECH_DOCS += technical/pack-heuristics +TECH_DOCS += technical/pack-protocol +TECH_DOCS += technical/protocol-capabilities +TECH_DOCS += technical/protocol-common +TECH_DOCS += technical/racy-git +TECH_DOCS += technical/send-pack-pipeline +TECH_DOCS += technical/shallow +TECH_DOCS += technical/trivial-merge +SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) @@ -44,9 +66,10 @@ man5dir=$(mandir)/man5 man7dir=$(mandir)/man7 # DESTDIR= -ASCIIDOC=asciidoc +ASCIIDOC = asciidoc ASCIIDOC_EXTRA = MANPAGE_XSL = manpage-normal.xsl +XMLTO = xmlto XMLTO_EXTRA = INSTALL?=install RM ?= rm -f @@ -230,7 +253,7 @@ clean: $(RM) *.texi *.texi+ *.texi++ git.info gitman.info $(RM) *.pdf $(RM) howto-index.txt howto/*.html doc.dep - $(RM) technical/api-*.html technical/api-index.txt + $(RM) technical/*.html technical/api-index.txt $(RM) $(cmds_txt) *.made $(RM) manpage-base-url.xsl @@ -245,7 +268,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(QUIET_XMLTO)$(RM) $@ && \ - xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< %.xml : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ @@ -263,7 +286,7 @@ technical/api-index.txt: technical/api-index-skel.txt \ $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ -$(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt +$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt @@ -344,4 +367,7 @@ require-htmlrepo:: quick-install-html: require-htmlrepo '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) +print-man1: + @for i in $(MAN1_TXT); do echo $$i; done + .PHONY: FORCE diff --git a/Documentation/RelNotes/1.5.2.1.txt b/Documentation/RelNotes/1.5.2.1.txt index ebf20e22a7..d41984df0b 100644 --- a/Documentation/RelNotes/1.5.2.1.txt +++ b/Documentation/RelNotes/1.5.2.1.txt @@ -45,9 +45,3 @@ Fixes since v1.5.2 - git-fastimport --import-marks was broken; fixed. - A lot of documentation updates, clarifications and fixes. - --- -exec >/var/tmp/1 -O=v1.5.2-65-g996e2d6 -echo O=`git describe refs/heads/maint` -git shortlog --no-merges $O..refs/heads/maint diff --git a/Documentation/RelNotes/1.6.0.2.txt b/Documentation/RelNotes/1.6.0.2.txt index e1e24b3295..7d8fb85e1b 100644 --- a/Documentation/RelNotes/1.6.0.2.txt +++ b/Documentation/RelNotes/1.6.0.2.txt @@ -79,9 +79,3 @@ Fixes since v1.6.0.1 packfile. Also contains many documentation updates. - --- -exec >/var/tmp/1 -O=v1.6.0.1-78-g3632cfc -echo O=$(git describe maint) -git shortlog --no-merges $O..maint diff --git a/Documentation/RelNotes/1.6.1.3.txt b/Documentation/RelNotes/1.6.1.3.txt index 6f0bde156a..cd08d8174e 100644 --- a/Documentation/RelNotes/1.6.1.3.txt +++ b/Documentation/RelNotes/1.6.1.3.txt @@ -26,7 +26,3 @@ Fixes since v1.6.1.2 * RPM binary package installed the html manpages in a wrong place. Also includes minor documentation fixes and updates. - - --- -git shortlog --no-merges v1.6.1.2-33-gc789350.. diff --git a/Documentation/RelNotes/1.6.1.4.txt b/Documentation/RelNotes/1.6.1.4.txt index 0ce6316d75..ccbad794c0 100644 --- a/Documentation/RelNotes/1.6.1.4.txt +++ b/Documentation/RelNotes/1.6.1.4.txt @@ -39,6 +39,3 @@ Fixes since v1.6.1.3 This fix was first merged to 1.6.2.3. Also includes minor documentation fixes and updates. - --- -git shortlog --no-merges v1.6.1.3.. diff --git a/Documentation/RelNotes/1.6.1.txt b/Documentation/RelNotes/1.6.1.txt index adb7ccab0a..7b152a6fdc 100644 --- a/Documentation/RelNotes/1.6.1.txt +++ b/Documentation/RelNotes/1.6.1.txt @@ -278,9 +278,3 @@ release, unless otherwise noted. * "gitweb" did not mark non-ASCII characters imported from external HTML fragments correctly. - --- -exec >/var/tmp/1 -O=v1.6.1-rc3-74-gf66bc5f -echo O=$(git describe master) -git shortlog --no-merges $O..master ^maint diff --git a/Documentation/RelNotes/1.7.11.6.txt b/Documentation/RelNotes/1.7.11.6.txt new file mode 100644 index 0000000000..ba7d3c3966 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.6.txt @@ -0,0 +1,84 @@ +Git v1.7.11.6 Release Notes +=========================== + +Fixes since v1.7.11.5 +--------------------- + + * "ciabot" script (in contrib/) has been updated with extensive + documentation. + + * "git foo" errored out with "Not a directory" when the user had a + non-directory on $PATH, and worse yet it masked an alias "foo" from + running. + + * When the user exports a non-default IFS without HT, scripts that + rely on being able to parse "ls-files -s | while read a b c..." + started to fail. Protect them from such a misconfiguration. + + * When the user gives an argument that can be taken as both a + revision name and a pathname without disambiguating with "--", we + used to give a help message "Use '--' to separate". The message + has been clarified to show where that '--' goes on the command + line. + + * Documentation for the configuration file format had a confusing + example. + + * Older parts of the documentation described as if having a regular + file in .git/refs/ hierarchy were the only way to have branches and + tags, which is not true for quite some time. + + * It was generally understood that "--long-option"s to many of our + subcommands can be abbreviated to the unique prefix, but it was not + easy to find it described for new readers of the documentation set. + + * The "--topo-order", "--date-order" (and the lack of either means + the default order) options to "rev-list" and "log" family of + commands were poorly described in the documentation. + + * "git commit --amend" let the user edit the log message and then + died when the human-readable committer name was given + insufficiently by getpwent(3). + + * The exit status code from "git config" was way overspecified while + being incorrect. The implementation has been updated to give the + documented status for a case that was documented, and introduce a + new code for "all other errors". + + * The output from "git diff -B" for a file that ends with an + incomplete line did not put "\ No newline..." on a line of its own. + + * "git diff" had a confusion between taking data from a path in the + working tree and taking data from an object that happens to have + name 0{40} recorded in a tree. + + * The "--rebase" option to "git pull" can be abbreviated to "-r", + but we didn't document it. + + * When "git push" triggered the automatic gc on the receiving end, a + message from "git prune" that said it was removing cruft leaked to + the standard output, breaking the communication protocol. + + * The reflog entries left by "git rebase" and "git rebase -i" were + inconsistent (the interactive one gave an abbreviated object name). + + * "git send-email" did not unquote encoded words that appear on the + header correctly, and lost "_" from strings. + + * "git stash apply/pop" did not trigger "rerere" upon conflicts + unlike other mergy operations. + + * "git submodule <cmd> path" did not error out when the path to the + submodule was misspelt. + + * "git submodule update -f" did not update paths in the working tree + that has local changes. + (merge 01d4721 sz/submodule-force-update later to maint). + + * "gitweb" when used with PATH_INFO failed to notice directories with + SP (and other characters that need URL-style quoting) in them. + + * Fallback 'getpass' implementation made unportable use of stdio API. + + * A utility shell function test_seq has been added as a replacement + for the 'seq' utility found on some platforms. diff --git a/Documentation/RelNotes/1.7.11.7.txt b/Documentation/RelNotes/1.7.11.7.txt new file mode 100644 index 0000000000..e7e79d999b --- /dev/null +++ b/Documentation/RelNotes/1.7.11.7.txt @@ -0,0 +1,46 @@ +Git v1.7.11.7 Release Notes +=========================== + +Fixes since v1.7.11.6 +--------------------- + + * The synopsis said "checkout [-B branch]" to make it clear the + branch name is a parameter to the option, but the heading for the + option description was "-B::", not "-B branch::", making the + documentation misleading. + + * Git ships with a fall-back regexp implementation for platforms with + buggy regexp library, but it was easy for people to keep using their + platform regexp. A new test has been added to check this. + + * "git apply -p0" did not parse pathnames on "diff --git" line + correctly. This caused patches that had pathnames in no other + places to be mistakenly rejected (most notably, binary patch that + does not rename nor change mode). Textual patches, renames or mode + changes have preimage and postimage pathnames in different places + in a form that can be parsed unambiguously and did not suffer from + this problem. + + * After "gitk" showed the contents of a tag, neither "Reread + references" nor "Reload" did not update what is shown as the + contents of it, when the user overwrote the tag with "git tag -f". + + * "git for-each-ref" did not currectly support more than one --sort + option. + + * "git log .." errored out saying it is both rev range and a path + when there is no disambiguating "--" is on the command line. + Update the command line parser to interpret ".." as a path in such + a case. + + * Pushing to smart HTTP server with recent Git fails without having + the username in the URL to force authentication, if the server is + configured to allow GET anonymously, while requiring authentication + for POST. + + * "git show --format='%ci'" did not give timestamp correctly for + commits created without human readable name on "committer" line. + (merge e27ddb6 jc/maint-ident-missing-human-name later to maint). + + * "git show --quiet" ought to be a synonym for "git show -s", but + wasn't. diff --git a/Documentation/RelNotes/1.7.12.1.txt b/Documentation/RelNotes/1.7.12.1.txt new file mode 100644 index 0000000000..b8f04af19f --- /dev/null +++ b/Documentation/RelNotes/1.7.12.1.txt @@ -0,0 +1,134 @@ +Git 1.7.12.1 Release Notes +========================== + +Fixes since v1.7.12 +------------------- + + * "git apply -p0" did not parse pathnames on "diff --git" line + correctly. This caused patches that had pathnames in no other + places to be mistakenly rejected (most notably, binary patch that + does not rename nor change mode). Textual patches, renames or mode + changes have preimage and postimage pathnames in different places + in a form that can be parsed unambiguously and did not suffer from + this problem. + + * "git cherry-pick A C B" used to replay changes in A and then B and + then C if these three commits had committer timestamps in that + order, which is not what the user who said "A C B" naturally + expects. + + * "git commit --amend" let the user edit the log message and then + died when the human-readable committer name was given + insufficiently by getpwent(3). + + * Some capabilities were asked by fetch-pack even when upload-pack + did not advertise that they are available. fetch-pack has been + fixed not to do so. + + * "git diff" had a confusion between taking data from a path in the + working tree and taking data from an object that happens to have + name 0{40} recorded in a tree. + + * "git for-each-ref" did not correctly support more than one --sort + option. + + * "git log .." errored out saying it is both rev range and a path + when there is no disambiguating "--" is on the command line. + Update the command line parser to interpret ".." as a path in such + a case. + + * The "--topo-order", "--date-order" (and the lack of either means + the default order) options to "rev-list" and "log" family of + commands were poorly described in the documentation. + + * "git prune" without "-v" used to warn about leftover temporary + files (which is an indication of an earlier aborted operation). + + * Pushing to smart HTTP server with recent Git fails without having + the username in the URL to force authentication, if the server is + configured to allow GET anonymously, while requiring authentication + for POST. + + * The reflog entries left by "git rebase" and "git rebase -i" were + inconsistent (the interactive one gave an abbreviated object name). + + * When "git push" triggered the automatic gc on the receiving end, a + message from "git prune" that said it was removing cruft leaked to + the standard output, breaking the communication protocol. + + * "git show --quiet" ought to be a synonym for "git show -s", but + wasn't. + + * "git show --format='%ci'" did not give timestamp correctly for + commits created without human readable name on "committer" line. + + * "git send-email" did not unquote encoded words that appear on the + header correctly, and lost "_" from strings. + + * The interactive prompt "git send-email" gives was error prone. It + asked "What e-mail address do you want to use?" with the address it + guessed (correctly) the user would want to use in its prompt, + tempting the user to say "y". But the response was taken as "No, + please use 'y' as the e-mail address instead", which is most + certainly not what the user meant. + + * "gitweb" when used with PATH_INFO failed to notice directories with + SP (and other characters that need URL-style quoting) in them. + + * When the user gives an argument that can be taken as both a + revision name and a pathname without disambiguating with "--", we + used to give a help message "Use '--' to separate". The message + has been clarified to show where that '--' goes on the command + line. + + * When the user exports a non-default IFS without HT, scripts that + rely on being able to parse "ls-files -s | while read a b c..." + started to fail. Protect them from such a misconfiguration. + + * The attribute system may be asked for a path that itself or its + leading directories no longer exists in the working tree, and it is + fine if we cannot open .gitattribute file in such a case. Failure + to open per-directory .gitattributes with error status other than + ENOENT and ENOTDIR should be diagnosed, but it wasn't. + + * After "gitk" showed the contents of a tag, neither "Reread + references" nor "Reload" did not update what is shown as the + contents of it, when the user overwrote the tag with "git tag -f". + + * "ciabot" script (in contrib/) has been updated with extensive + documentation. + + * "git-jump" script (in contrib/) did not work well when + diff.noprefix or diff.mnemonicprefix is in effect. + + * Older parts of the documentation described as if having a regular + file in .git/refs/ hierarchy were the only way to have branches and + tags, which is not true for quite some time. + + * A utility shell function test_seq has been added as a replacement + for the 'seq' utility found on some platforms. + + * Compatibility wrapper to learn the maximum number of file + descriptors we can open around sysconf(_SC_OPEN_MAX) and + getrlimit(RLIMIT_NO_FILE) has been introduced for portability. + + * We used curl_easy_strerror() without checking version of cURL, + breaking the build for versions before curl 7.12.0. + + * Code to work around MacOS X UTF-8 gotcha has been cleaned up. + + * Fallback 'getpass' implementation made unportable use of stdio API. + + * The "--rebase" option to "git pull" can be abbreviated to "-r", + but we didn't document it. + + * It was generally understood that "--long-option"s to many of our + subcommands can be abbreviated to the unique prefix, but it was not + easy to find it described for new readers of the documentation set. + + * The synopsis said "checkout [-B branch]" to make it clear the + branch name is a parameter to the option, but the heading for the + option description was "-B::", not "-B branch::", making the + documentation misleading. + +Also contains numerous documentation updates. diff --git a/Documentation/RelNotes/1.7.12.2.txt b/Documentation/RelNotes/1.7.12.2.txt new file mode 100644 index 0000000000..69255745e6 --- /dev/null +++ b/Documentation/RelNotes/1.7.12.2.txt @@ -0,0 +1,40 @@ +Git 1.7.12.2 Release Notes +========================== + +Fixes since v1.7.12.1 +--------------------- + + * When "git am" is fed an input that has multiple "Content-type: ..." + header, it did not grok charset= attribute correctly. + + * Even during a conflicted merge, "git blame $path" always meant to + blame uncommitted changes to the "working tree" version; make it + more useful by showing cleanly merged parts as coming from the other + branch that is being merged. + + * "git blame MAKEFILE" run in a history that has "Makefile" but not + "MAKEFILE" should say "No such file MAKEFILE in HEAD", but got + confused on a case insensitive filesystem and failed to do so. + + * "git fetch --all", when passed "--no-tags", did not honor the + "--no-tags" option while fetching from individual remotes (the same + issue existed with "--tags", but combination "--all --tags" makes + much less sense than "--all --no-tags"). + + * "git log/diff/format-patch --stat" showed the "N line(s) added" + comment in user's locale and caused careless submitters to send + patches with such a line in them to projects whose project language + is not their language, mildly irritating others. Localization to + the line has been disabled for now. + + * "git log --all-match --grep=A --grep=B" ought to show commits that + mention both A and B, but when these three options are used with + --author or --committer, it showed commits that mention either A or + B (or both) instead. + + * The subcommand to remove the definition of a remote in "git remote" + was named "rm" even though all other subcommands were spelled out. + Introduce "git remote remove" to remove confusion, and keep "rm" as + a backward compatible synonym. + +Also contains a handful of documentation updates. diff --git a/Documentation/RelNotes/1.7.12.3.txt b/Documentation/RelNotes/1.7.12.3.txt new file mode 100644 index 0000000000..ecda427a35 --- /dev/null +++ b/Documentation/RelNotes/1.7.12.3.txt @@ -0,0 +1,34 @@ +Git 1.7.12.3 Release Notes +========================== + +Fixes since v1.7.12.2 +--------------------- + + * "git am" mishandled a patch attached as application/octet-stream + (e.g. not text/*); Content-Transfer-Encoding (e.g. base64) was not + honored correctly. + + * It was unclear in the documentation for "git blame" that it is + unnecessary for users to use the "--follow" option. + + * A repository created with "git clone --single" had its fetch + refspecs set up just like a clone without "--single", leading the + subsequent "git fetch" to slurp all the other branches, defeating + the whole point of specifying "only this branch". + + * "git fetch" over http had an old workaround for an unlikely server + misconfiguration; it turns out that this hurts debuggability of the + configuration in general, and has been reverted. + + * "git fetch" over http advertised that it supports "deflate", which + is much less common, and did not advertise the more common "gzip" on + its Accept-Encoding header. + + * "git receive-pack" (the counterpart to "git push") did not give + progress output while processing objects it received to the puser + when run over the smart-http protocol. + + * "git status" honored the ignore=dirty settings in .gitmodules but + "git commit" didn't. + +Also contains a handful of documentation updates. diff --git a/Documentation/RelNotes/1.7.12.4.txt b/Documentation/RelNotes/1.7.12.4.txt new file mode 100644 index 0000000000..c6da3cc939 --- /dev/null +++ b/Documentation/RelNotes/1.7.12.4.txt @@ -0,0 +1,23 @@ +Git 1.7.12.4 Release Notes +========================== + +Fixes since v1.7.12.3 +--------------------- + + * "git fetch" over the dumb-http revision walker could segfault when + curl's multi interface was used. + + * It was possible to give specific paths for "asciidoc" and other + tools in the documentation toolchain, but not for "xmlto". + + * "gitweb" did not give the correct committer timezone in its feed + output due to a typo. + + * The "-Xours" (and similarly -Xtheirs) backend option to "git + merge -s recursive" was ignored for binary files. Now it is + honored. + + * The "binary" synthetic attribute made "diff" to treat the path as + binary, but not "merge". + +Also contains many documentation updates. diff --git a/Documentation/RelNotes/1.8.0.1.txt b/Documentation/RelNotes/1.8.0.1.txt new file mode 100644 index 0000000000..cda8b3e7a0 --- /dev/null +++ b/Documentation/RelNotes/1.8.0.1.txt @@ -0,0 +1,52 @@ +Git v1.8.0.1 Release Notes +========================== + +Fixes since v1.8.0 +------------------ + + * The configuration parser had an unnecessary hardcoded limit on + variable names that was not checked consistently. + + * The "say" function in the test scaffolding incorrectly allowed + "echo" to interpret "\a" as if it were a C-string asking for a + BEL output. + + * "git mergetool" feeds /dev/null as a common ancestor when dealing + with an add/add conflict, but p4merge backend cannot handle + it. Work it around by passing a temporary empty file. + + * "git log -F -E --grep='<ere>'" failed to use the given <ere> + pattern as extended regular expression, and instead looked for the + string literally. + + * "git grep -e pattern <tree>" asked the attribute system to read + "<tree>:.gitattributes" file in the working tree, which was + nonsense. + + * A symbolic ref refs/heads/SYM was not correctly removed with "git + branch -d SYM"; the command removed the ref pointed by SYM + instead. + + * Earlier we fixed documentation to hyphenate "remote-tracking branch" + to clarify that these are not a remote entity, but unhyphenated + spelling snuck in to a few places since then. + + * "git pull --rebase" run while the HEAD is detached tried to find + the upstream branch of the detached HEAD (which by definition + does not exist) and emitted unnecessary error messages. + + * The refs/replace hierarchy was not mentioned in the + repository-layout docs. + + * Sometimes curl_multi_timeout() function suggested a wrong timeout + value when there is no file descriptors to wait on and the http + transport ended up sleeping for minutes in select(2) system call. + A workaround has been added for this. + + * Various rfc2047 quoting issues around a non-ASCII name on the + From: line in the output from format-patch have been corrected. + + * "git diff -G<pattern>" did not honor textconv filter when looking + for changes. + +Also contains other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.8.0.txt b/Documentation/RelNotes/1.8.0.txt new file mode 100644 index 0000000000..43883c14f0 --- /dev/null +++ b/Documentation/RelNotes/1.8.0.txt @@ -0,0 +1,267 @@ +Git v1.8.0 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the next major release (not *this* one), we will change the +behavior of the "git push" command. + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). We will use the "simple" semantics that pushes the +current branch to the branch with the same name, only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this, and +"git push" will warn about the upcoming change until you set this +variable in this release. + +"git branch --set-upstream" is deprecated and may be removed in a +relatively distant future. "git branch [-u|--set-upstream-to]" has +been introduced with a saner order of arguments. + + +Updates since v1.7.12 +--------------------- + +UI, Workflows & Features + + * A credential helper for Win32 to allow access to the keychain of + the logged-in user has been added. + + * An initial port to HP NonStop. + + * A credential helper to allow access to the Gnome keyring has been + added. + + * When "git am" sanitizes the "Subject:" line, we strip the prefix from + "Re: subject" and also from a less common "re: subject", but left + the even less common "RE: subject" intact. Now we strip that too. + + * It was tempting to say "git branch --set-upstream origin/master", + but that tells Git to arrange the local branch "origin/master" to + integrate with the currently checked out branch, which is highly + unlikely what the user meant. The option is deprecated; use the + new "--set-upstream-to" (with a short-and-sweet "-u") option + instead. + + * "git cherry-pick" learned the "--allow-empty-message" option to + allow it to replay a commit without any log message. + + * After "git cherry-pick -s" gave control back to the user asking + help to resolve conflicts, concluding "git commit" used to need to + be run with "-s" if the user wants to sign it off; now the command + leaves the sign-off line in the log template. + + * "git daemon" learned the "--access-hook" option to allow an + external command to decline service based on the client address, + repository path, etc. + + * "git difftool --dir-diff" learned to use symbolic links to prepare + a temporary copy of the working tree when available. + + * "git grep" learned to use a non-standard pattern type by default if + a configuration variable tells it to. + + * Accumulated updates to "git gui" has been merged. + + * "git log -g" learned the "--grep-reflog=<pattern>" option to limit + its output to commits with a reflog message that matches the given + pattern. + + * "git merge-base" learned the "--is-ancestor A B" option to tell if A is + an ancestor of B. The result is indicated by its exit status code. + + * "git mergetool" now allows users to override the actual command used + with the mergetool.$name.cmd configuration variable even for built-in + mergetool backends. + + * "git rebase -i" learned the "--edit-todo" option to open an editor + to edit the instruction sheet. + + +Foreign Interface + + * "git svn" has been updated to work with SVN 1.7. + + * "git p4" learned the "--conflicts" option to specify what to do when + encountering a conflict during "p4 submit". + + +Performance, Internal Implementation, etc. + + * Git ships with a fall-back regexp implementation for platforms with + buggy regexp library, but it was easy for people to keep using their + platform regexp by mistake. A new test has been added to check this. + + * The "check-docs" build target has been updated and greatly + simplified. + + * The test suite is run under MALLOC_CHECK_ when running with a glibc + that supports the feature. + + * The documentation in the TeXinfo format was using indented output + for materials meant to be examples that are better typeset in + monospace. + + * Compatibility wrapper around some mkdir(2) implementations that + reject parameters with trailing slash has been introduced. + + * Compatibility wrapper for systems that lack usable setitimer() has + been added. + + * The option parsing of "git checkout" had error checking, dwim and + defaulting missing options, all mixed in the code, and issuing an + appropriate error message with useful context was getting harder. + The code has been reorganized to allow giving a proper diagnosis + when the user says "git checkout -b -t foo bar" (e.g. "-t" is not a + good name for a branch). + + * Many internal uses of a "git merge-base" equivalent were only to see + if one commit fast-forwards to the other, which did not need the + full set of merge bases to be computed. They have been updated to + use less expensive checks. + + * The heuristics to detect and silently convert latin1 to utf8 when + we were told to use utf-8 in the log message has been transplanted + from "mailinfo" to "commit" and "commit-tree". + + * Messages given by "git <subcommand> -h" from many subcommands have + been marked for translation. + + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.12 +------------------- + +Unless otherwise noted, all the fixes since v1.7.12 in the +maintenance track are contained in this release (see release notes +to them for details). + + * The attribute system may be asked for a path that itself or its + leading directories no longer exists in the working tree, and it is + fine if we cannot open .gitattribute file in such a case. Failure + to open per-directory .gitattributes with error status other than + ENOENT and ENOTDIR should be diagnosed, but it wasn't. + + * When looking for $HOME/.gitconfig etc., it is OK if we cannot read + them because they do not exist, but we did not diagnose existing + files that we cannot read. + + * When "git am" is fed an input that has multiple "Content-type: ..." + header, it did not grok charset= attribute correctly. + + * "git am" mishandled a patch attached as application/octet-stream + (e.g. not text/*); Content-Transfer-Encoding (e.g. base64) was not + honored correctly. + + * "git blame MAKEFILE" run in a history that has "Makefile" but not + "MAKEFILE" should say "No such file MAKEFILE in HEAD", but got + confused on a case insensitive filesystem and failed to do so. + + * Even during a conflicted merge, "git blame $path" always meant to + blame uncommitted changes to the "working tree" version; make it + more useful by showing cleanly merged parts as coming from the other + branch that is being merged. + + * It was unclear in the documentation for "git blame" that it is + unnecessary for users to use the "--follow" option. + + * Output from "git branch -v" contains "(no branch)" that could be + localized, but the code to align it along with the names of + branches was counting in bytes, not in display columns. + + * "git cherry-pick A C B" used to replay changes in A and then B and + then C if these three commits had committer timestamps in that + order, which is not what the user who said "A C B" naturally + expects. + + * A repository created with "git clone --single" had its fetch + refspecs set up just like a clone without "--single", leading the + subsequent "git fetch" to slurp all the other branches, defeating + the whole point of specifying "only this branch". + + * Documentation talked about "first line of commit log" when it meant + the title of the commit. The description was clarified by defining + how the title is decided and rewording the casual mention of "first + line" to "title". + + * "git cvsimport" did not thoroughly cleanse tag names that it + inferred from the names of the tags it obtained from CVS, which + caused "git tag" to barf and stop the import in the middle. + + * Earlier we made the diffstat summary line that shows the number of + lines added/deleted localizable, but it was found irritating having + to see them in various languages on a list whose discussion language + is English, and this change has been reverted. + + * "git fetch --all", when passed "--no-tags", did not honor the + "--no-tags" option while fetching from individual remotes (the same + issue existed with "--tags", but the combination "--all --tags" makes + much less sense than "--all --no-tags"). + + * "git fetch" over http had an old workaround for an unlikely server + misconfiguration; it turns out that this hurts debuggability of the + configuration in general, and has been reverted. + + * "git fetch" over http advertised that it supports "deflate", which + is much less common, and did not advertise the more common "gzip" on + its Accept-Encoding header. + + * "git fetch" over the dumb-http revision walker could segfault when + curl's multi interface was used. + + * "git gc --auto" notified the user that auto-packing has triggered + even under the "--quiet" option. + + * After "gitk" showed the contents of a tag, neither "Reread + references" nor "Reload" updated what is shown as the + contents of it when the user overwrote the tag with "git tag -f". + + * "git log --all-match --grep=A --grep=B" ought to show commits that + mention both A and B, but when these three options are used with + --author or --committer, it showed commits that mention either A or + B (or both) instead. + + * The "-Xours" backend option to "git merge -s recursive" was ignored + for binary files. + + * "git p4", when "--use-client-spec" and "--detect-branches" are used + together, misdetected branches. + + * "git receive-pack" (the counterpart to "git push") did not give + progress output while processing objects it received to the puser + when run over the smart-http protocol. + + * When you misspell the command name you give to the "exec" action in + the "git rebase -i" instruction sheet you were told that 'rebase' is not a + git subcommand from "git rebase --continue". + + * The subcommand in "git remote" to remove a defined remote was + "rm" and the command did not take a fully-spelled "remove". + + * The interactive prompt that "git send-email" gives was error prone. It + asked "What e-mail address do you want to use?" with the address it + guessed (correctly) the user would want to use in its prompt, + tempting the user to say "y". But the response was taken as "No, + please use 'y' as the e-mail address instead", which is most + certainly not what the user meant. + + * "git show --format='%ci'" did not give the timestamp correctly for + commits created without human readable name on the "committer" line. + + * "git show --quiet" ought to be a synonym for "git show -s", but + wasn't. + + * "git submodule frotz" was not diagnosed as "frotz" being an unknown + subcommand to "git submodule"; the user instead got a complaint + that "git submodule status" was run with an unknown path "frotz". + + * "git status" honored the ignore=dirty settings in .gitmodules but + "git commit" didn't. + + * "gitweb" did not give the correct committer timezone in its feed + output due to a typo. diff --git a/Documentation/RelNotes/1.8.1.txt b/Documentation/RelNotes/1.8.1.txt new file mode 100644 index 0000000000..107e5f3d50 --- /dev/null +++ b/Documentation/RelNotes/1.8.1.txt @@ -0,0 +1,151 @@ +Git v1.8.1 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the next major release (not *this* one), we will change the +behavior of the "git push" command. + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). We will use the "simple" semantics that pushes the +current branch to the branch with the same name, only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this, and +"git push" will warn about the upcoming change until you set this +variable in this release. + +"git branch --set-upstream" is deprecated and may be removed in a +relatively distant future. "git branch [-u|--set-upstream-to]" has +been introduced with a saner order of arguments. + + +Updates since v1.8.0 +-------------------- + +UI, Workflows & Features + + * We used to have a workaround for a bug in ancient "less" that + causes it to exit without any output when the terminal is resized. + The bug has been fixed in "less" version 406 (June 2007), and the + workaround has been removed in this release. + + * A new configuration variable "diff.context" can be used to + give the default number of context lines in the patch output, to + override the hardcoded default of 3 lines. + + * "git format-patch" leraned the "--notes=<ref>" option to give + notes for the commit after the three-dash lines in its output. + + * "git log --grep=<pcre>" learned to honor the "grep.patterntype" + configuration set to "perl". + + * "git rm $submodule" used to punt on removing a submodule working + tree to avoid losing the repository embedded in it. Because + recent git uses a mechanism to separate the submodule repository + from the submodule working tree, "git rm" learned to detect this + case and removes the submodule working tree when it is safe. + + * "git submodule add" learned to add a new submodule at the same + path as the path where an unrelated submodule was bound to in an + existing revision via the "--name" option. + + * "git submodule sync" learned the "--recursive" option. + + * "git symbolic-ref" learned the "-d $symref" option to delete the + named symbolic ref, which is more intuitive way to spell it than + "update-ref -d --no-deref". + + +Foreign Interface + + * "git cvsimport" can be told to record timezones (other than GMT) + per-author via its author info file. + + * The remote helper interface to interact with subversion + repositories (one of the GSoC 2012 projects) has been merged. + + +Performance, Internal Implementation, etc. + + * The logic to generate the initial advertisement from + "upload-pack" (what is invoked by "git fetch" on the other side + of the connection) to list what refs are available in the + repository has been optimized. + + * The logic to find set of attributes that match a given path has + been optimized. + + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.8.0 +------------------ + +Unless otherwise noted, all the fixes since v1.8.0 in the maintenance +track are contained in this release (see release notes to them for +details). + + * The configuration parser had an unnecessary hardcoded limit on + variable names that was not checked consistently. + (merge 0971e99 bw/config-lift-variable-name-length-limit later to maint). + + * The "say" function in the test scaffolding incorrectly allowed + "echo" to interpret "\a" as if it were a C-string asking for a + BEL output. + (merge 7bc0911 jc/test-say-color-avoid-echo-escape later to maint). + + * "git mergetool" feeds /dev/null as a common ancestor when dealing + with an add/add conflict, but p4merge backend cannot handle + it. Work it around by passing a temporary empty file. + (merge 3facc60 da/mergetools-p4 later to maint). + + * "git log -F -E --grep='<ere>'" failed to use the given <ere> + pattern as extended regular expression, and instead looked for the + string literally. + (merge 727b6fc jc/grep-pcre-loose-ends~1 later to maint). + + * "git grep -e pattern <tree>" asked the attribute system to read + "<tree>:.gitattributes" file in the working tree, which was + nonsense. + (merge 55c6168 nd/grep-true-path later to maint). + + * A symbolic ref refs/heads/SYM was not correctly removed with "git + branch -d SYM"; the command removed the ref pointed by SYM + instead. + (merge 13baa9f rs/branch-del-symref later to maint). + + * Update "remote tracking branch" in the documentation to + "remote-tracking branch". + (merge a6d3bde mm/maint-doc-remote-tracking later to maint). + + * "git pull --rebase" run while the HEAD is detached tried to find + the upstream branch of the detached HEAD (which by definition + does not exist) and emitted unnecessary error messages. + (merge e980765 ph/pull-rebase-detached later to maint). + + * The refs/replace hierarchy was not mentioned in the + repository-layout docs. + (merge 11fbe18 po/maint-refs-replace-docs later to maint). + + * Various rfc2047 quoting issues around a non-ASCII name on the + From: line in the output from format-patch has been corrected. + (merge 25dc8da js/format-2047 later to maint). + + * Sometimes curl_multi_timeout() function suggested a wrong timeout + value when there is no file descriptors to wait on and the http + transport ended up sleeping for minutes in select(2) system call. + A workaround has been added for this. + (merge 7202b81 sz/maint-curl-multi-timeout later to maint). + + * For a fetch refspec (or the result of applying wildcard on one), + we always want the RHS to map to something inside "refs/" + hierarchy, but the logic to check it was not exactly right. + (merge 5c08c1f jc/maint-fetch-tighten-refname-check later to maint). + + * "git diff -G<pattern>" did not honor textconv filter when looking + for changes. + (merge b1c2f57 jk/maint-diff-grep-textconv later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0dbf2c9843..3d8b2fe4d1 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -179,7 +179,8 @@ message starts, you can put a "From: " line to name that person. You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" -material between the three dash lines and the diffstat. +material between the three dash lines and the diffstat. Git-notes +can also be inserted using the `--notes` option. Do not attach the patch as a MIME attachment, compressed or not. Do not let your e-mail client send quoted-printable. Do not let diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index a26d245ab4..1273a85c8a 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -36,7 +36,7 @@ ifndef::git-asciidoc-no-roff[] # v1.72 breaks with this because it replaces dots not in roff requests. [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> ifdef::doctype-manpage[] .ft C endif::doctype-manpage[] @@ -53,7 +53,7 @@ ifdef::doctype-manpage[] # The following two small workarounds insert a simple paragraph after screen [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> | </literallayout><simpara></simpara> {title#}</example> diff --git a/Documentation/config.txt b/Documentation/config.txt index a95e5a4ac9..9a0544cf1f 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -538,14 +538,14 @@ core.pager:: `LESS` variable to some other value. Alternately, these settings can be overridden on a project or global basis by setting the `core.pager` option. - Setting `core.pager` has no affect on the `LESS` + Setting `core.pager` has no effect on the `LESS` environment variable behaviour above, so if you want to override git's default settings this way, you need to be explicit. For example, to disable the S option in a backward compatible manner, set `core.pager` - to `less -+$LESS -FRX`. This will be passed to the - shell by git, which will translate the final command to - `LESS=FRSX less -+FRSX -FRX`. + to `less -+S`. This will be passed to the shell by + git, which will translate the final command to + `LESS=FRSX less -+S`. core.whitespace:: A comma separated list of common whitespace problems to @@ -559,8 +559,9 @@ core.whitespace:: * `space-before-tab` treats a space character that appears immediately before a tab character in the initial indent part of the line as an error (enabled by default). -* `indent-with-non-tab` treats a line that is indented with 8 or more - space characters as an error (not enabled by default). +* `indent-with-non-tab` treats a line that is indented with space + characters instead of the equivalent tabs as an error (not enabled by + default). * `tab-in-indent` treats a tab character in the initial indent part of the line as an error (not enabled by default). * `blank-at-eof` treats blank lines added at the end of file as an error @@ -1210,8 +1211,16 @@ gitweb.snapshot:: grep.lineNumber:: If set to true, enable '-n' option by default. +grep.patternType:: + Set the default matching behavior. Using a value of 'basic', 'extended', + 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', + '--fixed-strings', or '--perl-regexp' option accordingly, while the + value 'default' will return to the default matching behavior. + grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. + If set to true, enable '--extended-regexp' option by default. This + option is ignored when the 'grep.patternType' option is set to a value + other than 'default'. gpg.program:: Use this custom program instead of "gpg" found on $PATH when diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 67a90a828c..75ab8a51ca 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -56,6 +56,10 @@ diff.statGraphWidth:: Limit the width of the graph part in --stat output. If set, applies to all commands generating --stat output except format-patch. +diff.context:: + Generate diffs with <n> lines of context instead of the default of + 3. This value is overridden by the -U option. + diff.external:: If this config variable is set, diff generation is not performed using the internal diff machinery, but using the diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 39d326abc6..b4d6476ac8 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -10,7 +10,8 @@ --depth=<depth>:: Deepen the history of a 'shallow' repository created by `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) - by the specified number of commits. + to the specified number of commits from the tip of each remote + branch history. Tags for the deepened commits are not fetched. ifndef::git-pull[] --dry-run:: diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 9c1d395722..fd9e36b99f 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -155,7 +155,7 @@ Configuration The optional configuration variable `core.excludesfile` indicates a path to a file containing patterns of file names to exclude from git-add, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to -those in info/exclude. See linkgit:gitrepository-layout[5]. +those in info/exclude. See linkgit:gitignore[5]. EXAMPLES diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 8a2ba37904..ec4497e098 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -257,7 +257,7 @@ Date: Sat May 3 11:59:44 2008 -0700 Linux 2.6.26-rc1 -:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M Makefile +:100644 100644 5cf82581... 4492984e... M Makefile ------------- At this point we can see what the commit does, check it out (if it's @@ -331,7 +331,7 @@ Date: Sat May 3 11:59:44 2008 -0700 Linux 2.6.26-rc1 -:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M Makefile +:100644 100644 5cf82581... 4492984e... M Makefile bisect run success ------------- diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 7ee923629e..e44173f66a 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -20,6 +20,12 @@ last modified the line. Optionally, start annotating from the given revision. The command can also limit the range of lines annotated. +The origin of lines is automatically followed across whole-file +renames (currently there is no option to turn the rename-following +off). To follow lines moved from one file to another, or to follow +lines that were copied and pasted from another file, etc., see the +`-C` and `-M` options. + The report does not tell you anything about lines which have been deleted or replaced; you need to use a tool such as 'git diff' or the "pickaxe" interface briefly mentioned in the following paragraph. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 47235bea04..45a225e0aa 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -13,6 +13,8 @@ SYNOPSIS [--column[=<options>] | --no-column] [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] +'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] +'git branch' --unset-upstream [<branchname>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> 'git branch' (-d | -D) [-r] <branchname>... 'git branch' --edit-description [<branchname>] @@ -48,7 +50,7 @@ branch so that 'git pull' will appropriately merge from the remote-tracking branch. This behavior may be changed via the global `branch.autosetupmerge` configuration flag. That setting can be overridden by using the `--track` and `--no-track` options, and -changed later using `git branch --set-upstream`. +changed later using `git branch --set-upstream-to`. With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match @@ -129,11 +131,13 @@ This option is only applicable in non-verbose mode. use `git branch --list <pattern>` to list matching branches. -v:: +-vv:: --verbose:: When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print - the name of the upstream branch, as well. + the name of the upstream branch, as well (see also `git remote + show <remote>`). -q:: --quiet:: @@ -173,6 +177,16 @@ start-point is either a local or remote-tracking branch. like `--track` would when creating the branch, except that where branch points to is not changed. +-u <upstream>:: +--set-upstream-to=<upstream>:: + Set up <branchname>'s tracking information so <upstream> is + considered <branchname>'s upstream branch. If no <branchname> + is specified, then it defaults to the current branch. + +--unset-upstream:: + Remove the upstream information for <branchname>. If no branch + is specified it defaults to the current branch. + --edit-description:: Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. `request-pull`). diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 63a251612a..7958a47006 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -84,11 +84,11 @@ entries; instead, unmerged entries are ignored. When checking out paths from the index, check out stage #2 ('ours') or #3 ('theirs') for unmerged paths. --b:: +-b <new_branch>:: Create a new branch named <new_branch> and start it at <start_point>; see linkgit:git-branch[1] for details. --B:: +-B <new_branch>:: 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 @@ -124,7 +124,7 @@ explicitly give a name with '-b' in such a case. <commit> is not a branch name. See the "DETACHED HEAD" section below for details. ---orphan:: +--orphan <new_branch>:: Create a new 'orphan' branch, named <new_branch>, started from <start_point> and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new @@ -367,6 +367,18 @@ $ git checkout hello.c <3> <2> take a file out of another commit <3> restore hello.c from the index + +If you want to check out _all_ C source files out of the index, +you can say ++ +------------ +$ git checkout -- '*.c' +------------ ++ +Note the quotes around `*.c`. The file `hello.c` will also be +checked out, even though it is no longer in the working tree, +because the file globbing is used to match entries in the index +(not in the working tree by the shell). ++ If you have an unfortunate branch that is named `hello.c`, this step would be confused as an instruction to switch to that branch. You should instead write: diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 0e170a51ca..c205d2363e 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -118,6 +118,11 @@ effect to your index in a row. previous commit are dropped. To force the inclusion of those commits use `--keep-redundant-commits`. +--allow-empty-message:: + By default, cherry-picking a commit with an empty message will fail. + This option overrides that behaviour, allowing commits with empty + messages to be cherry picked. + --keep-redundant-commits:: If a commit being cherry picked duplicates a commit already in the current history, it will become empty. By default these diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 79fb984144..9f42c0d0e6 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -63,6 +63,10 @@ OPTIONS Remove only files ignored by git. This may be useful to rebuild everything from scratch, but keep manually created files. +SEE ALSO +-------- +linkgit:gitignore[5] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index c1ddd4c2cc..7fefdb0384 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -29,7 +29,8 @@ currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without arguments will in addition merge the remote master branch into the -current master branch, if any. +current master branch, if any (this is untrue when "--single-branch" +is given; see below). This default configuration is achieved by creating references to the remote branch heads under `refs/remotes/origin` and @@ -152,9 +153,10 @@ objects from the source repository into a pack in the cloned repository. -b <name>:: Instead of pointing the newly created HEAD to the branch pointed to by the cloned repository's HEAD, point to `<name>` branch - instead. `--branch` can also take tags and treat them like - detached HEAD. In a non-bare repository, this is the branch - that will be checked out. + instead. In a non-bare repository, this is the branch that will + be checked out. + `--branch` can also take tags and detaches the HEAD at that commit + in the resulting repository. --upload-pack <upload-pack>:: -u <upload-pack>:: @@ -193,6 +195,11 @@ objects from the source repository into a pack in the cloned repository. clone with the `--depth` option, this is the default, unless `--no-single-branch` is given to fetch the histories near the tips of all branches. + Further fetches into the resulting repository will only update the + remote-tracking branch for the branch this option was used for the + initial cloning. If the HEAD at the remote did not point at any + branch when `--single-branch` clone was made, no remote-tracking + branch is created. --recursive:: --recurse-submodules:: diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 4622297ec9..7bdb039d5e 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -13,7 +13,7 @@ SYNOPSIS [-F <file> | -m <msg>] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] [--status | --no-status] - [-i | -o] [--] [<file>...] + [-i | -o] [-S[<keyid>]] [--] [<file>...] DESCRIPTION ----------- @@ -109,6 +109,10 @@ OPTIONS format. See linkgit:git-status[1] for details. Implies `--dry-run`. +--long:: + When doing a dry-run, give the output in a the long-format. + Implies `--dry-run`. + -z:: --null:: When showing `short` or `porcelain` status output, terminate @@ -184,6 +188,11 @@ OPTIONS commit log message unmodified. This option lets you further edit the message taken from these sources. +--no-edit:: + Use the selected commit message without launching an editor. + For example, `git commit --amend --no-edit` amends a commit + without changing its commit message. + --amend:: Used to amend the tip of the current branch. Prepare the tree object you would want to replace the latest commit as usual @@ -193,10 +202,6 @@ OPTIONS current tip -- if it was a merge, it will have the parents of the current tip as parents -- so the current top commit is discarded. - ---no-post-rewrite:: - Bypass the post-rewrite hook. - + -- It is a rough equivalent for: @@ -213,6 +218,9 @@ You should understand the implications of rewriting history if you amend a commit that has already been published. (See the "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) +--no-post-rewrite:: + Bypass the post-rewrite hook. + -i:: --include:: Before making a commit out of staged contents so far, @@ -276,6 +284,10 @@ configuration variable documented in linkgit:git-config[1]. commit message template when using an editor to prepare the default commit message. +-S[<keyid>]:: +--gpg-sign[=<keyid>]:: + GPG-sign commit. + \--:: Do not interpret any more arguments as options. @@ -389,8 +401,10 @@ DISCUSSION Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. -Tools that turn commits into email, for example, use the first line -on the Subject: line and the rest of the commit in the body. +The text up to the first blank line in a commit message is treated +as the commit title, and that title is used throughout git. +For example, linkgit:git-format-patch[1] turns a commit into email, and it uses +the title on the Subject line and the rest of the commit in the body. include::i18n.txt[] diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 2d6ef32a08..eaea079165 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -54,16 +54,16 @@ configuration file by default, and options '--system', '--global', '--file <filename>' can be used to tell the command to write to that location (you can say '--local' but that is the default). -This command will fail (with exit code ret) if: +This command will fail with non-zero status upon error. Some exit +codes are: . The config file is invalid (ret=3), . can not write to the config file (ret=4), . no section or name was provided (ret=2), . the section or key is invalid (ret=1), . you try to unset an option which does not exist (ret=5), -. you try to unset/set an option for which multiple lines match (ret=5), -. you try to use an invalid regexp (ret=6), or -. you use '--global' option without $HOME being properly set (ret=128). +. you try to unset/set an option for which multiple lines match (ret=5), or +. you try to use an invalid regexp (ret=6). On success, the command returns the exit code 0. @@ -267,7 +267,7 @@ Given a .git/config like this: ; Proxy settings [core] - gitproxy="proxy-command" for kernel.org + gitproxy=proxy-command for kernel.org gitproxy=default-proxy ; for all the rest you can set the filemode to true with @@ -342,7 +342,7 @@ To actually match only values with an exclamation mark, you have to To add a new proxy, without altering any of the existing ones, use ------------ -% git config core.gitproxy '"proxy-command" for example.com' +% git config --add core.gitproxy '"proxy-command" for example.com' ------------ An example to use customized color from the configuration in your diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt index 11edc5a173..d15db42d43 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -3,7 +3,7 @@ git-credential-cache--daemon(1) NAME ---- -git-credential-cache--daemon - temporarily store user credentials in memory +git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index f3d09c5d51..eeff5fa989 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -3,7 +3,7 @@ git-credential-cache(1) NAME ---- -git-credential-cache - helper to temporarily store passwords in memory +git-credential-cache - Helper to temporarily store passwords in memory SYNOPSIS -------- diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 31093467d1..b27c03c361 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -3,7 +3,7 @@ git-credential-store(1) NAME ---- -git-credential-store - helper to store credentials on disk +git-credential-store - Helper to store credentials on disk SYNOPSIS -------- diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 6695ab3b4b..98d9881d7e 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -137,17 +137,19 @@ This option can be used several times to provide several detection regexes. -A <author-conv-file>:: CVS by default uses the Unix username when writing its commit logs. Using this option and an author-conv-file - in this format + maps the name recorded in CVS to author name, e-mail and + optional timezone: + --------- exon=Andreas Ericsson <ae@op5.se> - spawn=Simon Pawn <spawn@frog-pond.org> + spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago --------- + 'git cvsimport' will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly -all along. +all along. If a timezone is specified, GIT_AUTHOR_DATE will +have the corresponding offset applied. + For convenience, this data is saved to `$GIT_DIR/cvs-authors` each time the '-A' option is provided and read from that same diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index e8f757704c..7e5098a95e 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -16,6 +16,7 @@ SYNOPSIS [--reuseaddr] [--detach] [--pid-file=<file>] [--enable=<service>] [--disable=<service>] [--allow-override=<service>] [--forbid-override=<service>] + [--access-hook=<path>] [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]] [<directory>...] @@ -171,6 +172,21 @@ the facility of inet daemon to achieve the same before spawning errors are not enabled, all errors report "access denied" to the client. The default is --no-informative-errors. +--access-hook=<path>:: + Every time a client connects, first run an external command + specified by the <path> with service name (e.g. "upload-pack"), + path to the repository, hostname (%H), canonical hostname + (%CH), ip address (%IP), and tcp port (%P) as its command line + arguments. The external command can decide to decline the + service by exiting with a non-zero status (or to allow it by + exiting with a zero status). It can also look at the $REMOTE_ADDR + and $REMOTE_PORT environment variables to learn about the + requestor when making this decision. ++ +The external command can optionally write a single line to its +standard output to be sent to the requestor as an error message when +it declines the service. + <directory>:: A directory to add to the whitelist of allowed directories. Unless --strict-paths is specified this will also include subdirectories diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 039cce2e98..72d6bb612b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -36,12 +36,12 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref - found in `.git/refs/`. This option enables matching + found in `refs/` namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. This option enables matching + found in `refs/tags` namespace. This option enables matching a lightweight (non-annotated) tag. --contains:: diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 31fc2e3aed..73ca7025a3 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -69,6 +69,14 @@ with custom merge tool commands and has the same value as `$MERGED`. --tool-help:: Print a list of diff tools that may be used with `--tool`. +--symlinks:: +--no-symlinks:: + 'git difftool''s default behavior is create symlinks to the + working tree when run in `--dir-diff` mode. ++ + Specifying `--no-symlinks` instructs 'git difftool' to create + copies instead. `--no-symlinks` is the default on Windows. + -x <command>:: --extcmd=<command>:: Specify a custom command for viewing diffs. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 2620d28b4b..6603a7ab73 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -39,6 +39,10 @@ OPTIONS See ``Date Formats'' below for details about which formats are supported, and their syntax. +-- done:: + Terminate with error if there is no 'done' command at the + end of the stream. + --force:: Force updating modified existing branches, even if doing so would cause commits to be lost (as the new commit does @@ -1047,7 +1051,9 @@ done:: Error out if the stream ends without a 'done' command. Without this feature, errors causing the frontend to end abruptly at a convenient point in the stream can go - undetected. + undetected. This may occur, for example, if an import + front end dies in mid-operation without emitting SIGTERM + or SIGKILL at its subordinate git fast-import instance. `option` ~~~~~~~~ diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 474fa307a0..8c751202d7 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -9,7 +9,10 @@ git-fetch-pack - Receive missing objects from another repository SYNOPSIS -------- [verse] -'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...] +'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] + [--upload-pack=<git-upload-pack>] + [--depth=<n>] [--no-progress] + [-v] [<host>:]<directory> [<refs>...] DESCRIPTION ----------- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 81f58234a7..e2301f5c01 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,7 +32,8 @@ changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. -*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +*NOTE*: This command honors `.git/info/grafts` file and refs in +the `refs/replace/` namespace. If you have any grafts or replacement refs defined, running this command will make them permanent. @@ -303,6 +304,11 @@ committed a merge between P1 and P2, it will be propagated properly and all children of the merge will become merge commits with P1,P2 as their parents instead of the merge commit. +*NOTE* the changes introduced by the commits, and which are not reverted +by subsequent commits, will still be in the rewritten branch. If you want +to throw out _changes_ together with the commits, you should use the +interactive mode of 'git rebase'. + You can rewrite the commit log messages using `--msg-filter`. For example, 'git svn-id' strings in a repository created by 'git svn' can be removed this way: @@ -313,11 +319,6 @@ git filter-branch --msg-filter ' ' ------------------------------------------------------- -To restrict rewriting to only part of the history, specify a revision -range in addition to the new branch name. The new branch name will -point to the top-most revision that a 'git rev-list' of this range -will print. - If you need to add 'Acked-by' lines to, say, the last 10 commits (none of which is a merge), use this command: @@ -328,11 +329,10 @@ git filter-branch --msg-filter ' ' HEAD~10..HEAD -------------------------------------------------------- -*NOTE* the changes introduced by the commits, and which are not reverted -by subsequent commits, will still be in the rewritten branch. If you want -to throw out _changes_ together with the commits, you should use the -interactive mode of 'git rebase'. - +To restrict rewriting to only part of the history, specify a revision +range in addition to the new branch name. The new branch name will +point to the top-most revision that a 'git rev-list' of this range +will print. Consider this history: diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index c872b883ba..db55a4e0bb 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`, and `date` to extract the named component. The complete message in a commit and tag object is `contents`. -Its first line is `contents:subject`, the remaining lines -are `contents:body` and the optional GPG signature -is `contents:signature`. +Its first line is `contents:subject`, where subject is the concatenation +of all lines of the commit message up to the first blank line. The next +line is 'contents:body', where body is all of the lines after the first +blank line. Finally, the optional GPG signature is `contents:signature`. For sorting purposes, fields with numeric values sort in numeric order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 04c7346e3e..259dce4994 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -20,7 +20,7 @@ SYNOPSIS [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] [--to=<email>] [--cc=<email>] - [--cover-letter] [--quiet] + [--cover-letter] [--quiet] [--notes[=<ref>]] [<common diff options>] [ <since> | <revision range> ] @@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified. If `-o` is specified, output files are created in <dir>. Otherwise they are created in the current working directory. -By default, the subject of a single patch is "[PATCH] First Line" and -the subject when multiple patches are output is "[PATCH n/m] First -Line". To force 1/1 to be added for a single patch, use `-n`. To omit -patch numbers from the subject, use `-N`. +By default, the subject of a single patch is "[PATCH] " followed by +the concatenation of lines from the commit message up to the first blank +line (see the DISCUSSION section of linkgit:git-commit[1]). + +When multiple patches are output, the subject prefix will instead be +"[PATCH n/m] ". To force 1/1 to be added for a single patch, use `-n`. +To omit patch numbers from the subject, use `-N`. If given `--thread`, `git-format-patch` will generate `In-Reply-To` and `References` headers to make the second and subsequent patch mails appear @@ -188,6 +191,18 @@ will want to ensure that threading is disabled for `git send-email`. containing the shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--notes[=<ref>]:: + Append the notes (see linkgit:git-notes[1]) for the commit + after the three-dash line. ++ +The expected use case of this is to write supporting explanation for +the commit that does not belong to the commit log message proper, +and include it with the patch submission. While one can simply write +these explanations after `format-patch` has run but before sending, +keeping them as git notes allows them to be maintained between versions +of the patch series (but see the discussion of the `notes.rewrite` +configuration options in linkgit:git-notes[1] to use this workflow). + --[no]-signature=<signature>:: Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index bbb25da2dd..da348fc942 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -23,8 +23,8 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the -index file, all SHA1 references in .git/refs/*, and all reflogs (unless ---no-reflogs is given) as heads. +index file, all SHA1 references in `refs` namespace, and all reflogs +(unless --no-reflogs is given) as heads. --unreachable:: Print out objects that exist but that aren't reachable from any diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 3bec036883..cfecf848fb 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -42,8 +42,16 @@ CONFIGURATION grep.lineNumber:: If set to true, enable '-n' option by default. +grep.patternType:: + Set the default matching behavior. Using a value of 'basic', 'extended', + 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', + '--fixed-strings', or '--perl-regexp' option accordingly, while the + value 'default' will return to the default matching behavior. + grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. + If set to true, enable '--extended-regexp' option by default. This + option is ignored when the 'grep.patternType' option is set to a value + other than 'default'. OPTIONS diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 1f906208f9..585dac40ba 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -24,10 +24,6 @@ each commit introduces are shown. OPTIONS ------- --<n>:: - Limits the number of commits to show. - Note that this is a commit limiting option, see below. - <since>..<until>:: Show only commits between the named two commits. When either <since> or <until> is omitted, it defaults to @@ -137,6 +133,8 @@ Examples This makes sense only when following a strict policy of merging all topic branches when staying on a single integration branch. +`git log -3`:: + Limits the number of commits to show to 3. Discussion ---------- diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index c406a11001..d54932889f 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -48,7 +48,8 @@ $ gitk $(cd .git/lost-found/commit && echo ??*) ------------ After making sure you know which the object is the tag you are looking -for, you can reconnect it to your regular .git/refs hierarchy. +for, you can reconnect it to your regular `refs` hierarchy by using +the `update-ref` command. ------------ $ git cat-file -t 1ef2b196 diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index 7a9b86a58a..774de5e9d9 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -42,6 +42,11 @@ OPTIONS it successfully talked with the remote repository, whether it found any matching refs. +--get-url:: + Expand the URL of the given remote repository taking into account any + "url.<base>.insteadOf" config setting (See linkgit:git-config[1]) and + exit without talking to the remote. + <repository>:: Location of the repository. The shorthand defined in $GIT_DIR/branches/ can be used. Use "." (dot) to list references in diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index b295bf8330..87842e33f8 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git merge-base' [-a|--all] <commit> <commit>... 'git merge-base' [-a|--all] --octopus <commit>... +'git merge-base' --is-ancestor <commit> <commit> 'git merge-base' --independent <commit>... DESCRIPTION @@ -50,6 +51,12 @@ from linkgit:git-show-branch[1] when used with the `--merge-base` option. from any other. This mimics the behavior of 'git show-branch --independent'. +--is-ancestor:: + Check if the first <commit> is an ancestor of the second <commit>, + and exit with status 0 if true, or with status 1 if not. + Errors are signaled by a non-zero status that is not 1. + + OPTIONS ------- -a:: @@ -110,6 +117,27 @@ both '1' and '2' are merge-bases of A and B. Neither one is better than the other (both are 'best' merge bases). When the `--all` option is not given, it is unspecified which best one is output. +A common idiom to check "fast-forward-ness" between two commits A +and B is (or at least used to be) to compute the merge base between +A and B, and check if it is the same as A, in which case, A is an +ancestor of B. You will see this idiom used often in older scripts. + + A=$(git rev-parse --verify A) + if test "$A" = "$(git merge-base A B)" + then + ... A is an ancestor of B ... + fi + +In modern git, you can say this in a more direct way: + + if git merge-base --is-ancestor A B + then + ... A is an ancestor of B ... + fi + +instead. + + See also -------- linkgit:git-rev-list[1], diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 20f9228511..d34ea3c50b 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -99,7 +99,7 @@ commit or stash your changes before running 'git merge'. more than two parents (affectionately called an Octopus merge). + If no commit is given from the command line, and if `merge.defaultToUpstream` -configuration variable is set, merge the remote tracking branches +configuration variable is set, merge the remote-tracking branches that the current branch is configured to use as its upstream. See also the configuration section of this manual page. diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index d7207bd9b9..6b563c500f 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -64,6 +64,9 @@ variable `mergetool.<tool>.trustExitCode` can be set to `true`. Otherwise, 'git mergetool' will prompt the user to indicate the success of the resolution after the custom tool has exited. +--tool-help:: + Print a list of merge tools that may be used with `--tool`. + -y:: --no-prompt:: Don't prompt before each invocation of the merge resolution diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index b95aafae2d..46ef0466be 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -39,6 +39,10 @@ message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or "Notes:" for `refs/notes/commits`). +Notes can also be added to patches prepared with `git format-patch` by +using the `--notes` option. Such notes are added as a patch commentary +after a three dash separator line. + To change which notes are shown by 'git log', see the "notes.displayRef" configuration in linkgit:git-log[1]. diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 8228f33e3f..beff6229c8 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -163,7 +163,7 @@ All commands except clone accept these options. --git-dir <dir>:: Set the 'GIT_DIR' environment variable. See linkgit:git[1]. ---verbose:: +--verbose, -v:: Provide more progress information. Sync options @@ -269,6 +269,24 @@ These options can be used to modify 'git p4 submit' behavior. Export tags from git as p4 labels. Tags found in git are applied to the perforce working directory. +--dry-run, -n:: + Show just what commits would be submitted to p4; do not change + state in git or p4. + +--prepare-p4-only:: + Apply a commit to the p4 workspace, opening, adding and deleting + files in p4 as for a normal submit operation. Do not issue the + final "p4 submit", but instead print a message about how to + submit manually or revert. This option always stops after the + first (oldest) commit. Git tags are not exported to p4. + +--conflict=(ask|skip|quit):: + Conflicts can occur when applying a commit to p4. When this + happens, the default behavior ("ask") is to prompt whether to + skip this commit and continue, or quit. This option can be used + to bypass the prompt, causing conflicting commits to be automatically + skipped, or to quit trying to apply commits, without prompting. + Rebase options ~~~~~~~~~~~~~~ These options can be used to modify 'git p4 rebase' behavior. @@ -519,6 +537,10 @@ git-p4.labelExportRegexp:: Only p4 labels matching this regular expression will be exported. The default value is '[a-zA-Z0-9_\-.]+$'. +git-p4.conflict:: + Specify submit behavior when a conflict with p4 is found, as per + --conflict. The default behavior is 'ask'. + IMPLEMENTATION DETAILS ---------------------- * Changesets from p4 are imported using git fast-import. diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 10afd4edfe..f131677478 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -14,7 +14,8 @@ DESCRIPTION ----------- Traditionally, tips of branches and tags (collectively known as -'refs') were stored one file per ref under `$GIT_DIR/refs` +'refs') were stored one file per ref in a (sub)directory +under `$GIT_DIR/refs` directory. While many branch tips tend to be updated often, most tags and some branch tips are never updated. When a repository has hundreds or thousands of tags, this @@ -22,13 +23,14 @@ one-file-per-ref format both wastes storage and hurts performance. This command is used to solve the storage and performance -problem by stashing the refs in a single file, +problem by storing the refs in a single file, `$GIT_DIR/packed-refs`. When a ref is missing from the -traditional `$GIT_DIR/refs` hierarchy, it is looked up in this +traditional `$GIT_DIR/refs` directory hierarchy, it is looked +up in this file and used if found. Subsequent updates to branches always create new files under -`$GIT_DIR/refs` hierarchy. +`$GIT_DIR/refs` directory hierarchy. A recommended practice to deal with a repository with too many refs is to pack its refs with `--all --prune` once, and @@ -57,6 +59,15 @@ a repository with many branches of historical interests. The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. + +BUGS +---- + +Older documentation written before the packed-refs mechanism was +introduced may still say things like ".git/refs/heads/<branch> file +exists" when it means "branch <branch> exists". + + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index defb544ed0..67fa5ee195 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -101,6 +101,7 @@ include::merge-options.txt[] :git-pull: 1 +-r:: --rebase:: Rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index cb97cc1c3b..fe46c4258a 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -37,7 +37,9 @@ OPTIONS[[OPTIONS]] `+`, followed by the source ref <src>, followed by a colon `:`, followed by the destination ref <dst>. It is used to specify with what <src> object the <dst> ref - in the remote repository is to be updated. + in the remote repository is to be updated. If not specified, + the behavior of the command is controlled by the `push.default` + configuration variable. + 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 @@ -65,7 +67,8 @@ directs git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name already exists on the remote side. This is the default operation mode if no explicit refspec is found (that is neither on the command line -nor in any Push line of the corresponding remotes file---see below). +nor in any Push line of the corresponding remotes file---see below) and +no `push.default` configuration variable is set. --all:: Instead of naming each ref to push, specifies that all @@ -172,7 +175,7 @@ useful if you write an alias or script around 'git push'. --recurse-submodules=check|on-demand:: Make sure all submodule commits used by the revisions to be - pushed are available on a remote tracking branch. If 'check' is + pushed are available on a remote-tracking branch. If 'check' is used git will verify that all submodule commits that changed in the revisions to be pushed are available on at least one remote of the submodule. If any commits are missing the push will be @@ -357,7 +360,8 @@ Examples `git push origin :`. + The default behavior of this command when no <refspec> is given can be -configured by setting the `push` option of the remote. +configured by setting the `push` option of the remote, or the `push.default` +configuration variable. + For example, to default to pushing only the current branch to `origin` use `git config remote.origin.push HEAD`. Any valid <refspec> (like diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index fd535b06ab..da067ecafa 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -12,7 +12,7 @@ SYNOPSIS [<upstream>] [<branch>] 'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>] --root [<branch>] -'git rebase' --continue | --skip | --abort +'git rebase' --continue | --skip | --abort | --edit-todo DESCRIPTION ----------- @@ -245,6 +245,9 @@ leave out at most one of A and B, in which case it defaults to HEAD. --skip:: Restart the rebasing process by skipping the current patch. +--edit-todo:: + Edit the todo list during an interactive rebase. + -m:: --merge:: Use merging strategies to rebase. When the recursive (default) merge diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index f5836e46d0..5ce4cda8e7 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -98,6 +98,20 @@ advertised with this capability must cover all refs reported by the list command. If no 'refspec' capability is advertised, there is an implied `refspec *:*`. +'bidi-import':: + The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers + to retrieve information about blobs and trees that already exist in + fast-import's memory. This requires a channel from fast-import to the + remote-helper. + If it is advertised in addition to "import", git establishes a pipe from + fast-import to the remote-helper's stdin. + It follows that git and fast-import are both connected to the + remote-helper's stdin. Because git can send multiple commands to + the remote-helper it is required that helpers that use 'bidi-import' + buffer all 'import' commands of a batch before sending data to fast-import. + This is to prevent mixing commands and fast-import responses on the + helper's stdin. + Capabilities for Pushing ~~~~~~~~~~~~~~~~~~~~~~~~ 'connect':: @@ -286,7 +300,12 @@ terminated with a blank line. For each batch of 'import', the remote helper should produce a fast-import stream terminated by a 'done' command. + -Supported if the helper has the "import" capability. +Note that if the 'bidi-import' capability is used the complete batch +sequence has to be buffered before starting to send data to fast-import +to prevent mixing of commands and fast-import responses on the helper's +stdin. ++ +Supported if the helper has the 'import' capability. 'connect' <service>:: Connects to given service. Standard input and standard output diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index a308f4c79f..e8c396b5f9 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git remote' [-v | --verbose] 'git remote add' [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror=<fetch|push>] <name> <url> 'git remote rename' <old> <new> -'git remote rm' <name> +'git remote remove' <name> 'git remote set-head' <name> (-a | -d | <branch>) 'git remote set-branches' [--add] <name> <branch>... 'git remote set-url' [--push] <name> <newurl> [<oldurl>] @@ -85,6 +85,7 @@ In case <old> and <new> are the same, and <old> is a file under `$GIT_DIR/remotes` or `$GIT_DIR/branches`, the remote is converted to the configuration file format. +'remove':: 'rm':: Remove the remote named <name>. All remote-tracking branches and diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 17df525275..51131d0858 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -14,14 +14,13 @@ SYNOPSIS DESCRIPTION ----------- -Adds a 'replace' reference in `.git/refs/replace/` +Adds a 'replace' reference in `refs/replace/` namespace. The name of the 'replace' reference is the SHA1 of the object that is replaced. The content of the 'replace' reference is the SHA1 of the replacement object. -Unless `-f` is given, the 'replace' reference must not yet exist in -`.git/refs/replace/` directory. +Unless `-f` is given, the 'replace' reference must not yet exist. Replacement references will be used by default by all git commands except those doing reachability traversal (prune, pack transfer and diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 117e3743a6..978d8da50c 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git reset' [-q] [<commit>] [--] <paths>... 'git reset' (--patch | -p) [<commit>] [--] [<paths>...] -'git reset' (--soft | --mixed | --hard | --merge | --keep) [-q] [<commit>] +'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- @@ -43,11 +43,11 @@ This means that `git reset -p` is the opposite of `git add -p`, i.e. you can use it to selectively reset hunks. See the ``Interactive Mode'' section of linkgit:git-add[1] to learn how to operate the `--patch` mode. -'git reset' --<mode> [<commit>]:: +'git reset' [<mode>] [<commit>]:: This form resets the current branch head to <commit> and possibly updates the index (resetting it to the tree of <commit>) and - the working tree depending on <mode>, which - must be one of the following: + the working tree depending on <mode>. If <mode> is omitted, + defaults to "--mixed". The <mode> must be one of the following: + -- --soft:: diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 5d31860eb1..262436b7b1 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -134,6 +134,21 @@ use the following command: git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached ---------------- +Submodules +~~~~~~~~~~ +Only submodules using a gitfile (which means they were cloned +with a git version 1.7.8 or newer) will be removed from the work +tree, as their repository lives inside the .git directory of the +superproject. If a submodule (or one of those nested inside it) +still uses a .git directory, `git rm` will fail - no matter if forced +or not - to protect the submodule's history. + +A submodule is considered up-to-date when the HEAD is the same as +recorded in the index, no tracked files are modified and no untracked +files that aren't ignored are present in the submodules work tree. +Ignored files are deemed expendable and won't stop a submodule's work +tree from being removed. + EXAMPLES -------- `git rm Documentation/\*.txt`:: diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 324117072d..eeb561cf14 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -126,6 +126,10 @@ The --to option must be repeated for each user you want on the to list. + Note that no attempts whatsoever are made to validate the encoding. +--compose-encoding=<encoding>:: + Specify encoding of compose message. Default is the value of the + 'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed. + Sending ~~~~~~~ diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 01d8417316..afeb4cdf16 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -14,8 +14,7 @@ git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] DESCRIPTION ----------- Summarizes 'git log' output in a format suitable for inclusion -in release announcements. Each commit will be grouped by author and -the first line of the commit message will be shown. +in release announcements. Each commit will be grouped by author and title. Additionally, "[PATCH]" will be stripped from the commit description. diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 67e5f53a9e..9f1ef9a463 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -38,6 +38,9 @@ OPTIONS across git versions and regardless of user configuration. See below for details. +--long:: + Give the output in the long-format. This is the default. + -u[<mode>]:: --untracked-files[=<mode>]:: Show untracked files. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index fbbbcb282c..1d6527ab9f 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] [-f|--force] +'git submodule' [--quiet] add [-b branch] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] @@ -112,7 +112,6 @@ status:: initialized, `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing repository and `U` if the submodule has merge conflicts. - This command is the default command for 'git submodule'. + If `--recursive` is specified, this command will recurse into nested submodules, and show their status as well. @@ -149,6 +148,11 @@ submodule with the `--init` option. + If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. ++ +If `--force` is specified, the submodule will be checked out (using +`git checkout --force` if appropriate), even if the commit specified in the +index of the containing repository already matches the commit checked out in +the submodule. summary:: Show commit summary between the given commit (defaults to HEAD) and @@ -210,7 +214,9 @@ OPTIONS This option is only valid for add and update commands. When running add, allow adding an otherwise ignored submodule path. When running update, throw away local changes in submodules when - switching to a different commit. + switching to a different commit; and always run a checkout operation + in the submodule, even if the commit listed in the index of the + containing repository matches the commit checked out in the submodule. --cached:: This option is only valid for status and summary commands. These @@ -259,6 +265,11 @@ OPTIONS Initialize all submodules for which "git submodule init" has not been called so far before updating. +--name:: + This option is only valid for the add command. It sets the submodule's + name to the given string instead of defaulting to its path. The name + must be valid as a directory name and may not end with a '/'. + --reference <repository>:: This option is only valid for add and update commands. These commands sometimes need to clone a remote repository. In this case, diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index cfe8d2b5df..8b0d3adfed 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -146,6 +146,13 @@ Skip "branches" and "tags" of first level directories;; ------------------------------------------------------------------------ -- +--log-window-size=<n>;; + Fetch <n> log entries per request when scanning Subversion history. + The default is 100. For very large Subversion repositories, larger + values may be needed for 'clone'/'fetch' to complete in reasonable + time. But overly large values may lead to higher memory usage and + request timeouts. + 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 981d3a8fc1..ef68ad2b71 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -3,13 +3,14 @@ git-symbolic-ref(1) NAME ---- -git-symbolic-ref - Read and modify symbolic refs +git-symbolic-ref - Read, modify and delete symbolic refs SYNOPSIS -------- [verse] 'git symbolic-ref' [-m <reason>] <name> <ref> 'git symbolic-ref' [-q] [--short] <name> +'git symbolic-ref' --delete [-q] <name> DESCRIPTION ----------- @@ -21,6 +22,9 @@ argument to see which branch your working tree is on. Given two arguments, creates or updates a symbolic ref <name> to point at the given branch <ref>. +Given `--delete` and an additional argument, deletes the given +symbolic ref. + A symbolic ref is a regular file that stores a string that begins with `ref: refs/`. For example, your `.git/HEAD` is a regular file whose contents is `ref: refs/heads/master`. @@ -28,6 +32,10 @@ a regular file whose contents is `ref: refs/heads/master`. OPTIONS ------- +-d:: +--delete:: + Delete the symbolic ref <name>. + -q:: --quiet:: Do not issue an error message if the <name> is not a diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index e36a7c3d1e..247534e908 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -20,11 +20,10 @@ SYNOPSIS DESCRIPTION ----------- -Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given to delete, list or verify tags. -Unless `-f` is given, the tag to be created must not yet exist in the -`.git/refs/tags/` directory. +Unless `-f` is given, the named tag must not yet exist. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command creates a 'tag' object, and requires a tag message. Unless diff --git a/Documentation/git.txt b/Documentation/git.txt index 27da0eb209..4a89a12513 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -22,18 +22,17 @@ unusually rich command set that provides both high-level operations and full access to internals. See linkgit:gittutorial[7] to get started, then see -link:everyday.html[Everyday Git] for a useful minimum set of commands, and -"man git-commandname" for documentation of each command. CVS users may -also want to read linkgit:gitcvs-migration[7]. See -the link:user-manual.html[Git User's Manual] for a more in-depth -introduction. +link:everyday.html[Everyday Git] for a useful minimum set of +commands. The link:user-manual.html[Git User's Manual] has a more +in-depth introduction. -The '<command>' is either a name of a Git command (see below) or an alias -as defined in the configuration file (see linkgit:git-config[1]). +After you mastered the basic concepts, you can come back to this +page to learn what commands git offers. You can learn more about +individual git commands with "git help command". linkgit:gitcli[7] +manual page gives you an overview of the command line command syntax. -Formatted and hyperlinked version of the latest git -documentation can be viewed at -`http://git-htmldocs.googlecode.com/git/git.html`. +Formatted and hyperlinked version of the latest git documentation +can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`. ifdef::stalenotes[] [NOTE] @@ -44,14 +43,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.12/git.html[documentation for release 1.7.12] +* link:v1.8.0/git.html[documentation for release 1.8.0] * release notes for + link:RelNotes/1.8.0.txt[1.8.0], + +* link:v1.7.12.4/git.html[documentation for release 1.7.12.4] + +* release notes for + link:RelNotes/1.7.12.4.txt[1.7.12.4], + link:RelNotes/1.7.12.3.txt[1.7.12.3], + link:RelNotes/1.7.12.2.txt[1.7.12.2], + link:RelNotes/1.7.12.1.txt[1.7.12.1], link:RelNotes/1.7.12.txt[1.7.12]. -* link:v1.7.11.5/git.html[documentation for release 1.7.11.5] +* link:v1.7.11.7/git.html[documentation for release 1.7.11.7] * release notes for + link:RelNotes/1.7.11.7.txt[1.7.11.7], + link:RelNotes/1.7.11.6.txt[1.7.11.6], link:RelNotes/1.7.11.5.txt[1.7.11.5], link:RelNotes/1.7.11.4.txt[1.7.11.4], link:RelNotes/1.7.11.3.txt[1.7.11.3], @@ -411,24 +421,6 @@ help ...`. linkgit:git-replace[1] for more information. -FURTHER DOCUMENTATION ---------------------- - -See the references above to get started using git. The following is -probably more detail than necessary for a first-time user. - -The link:user-manual.html#git-concepts[git concepts chapter of the -user-manual] and linkgit:gitcore-tutorial[7] both provide -introductions to the underlying git architecture. - -See linkgit:gitworkflows[7] for an overview of recommended workflows. - -See also the link:howto-index.html[howto] documents for some useful -examples. - -The internals are documented in the -link:technical/api-index.html[GIT API documentation]. - GIT COMMANDS ------------ @@ -848,6 +840,29 @@ The index is also capable of storing multiple entries (called "stages") for a given pathname. These stages are used to hold the various unmerged version of a file when a merge is in progress. +FURTHER DOCUMENTATION +--------------------- + +See the references in the "description" section to get started +using git. The following is probably more detail than necessary +for a first-time user. + +The link:user-manual.html#git-concepts[git concepts chapter of the +user-manual] and linkgit:gitcore-tutorial[7] both provide +introductions to the underlying git architecture. + +See linkgit:gitworkflows[7] for an overview of recommended workflows. + +See also the link:howto-index.html[howto] documents for some useful +examples. + +The internals are documented in the +link:technical/api-index.html[GIT API documentation]. + +Users migrating from CVS may also want to +read linkgit:gitcvs-migration[7]. + + Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index e16f3e175b..2698f63cf9 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -56,6 +56,7 @@ When more than one pattern matches the path, a later line overrides an earlier line. This overriding is done per attribute. The rules how the pattern matches paths are the same as in `.gitignore` files; see linkgit:gitignore[5]. +Unlike `.gitignore`, negative patterns are forbidden. When deciding what attributes are assigned to a path, git consults `$GIT_DIR/info/attributes` file (which has the highest @@ -66,6 +67,11 @@ is from the path in question, the lower its precedence). Finally global and system-wide files are considered (they have the lowest precedence). +When the `.gitattributes` file is missing from the work tree, the +path in the index is used as a fall-back. During checkout process, +`.gitattributes` in the index is used and then the file in the +working tree is used as a fall-back. + If you wish to affect only a single repository (i.e., to assign attributes to files that are particular to one user's workflow for that repository), then @@ -511,6 +517,8 @@ configuration file (you still need to enable this with the attribute mechanism, via `.gitattributes`). The following built in patterns are available: +- `ada` suitable for source code in the Ada language. + - `bibtex` suitable for files with BibTeX coded references. - `cpp` suitable for source code in the C and C++ languages. @@ -927,7 +935,7 @@ file at the toplevel (i.e. not in any subdirectory). The built-in macro attribute "binary" is equivalent to: ------------ -[attr]binary -diff -text +[attr]binary -diff -merge -text ------------ diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index ea17f7a53b..3bc1500eda 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -37,11 +37,28 @@ arguments. Here are the rules: file called HEAD in your work tree, `git diff HEAD` is ambiguous, and you have to say either `git diff HEAD --` or `git diff -- HEAD` to disambiguate. - ++ When writing a script that is expected to handle random user-input, it is a good practice to make it explicit which arguments are which by placing disambiguating `--` at appropriate places. + * Many commands allow wildcards in paths, but you need to protect + them from getting globbed by the shell. These two mean different + things: ++ +-------------------------------- +$ git checkout -- *.c +$ git checkout -- \*.c +-------------------------------- ++ +The former lets your shell expand the fileglob, and you are asking +the dot-C files in your working tree to be overwritten with the version +in the index. The latter passes the `*.c` to Git, and you are asking +the paths in the index that match the pattern to be checked out to your +working tree. After running `git add hello.c; rm hello.c`, you will _not_ +see `hello.c` in your working tree with the former, but with the latter +you will. + Here are the rules regarding the "flags" that you should follow when you are scripting git: @@ -62,13 +79,21 @@ scripting git: `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. + * many commands allow a long option "--option" to be abbreviated + only to their unique prefix (e.g. if there is no other option + whose name begins with "opt", you may be able to spell "--opt" to + invoke the "--option" flag), but you should fully spell them out + when writing your scripts; later versions of Git may introduce a + new option whose name shares the same prefix, e.g. "--optimize", + to make a short prefix that used to be unique no longer unique. + ENHANCED OPTION PARSER ---------------------- From the git 1.5.4 series and further, many git commands (not all of them at the time of the writing though) come with an enhanced option parser. -Here is an exhaustive list of the facilities provided by this option parser. +Here is a list of the facilities provided by this option parser. Magic Options @@ -112,6 +137,16 @@ options. This means that you can for example use `git rm -rf` or `git clean -fdx`. +Abbreviating long options +~~~~~~~~~~~~~~~~~~~~~~~~~ +Commands that support the enhanced option parser accepts unique +prefix of a long option as if it is fully spelled out, but use this +with a caution. For example, `git commit --amen` behaves as if you +typed `git commit --amend`, but that is true only until a later version +of Git introduces another option that shares the same prefix, +e.g `git commit --amenity" option. + + Separating argument from the option ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can write the mandatory option parameter to an option as a separate diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 9d893369a0..5325c5a7d5 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -956,12 +956,11 @@ $ git show-branch --topo-order --more=1 master mybranch ------------------------------------------------ The first two lines indicate that it is showing the two branches -and the first line of the commit log message from their -top-of-the-tree commits, you are currently on `master` branch -(notice the asterisk `*` character), and the first column for -the later output lines is used to show commits contained in the +with the titles of their top-of-the-tree commits, you are currently on +`master` branch (notice the asterisk `*` character), and the first +column for the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` -branch. Three commits are shown along with their log messages. +branch. Three commits are shown along with their titles. All of them have non blank characters in the first column (`*` shows an ordinary commit on the current branch, `-` is a merge commit), which means they are now part of the `master` branch. Only the "Some diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index c1f692a71e..1b82fe1969 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -41,18 +41,24 @@ precedence, the last matching pattern decides the outcome): variable 'core.excludesfile'. Which file to place a pattern in depends on how the pattern is meant to -be used. Patterns which should be version-controlled and distributed to -other repositories via clone (i.e., files that all developers will want -to ignore) should go into a `.gitignore` file. Patterns which are -specific to a particular repository but which do not need to be shared -with other related repositories (e.g., auxiliary files that live inside -the repository but are specific to one user's workflow) should go into -the `$GIT_DIR/info/exclude` file. Patterns which a user wants git to -ignore in all situations (e.g., backup or temporary files generated by -the user's editor of choice) generally go into a file specified by -`core.excludesfile` in the user's `~/.gitconfig`. Its default value is -$XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or empty, -$HOME/.config/git/ignore is used instead. +be used. + + * Patterns which should be version-controlled and distributed to + other repositories via clone (i.e., files that all developers will want + to ignore) should go into a `.gitignore` file. + + * Patterns which are + specific to a particular repository but which do not need to be shared + with other related repositories (e.g., auxiliary files that live inside + the repository but are specific to one user's workflow) should go into + the `$GIT_DIR/info/exclude` file. + + * Patterns which a user wants git to + ignore in all situations (e.g., backup or temporary files generated by + the user's editor of choice) generally go into a file specified by + `core.excludesfile` in the user's `~/.gitconfig`. Its default value is + $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or + empty, $HOME/.config/git/ignore is used instead. The underlying git plumbing tools, such as 'git ls-files' and 'git read-tree', read @@ -68,11 +74,15 @@ PATTERN FORMAT for readability. - A line starting with # serves as a comment. + Put a backslash ("`\`") in front of the first hash for patterns + that begin with a hash. - - An optional prefix '!' which negates the pattern; any + - An optional prefix "`!`" which negates the pattern; any matching file excluded by a previous pattern will become included again. If a negated pattern matches, this will override lower precedence patterns sources. + Put a backslash ("`\`") in front of the first "`!`" for patterns + that begin with a literal "`!`", for example, "`\!important!.txt`". - If the pattern ends with a slash, it is removed for the purpose of the following description, but it would only find diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 4effd78902..ab3e91c054 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -18,7 +18,9 @@ working tree, is a text file with a syntax matching the requirements of linkgit:git-config[1]. The file contains one subsection per submodule, and the subsection value -is the name of the submodule. Each submodule section also contains the +is the name of the submodule. The name is set to the path where the +submodule has been added unless it was customized with the '--name' +option of 'git submodule add'. Each submodule section also contains the following required keys: submodule.<name>.path:: diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 5c891f1169..9f628862b4 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -93,6 +93,12 @@ refs/remotes/`name`:: records tip-of-the-tree commit objects of branches copied from a remote repository. +refs/replace/`<obj-sha1>`:: + records the SHA1 of the object that replaces `<obj-sha1>`. + This is similar to info/grafts and is internally used and + maintained by linkgit:git-replace[1]. Such refs can be exchanged + between repositories while grafts are not. + packed-refs:: records the same information as refs/heads/, refs/tags/, and friends record in a more efficient way. See diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index dee050567e..f1cb6f3be6 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -139,9 +139,11 @@ them to the index, and commit, all in one step. A note on commit messages: Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more -thorough description. Tools that turn commits into email, for -example, use the first line on the Subject: line and the rest of the -commit in the body. +thorough description. The text up to the first blank line in a commit +message is treated as the commit title, and that title is used +throughout git. For example, linkgit:git-format-patch[1] turns a +commit into email, and it uses the title on the Subject line and the +rest of the commit in the body. Git tracks content not files ---------------------------- diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index 8823a37067..ea6e4a52c9 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -5,6 +5,10 @@ Abstract: Imagine that git development is racing along as usual, when our friend neighborhood maintainer is struck down by a wayward bus. Out of the hordes of suckers (loyal developers), you have been tricked (chosen) to step up as the new maintainer. This howto will show you "how to" do it. +Content-type: text/asciidoc + +How to maintain Git +=================== The maintainer's git time is spent on three activities. diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt index 74a1c0c4ba..4627ee47f2 100644 --- a/Documentation/howto/rebase-from-internal-branch.txt +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -8,7 +8,12 @@ Abstract: In this article, JC talks about how he rebases the the "master" branch, and how "rebase" works. Also discussed is how this applies to individual developers who sends patches upstream. +Content-type: text/asciidoc +How to rebase from an internal branch +===================================== + +-------------------------------------- Petr Baudis <pasky@suse.cz> writes: > Dear diary, on Sun, Aug 14, 2005 at 09:57:13AM CEST, I got a letter @@ -19,6 +24,7 @@ Petr Baudis <pasky@suse.cz> writes: >> > branch to the real branches. >> > Actually, wouldn't this be also precisely for what StGIT is intended to? +-------------------------------------- Exactly my feeling. I was sort of waiting for Catalin to speak up. With its basing philosophical ancestry on quilt, this is @@ -156,8 +162,3 @@ you continue on starting from the new "master" head, which is the #1' commit. -jc - -- -To unsubscribe from this list: send the line "unsubscribe git" in -the body of a message to majordomo@vger.kernel.org -More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/howto/rebuild-from-update-hook.txt b/Documentation/howto/rebuild-from-update-hook.txt index 48c67568d3..00c1b45b79 100644 --- a/Documentation/howto/rebuild-from-update-hook.txt +++ b/Documentation/howto/rebuild-from-update-hook.txt @@ -5,6 +5,10 @@ Date: Fri, 26 Aug 2005 18:19:10 -0700 Abstract: In this how-to article, JC talks about how he uses the post-update hook to automate git documentation page shown at http://www.kernel.org/pub/software/scm/git/docs/. +Content-type: text/asciidoc + +How to rebuild from update hook +=============================== The pages under http://www.kernel.org/pub/software/scm/git/docs/ are built from Documentation/ directory of the git.git project diff --git a/Documentation/howto/recover-corrupted-blob-object.txt b/Documentation/howto/recover-corrupted-blob-object.txt index 323b513ed0..7484735320 100644 --- a/Documentation/howto/recover-corrupted-blob-object.txt +++ b/Documentation/howto/recover-corrupted-blob-object.txt @@ -3,11 +3,17 @@ From: Linus Torvalds <torvalds@linux-foundation.org> Subject: corrupt object on git-gc Abstract: Some tricks to reconstruct blob objects in order to fix a corrupted repository. +Content-type: text/asciidoc +How to recover a corrupted blob object +====================================== + +----------------------------------------------------------- On Fri, 9 Nov 2007, Yossi Leybovich wrote: > > Did not help still the repository look for this object? > Any one know how can I track this object and understand which file is it +----------------------------------------------------------- So exactly *because* the SHA1 hash is cryptographically secure, the hash itself doesn't actually tell you anything, in order to fix a corrupt @@ -31,19 +37,23 @@ original object, so right now the corrupt object is useless, but it's very interesting for the future, in the hope that you can re-create a non-corrupt version. +----------------------------------------------------------- So: > ib]$ mv .git/objects/4b/9458b3786228369c63936db65827de3cc06200 ../ +----------------------------------------------------------- This is the right thing to do, although it's usually best to save it under it's full SHA1 name (you just dropped the "4b" from the result ;). Let's see what that tells us: +----------------------------------------------------------- > ib]$ git-fsck --full > broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 > to blob 4b9458b3786228369c63936db65827de3cc06200 > missing blob 4b9458b3786228369c63936db65827de3cc06200 +----------------------------------------------------------- Ok, I removed the "dangling commit" messages, because they are just messages about the fact that you probably have rebased etc, so they're not diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt index 6fd711996a..8a685483f4 100644 --- a/Documentation/howto/revert-a-faulty-merge.txt +++ b/Documentation/howto/revert-a-faulty-merge.txt @@ -7,6 +7,10 @@ Abstract: Sometimes a branch that was already merged to the mainline after the offending branch is fixed. Message-ID: <7vocz8a6zk.fsf@gitster.siamese.dyndns.org> References: <alpine.LFD.2.00.0812181949450.14014@localhost.localdomain> +Content-type: text/asciidoc + +How to revert a faulty merge +============================ Alan <alan@clueserver.org> said: diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt index 093c656048..a59ced8d04 100644 --- a/Documentation/howto/revert-branch-rebase.txt +++ b/Documentation/howto/revert-branch-rebase.txt @@ -8,8 +8,8 @@ Date: Mon, 29 Aug 2005 21:39:02 -0700 Content-type: text/asciidoc Message-ID: <7voe7g3uop.fsf@assigned-by-dhcp.cox.net> -Reverting an existing commit -============================ +How to revert an existing commit +================================ One of the changes I pulled into the 'master' branch turns out to break building GIT with GCC 2.95. While they were well intentioned diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt index 6d3eb8ed00..bd1027433b 100644 --- a/Documentation/howto/separating-topic-branches.txt +++ b/Documentation/howto/separating-topic-branches.txt @@ -1,6 +1,10 @@ From: Junio C Hamano <gitster@pobox.com> Subject: Separating topic branches Abstract: In this article, JC describes how to separate topic branches. +Content-type: text/asciidoc + +How to separate topic branches +============================== This text was originally a footnote to a discussion about the behaviour of the git diff commands. diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt index 622ee5c8dd..a695f01f0e 100644 --- a/Documentation/howto/setup-git-server-over-http.txt +++ b/Documentation/howto/setup-git-server-over-http.txt @@ -1,6 +1,10 @@ From: Rutger Nijlunsing <rutger@nospam.com> Subject: Setting up a git repository which can be pushed into and pulled from over HTTP(S). Date: Thu, 10 Aug 2006 22:00:26 +0200 +Content-type: text/asciidoc + +How to setup git server over http +================================= Since Apache is one of those packages people like to compile themselves while others prefer the bureaucrat's dream Debian, it is diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt index b7f8d416d6..a5193b1e5c 100644 --- a/Documentation/howto/update-hook-example.txt +++ b/Documentation/howto/update-hook-example.txt @@ -5,6 +5,10 @@ Message-ID: <7vfypumlu3.fsf@assigned-by-dhcp.cox.net> Abstract: An example hooks/update script is presented to implement repository maintenance policies, such as who can push into which branch and who can make a tag. +Content-type: text/asciidoc + +How to use the update hook +========================== When your developer runs git-push into the repository, git-receive-pack is run (either locally or over ssh) as that @@ -32,8 +36,7 @@ like this as your hooks/update script. [jc: editorial note. This is a much improved version by Carl since I posted the original outline] --- >8 -- beginning of script -- >8 -- - +---------------------------------------------------- #!/bin/bash umask 002 @@ -111,12 +114,12 @@ then info "Found matching head pattern: '$head_pattern'" for user_pattern in $user_patterns; do - info "Checking user: '$username' against pattern: '$user_pattern'" - matchlen=$(expr "$username" : "$user_pattern") - if test "$matchlen" = "${#username}" - then - grant "Allowing user: '$username' with pattern: '$user_pattern'" - fi + info "Checking user: '$username' against pattern: '$user_pattern'" + matchlen=$(expr "$username" : "$user_pattern") + if test "$matchlen" = "${#username}" + then + grant "Allowing user: '$username' with pattern: '$user_pattern'" + fi done deny "The user is not in the access list for this branch" done @@ -149,13 +152,13 @@ then info "Found matching head pattern: '$head_pattern'" for group_pattern in $group_patterns; do - for groupname in $groups; do - info "Checking group: '$groupname' against pattern: '$group_pattern'" - matchlen=$(expr "$groupname" : "$group_pattern") - if test "$matchlen" = "${#groupname}" - then - grant "Allowing group: '$groupname' with pattern: '$group_pattern'" - fi + for groupname in $groups; do + info "Checking group: '$groupname' against pattern: '$group_pattern'" + matchlen=$(expr "$groupname" : "$group_pattern") + if test "$matchlen" = "${#groupname}" + then + grant "Allowing group: '$groupname' with pattern: '$group_pattern'" + fi done done deny "None of the user's groups are in the access list for this branch" @@ -169,24 +172,21 @@ then fi deny >/dev/null "There are no more rules to check. Denying access" - --- >8 -- end of script -- >8 -- +---------------------------------------------------- This uses two files, $GIT_DIR/info/allowed-users and allowed-groups, to describe which heads can be pushed into by whom. The format of each file would look like this: - refs/heads/master junio - +refs/heads/pu junio - refs/heads/cogito$ pasky - refs/heads/bw/.* linus - refs/heads/tmp/.* .* - refs/tags/v[0-9].* junio + refs/heads/master junio + +refs/heads/pu junio + refs/heads/cogito$ pasky + refs/heads/bw/.* linus + refs/heads/tmp/.* .* + refs/tags/v[0-9].* junio With this, Linus can push or create "bw/penguin" or "bw/zebra" or "bw/panda" branches, Pasky can do only "cogito", and JC can do master and pu branches and make versioned tags. And anybody can do tmp/blah branches. The '+' sign at the pu record means that JC can make non-fast-forward pushes on it. - ------------- diff --git a/Documentation/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.txt index 4e2f75cb61..23cdf35435 100644 --- a/Documentation/howto/use-git-daemon.txt +++ b/Documentation/howto/use-git-daemon.txt @@ -1,4 +1,7 @@ +Content-type: text/asciidoc + How to use git-daemon +===================== Git can be run in inetd mode and in stand alone mode. But all you want is let a coworker pull from you, and therefore need to set up a git server diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt index 98c0033a55..00f693bde8 100644 --- a/Documentation/howto/using-signed-tag-in-pull-request.txt +++ b/Documentation/howto/using-signed-tag-in-pull-request.txt @@ -7,8 +7,8 @@ Abstract: Beginning v1.7.9, a contributor can push a signed tag to her later validate it. Content-type: text/asciidoc -Using signed tag in pull requests -================================= +How to use a signed tag in pull requests +======================================== A typical distributed workflow using Git is for a contributor to fork a project, build on it, publish the result to her public repository, and ask diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 861bd6f553..9bb4956ccd 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -9,11 +9,11 @@ merge.conflictstyle:: merge.defaultToUpstream:: If merge is called without any commit argument, merge the upstream branches configured for the current branch by using their last - observed values stored in their remote tracking branches. + observed values stored in their remote-tracking branches. The values of the `branch.<current branch>.merge` that name the branches at the remote named by `branch.<current branch>.remote` are consulted, and then they are mapped via `remote.<remote>.fetch` - to their corresponding remote tracking branches, and the tips of + to their corresponding remote-tracking branches, and the tips of these tracking branches are merged. merge.ff:: diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 595a3cf1a7..66db80296f 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -32,13 +32,14 @@ ours;; This option forces conflicting hunks to be auto-resolved cleanly by favoring 'our' version. Changes from the other tree that do not conflict with our side are reflected to the merge result. + For a binary file, the entire contents are taken from our side. + This should not be confused with the 'ours' merge strategy, which does not even look at what the other tree contains at all. It discards everything the other tree did, declaring 'our' history contains all that happened in it. theirs;; - This is opposite of 'ours'. + This is the opposite of 'ours'. patience;; With this option, 'merge-recursive' spends a little extra time diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index e3d8a83b23..d9eddedc72 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -130,6 +130,9 @@ The placeholders are: - '%b': body - '%B': raw body (unwrapped subject and body) - '%N': commit notes +- '%GG': raw verification message from GPG for a signed commit +- '%G?': show either "G" for Good or "B" for Bad for a signed commit +- '%GS': show the name of the signer for a signed commit - '%gD': reflog selector, e.g., `refs/stash@{1}` - '%gd': shortened reflog selector, e.g., `stash@{1}` - '%gn': reflog identity name diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 2a3dc8664f..5e499421a4 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -66,3 +66,7 @@ being displayed. Examples: "--notes=foo" will show only notes from --[no-]standard-notes:: These options are deprecated. Use the above --notes/--no-notes options instead. + +--show-signature:: + Check the validity of a signed commit object by passing the signature + to `gpg --verify` and show the output. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index d9b2b5b2e0..1ec14a068e 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -3,12 +3,20 @@ Commit Limiting Besides specifying a range of commits that should be listed using the special notations explained in the description, additional commit -limiting may be applied. Note that they are applied before commit -ordering and formatting options, such as '--reverse'. +limiting may be applied. + +Using more options generally further limits the output (e.g. +`--since=<date1>` limits to commits newer than `<date1>`, and using it +with `--grep=<pattern>` further limits to commits whose log message +has a line that matches `<pattern>`), unless otherwise noted. + +Note that these are applied before commit +ordering and formatting options, such as `--reverse`. -- --n 'number':: +-<number>:: +-n <number>:: --max-count=<number>:: Limit the number of commits to output. @@ -38,22 +46,44 @@ endif::git-rev-list[] --committer=<pattern>:: Limit the commits output to ones with author/committer - header lines that match the specified pattern (regular expression). + header lines that match the specified pattern (regular + expression). With more than one `--author=<pattern>`, + commits whose author matches any of the given patterns are + chosen (similarly for multiple `--committer=<pattern>`). + +--grep-reflog=<pattern>:: + + Limit the commits output to ones with reflog entries that + match the specified pattern (regular expression). With + more than one `--grep-reflog`, commits whose reflog message + matches any of the given patterns are chosen. It is an + error to use this option unless `--walk-reflogs` is in use. --grep=<pattern>:: Limit the commits output to ones with log message that - matches the specified pattern (regular expression). + matches the specified pattern (regular expression). With + more than one `--grep=<pattern>`, commits whose message + matches any of the given patterns are chosen (but see + `--all-match`). ++ +When `--show-notes` is in effect, the message from the notes as +if it is part of the log message. --all-match:: Limit the commits output to ones that match all given --grep, - --author and --committer instead of ones that match at least one. + instead of ones that match at least one. -i:: --regexp-ignore-case:: Match the regexp limiting patterns without regard to letters case. +--basic-regexp:: + + Consider the limiting patterns to be basic regular expressions; + this is the default. + -E:: --extended-regexp:: @@ -66,6 +96,11 @@ endif::git-rev-list[] Consider the limiting patterns to be fixed strings (don't interpret pattern as a regular expression). +--perl-regexp:: + + Consider the limiting patterns to be Perl-compatible regexp. + Requires libpcre to be compiled in. + --remove-empty:: Stop when a given path disappears from the tree. @@ -578,16 +613,33 @@ Commit Ordering By default, the commits are shown in reverse chronological order. ---topo-order:: +--date-order:: + Show no parents before all of its children are shown, but + otherwise show commits in the commit timestamp order. - This option makes them appear in topological order (i.e. - descendant commits are shown before their parents). +--topo-order:: + Show no parents before all of its children are shown, and + avoid showing commits on multiple lines of history + intermixed. ++ +For example, in a commit history like this: ++ +---------------------------------------------------------------- ---date-order:: + ---1----2----4----7 + \ \ + 3----5----6----8--- - This option is similar to '--topo-order' in the sense that no - parent comes before all of its children, but otherwise things - are still ordered in the commit timestamp order. +---------------------------------------------------------------- ++ +where the numbers denote the order of commit timestamps, `git +rev-list` and friends with `--date-order` show the commits in the +timestamp order: 8 7 6 5 4 3 2 1. ++ +With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 +3 1); some older commits are shown before newer ones in order to +avoid showing the commits from two parallel development track mixed +together. --reverse:: @@ -619,10 +671,14 @@ These options are mostly targeted for packing of git repositories. Only useful with '--objects'; print the object IDs that are not in packs. ---no-walk:: +--no-walk[=(sorted|unsorted)]:: - Only show the given revs, but do not traverse their ancestors. - This has no effect if a range is specified. + Only show the given commits, but do not traverse their ancestors. + This has no effect if a range is specified. If the argument + "unsorted" is given, the commits are show in the order they were + given on the command line. Otherwise (if "sorted" or no argument + was given), the commits are show in reverse chronological order + by commit time. --do-walk:: diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index dc0070bcb7..991fcd8f3f 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -55,6 +55,8 @@ when you run `git cherry-pick`. + 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. +While the ref name encoding is unspecified, UTF-8 is prefered as +some output processing may assume ref names in UTF-8. '<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: A ref followed by the suffix '@' with a date specification @@ -213,6 +215,13 @@ of 'r1' and 'r2' and is defined as It is the set of commits that are reachable from either one of 'r1' or 'r2' but not from both. +In these two shorthands, you can omit one end and let it default to HEAD. +For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What +did I do since I forked from the origin branch?" Similarly, '..origin' +is a shorthand for 'HEAD..origin' and asks "What did the origin do since +I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an +empty range that is both reachable and unreachable from HEAD. + 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 diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 1b7d8f140c..a959517b23 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -46,6 +46,18 @@ Functions Format a string and push it onto the end of the array. This is a convenience wrapper combining `strbuf_addf` and `argv_array_push`. +`argv_array_pop`:: + Remove the final element from the array. If there are no + elements in the array, do nothing. + `argv_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. + +`argv_array_detach`:: + Detach the argv array from the `struct argv_array`, transfering + ownership of the allocated array and strings. + +`argv_array_free_detached`:: + Free the memory allocated by a `struct argv_array` that was later + detached and is now no longer needed. diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-sha1-array.txt index 4a4bae8109..45d1c517cd 100644 --- a/Documentation/technical/api-sha1-array.txt +++ b/Documentation/technical/api-sha1-array.txt @@ -25,9 +25,6 @@ Functions the array (but note that some operations below may lose this ordering). -`sha1_array_sort`:: - Sort the elements in the array. - `sha1_array_lookup`:: Perform a binary search of the array for a specific sha1. If found, returns the offset (in number of elements) of the diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index 95a8bf3846..84686b5c69 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -279,6 +279,22 @@ same behaviour as well. Strip whitespace from a buffer. The second parameter controls if comments are considered contents to be removed or not. +`strbuf_split_buf`:: +`strbuf_split_str`:: +`strbuf_split_max`:: +`strbuf_split`:: + + Split a string or strbuf into a list of strbufs at a specified + terminator character. The returned substrings include the + terminator characters. Some of these functions take a `max` + parameter, which, if positive, limits the output to that + number of substrings. + +`strbuf_list_free`:: + + Free a list of strbufs (for example, the return values of the + `strbuf_split()` functions). + `launch_editor`:: Launch the user preferred editor to edit a file and fill the buffer diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 5a0c14fceb..7386bcab3e 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -1,8 +1,9 @@ string-list API =============== -The string_list API offers a data structure and functions to handle sorted -and unsorted string lists. +The string_list API offers a data structure and functions to handle +sorted and unsorted string lists. A "sorted" list is one whose +entries are sorted by string value in `strcmp()` order. The 'string_list' struct used to be called 'path_list', but was renamed because it is not specific to paths. @@ -20,8 +21,9 @@ If you need something advanced, you can manually malloc() the `items` member (you need this if you add things later) and you should set the `nr` and `alloc` members in that case, too. -. Adds new items to the list, using `string_list_append` or - `string_list_insert`. +. Adds new items to the list, using `string_list_append`, + `string_list_append_nodup`, `string_list_insert`, + `string_list_split`, and/or `string_list_split_in_place`. . Can check if a string is in the list using `string_list_has_string` or `unsorted_string_list_has_string` and get it from the list using @@ -29,18 +31,24 @@ member (you need this if you add things later) and you should set the . Can sort an unsorted list using `sort_string_list`. +. Can remove duplicate items from a sorted list using + `string_list_remove_duplicates`. + . Can remove individual items of an unsorted list using `unsorted_string_list_delete_item`. +. Can remove items not matching a criterion from a sorted or unsorted + list using `filter_string_list`, or remove empty strings using + `string_list_remove_empty_items`. + . Finally it should free the list using `string_list_clear`. Example: ---- -struct string_list list; +struct string_list list = STRING_LIST_INIT_NODUP; int i; -memset(&list, 0, sizeof(struct string_list)); string_list_append(&list, "foo"); string_list_append(&list, "bar"); for (i = 0; i < list.nr; i++) @@ -60,6 +68,28 @@ Functions * General ones (works with sorted and unsorted lists as well) +`filter_string_list`:: + + Apply a function to each item in a list, retaining only the + items for which the function returns true. If free_util is + true, call free() on the util members of any items that have + to be deleted. Preserve the order of the items that are + retained. + +`string_list_remove_empty_items`:: + + Remove any empty strings from the list. If free_util is true, + call free() on the util members of any items that have to be + deleted. Preserve the order of the items that are retained. + +`string_list_longest_prefix`:: + + Return the longest string within a string_list that is a + prefix (in the sense of prefixcmp()) of the specified string, + or NULL if no such prefix exists. This function does not + require the string_list to be sorted (it does a linear + search). + `print_string_list`:: Dump a string_list to stdout, useful mainly for debugging purposes. It @@ -96,15 +126,32 @@ write `string_list_insert(...)->util = ...;`. Look up a given string in the string_list, returning the containing string_list_item. If the string is not found, NULL is returned. +`string_list_remove_duplicates`:: + + Remove all but the first of consecutive entries that have the + same string value. If free_util is true, call free() on the + util members of any items that have to be deleted. + * Functions for unsorted lists only `string_list_append`:: - Append a new string to the end of the string_list. + Append a new string to the end of the string_list. If + `strdup_string` is set, then the string argument is copied; + otherwise the new `string_list_entry` refers to the input + string. + +`string_list_append_nodup`:: + + Append a new string to the end of the string_list. The new + `string_list_entry` always refers to the input string, even if + `strdup_string` is set. This function can be used to hand + ownership of a malloc()ed string to a `string_list` that has + `strdup_string` set. `sort_string_list`:: - Make an unsorted list sorted. + Sort the list's entries by string value in `strcmp()` order. `unsorted_string_list_has_string`:: @@ -124,6 +171,25 @@ counterpart for sorted lists, which performs a binary search. is set. The third parameter controls if the `util` pointer of the items should be freed or not. +`string_list_split`:: +`string_list_split_in_place`:: + + Split a string into substrings on a delimiter character and + append the substrings to a `string_list`. If `maxsplit` is + non-negative, then split at most `maxsplit` times. Return the + number of substrings appended to the list. ++ +`string_list_split` requires a `string_list` that has `strdup_strings` +set to true; it leaves the input string untouched and makes copies of +the substrings in newly-allocated memory. +`string_list_split_in_place` requires a `string_list` that has +`strdup_strings` set to false; it splits the input string in place, +overwriting the delimiter characters with NULs and creating new +string_list_items that point into the original string (the original +string must therefore not be modified or freed while the `string_list` +is in use). + + Data structures --------------- diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 9d25b30178..57d6f915b1 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -1,7 +1,7 @@ GIT index format ================ -= The git index file has the following format +== The git index file has the following format All binary numbers are in network byte order. Version 2 is described here unless stated otherwise. diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index 1803e64e46..a7871fb865 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -1,7 +1,7 @@ GIT pack format =============== -= pack-*.pack files have the following format: +== pack-*.pack files have the following format: - A header appears at the beginning and consists of the following: @@ -34,7 +34,7 @@ GIT pack format - The trailer records 20-byte SHA1 checksum of all of the above. -= Original (version 1) pack-*.idx files have the following format: +== Original (version 1) pack-*.idx files have the following format: - The header consists of 256 4-byte network byte order integers. N-th entry of this table records the number of @@ -123,8 +123,8 @@ Pack file entry: <+ -= Version 2 pack-*.idx files support packs larger than 4 GiB, and - have some other reorganizations. They have the format: +== Version 2 pack-*.idx files support packs larger than 4 GiB, and + have some other reorganizations. They have the format: - A 4-byte magic number '\377tOc' which is an unreasonable fanout[0] value. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 49cdc571cd..f1a51edf47 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -117,7 +117,7 @@ A few things to remember here: - The repository path is always quoted with single quotes. Fetching Data From a Server -=========================== +--------------------------- When one Git repository wants to get data that a second repository has, the first can 'fetch' from the second. This operation determines @@ -134,7 +134,8 @@ with the object name that each reference currently points to. $ echo -e -n "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" | nc -v example.com 9418 - 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag + 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack + side-band side-band-64k ofs-delta shallow no-progress include-tag 00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration 003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master 003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9 @@ -259,8 +260,10 @@ a positive depth, this step is skipped. ---- If the client has requested a positive depth, the server will compute -the set of commits which are no deeper than the desired depth, starting -at the client's wants. The server writes 'shallow' lines for each +the set of commits which are no deeper than the desired depth. The set +of commits start at the client's wants. + +The server writes 'shallow' lines for each commit whose parents will not be sent as a result. The server writes an 'unshallow' line for each commit which the client has indicated is shallow, but is no longer shallow at the currently requested depth @@ -419,7 +422,7 @@ entire packfile without multiplexing. Pushing Data To a Server -======================== +------------------------ Pushing data to a server will invoke the 'receive-pack' process on the server, which will allow the client to tell it which references it should diff --git a/Documentation/technical/send-pack-pipeline.txt b/Documentation/technical/send-pack-pipeline.txt index 681efe4219..9b5a0bc186 100644 --- a/Documentation/technical/send-pack-pipeline.txt +++ b/Documentation/technical/send-pack-pipeline.txt @@ -1,5 +1,5 @@ -git-send-pack -============= +Git-send-pack internals +======================= Overall operation ----------------- diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt index 559263af48..0502a5471e 100644 --- a/Documentation/technical/shallow.txt +++ b/Documentation/technical/shallow.txt @@ -1,6 +1,12 @@ -Def.: Shallow commits do have parents, but not in the shallow +Shallow commits +=============== + +.Definition +********************************************************* +Shallow commits do have parents, but not in the shallow repo, and therefore grafts are introduced pretending that these commits have no parents. +********************************************************* The basic idea is to write the SHA1s of shallow commits into $GIT_DIR/shallow, and handle its contents like the contents diff --git a/Documentation/technical/trivial-merge.txt b/Documentation/technical/trivial-merge.txt index 24c84100b0..c79d4a7c47 100644 --- a/Documentation/technical/trivial-merge.txt +++ b/Documentation/technical/trivial-merge.txt @@ -74,24 +74,24 @@ For multiple ancestors, a '+' means that this case applies even if only one ancestor or remote fits; a '^' means all of the ancestors must be the same. -case ancest head remote result ----------------------------------------- -1 (empty)+ (empty) (empty) (empty) -2ALT (empty)+ *empty* remote remote -2 (empty)^ (empty) remote no merge -3ALT (empty)+ head *empty* head -3 (empty)^ head (empty) no merge -4 (empty)^ head remote no merge -5ALT * head head head -6 ancest+ (empty) (empty) no merge -8 ancest^ (empty) ancest no merge -7 ancest+ (empty) remote no merge -10 ancest^ ancest (empty) no merge -9 ancest+ head (empty) no merge -16 anc1/anc2 anc1 anc2 no merge -13 ancest+ head ancest head -14 ancest+ ancest remote remote -11 ancest+ head remote no merge + case ancest head remote result + ---------------------------------------- + 1 (empty)+ (empty) (empty) (empty) + 2ALT (empty)+ *empty* remote remote + 2 (empty)^ (empty) remote no merge + 3ALT (empty)+ head *empty* head + 3 (empty)^ head (empty) no merge + 4 (empty)^ head remote no merge + 5ALT * head head head + 6 ancest+ (empty) (empty) no merge + 8 ancest^ (empty) ancest no merge + 7 ancest+ (empty) remote no merge + 10 ancest^ ancest (empty) no merge + 9 ancest+ head (empty) no merge + 16 anc1/anc2 anc1 anc2 no merge + 13 ancest+ head ancest head + 14 ancest+ ancest remote remote + 11 ancest+ head remote no merge Only #2ALT and #3ALT use *empty*, because these are the only cases where there can be conflicts that didn't exist before. Note that we diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 289019478d..1d15ee7e52 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -6,8 +6,12 @@ address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. -Git natively supports ssh, git, http, https, ftp, ftps, and rsync -protocols. The following syntaxes may be used with them: +Git supports ssh, git, http, and https protocols (in addition, ftp, +and ftps can be used for fetching and rsync can be used for fetching +and pushing, but these are inefficient and deprecated; do not use +them). + +The following syntaxes may be used with them: - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/ - git://host.xz{startsb}:port{endsb}/path/to/repo.git/ diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf index 339b30919e..d87294de2f 100644 --- a/Documentation/user-manual.conf +++ b/Documentation/user-manual.conf @@ -14,7 +14,7 @@ ifdef::backend-docbook[] # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> | </literallayout> {title#}</example> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 03d95dc290..1b377dc207 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1136,9 +1136,12 @@ Creating good commit messages Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough -description. Tools that turn commits into email, for example, use -the first line on the Subject line and the rest of the commit in the -body. +description. The text up to the first blank line in a commit +message is treated as the commit title, and that title is used +throughout git. For example, linkgit:git-format-patch[1] turns a +commit into email, and it uses the title on the Subject line and the +rest of the commit in the body. + [[ignoring-files]] Ignoring files @@ -1784,6 +1787,13 @@ $ git format-patch origin will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD. +`git format-patch` can include an initial "cover letter". You can insert +commentary on individual patches after the three dash line which +`format-patch` places after the commit message but before the patch +itself. If you use `git notes` to track your cover letter material, +`git format-patch --notes` will include the commit's notes in a similar +manner. + You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the linkgit:git-send-email[1] script to automate the process. |