diff options
Diffstat (limited to 'Documentation')
356 files changed, 13209 insertions, 4569 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 1c3a9fead5..d62aebd848 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -3,6 +3,7 @@ *.[1-8] *.made *.texi +*.pdf git.info gitman.info howto-index.txt diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b8bf618a30..fe1c1e5bc2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -31,25 +31,36 @@ But if you must have a list of rules, here they are. For shell scripts specifically (not exhaustive): + - We use tabs for indentation. + + - Case arms are indented at the same depth as case and esac lines. + - We prefer $( ... ) for command substitution; unlike ``, it properly nests. It should have been the way Bourne spelled it from day one, but unfortunately isn't. - - We use ${parameter-word} and its [-=?+] siblings, and their - colon'ed "unset or null" form. + - We use POSIX compliant parameter substitutions and avoid bashisms; + namely: - - We use ${parameter#word} and its [#%] siblings, and their - doubled "longest matching" form. + - We use ${parameter-word} and its [-=?+] siblings, and their + colon'ed "unset or null" form. - - We use Arithmetic Expansion $(( ... )). + - We use ${parameter#word} and its [#%] siblings, and their + doubled "longest matching" form. - - No "Substring Expansion" ${parameter:offset:length}. + - No "Substring Expansion" ${parameter:offset:length}. - - No shell arrays. + - No shell arrays. - - No strlen ${#parameter}. + - No strlen ${#parameter}. - - No regexp ${parameter/pattern/string}. + - No pattern replacement ${parameter/pattern/string}. + + - We use Arithmetic Expansion $(( ... )). + + - Inside Arithmetic Expansion, spell shell variables with $ in front + of them, as some shells do not grok $((x)) while accepting $(($x)) + just fine (e.g. dash older than 0.5.4). - We do not use Process Substitution <(list) or >(list). @@ -132,3 +143,55 @@ For C programs: - When we pass <string, length> pair to functions, we should try to pass them in that order. + +Writing Documentation: + + Every user-visible change should be reflected in the documentation. + The same general rule as for code applies -- imitate the existing + conventions. A few commented examples follow to provide reference + when writing or modifying command usage strings and synopsis sections + in the manual pages: + + Placeholders are spelled in lowercase and enclosed in angle brackets: + <file> + --sort=<key> + --abbrev[=<n>] + + Possibility of multiple occurrences is indicated by three dots: + <file>... + (One or more of <file>.) + + Optional parts are enclosed in square brackets: + [<extra>] + (Zero or one <extra>.) + + --exec-path[=<path>] + (Option with an optional argument. Note that the "=" is inside the + brackets.) + + [<patch>...] + (Zero or more of <patch>. Note that the dots are inside, not + outside the brackets.) + + Multiple alternatives are indicated with vertical bar: + [-q | --quiet] + [--utf8 | --no-utf8] + + Parentheses are used for grouping: + [(<rev>|<range>)...] + (Any number of either <rev> or <range>. Parens are needed to make + it clear that "..." pertains to both <rev> and <range>.) + + [(-p <parent>)...] + (Any number of option -p, each with one <parent> argument.) + + git remote set-head <name> (-a | -d | <branch>) + (One and only one of "-a", "-d" or "<branch>" _must_ (no square + brackets) be provided.) + + And a somewhat more contrived example: + --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] + Here "=" is outside the brackets, because "--diff-filter=" is a + valid usage. "*" has its own pair of brackets, because it can + (optionally) be specified only when one or more of the letters is + also provided. diff --git a/Documentation/Makefile b/Documentation/Makefile index 8a8a3954dc..304b31edee 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,12 +1,12 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ - gitk.txt git.txt + gitk.txt gitweb.txt git.txt MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ - gitrepository-layout.txt + gitrepository-layout.txt gitweb.conf.txt MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \ gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \ - gitdiffcore.txt gitworkflows.txt + gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) @@ -46,8 +46,8 @@ MANPAGE_XSL = manpage-normal.xsl XMLTO_EXTRA = INSTALL?=install RM ?= rm -f -DOC_REF = origin/man -HTML_REF = origin/html +MAN_REPO = ../../git-manpages +HTML_REPO = ../../git-htmldocs infodir?=$(prefix)/share/info MAKEINFO=makeinfo @@ -63,35 +63,28 @@ endif # # For asciidoc ... -# -7.1.2, no extra settings are needed. -# 8.0-, set ASCIIDOC8. +# -7.1.2, set ASCIIDOC7 +# 8.0-, no extra settings are needed # # # For docbook-xsl ... -# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) -# 1.69.0, no extra settings are needed? +# -1.68.1, no extra settings are needed? +# 1.69.0, set ASCIIDOC_ROFF? # 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? -# 1.71.1, no extra settings are needed? +# 1.71.1, set ASCIIDOC_ROFF? # 1.72.0, set DOCBOOK_XSL_172. -# 1.73.0-, set ASCIIDOC_NO_ROFF +# 1.73.0-, no extra settings are needed # -# -# If you had been using DOCBOOK_XSL_172 in an attempt to get rid -# of 'the ".ft C" problem' in your generated manpages, and you -# instead ended up with weird characters around callouts, try -# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). -# - -ifdef ASCIIDOC8 +ifndef ASCIIDOC7 ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal endif ifdef DOCBOOK_XSL_172 ASCIIDOC_EXTRA += -a git-asciidoc-no-roff MANPAGE_XSL = manpage-1.72.xsl else - ifdef ASCIIDOC_NO_ROFF + ifndef ASCIIDOC_ROFF # docbook-xsl after 1.72 needs the regular XSL, but will not # pass-thru raw roff codes from asciidoc.conf, so turn them off. ASCIIDOC_EXTRA += -a git-asciidoc-no-roff @@ -239,6 +232,7 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) clean: $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 $(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) $(cmds_txt) *.made @@ -264,7 +258,9 @@ manpage-base-url.xsl: manpage-base-url.xsl.in mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf - $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book $< + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o $@+ $< && \ + mv $@+ $@ technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) @@ -277,8 +273,10 @@ $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css -user-manual.html: user-manual.xml - $(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< +user-manual.html: user-manual.xml $(XSLT) + $(QUIET_XSLTPROC)$(RM) $@+ $@ && \ + xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \ + mv $@+ $@ git.info: user-manual.texi $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi @@ -329,12 +327,23 @@ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt install-webdoc : html '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST) +# You must have a clone of git-htmldocs and git-manpages repositories +# next to the git repository itself for the following to work. + quick-install: quick-install-man -quick-install-man: - '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(DOC_REF) $(DESTDIR)$(mandir) +require-manrepo:: + @if test ! -d $(MAN_REPO); \ + then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi + +quick-install-man: require-manrepo + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) + +require-htmlrepo:: + @if test ! -d $(HTML_REPO); \ + then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi -quick-install-html: - '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir) +quick-install-html: require-htmlrepo + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) .PHONY: FORCE diff --git a/Documentation/RelNotes-1.6.6.1.txt b/Documentation/RelNotes-1.6.6.1.txt deleted file mode 100644 index 4c88bebb90..0000000000 --- a/Documentation/RelNotes-1.6.6.1.txt +++ /dev/null @@ -1,15 +0,0 @@ -Git v1.6.6.1 Release Notes -========================== - -Fixes since v1.6.6 ------------------- - - * http-backend was not listed in the command list in the documentation. - -Other minor documentation updates are included. - --- -exec >/var/tmp/1 -O=v1.6.6-4-gd828fdb -echo O=$(git describe maint) -git shortlog --no-merges $O..maint diff --git a/Documentation/RelNotes-1.7.0.txt b/Documentation/RelNotes-1.7.0.txt deleted file mode 100644 index 321ae973b7..0000000000 --- a/Documentation/RelNotes-1.7.0.txt +++ /dev/null @@ -1,107 +0,0 @@ -Git v1.7.0 Release Notes -======================== - -Notes on behaviour change -------------------------- - - * "git push" into a branch that is currently checked out (i.e. pointed by - HEAD in a repository that is not bare) is refused by default. - - Similarly, "git push $there :$killed" to delete the branch $killed - in a remote repository $there, when $killed branch is the current - branch pointed at by its HEAD, will be refused by default. - - Setting the configuration variables receive.denyCurrentBranch and - receive.denyDeleteCurrent to 'ignore' in the receiving repository - can be used to override these safety features. - - * "git send-email" does not make deep threads by default when sending a - patch series with more than two messages. All messages will be sent - as a reply to the first message, i.e. cover letter. - - It has been possible to configure send-email to send "shallow thread" - by setting sendemail.chainreplyto configuration variable to false. The - only thing this release does is to change the default when you haven't - configured that variable. - - * "git status" is not "git commit --dry-run" anymore. This change does - not affect you if you run the command without pathspec. - - * "git diff" traditionally treated various "ignore whitespace" options - only as a way to filter the patch output. "git diff --exit-code -b" - exited with non-zero status even if all changes were about changing the - ammount of whitespace and nothing else. and "git diff -b" showed the - "diff --git" header line for such a change without patch text. - - In this release, the "ignore whitespaces" options affect the semantics - of the diff operation. A change that does not affect anything but - whitespaces is reported with zero exit status when run with - --exit-code, and there is no "diff --git" header for such a change. - - -Updates since v1.6.6 --------------------- - -(subsystems) - - * "git fast-import" updates; adds "option" and "feature" to detect the - mismatch between fast-import and the frontends that produce the input - stream. - -(portability) - -(performance) - -(usability, bells and whistles) - - * More commands learned "--quiet" and "--[no-]progress" options. - - * Various commands given by the end user (e.g. diff.type.textconv, - and GIT_EDITOR) can be specified with command line arguments. E.g. it - is now possible to say "[diff "utf8doc"] textconv = nkf -w". - - * "sparse checkout" feature allows only part of the work tree to be - checked out. - - * HTTP transfer can use authentication scheme other than basic - (i.e./e.g. digest). - - * "git checkout A...B" is a way to detach HEAD at the merge base between - A and B. - - * "git commit --date='<date>'" can be used to override the author date - just like "git commit --author='<name> <email>'" can be used to - override the author identity. - - * "git commit --no-status" can be used to omit the listing of the index - and the work tree status in the editor used to prepare the log message. - - * "git fetch --all" can now be used in place of "git remote update". - - * "git push" learned "git push origin --delete branch", a syntactic sugar - for "git push origin :branch". - - * "git rebase --onto A...B" means the history is replayed on top of the - merge base between A and B. - - * Use of "git reset --merge" has become easier when resetting away a - conflicted mess left in the work tree. - - * "git status" learned "-s(hort)" output format. - -(developers) - - * The infrastructure to build foreign SCM interface has been updated. - - -Fixes since v1.6.6 ------------------- - -All of the fixes in v1.6.6.X maintenance series are included in this -release, unless otherwise noted. - --- -exec >/var/tmp/1 -O=v1.6.6-242-gf287c65 -echo O=$(git describe master) -git shortlog --no-merges $O..master ^maint diff --git a/Documentation/RelNotes-1.5.0.1.txt b/Documentation/RelNotes/1.5.0.1.txt index fea3f9935b..fea3f9935b 100644 --- a/Documentation/RelNotes-1.5.0.1.txt +++ b/Documentation/RelNotes/1.5.0.1.txt diff --git a/Documentation/RelNotes-1.5.0.2.txt b/Documentation/RelNotes/1.5.0.2.txt index b061e50ff0..b061e50ff0 100644 --- a/Documentation/RelNotes-1.5.0.2.txt +++ b/Documentation/RelNotes/1.5.0.2.txt diff --git a/Documentation/RelNotes-1.5.0.3.txt b/Documentation/RelNotes/1.5.0.3.txt index cd500f96bf..cd500f96bf 100644 --- a/Documentation/RelNotes-1.5.0.3.txt +++ b/Documentation/RelNotes/1.5.0.3.txt diff --git a/Documentation/RelNotes-1.5.0.4.txt b/Documentation/RelNotes/1.5.0.4.txt index feefa5dfd4..feefa5dfd4 100644 --- a/Documentation/RelNotes-1.5.0.4.txt +++ b/Documentation/RelNotes/1.5.0.4.txt diff --git a/Documentation/RelNotes-1.5.0.5.txt b/Documentation/RelNotes/1.5.0.5.txt index eeec3d73d0..eeec3d73d0 100644 --- a/Documentation/RelNotes-1.5.0.5.txt +++ b/Documentation/RelNotes/1.5.0.5.txt diff --git a/Documentation/RelNotes-1.5.0.6.txt b/Documentation/RelNotes/1.5.0.6.txt index c02015ad5f..c02015ad5f 100644 --- a/Documentation/RelNotes-1.5.0.6.txt +++ b/Documentation/RelNotes/1.5.0.6.txt diff --git a/Documentation/RelNotes-1.5.0.7.txt b/Documentation/RelNotes/1.5.0.7.txt index 670ad32b85..670ad32b85 100644 --- a/Documentation/RelNotes-1.5.0.7.txt +++ b/Documentation/RelNotes/1.5.0.7.txt diff --git a/Documentation/RelNotes-1.5.0.txt b/Documentation/RelNotes/1.5.0.txt index daf4bdb0d7..daf4bdb0d7 100644 --- a/Documentation/RelNotes-1.5.0.txt +++ b/Documentation/RelNotes/1.5.0.txt diff --git a/Documentation/RelNotes-1.5.1.1.txt b/Documentation/RelNotes/1.5.1.1.txt index 91471213bd..91471213bd 100644 --- a/Documentation/RelNotes-1.5.1.1.txt +++ b/Documentation/RelNotes/1.5.1.1.txt diff --git a/Documentation/RelNotes-1.5.1.2.txt b/Documentation/RelNotes/1.5.1.2.txt index d88456306c..d88456306c 100644 --- a/Documentation/RelNotes-1.5.1.2.txt +++ b/Documentation/RelNotes/1.5.1.2.txt diff --git a/Documentation/RelNotes-1.5.1.3.txt b/Documentation/RelNotes/1.5.1.3.txt index 876408b65a..876408b65a 100644 --- a/Documentation/RelNotes-1.5.1.3.txt +++ b/Documentation/RelNotes/1.5.1.3.txt diff --git a/Documentation/RelNotes-1.5.1.4.txt b/Documentation/RelNotes/1.5.1.4.txt index df2f66ccb5..df2f66ccb5 100644 --- a/Documentation/RelNotes-1.5.1.4.txt +++ b/Documentation/RelNotes/1.5.1.4.txt diff --git a/Documentation/RelNotes-1.5.1.5.txt b/Documentation/RelNotes/1.5.1.5.txt index b0ab8eb371..b0ab8eb371 100644 --- a/Documentation/RelNotes-1.5.1.5.txt +++ b/Documentation/RelNotes/1.5.1.5.txt diff --git a/Documentation/RelNotes-1.5.1.6.txt b/Documentation/RelNotes/1.5.1.6.txt index 55f3ac13e3..55f3ac13e3 100644 --- a/Documentation/RelNotes-1.5.1.6.txt +++ b/Documentation/RelNotes/1.5.1.6.txt diff --git a/Documentation/RelNotes-1.5.1.txt b/Documentation/RelNotes/1.5.1.txt index daed367270..daed367270 100644 --- a/Documentation/RelNotes-1.5.1.txt +++ b/Documentation/RelNotes/1.5.1.txt diff --git a/Documentation/RelNotes-1.5.2.1.txt b/Documentation/RelNotes/1.5.2.1.txt index ebf20e22a7..ebf20e22a7 100644 --- a/Documentation/RelNotes-1.5.2.1.txt +++ b/Documentation/RelNotes/1.5.2.1.txt diff --git a/Documentation/RelNotes-1.5.2.2.txt b/Documentation/RelNotes/1.5.2.2.txt index 7bfa341750..7bfa341750 100644 --- a/Documentation/RelNotes-1.5.2.2.txt +++ b/Documentation/RelNotes/1.5.2.2.txt diff --git a/Documentation/RelNotes-1.5.2.3.txt b/Documentation/RelNotes/1.5.2.3.txt index addb22955b..addb22955b 100644 --- a/Documentation/RelNotes-1.5.2.3.txt +++ b/Documentation/RelNotes/1.5.2.3.txt diff --git a/Documentation/RelNotes-1.5.2.4.txt b/Documentation/RelNotes/1.5.2.4.txt index 75cff475f6..75cff475f6 100644 --- a/Documentation/RelNotes-1.5.2.4.txt +++ b/Documentation/RelNotes/1.5.2.4.txt diff --git a/Documentation/RelNotes-1.5.2.5.txt b/Documentation/RelNotes/1.5.2.5.txt index e8281c72a0..e8281c72a0 100644 --- a/Documentation/RelNotes-1.5.2.5.txt +++ b/Documentation/RelNotes/1.5.2.5.txt diff --git a/Documentation/RelNotes-1.5.2.txt b/Documentation/RelNotes/1.5.2.txt index e8328d090a..e8328d090a 100644 --- a/Documentation/RelNotes-1.5.2.txt +++ b/Documentation/RelNotes/1.5.2.txt diff --git a/Documentation/RelNotes-1.5.3.1.txt b/Documentation/RelNotes/1.5.3.1.txt index 7ff546c743..7ff546c743 100644 --- a/Documentation/RelNotes-1.5.3.1.txt +++ b/Documentation/RelNotes/1.5.3.1.txt diff --git a/Documentation/RelNotes-1.5.3.2.txt b/Documentation/RelNotes/1.5.3.2.txt index 4bbde3cab4..4bbde3cab4 100644 --- a/Documentation/RelNotes-1.5.3.2.txt +++ b/Documentation/RelNotes/1.5.3.2.txt diff --git a/Documentation/RelNotes-1.5.3.3.txt b/Documentation/RelNotes/1.5.3.3.txt index d213846951..d213846951 100644 --- a/Documentation/RelNotes-1.5.3.3.txt +++ b/Documentation/RelNotes/1.5.3.3.txt diff --git a/Documentation/RelNotes-1.5.3.4.txt b/Documentation/RelNotes/1.5.3.4.txt index b04b3a45a5..b04b3a45a5 100644 --- a/Documentation/RelNotes-1.5.3.4.txt +++ b/Documentation/RelNotes/1.5.3.4.txt diff --git a/Documentation/RelNotes-1.5.3.5.txt b/Documentation/RelNotes/1.5.3.5.txt index 7ff1d5d0d1..7ff1d5d0d1 100644 --- a/Documentation/RelNotes-1.5.3.5.txt +++ b/Documentation/RelNotes/1.5.3.5.txt diff --git a/Documentation/RelNotes-1.5.3.6.txt b/Documentation/RelNotes/1.5.3.6.txt index 069a2b2cf9..069a2b2cf9 100644 --- a/Documentation/RelNotes-1.5.3.6.txt +++ b/Documentation/RelNotes/1.5.3.6.txt diff --git a/Documentation/RelNotes-1.5.3.7.txt b/Documentation/RelNotes/1.5.3.7.txt index 2f690616c8..2f690616c8 100644 --- a/Documentation/RelNotes-1.5.3.7.txt +++ b/Documentation/RelNotes/1.5.3.7.txt diff --git a/Documentation/RelNotes-1.5.3.8.txt b/Documentation/RelNotes/1.5.3.8.txt index 0e3ff58a46..0e3ff58a46 100644 --- a/Documentation/RelNotes-1.5.3.8.txt +++ b/Documentation/RelNotes/1.5.3.8.txt diff --git a/Documentation/RelNotes-1.5.3.txt b/Documentation/RelNotes/1.5.3.txt index 0668d3c0ca..0668d3c0ca 100644 --- a/Documentation/RelNotes-1.5.3.txt +++ b/Documentation/RelNotes/1.5.3.txt diff --git a/Documentation/RelNotes-1.5.4.1.txt b/Documentation/RelNotes/1.5.4.1.txt index d4e44b8b09..d4e44b8b09 100644 --- a/Documentation/RelNotes-1.5.4.1.txt +++ b/Documentation/RelNotes/1.5.4.1.txt diff --git a/Documentation/RelNotes-1.5.4.2.txt b/Documentation/RelNotes/1.5.4.2.txt index 21d0df59fb..21d0df59fb 100644 --- a/Documentation/RelNotes-1.5.4.2.txt +++ b/Documentation/RelNotes/1.5.4.2.txt diff --git a/Documentation/RelNotes-1.5.4.3.txt b/Documentation/RelNotes/1.5.4.3.txt index b0fc67fb2a..b0fc67fb2a 100644 --- a/Documentation/RelNotes-1.5.4.3.txt +++ b/Documentation/RelNotes/1.5.4.3.txt diff --git a/Documentation/RelNotes-1.5.4.4.txt b/Documentation/RelNotes/1.5.4.4.txt index 323c1a88c7..323c1a88c7 100644 --- a/Documentation/RelNotes-1.5.4.4.txt +++ b/Documentation/RelNotes/1.5.4.4.txt diff --git a/Documentation/RelNotes-1.5.4.5.txt b/Documentation/RelNotes/1.5.4.5.txt index bbd130e36d..bbd130e36d 100644 --- a/Documentation/RelNotes-1.5.4.5.txt +++ b/Documentation/RelNotes/1.5.4.5.txt diff --git a/Documentation/RelNotes-1.5.4.6.txt b/Documentation/RelNotes/1.5.4.6.txt index 3e3c3e55a3..3e3c3e55a3 100644 --- a/Documentation/RelNotes-1.5.4.6.txt +++ b/Documentation/RelNotes/1.5.4.6.txt diff --git a/Documentation/RelNotes-1.5.4.7.txt b/Documentation/RelNotes/1.5.4.7.txt index 9065a0e273..9065a0e273 100644 --- a/Documentation/RelNotes-1.5.4.7.txt +++ b/Documentation/RelNotes/1.5.4.7.txt diff --git a/Documentation/RelNotes-1.5.4.txt b/Documentation/RelNotes/1.5.4.txt index f1323b6174..f1323b6174 100644 --- a/Documentation/RelNotes-1.5.4.txt +++ b/Documentation/RelNotes/1.5.4.txt diff --git a/Documentation/RelNotes-1.5.5.1.txt b/Documentation/RelNotes/1.5.5.1.txt index 7de419708f..7de419708f 100644 --- a/Documentation/RelNotes-1.5.5.1.txt +++ b/Documentation/RelNotes/1.5.5.1.txt diff --git a/Documentation/RelNotes-1.5.5.2.txt b/Documentation/RelNotes/1.5.5.2.txt index 391a7b02ea..391a7b02ea 100644 --- a/Documentation/RelNotes-1.5.5.2.txt +++ b/Documentation/RelNotes/1.5.5.2.txt diff --git a/Documentation/RelNotes-1.5.5.3.txt b/Documentation/RelNotes/1.5.5.3.txt index f22f98b734..f22f98b734 100644 --- a/Documentation/RelNotes-1.5.5.3.txt +++ b/Documentation/RelNotes/1.5.5.3.txt diff --git a/Documentation/RelNotes-1.5.5.4.txt b/Documentation/RelNotes/1.5.5.4.txt index 2d0279ecce..2d0279ecce 100644 --- a/Documentation/RelNotes-1.5.5.4.txt +++ b/Documentation/RelNotes/1.5.5.4.txt diff --git a/Documentation/RelNotes-1.5.5.5.txt b/Documentation/RelNotes/1.5.5.5.txt index 30fa3615c7..30fa3615c7 100644 --- a/Documentation/RelNotes-1.5.5.5.txt +++ b/Documentation/RelNotes/1.5.5.5.txt diff --git a/Documentation/RelNotes-1.5.5.6.txt b/Documentation/RelNotes/1.5.5.6.txt index d5e85cb70e..d5e85cb70e 100644 --- a/Documentation/RelNotes-1.5.5.6.txt +++ b/Documentation/RelNotes/1.5.5.6.txt diff --git a/Documentation/RelNotes-1.5.5.txt b/Documentation/RelNotes/1.5.5.txt index 2932212488..2932212488 100644 --- a/Documentation/RelNotes-1.5.5.txt +++ b/Documentation/RelNotes/1.5.5.txt diff --git a/Documentation/RelNotes-1.5.6.1.txt b/Documentation/RelNotes/1.5.6.1.txt index 4864b16445..4864b16445 100644 --- a/Documentation/RelNotes-1.5.6.1.txt +++ b/Documentation/RelNotes/1.5.6.1.txt diff --git a/Documentation/RelNotes-1.5.6.2.txt b/Documentation/RelNotes/1.5.6.2.txt index 5902a85a78..5902a85a78 100644 --- a/Documentation/RelNotes-1.5.6.2.txt +++ b/Documentation/RelNotes/1.5.6.2.txt diff --git a/Documentation/RelNotes-1.5.6.3.txt b/Documentation/RelNotes/1.5.6.3.txt index 942611299d..f61dd3504a 100644 --- a/Documentation/RelNotes-1.5.6.3.txt +++ b/Documentation/RelNotes/1.5.6.3.txt @@ -4,7 +4,7 @@ GIT v1.5.6.3 Release Notes Fixes since v1.5.6.2 -------------------- -* Setting core.sharerepository to traditional "true" value was supposed to make +* Setting core.sharedrepository to traditional "true" value was supposed to make the repository group writable but should not affect permission for others. However, since 1.5.6, it was broken to drop permission for others when umask is 022, making the repository unreadable by others. diff --git a/Documentation/RelNotes-1.5.6.4.txt b/Documentation/RelNotes/1.5.6.4.txt index d8968f1ecb..d8968f1ecb 100644 --- a/Documentation/RelNotes-1.5.6.4.txt +++ b/Documentation/RelNotes/1.5.6.4.txt diff --git a/Documentation/RelNotes-1.5.6.5.txt b/Documentation/RelNotes/1.5.6.5.txt index 47ca172462..47ca172462 100644 --- a/Documentation/RelNotes-1.5.6.5.txt +++ b/Documentation/RelNotes/1.5.6.5.txt diff --git a/Documentation/RelNotes-1.5.6.6.txt b/Documentation/RelNotes/1.5.6.6.txt index 79da23db5a..79da23db5a 100644 --- a/Documentation/RelNotes-1.5.6.6.txt +++ b/Documentation/RelNotes/1.5.6.6.txt diff --git a/Documentation/RelNotes-1.5.6.txt b/Documentation/RelNotes/1.5.6.txt index e143d8d61b..e143d8d61b 100644 --- a/Documentation/RelNotes-1.5.6.txt +++ b/Documentation/RelNotes/1.5.6.txt diff --git a/Documentation/RelNotes-1.6.0.1.txt b/Documentation/RelNotes/1.6.0.1.txt index 49d7a1cafa..49d7a1cafa 100644 --- a/Documentation/RelNotes-1.6.0.1.txt +++ b/Documentation/RelNotes/1.6.0.1.txt diff --git a/Documentation/RelNotes-1.6.0.2.txt b/Documentation/RelNotes/1.6.0.2.txt index 51b32f5d94..e1e24b3295 100644 --- a/Documentation/RelNotes-1.6.0.2.txt +++ b/Documentation/RelNotes/1.6.0.2.txt @@ -17,7 +17,7 @@ Fixes since v1.6.0.1 * Many commands did not use the correct working tree location when used with GIT_WORK_TREE environment settings. -* Some systems needs to use compatibility fnmach and regex libraries +* Some systems need to use compatibility fnmatch and regex libraries independent from each other; the compat/ area has been reorganized to allow this. diff --git a/Documentation/RelNotes-1.6.0.3.txt b/Documentation/RelNotes/1.6.0.3.txt index ae0577836a..ae0577836a 100644 --- a/Documentation/RelNotes-1.6.0.3.txt +++ b/Documentation/RelNotes/1.6.0.3.txt diff --git a/Documentation/RelNotes-1.6.0.4.txt b/Documentation/RelNotes/1.6.0.4.txt index d522661d31..d522661d31 100644 --- a/Documentation/RelNotes-1.6.0.4.txt +++ b/Documentation/RelNotes/1.6.0.4.txt diff --git a/Documentation/RelNotes-1.6.0.5.txt b/Documentation/RelNotes/1.6.0.5.txt index a08bb96738..a08bb96738 100644 --- a/Documentation/RelNotes-1.6.0.5.txt +++ b/Documentation/RelNotes/1.6.0.5.txt diff --git a/Documentation/RelNotes-1.6.0.6.txt b/Documentation/RelNotes/1.6.0.6.txt index 64ece1ffd5..64ece1ffd5 100644 --- a/Documentation/RelNotes-1.6.0.6.txt +++ b/Documentation/RelNotes/1.6.0.6.txt diff --git a/Documentation/RelNotes-1.6.0.txt b/Documentation/RelNotes/1.6.0.txt index de7ef166b6..de7ef166b6 100644 --- a/Documentation/RelNotes-1.6.0.txt +++ b/Documentation/RelNotes/1.6.0.txt diff --git a/Documentation/RelNotes-1.6.1.1.txt b/Documentation/RelNotes/1.6.1.1.txt index 8c594ba02f..8c594ba02f 100644 --- a/Documentation/RelNotes-1.6.1.1.txt +++ b/Documentation/RelNotes/1.6.1.1.txt diff --git a/Documentation/RelNotes-1.6.1.2.txt b/Documentation/RelNotes/1.6.1.2.txt index be37cbb858..be37cbb858 100644 --- a/Documentation/RelNotes-1.6.1.2.txt +++ b/Documentation/RelNotes/1.6.1.2.txt diff --git a/Documentation/RelNotes-1.6.1.3.txt b/Documentation/RelNotes/1.6.1.3.txt index 6f0bde156a..6f0bde156a 100644 --- a/Documentation/RelNotes-1.6.1.3.txt +++ b/Documentation/RelNotes/1.6.1.3.txt diff --git a/Documentation/RelNotes-1.6.1.4.txt b/Documentation/RelNotes/1.6.1.4.txt index 0ce6316d75..0ce6316d75 100644 --- a/Documentation/RelNotes-1.6.1.4.txt +++ b/Documentation/RelNotes/1.6.1.4.txt diff --git a/Documentation/RelNotes-1.6.1.txt b/Documentation/RelNotes/1.6.1.txt index adb7ccab0a..adb7ccab0a 100644 --- a/Documentation/RelNotes-1.6.1.txt +++ b/Documentation/RelNotes/1.6.1.txt diff --git a/Documentation/RelNotes-1.6.2.1.txt b/Documentation/RelNotes/1.6.2.1.txt index dfa36416af..dfa36416af 100644 --- a/Documentation/RelNotes-1.6.2.1.txt +++ b/Documentation/RelNotes/1.6.2.1.txt diff --git a/Documentation/RelNotes-1.6.2.2.txt b/Documentation/RelNotes/1.6.2.2.txt index fafa9986b0..fafa9986b0 100644 --- a/Documentation/RelNotes-1.6.2.2.txt +++ b/Documentation/RelNotes/1.6.2.2.txt diff --git a/Documentation/RelNotes-1.6.2.3.txt b/Documentation/RelNotes/1.6.2.3.txt index 4d3c1ac91c..4d3c1ac91c 100644 --- a/Documentation/RelNotes-1.6.2.3.txt +++ b/Documentation/RelNotes/1.6.2.3.txt diff --git a/Documentation/RelNotes-1.6.2.4.txt b/Documentation/RelNotes/1.6.2.4.txt index f4bf1d0986..f4bf1d0986 100644 --- a/Documentation/RelNotes-1.6.2.4.txt +++ b/Documentation/RelNotes/1.6.2.4.txt diff --git a/Documentation/RelNotes-1.6.2.5.txt b/Documentation/RelNotes/1.6.2.5.txt index b23f9e95d1..b23f9e95d1 100644 --- a/Documentation/RelNotes-1.6.2.5.txt +++ b/Documentation/RelNotes/1.6.2.5.txt diff --git a/Documentation/RelNotes-1.6.2.txt b/Documentation/RelNotes/1.6.2.txt index ad060f4f89..ad060f4f89 100644 --- a/Documentation/RelNotes-1.6.2.txt +++ b/Documentation/RelNotes/1.6.2.txt diff --git a/Documentation/RelNotes-1.6.3.1.txt b/Documentation/RelNotes/1.6.3.1.txt index 2400b72ef7..2400b72ef7 100644 --- a/Documentation/RelNotes-1.6.3.1.txt +++ b/Documentation/RelNotes/1.6.3.1.txt diff --git a/Documentation/RelNotes-1.6.3.2.txt b/Documentation/RelNotes/1.6.3.2.txt index b2f3f0293c..b2f3f0293c 100644 --- a/Documentation/RelNotes-1.6.3.2.txt +++ b/Documentation/RelNotes/1.6.3.2.txt diff --git a/Documentation/RelNotes-1.6.3.3.txt b/Documentation/RelNotes/1.6.3.3.txt index 1c28398bb6..1c28398bb6 100644 --- a/Documentation/RelNotes-1.6.3.3.txt +++ b/Documentation/RelNotes/1.6.3.3.txt diff --git a/Documentation/RelNotes-1.6.3.4.txt b/Documentation/RelNotes/1.6.3.4.txt index cad461bc76..cad461bc76 100644 --- a/Documentation/RelNotes-1.6.3.4.txt +++ b/Documentation/RelNotes/1.6.3.4.txt diff --git a/Documentation/RelNotes-1.6.3.txt b/Documentation/RelNotes/1.6.3.txt index 418c685cf8..418c685cf8 100644 --- a/Documentation/RelNotes-1.6.3.txt +++ b/Documentation/RelNotes/1.6.3.txt diff --git a/Documentation/RelNotes-1.6.4.1.txt b/Documentation/RelNotes/1.6.4.1.txt index e439e45b96..e439e45b96 100644 --- a/Documentation/RelNotes-1.6.4.1.txt +++ b/Documentation/RelNotes/1.6.4.1.txt diff --git a/Documentation/RelNotes-1.6.4.2.txt b/Documentation/RelNotes/1.6.4.2.txt index c11ec0115c..c11ec0115c 100644 --- a/Documentation/RelNotes-1.6.4.2.txt +++ b/Documentation/RelNotes/1.6.4.2.txt diff --git a/Documentation/RelNotes-1.6.4.3.txt b/Documentation/RelNotes/1.6.4.3.txt index 4f29babdeb..5643e6537d 100644 --- a/Documentation/RelNotes-1.6.4.3.txt +++ b/Documentation/RelNotes/1.6.4.3.txt @@ -11,7 +11,7 @@ Fixes since v1.6.4.2 been deprecated. * "git fetch" and "git clone" had an extra sanity check to verify the - presense of the corresponding *.pack file before downloading *.idx + presence of the corresponding *.pack file before downloading *.idx file by issuing a HEAD request. Github server however sometimes gave 500 (Internal server error) response to HEAD even if a GET request for *.pack file to the same URL would have succeeded, and broke diff --git a/Documentation/RelNotes-1.6.4.4.txt b/Documentation/RelNotes/1.6.4.4.txt index 0ead45fc72..0ead45fc72 100644 --- a/Documentation/RelNotes-1.6.4.4.txt +++ b/Documentation/RelNotes/1.6.4.4.txt diff --git a/Documentation/RelNotes/1.6.4.5.txt b/Documentation/RelNotes/1.6.4.5.txt new file mode 100644 index 0000000000..eb6307dcbb --- /dev/null +++ b/Documentation/RelNotes/1.6.4.5.txt @@ -0,0 +1,20 @@ +Git v1.6.4.5 Release Notes +========================== + +Fixes since v1.6.4.4 +-------------------- + + * Simplified base85 implementation. + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git count-objects" did not handle packs larger than 4G. + + * "git rev-parse --parseopt --stop-at-non-option" did not stop at non option + when --keep-dashdash was in effect. + + * "gitweb" can sometimes be tricked into parrotting a filename argument + given in a request without properly quoting. + +Other minor fixes and documentation updates are included. diff --git a/Documentation/RelNotes-1.6.4.txt b/Documentation/RelNotes/1.6.4.txt index 7a904419f7..7a904419f7 100644 --- a/Documentation/RelNotes-1.6.4.txt +++ b/Documentation/RelNotes/1.6.4.txt diff --git a/Documentation/RelNotes-1.6.5.1.txt b/Documentation/RelNotes/1.6.5.1.txt index 309ba181b2..309ba181b2 100644 --- a/Documentation/RelNotes-1.6.5.1.txt +++ b/Documentation/RelNotes/1.6.5.1.txt diff --git a/Documentation/RelNotes-1.6.5.2.txt b/Documentation/RelNotes/1.6.5.2.txt index aa7ccce3a2..aa7ccce3a2 100644 --- a/Documentation/RelNotes-1.6.5.2.txt +++ b/Documentation/RelNotes/1.6.5.2.txt diff --git a/Documentation/RelNotes-1.6.5.3.txt b/Documentation/RelNotes/1.6.5.3.txt index b2fad1b22e..b2fad1b22e 100644 --- a/Documentation/RelNotes-1.6.5.3.txt +++ b/Documentation/RelNotes/1.6.5.3.txt diff --git a/Documentation/RelNotes-1.6.5.4.txt b/Documentation/RelNotes/1.6.5.4.txt index e42f8b2397..d3a2a3e712 100644 --- a/Documentation/RelNotes-1.6.5.4.txt +++ b/Documentation/RelNotes/1.6.5.4.txt @@ -26,7 +26,7 @@ Fixes since v1.6.5.3 future versions, but not in this release, * "git merge -m <message> <branch>..." added the standard merge message - on its own after user-supplied message, which should have overrided the + on its own after user-supplied message, which should have overridden the standard one. Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.5.5.txt b/Documentation/RelNotes/1.6.5.5.txt index ecfc57d875..ecfc57d875 100644 --- a/Documentation/RelNotes-1.6.5.5.txt +++ b/Documentation/RelNotes/1.6.5.5.txt diff --git a/Documentation/RelNotes-1.6.5.6.txt b/Documentation/RelNotes/1.6.5.6.txt index a9eaf76f62..a9eaf76f62 100644 --- a/Documentation/RelNotes-1.6.5.6.txt +++ b/Documentation/RelNotes/1.6.5.6.txt diff --git a/Documentation/RelNotes-1.6.5.7.txt b/Documentation/RelNotes/1.6.5.7.txt index 5b49ea53be..dc5302c21c 100644 --- a/Documentation/RelNotes-1.6.5.7.txt +++ b/Documentation/RelNotes/1.6.5.7.txt @@ -10,7 +10,7 @@ Fixes since v1.6.5.6 an older version of git should just ignore them. Instead we diagnosed it as an error. -* With help.autocorrect set to non-zero value, the logic to guess typoes +* With help.autocorrect set to non-zero value, the logic to guess typos in the subcommand name misfired and ran a random nonsense command. * If a command is run with an absolute path as a pathspec inside a bare diff --git a/Documentation/RelNotes/1.6.5.8.txt b/Documentation/RelNotes/1.6.5.8.txt new file mode 100644 index 0000000000..8b24bebb96 --- /dev/null +++ b/Documentation/RelNotes/1.6.5.8.txt @@ -0,0 +1,28 @@ +Git v1.6.5.8 Release Notes +========================== + +Fixes since v1.6.5.7 +-------------------- + +* "git count-objects" did not handle packfiles that are bigger than 4G on + platforms with 32-bit off_t. + +* "git rebase -i" did not abort cleanly if it failed to launch the editor. + +* "git blame" did not work well when commit lacked the author name. + +* "git fast-import" choked when handling a tag that points at an object + that is not a commit. + +* "git reset --hard" did not work correctly when GIT_WORK_TREE environment + variable is used to point at the root of the true work tree. + +* "git grep" fed a buffer that is not NUL-terminated to underlying + regexec(). + +* "git checkout -m other" while on a branch that does not have any commit + segfaulted, instead of failing. + +* "git branch -a other" should have diagnosed the command as an error. + +Other minor documentation updates are also included. diff --git a/Documentation/RelNotes/1.6.5.9.txt b/Documentation/RelNotes/1.6.5.9.txt new file mode 100644 index 0000000000..bb469dd71e --- /dev/null +++ b/Documentation/RelNotes/1.6.5.9.txt @@ -0,0 +1,18 @@ +Git v1.6.5.9 Release Notes +========================== + +Fixes since v1.6.5.8 +-------------------- + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git blame -L $start,$end" segfaulted when too large $start was given. + + * "git rev-parse --parseopt --stop-at-non-option" did not stop at non option + when --keep-dashdash was in effect. + + * "gitweb" can sometimes be tricked into parrotting a filename argument + given in a request without properly quoting. + +Other minor fixes and documentation updates are included. diff --git a/Documentation/RelNotes-1.6.5.txt b/Documentation/RelNotes/1.6.5.txt index ee141c19ad..ee141c19ad 100644 --- a/Documentation/RelNotes-1.6.5.txt +++ b/Documentation/RelNotes/1.6.5.txt diff --git a/Documentation/RelNotes/1.6.6.1.txt b/Documentation/RelNotes/1.6.6.1.txt new file mode 100644 index 0000000000..f1d0a4ae2d --- /dev/null +++ b/Documentation/RelNotes/1.6.6.1.txt @@ -0,0 +1,37 @@ +Git v1.6.6.1 Release Notes +========================== + +Fixes since v1.6.6 +------------------ + + * "git blame" did not work well when commit lacked the author name. + + * "git branch -a name" wasn't diagnosed as an error. + + * "git count-objects" did not handle packfiles that are bigger than 4G on + platforms with 32-bit off_t. + + * "git checkout -m other" while on a branch that does not have any commit + segfaulted, instead of failing. + + * "git fast-import" choked when fed a tag that do not point at a + commit. + + * "git grep" finding from work tree files could have fed garbage to + the underlying regexec(3). + + * "git grep -L" didn't show empty files (they should never match, and + they should always appear in -L output as unmatching). + + * "git rebase -i" did not abort cleanly if it failed to launch the editor. + + * "git reset --hard" did not work correctly when GIT_WORK_TREE environment + variable is used to point at the root of the true work tree. + + * http-backend was not listed in the command list in the documentation. + + * Building on FreeBSD (both 7 and 8) needs OLD_ICONV set in the Makefile + + * "git checkout -m some-branch" while on an unborn branch crashed. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.6.2.txt b/Documentation/RelNotes/1.6.6.2.txt new file mode 100644 index 0000000000..4eaddc0106 --- /dev/null +++ b/Documentation/RelNotes/1.6.6.2.txt @@ -0,0 +1,46 @@ +Git v1.6.6.2 Release Notes +========================== + +Fixes since v1.6.6.1 +-------------------- + + * recursive merge didn't correctly diagnose its own programming errors, + and instead caused the caller to segfault. + + * The new "smart http" aware clients probed the web servers to see if + they support smart http, but did not fall back to dumb http transport + correctly with some servers. + + * Time based reflog syntax e.g. "@{yesterday}" didn't diagnose a misspelled + time specification and instead assumed "@{now}". + + * "git archive HEAD -- no-such-directory" produced an empty archive + without complaining. + + * "git blame -L start,end -- file" misbehaved when given a start that is + larger than the number of lines in the file. + + * "git checkout -m" didn't correctly call custom merge backend supplied + by the end user. + + * "git config -f <file>" misbehaved when run from a subdirectory. + + * "git cvsserver" didn't like having regex metacharacters (e.g. '+') in + CVSROOT environment. + + * "git fast-import" did not correctly handle large blobs that may + bust the pack size limit. + + * "git gui" is supposed to work even when launched from inside a .git + directory. + + * "git gui" misbehaved when applying a hunk that ends with deletion. + + * "git imap-send" did not honor imap.preformattedHTML as documented. + + * "git log" family incorrectly showed the commit notes unconditionally by + mistake, which was especially irritating when running "git log --oneline". + + * "git status" shouldn't require an write access to the repository. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.6.3.txt b/Documentation/RelNotes/1.6.6.3.txt new file mode 100644 index 0000000000..11483acaec --- /dev/null +++ b/Documentation/RelNotes/1.6.6.3.txt @@ -0,0 +1,23 @@ +Git v1.6.6.3 Release Notes +========================== + +Fixes since v1.6.6.2 +-------------------- + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git bisect $path" did not correctly diagnose an error when given a + non-existent path. + + * "git blame -L $start,$end" segfaulted when too large $start was given. + + * "git imap-send" did not write draft box with CRLF line endings per RFC. + + * "git rev-parse --parseopt --stop-at-non-option" did not stop at non option + when --keep-dashdash was in effect. + + * "gitweb" can sometimes be tricked into parrotting a filename argument + given in a request without properly quoting. + +Other minor fixes and documentation updates are included. diff --git a/Documentation/RelNotes-1.6.6.txt b/Documentation/RelNotes/1.6.6.txt index 04e205c457..c50b59c495 100644 --- a/Documentation/RelNotes-1.6.6.txt +++ b/Documentation/RelNotes/1.6.6.txt @@ -29,7 +29,7 @@ or adjust to the new behaviour, on the day their sysadmin decides to install the new version of git. When we switched from "git-foo" to "git foo" in 1.6.0, even though the change had been advertised and the transition guide had been provided for a very long time, the users procrastinated -during the entire transtion period, and ended up panicking on the day +during the entire transition period, and ended up panicking on the day their sysadmins updated their git installation. We are trying to avoid repeating that unpleasantness in the 1.7.0 release. @@ -94,7 +94,7 @@ users will fare this time. * "git diff" traditionally treated various "ignore whitespace" options only as a way to filter the patch output. "git diff --exit-code -b" exited with non-zero status even if all changes were about changing the - ammount of whitespace and nothing else. and "git diff -b" showed the + amount of whitespace and nothing else. and "git diff -b" showed the "diff --git" header line for such a change without patch text. In 1.7.0, the "ignore whitespaces" will affect the semantics of the diff --git a/Documentation/RelNotes/1.7.0.1.txt b/Documentation/RelNotes/1.7.0.1.txt new file mode 100644 index 0000000000..8ff5bcada8 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.1.txt @@ -0,0 +1,35 @@ +Git v1.7.0.1 Release Notes +========================== + +Fixes since v1.7.0 +------------------ + + * In a freshly created repository "rev-parse HEAD^0" complained that + it is dangling symref, even though "rev-parse HEAD" didn't. + + * "git show :no-such-name" tried to access the index without bounds + check, leading to a potential segfault. + + * Message from "git cherry-pick" was harder to read and use than necessary + when it stopped due to conflicting changes. + + * We referred to ".git/refs/" throughout the documentation when we + meant to talk about abstract notion of "ref namespace". Because + people's repositories often have packed refs these days, this was + confusing. + + * "git diff --output=/path/that/cannot/be/written" did not correctly + error out. + + * "git grep -e -pattern-that-begin-with-dash paths..." could not be + spelled as "git grep -- -pattern-that-begin-with-dash paths..." which + would be a GNU way to use "--" as "end of options". + + * "git grep" compiled with threading support tried to access an + uninitialized mutex on boxes with a single CPU. + + * "git stash pop -q --index" failed because the unnecessary --index + option was propagated to "git stash drop" that is internally run at the + end. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.0.2.txt b/Documentation/RelNotes/1.7.0.2.txt new file mode 100644 index 0000000000..fcb46ca6a4 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.2.txt @@ -0,0 +1,40 @@ +Git v1.7.0.2 Release Notes +========================== + +Fixes since v1.7.0.1 +-------------------- + + * GIT_PAGER was not honored consistently by some scripted Porcelains, most + notably "git am". + + * updating working tree files after telling git to add them to the + index and while it is still working created garbage object files in + the repository without diagnosing it as an error. + + * "git bisect -- pathspec..." did not diagnose an error condition properly when + the simplification with given pathspec made the history empty. + + * "git rev-list --cherry-pick A...B" now has an obvious optimization when the + histories haven't diverged (i.e. when one end is an ancestor of the other). + + * "git diff --quiet -w" did not work as expected. + + * "git fast-import" didn't work with a large input, as it lacked support + for producing the pack index in v2 format. + + * "git imap-send" didn't use CRLF line endings over the imap protocol + when storing its payload to the draft box, violating RFC 3501. + + * "git log --format='%w(x,y,z)%b'" and friends that rewrap message + has been optimized for utf-8 payload. + + * Error messages generated on the receiving end did not come back to "git + push". + + * "git status" in 1.7.0 lacked the optimization we used to have in 1.6.X series + to speed up scanning of large working tree. + + * "gitweb" did not diagnose parsing errors properly while reading tis configuration + file. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.0.3.txt b/Documentation/RelNotes/1.7.0.3.txt new file mode 100644 index 0000000000..3b355737c0 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.3.txt @@ -0,0 +1,34 @@ +Git v1.7.0.3 Release Notes +========================== + +Fixes since v1.7.0.2 +-------------------- + + * Object files are created in a more ACL friendly way in repositories + where group permission is ACL controlled. + + * "git add -i" didn't handle a deleted path very well. + + * "git blame" padded line numbers with one extra SP when the total number + of lines was one less than multiple of ten due to an off-by-one error. + + * "git fetch --all/--multi" used to discard information for remotes that + are fetched earlier. + + * "git log --author=me --grep=it" tried to find commits that have "it" + or are written by "me", instead of the ones that have "it" _and_ are + written by "me". + + * "git log -g branch" misbehaved when there was no entries in the reflog + for the named branch. + + * "git mailinfo" (hence "git am") incorrectly removed initial indent from + paragraphs. + + * "git prune" and "git reflog" (hence "git gc" as well) didn't honor + an instruction never to expire by setting gc.reflogexpire to never. + + * "git push" misbehaved when branch.<name>.merge was configured without + matching branch.<name>.remote. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.0.4.txt b/Documentation/RelNotes/1.7.0.4.txt new file mode 100644 index 0000000000..cf7f60e60d --- /dev/null +++ b/Documentation/RelNotes/1.7.0.4.txt @@ -0,0 +1,27 @@ +Git v1.7.0.4 Release Notes +========================== + +Fixes since v1.7.0.3 +-------------------- + + * Optimized ntohl/htonl on big-endian machines were broken. + + * Color values given to "color.<cmd>.<slot>" configuration can now have + more than one attributes (e.g. "bold ul"). + + * "git add -u nonexistent-path" did not complain. + + * "git apply --whitespace=fix" didn't work well when an early patch in + a patch series adds trailing blank lines and a later one depended on + such a block of blank lines at the end. + + * "git fast-export" didn't check error status and stop when marks file + cannot be opened. + + * "git format-patch --ignore-if-in-upstream" gave unwarranted errors + when the range was empty, instead of silently finishing. + + * "git remote prune" did not detect remote tracking refs that became + dangling correctly. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.0.5.txt b/Documentation/RelNotes/1.7.0.5.txt new file mode 100644 index 0000000000..3149c91b7b --- /dev/null +++ b/Documentation/RelNotes/1.7.0.5.txt @@ -0,0 +1,26 @@ +Git v1.7.0.5 Release Notes +========================== + +Fixes since v1.7.0.4 +-------------------- + + * "git daemon" failed to compile on platforms without sockaddr_storage type. + + * Output from "git rev-list --pretty=oneline" was unparsable when a + commit did not have any message, which is abnormal but possible in a + repository converted from foreign scm. + + * "git stash show <commit-that-is-not-a-stash>" gave an error message + that was not so useful. Reworded the message to "<it> is not a + stash". + + * Python scripts in contrib/ area now start with "#!/usr/bin/env python" + to honor user's PATH. + + * "git imap-send" used to mistake any line that begins with "From " as a + message separator in format-patch output. + + * Smart http server backend failed to report an internal server error and + infinitely looped instead after output pipe was closed. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.0.6.txt b/Documentation/RelNotes/1.7.0.6.txt new file mode 100644 index 0000000000..b2852b67d0 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.6.txt @@ -0,0 +1,13 @@ +Git v1.7.0.6 Release Notes +========================== + +Fixes since v1.7.0.5 +-------------------- + + * "git diff --stat" used "int" to count the size of differences, + which could result in overflowing. + + * "git rev-list --abbrev-commit" defaulted to 40-byte abbreviations, unlike + newer tools in the git toolset. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.0.7.txt b/Documentation/RelNotes/1.7.0.7.txt new file mode 100644 index 0000000000..d0cb7ca7e2 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.7.txt @@ -0,0 +1,16 @@ +Git v1.7.0.7 Release Notes +========================== + +Fixes since v1.7.0.6 +-------------------- + + * "make NO_CURL=NoThanks install" was broken. + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git config --path conf.var" to attempt to expand a variable conf.var + that uses "~/" short-hand segfaulted when $HOME environment variable + was not set. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.0.8.txt b/Documentation/RelNotes/1.7.0.8.txt new file mode 100644 index 0000000000..7f05b48e17 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.8.txt @@ -0,0 +1,10 @@ +Git v1.7.0.8 Release Notes +========================== + +This is primarily to backport support for the new "add.ignoreErrors" +name given to the existing "add.ignore-errors" configuration variable. + +The next version, Git 1.7.4, and future versions, will support both +old and incorrect name and the new corrected name, but without this +backport, users who want to use the new name "add.ignoreErrors" in +their repositories cannot use older versions of Git. diff --git a/Documentation/RelNotes/1.7.0.9.txt b/Documentation/RelNotes/1.7.0.9.txt new file mode 100644 index 0000000000..bfb3166387 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.9.txt @@ -0,0 +1,8 @@ +Git v1.7.0.9 Release Notes +========================== + +Fixes since v1.7.0.8 +-------------------- + + * "gitweb" can sometimes be tricked into parrotting a filename argument + given in a request without properly quoting. diff --git a/Documentation/RelNotes/1.7.0.txt b/Documentation/RelNotes/1.7.0.txt new file mode 100644 index 0000000000..0bb8c0b2a2 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.txt @@ -0,0 +1,214 @@ +Git v1.7.0 Release Notes +======================== + +Notes on behaviour change +------------------------- + + * "git push" into a branch that is currently checked out (i.e. pointed at by + HEAD in a repository that is not bare) is refused by default. + + Similarly, "git push $there :$killed" to delete the branch $killed + in a remote repository $there, when $killed branch is the current + branch pointed at by its HEAD, will be refused by default. + + Setting the configuration variables receive.denyCurrentBranch and + receive.denyDeleteCurrent to 'ignore' in the receiving repository + can be used to override these safety features. + + * "git send-email" does not make deep threads by default when sending a + patch series with more than two messages. All messages will be sent + as a reply to the first message, i.e. cover letter. + + It has been possible already to configure send-email to send "shallow thread" + by setting sendemail.chainreplyto configuration variable to false. The + only thing this release does is to change the default when you haven't + configured that variable. + + * "git status" is not "git commit --dry-run" anymore. This change does + not affect you if you run the command without argument. + + * "git diff" traditionally treated various "ignore whitespace" options + only as a way to filter the patch output. "git diff --exit-code -b" + exited with non-zero status even if all changes were about changing the + amount of whitespace and nothing else; and "git diff -b" showed the + "diff --git" header line for such a change without patch text. + + In this release, the "ignore whitespaces" options affect the semantics + of the diff operation. A change that does not affect anything but + whitespaces is reported with zero exit status when run with + --exit-code, and there is no "diff --git" header for such a change. + + * External diff and textconv helpers are now executed using the shell. + This makes them consistent with other programs executed by git, and + allows you to pass command-line parameters to the helpers. Any helper + paths containing spaces or other metacharacters now need to be + shell-quoted. The affected helpers are GIT_EXTERNAL_DIFF in the + environment, and diff.*.command and diff.*.textconv in the config + file. + + * The --max-pack-size argument to 'git repack', 'git pack-objects', and + 'git fast-import' was assuming the provided size to be expressed in MiB, + unlike the corresponding config variable and other similar options accepting + a size value. It is now expecting a size expressed in bytes, with a possible + unit suffix of 'k', 'm', or 'g'. + +Updates since v1.6.6 +-------------------- + +(subsystems) + + * "git fast-import" updates; adds "option" and "feature" to detect the + mismatch between fast-import and the frontends that produce the input + stream. + + * "git svn" support of subversion "merge tickets" and miscellaneous fixes. + + * "gitk" and "git gui" translation updates. + + * "gitweb" updates (code clean-up, load checking etc.) + +(portability) + + * Some more MSVC portability patches for msysgit port. + + * Minimum Pthreads emulation for msysgit port. + +(performance) + + * More performance improvement patches for msysgit port. + +(usability, bells and whistles) + + * More commands learned "--quiet" and "--[no-]progress" options. + + * Various commands given by the end user (e.g. diff.type.textconv, + and GIT_EDITOR) can be specified with command line arguments. E.g. it + is now possible to say "[diff "utf8doc"] textconv = nkf -w". + + * "sparse checkout" feature allows only part of the work tree to be + checked out. + + * HTTP transfer can use authentication scheme other than basic + (i.e./e.g. digest). + + * Switching from a version of superproject that used to have a submodule + to another version of superproject that no longer has it did not remove + the submodule directory when it should (namely, when you are not + interested in the submodule at all and didn't clone/checkout). + + * A new attribute conflict-marker-size can be used to change the size of + the conflict markers from the default 7; this is useful when tracked + contents (e.g. git-merge documentation) have strings that resemble the + conflict markers. + + * A new syntax "<branch>@{upstream}" can be used on the command line to + substitute the name of the "upstream" of the branch. Missing branch + defaults to the current branch, so "git fetch && git merge @{upstream}" + will be equivalent to "git pull". + + * "git am --resolved" has a synonym "git am --continue". + + * "git branch --set-upstream" can be used to update the (surprise!) upstream, + i.e. where the branch is supposed to pull and merge from (or rebase onto). + + * "git checkout A...B" is a way to detach HEAD at the merge base between + A and B. + + * "git checkout -m path" to reset the work tree file back into the + conflicted state works even when you already ran "git add path" and + resolved the conflicts. + + * "git commit --date='<date>'" can be used to override the author date + just like "git commit --author='<name> <email>'" can be used to + override the author identity. + + * "git commit --no-status" can be used to omit the listing of the index + and the work tree status in the editor used to prepare the log message. + + * "git commit" warns a bit more aggressively until you configure user.email, + whose default value almost always is not (and fundamentally cannot be) + what you want. + + * "git difftool" has been extended to make it easier to integrate it + with gitk. + + * "git fetch --all" can now be used in place of "git remote update". + + * "git grep" does not rely on external grep anymore. It can use more than + one thread to accelerate the operation. + + * "git grep" learned "--quiet" option. + + * "git log" and friends learned "--glob=heads/*" syntax that is a more + flexible way to complement "--branches/--tags/--remotes". + + * "git merge" learned to pass options specific to strategy-backends. E.g. + + - "git merge -Xsubtree=path/to/directory" can be used to tell the subtree + strategy how much to shift the trees explicitly. + + - "git merge -Xtheirs" can be used to auto-merge as much as possible, + while discarding your own changes and taking merged version in + conflicted regions. + + * "git push" learned "git push origin --delete branch", a syntactic sugar + for "git push origin :branch". + + * "git push" learned "git push --set-upstream origin forker:forkee" that + lets you configure your "forker" branch to later pull from "forkee" + branch at "origin". + + * "git rebase --onto A...B" means the history is replayed on top of the + merge base between A and B. + + * "git rebase -i" learned new action "fixup" that squashes the change + but does not affect existing log message. + + * "git rebase -i" also learned --autosquash option that is useful + together with the new "fixup" action. + + * "git remote" learned set-url subcommand that updates (surprise!) url + for an existing remote nickname. + + * "git rerere" learned "forget path" subcommand. Together with "git + checkout -m path" it will be useful when you recorded a wrong + resolution. + + * Use of "git reset --merge" has become easier when resetting away a + conflicted mess left in the work tree. + + * "git rerere" had rerere.autoupdate configuration but there was no way + to countermand it from the command line; --no-rerere-autoupdate option + given to "merge", "revert", etc. fixes this. + + * "git status" learned "-s(hort)" output format. + +(developers) + + * The infrastructure to build foreign SCM interface has been updated. + + * Many more commands are now built-in. + + * THREADED_DELTA_SEARCH is no more. If you build with threads, delta + compression will always take advantage of it. + +Fixes since v1.6.6 +------------------ + +All of the fixes in v1.6.6.X maintenance series are included in this +release, unless otherwise noted. + + * "git branch -d branch" used to refuse deleting the branch even when + the branch is fully merged to its upstream branch if it is not merged + to the current branch. It now deletes it in such a case. + + * "filter-branch" command incorrectly said --prune-empty and --filter-commit + were incompatible; the latter should be read as --commit-filter. + + * When using "git status" or asking "git diff" to compare the work tree + with something, they used to consider that a checked-out submodule with + uncommitted changes is not modified; this could cause people to forget + committing these changes in the submodule before committing in the + superproject. They now consider such a change as a modification and + "git diff" will append a "-dirty" to the work tree side when generating + patch output or when used with the --submodule option. diff --git a/Documentation/RelNotes/1.7.1.1.txt b/Documentation/RelNotes/1.7.1.1.txt new file mode 100644 index 0000000000..3f6b3148a3 --- /dev/null +++ b/Documentation/RelNotes/1.7.1.1.txt @@ -0,0 +1,96 @@ +Git v1.7.1.1 Release Notes +========================== + +Fixes since v1.7.1 +------------------ + + * Authentication over http transport can now be made lazily, in that the + request can first go to a URL without username, get a 401 response and + then the client will ask for the username to use. + + * We used to mistakenly think "../work" is a subdirectory of the current + directory when we are in "../work-xyz". + + * The attribute mechanism now allows an entry that uses an attribute + macro that set/unset one attribute, immediately followed by an + overriding setting; this makes attribute macros much easier to use. + + * We didn't recognize timezone "Z" as a synonym for "UTC" (75b37e70). + + * In 1.7.0, read-tree and user commands that use the mechanism such as + checkout and merge were fixed to handle switching between branches one + of which has a file while the other has a directory at the same path + correctly even when there are some "confusing" pathnames in them. But + the algorithm used for this fix was suboptimal and had a terrible + performance degradation especially in larger trees. + + * "git am -3" did not show diagnosis when the patch in the message was corrupt. + + * After "git apply --whitespace=fix" removed trailing blank lines in an + patch in a patch series, it failed to apply later patches that depend + on the presence of such blank lines. + + * "git bundle --stdin" segfaulted. + + * "git checkout" and "git rebase" overwrote paths that are marked "assume + unchanged". + + * "git commit --amend" on a commit with an invalid author-name line that + lacks the display name didn't work. + + * "git describe" did not tie-break tags that point at the same commit + correctly; newer ones are preferred by paying attention to the + tagger date now. + + * "git diff" used to tell underlying xdiff machinery to work very hard to + minimize the output, but this often was spending too many extra cycles + for very little gain. + + * "git diff --color" did not paint extended diff headers per line + (i.e. the coloring escape sequence didn't end at the end of line), + which confused "less -R". + + * "git fetch" over HTTP verifies the downloaded packfiles more robustly. + + * The memory usage by "git index-pack" (run during "git fetch" and "git + push") got leaner. + + * "GIT_DIR=foo.git git init --bare bar.git" created foo.git instead of bar.git. + + * "git log --abbrev=$num --format='%h' ignored --abbrev=$num. + + * "git ls-files ../out/side/cwd" refused to work. + + * "git merge --log" used to replace the custom message given by "-m" with + the shortlog, instead of appending to it. + + * "git notes copy" without any other argument segfaulted. + + * "git pull" accepted "--dry-run", gave it to underlying "git fetch" but + ignored the option itself, resulting in a bogus attempt to merge + unrelated commit. + + * "git rebase" did not faithfully reproduce a malformed author ident, that + is often seen in a repository converted from foreign SCMs. + + * "git reset --hard" started from a wrong directory and a working tree in + a nonstandard location is in use got confused. + + * "git send-email" lacked a way to specify the domainname used in the + EHLO/HELO exchange, causing rejected connection from picky servers. + It learned --smtp-domain option to solve this issue. + + * "git send-email" did not declare a content-transfer-encoding and + content-type even when its payload needs to be sent in 8-bit. + + * "git show -C -C" and other corner cases lost diff metainfo output + in 1.7.0. + + * "git stash" incorrectly lost paths in the working tree that were + previously removed from the index. + + * "git status" stopped refreshing the index by mistake in 1.7.1. + + * "git status" showed excess "hints" even when advice.statusHints is set to false. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.1.2.txt b/Documentation/RelNotes/1.7.1.2.txt new file mode 100644 index 0000000000..61ba14e262 --- /dev/null +++ b/Documentation/RelNotes/1.7.1.2.txt @@ -0,0 +1,28 @@ +Git v1.7.1.2 Release Notes +========================== + +Fixes since v1.7.1.1 +-------------------- + + * "git commit" did not honor GIT_REFLOG_ACTION environment variable, resulting + reflog messages for cherry-pick and revert actions to be recorded as "commit". + + * "git clone/fetch/pull" issued an incorrect error message when a ref and + a symref that points to the ref were updated at the same time. This + obviously would update them to the same value, and should not result in + an error condition. + + * "git diff" inside a tree with many pathnames that have certain + characters has become very slow in 1.7.0 by mistake. + + * "git rev-parse --parseopt --stop-at-non-option" did not stop at non option + when --keep-dashdash was in effect. + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git config --path conf.var" to attempt to expand a variable conf.var + that uses "~/" short-hand segfaulted when $HOME environment variable + was not set. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.1.3.txt b/Documentation/RelNotes/1.7.1.3.txt new file mode 100644 index 0000000000..5b18518449 --- /dev/null +++ b/Documentation/RelNotes/1.7.1.3.txt @@ -0,0 +1,10 @@ +Git v1.7.1.3 Release Notes +========================== + +This is primarily to backport support for the new "add.ignoreErrors" +name given to the existing "add.ignore-errors" configuration variable. + +The next version, Git 1.7.4, and future versions, will support both +old and incorrect name and the new corrected name, but without this +backport, users who want to use the new name "add.ignoreErrors" in +their repositories cannot use older versions of Git. diff --git a/Documentation/RelNotes/1.7.1.4.txt b/Documentation/RelNotes/1.7.1.4.txt new file mode 100644 index 0000000000..7c734b4f7b --- /dev/null +++ b/Documentation/RelNotes/1.7.1.4.txt @@ -0,0 +1,8 @@ +Git v1.7.1.4 Release Notes +========================== + +Fixes since v1.7.1.3 +-------------------- + + * "gitweb" can sometimes be tricked into parrotting a filename argument + given in a request without properly quoting. diff --git a/Documentation/RelNotes/1.7.1.txt b/Documentation/RelNotes/1.7.1.txt new file mode 100644 index 0000000000..9d89fedb36 --- /dev/null +++ b/Documentation/RelNotes/1.7.1.txt @@ -0,0 +1,89 @@ +Git v1.7.1 Release Notes +======================== + +Updates since v1.7.0 +-------------------- + + * Eric Raymond is the maintainer of updated CIAbot scripts, in contrib/. + + * gitk updates. + + * Some commands (e.g. svn and http interfaces) that interactively ask + for a password can be told to use an external program given via + GIT_ASKPASS. + + * Conflict markers that lead the common ancestor in diff3-style output + now have a label, which hopefully would help third-party tools that + expect one. + + * Comes with an updated bash-completion script. + + * "git am" learned "--keep-cr" option to handle inputs that are + a mixture of changes to files with and without CRLF line endings. + + * "git cvsimport" learned -R option to leave revision mapping between + CVS revisions and resulting git commits. + + * "git diff --submodule" notices and describes dirty submodules. + + * "git for-each-ref" learned %(symref), %(symref:short) and %(flag) + tokens. + + * "git hash-object --stdin-paths" can take "--no-filters" option now. + + * "git init" can be told to look at init.templatedir configuration + variable (obviously that has to come from either /etc/gitconfig or + $HOME/.gitconfig). + + * "git grep" learned "--no-index" option, to search inside contents that + are not managed by git. + + * "git grep" learned --color=auto/always/never. + + * "git grep" learned to paint filename and line-number in colors. + + * "git log -p --first-parent -m" shows one-parent diff for merge + commits, instead of showing combined diff. + + * "git merge-file" learned to use custom conflict marker size and also + to use the "union merge" behaviour. + + * "git notes" command has been rewritten in C and learned many commands + and features to help you carry notes forward across rebases and amends. + + * "git request-pull" identifies the commit the request is relative to in + a more readable way. + + * "git reset" learned "--keep" option that lets you discard commits + near the tip while preserving your local changes in a way similar + to how "git checkout branch" does. + + * "git status" notices and describes dirty submodules. + + * "git svn" should work better when interacting with repositories + with CRLF line endings. + + * "git imap-send" learned to support CRAM-MD5 authentication. + + * "gitweb" installation procedure can use "minified" js/css files + better. + + * Various documentation updates. + +Fixes since v1.7.0 +------------------ + +All of the fixes in v1.7.0.X maintenance series are included in this +release, unless otherwise noted. + + * "git add frotz/nitfol" did not complain when the entire frotz/ directory + was ignored. + + * "git diff --stat" used "int" to count the size of differences, + which could result in overflowing. + + * "git rev-list --pretty=oneline" didn't terminate a record with LF for + commits without any message. + + * "git rev-list --abbrev-commit" defaulted to 40-byte abbreviations, unlike + newer tools in the git toolset. diff --git a/Documentation/RelNotes/1.7.2.1.txt b/Documentation/RelNotes/1.7.2.1.txt new file mode 100644 index 0000000000..1103c47a4f --- /dev/null +++ b/Documentation/RelNotes/1.7.2.1.txt @@ -0,0 +1,25 @@ +Git v1.7.2.1 Release Notes +========================== + +Fixes since v1.7.2 +------------------ + + * "git instaweb" wasn't useful when your Apache was installed under a + name other than apache2 (e.g. "httpd"). + + * Similarly, "git web--browse" (invoked by "git help -w") learned that + chrome browser is sometimes called google-chrome. + + * An overlong line after ".gitdir: " in a git file caused out of bounds + access to an array on the stack. + + * "git config --path conf.var" to attempt to expand a variable conf.var + that uses "~/" short-hand segfaulted when $HOME environment variable + was not set. + + * Documentation on Cygwin failed to build. + + * The error message from "git pull blarg" when 'blarg' is an unknown + remote name has been improved. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.2.2.txt b/Documentation/RelNotes/1.7.2.2.txt new file mode 100644 index 0000000000..71eb6a8b0a --- /dev/null +++ b/Documentation/RelNotes/1.7.2.2.txt @@ -0,0 +1,22 @@ +Git v1.7.2.2 Release Notes +========================== + +Fixes since v1.7.2.1 +-------------------- + + * Object transfer over smart http transport deadlocked the client when + the remote HTTP server returned a failure, instead of erroring it out. + + * git-gui honors custom textconv filters when showing diff and blame; + + * git diff --relative=subdir (without the necessary trailing /) did not + work well; + + * "git diff-files -p --submodule" was recently broken; + + * "git checkout -b n ':/token'" did not work; + + * "git index-pack" (hence "git fetch/clone/pull/push") enabled the object + replacement machinery by mistake (it never should have); + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.2.3.txt b/Documentation/RelNotes/1.7.2.3.txt new file mode 100644 index 0000000000..610960cfe1 --- /dev/null +++ b/Documentation/RelNotes/1.7.2.3.txt @@ -0,0 +1,39 @@ +Git v1.7.2.3 Release Notes +========================== + +Fixes since v1.7.2.2 +-------------------- + + * When people try insane things such as delta-compressing 4GiB files, we + threw an assertion failure. + + * "git archive" gave the full commit ID for "$Format:%h$". + + * "git fetch --tags" did not fetch tags when remote.<nick>.tagopt was set + to --no-tags. The command line option now overrides the configuration + setting. + + * "git for-each-ref --format='%(objectname:short)'" has been completely + broken for a long time. + + * "git gc" incorrectly pruned a rerere record that was created long + time ago but still is actively and repeatedly used. + + * "git log --follow -M -p" was seriously broken in 1.7.2, reporting + assertion failure. + + * Running "git log" with an incorrect option started pager nevertheless, + forcing the user to dismiss it. + + * "git rebase" did not work well when the user has diff.renames + configuration variable set. + + * An earlier (and rather old) fix to "git rebase" against a rebased + upstream broke a more normal, non rebased upstream case rather badly, + attempting to re-apply patches that are already accepted upstream. + + * "git submodule sync" forgot to update the superproject's config file + when submodule URL changed. + + * "git pack-refs --all --prune" did not remove a directory that has + become empty. diff --git a/Documentation/RelNotes/1.7.2.4.txt b/Documentation/RelNotes/1.7.2.4.txt new file mode 100644 index 0000000000..f7950a4c04 --- /dev/null +++ b/Documentation/RelNotes/1.7.2.4.txt @@ -0,0 +1,10 @@ +Git v1.7.2.4 Release Notes +========================== + +This is primarily to backport support for the new "add.ignoreErrors" +name given to the existing "add.ignore-errors" configuration variable. + +The next version, Git 1.7.4, and future versions, will support both +old and incorrect name and the new corrected name, but without this +backport, users who want to use the new name "add.ignoreErrors" in +their repositories cannot use older versions of Git. diff --git a/Documentation/RelNotes/1.7.2.5.txt b/Documentation/RelNotes/1.7.2.5.txt new file mode 100644 index 0000000000..bf976c40db --- /dev/null +++ b/Documentation/RelNotes/1.7.2.5.txt @@ -0,0 +1,8 @@ +Git v1.7.2.5 Release Notes +========================== + +Fixes since v1.7.2.4 +-------------------- + + * "gitweb" can sometimes be tricked into parrotting a filename argument + given in a request without properly quoting. diff --git a/Documentation/RelNotes/1.7.2.txt b/Documentation/RelNotes/1.7.2.txt new file mode 100644 index 0000000000..15cf01178c --- /dev/null +++ b/Documentation/RelNotes/1.7.2.txt @@ -0,0 +1,151 @@ +Git v1.7.2 Release Notes +======================== + +Updates since v1.7.1 +-------------------- + + * core.eol configuration and text/eol attributes are the new way to control + the end of line conventions for files in the working tree. + + * core.autocrlf has been made safer - it will now only handle line + endings for new files and files that are LF-only in the + repository. To normalize content that has been checked in with + CRLF, use the new eol/text attributes. + + * The whitespace rules used in "git apply --whitespace" and "git diff" + gained a new member in the family (tab-in-indent) to help projects with + policy to indent only with spaces. + + * When working from a subdirectory, by default, git does not look for its + metadirectory ".git" across filesystems, primarily to help people who + have invocations of git in their custom PS1 prompts, as being outside + of a git repository would look for ".git" all the way up to the root + directory, and NFS mounts are often slow. DISCOVERY_ACROSS_FILESYSTEM + environment variable can be used to tell git not to stop at a + filesystem boundary. + + * Usage help messages generated by parse-options library (i.e. most + of the Porcelain commands) are sent to the standard output now. + + * ':/<string>' notation to look for a commit now takes regular expression + and it is not anchored at the beginning of the commit log message + anymore (this is a backward incompatible change). + + * "git" wrapper learned "-c name=value" option to override configuration + variable from the command line. + + * Improved portability for various platforms including older SunOS, + HP-UX 10/11, AIX, Tru64, etc. and platforms with Python 2.4. + + * The message from "git am -3" has been improved when conflict + resolution ended up making the patch a no-op. + + * "git blame" applies the textconv filter to the contents it works + on, when available. + + * "git checkout --orphan newbranch" is similar to "-b newbranch" but + prepares to create a root commit that is not connected to any existing + commit. + + * "git cherry-pick" learned to pick a range of commits + (e.g. "cherry-pick A..B" and "cherry-pick --stdin"), so did "git + revert"; these do not support the nicer sequencing control "rebase + [-i]" has, though. + + * "git cherry-pick" and "git revert" learned --strategy option to specify + the merge strategy to be used when performing three-way merges. + + * "git cvsserver" can be told to use pserver; its password file can be + stored outside the repository. + + * The output from the textconv filter used by "git diff" can be cached to + speed up their reuse. + + * "git diff --word-diff=<mode>" extends the existing "--color-words" + option, making it more useful in color-challenged environments. + + * The regexp to detect function headers used by "git diff" for PHP has + been enhanced for visibility modifiers (public, protected, etc.) to + better support PHP5. + + * "diff.noprefix" configuration variable can be used to implicitly + ask for "diff --no-prefix" behaviour. + + * "git for-each-ref" learned "%(objectname:short)" that gives the object + name abbreviated. + + * "git format-patch" learned --signature option and format.signature + configuration variable to customize the e-mail signature used in the + output. + + * Various options to "git grep" (e.g. --count, --name-only) work better + with binary files. + + * "git grep" learned "-Ovi" to open the files with hits in your editor. + + * "git help -w" learned "chrome" and "chromium" browsers. + + * "git log --decorate" shows commit decorations in various colours. + + * "git log --follow <path>" follows across copies (it used to only follow + renames). This may make the processing more expensive. + + * "git log --pretty=format:<template>" specifier learned "% <something>" + magic that inserts a space only when %<something> expands to a + non-empty string; this is similar to "%+<something>" magic, but is + useful in a context to generate a single line output. + + * "git notes prune" learned "-n" (dry-run) and "-v" options, similar to + what "git prune" has. + + * "git patch-id" can be fed a mbox without getting confused by the + signature line in the format-patch output. + + * "git remote" learned "set-branches" subcommand. + + * "git rev-list A..B" learned --ancestry-path option to further limit + the result to the commits that are on the ancestry chain between A and + B (i.e. commits that are not descendants of A are excluded). + + * "git show -5" is equivalent to "git show --do-walk 5"; this is similar + to the update to make "git show master..next" walk the history, + introduced in 1.6.4. + + * "git status [-s] --ignored" can be used to list ignored paths. + + * "git status -s -b" shows the current branch in the output. + + * "git status" learned "--ignore-submodules" option. + + * Various "gitweb" enhancements and clean-ups, including syntax + highlighting, "plackup" support for instaweb, .fcgi suffix to run + it as FastCGI script, etc. + + * The test harness has been updated to produce TAP-friendly output. + + * Many documentation improvement patches are also included. + + +Fixes since v1.7.1 +------------------ + +All of the fixes in v1.7.1.X maintenance series are included in this +release, unless otherwise noted. + + * We didn't URL decode "file:///path/to/repo" correctly when path/to/repo + had percent-encoded characters (638794c, 9d2e942, ce83eda, 3c73a1d). + + * "git clone" did not configure remote.origin.url correctly for bare + clones (df61c889). + + * "git diff --graph" works better with "--color-words" and other options + (81fa024..4297c0a). + + * "git diff" could show ambiguous abbreviation of blob object names on + its "index" line (3e5a188). + + * "git reset --hard" started from a wrong directory and a working tree in + a nonstandard location is in use got confused (560fb6a1). + + * "git read-tree -m A B" used to switch to branch B while retaining + local changes added an incorrect cache-tree information (b1f47514). diff --git a/Documentation/RelNotes/1.7.3.1.txt b/Documentation/RelNotes/1.7.3.1.txt new file mode 100644 index 0000000000..002c93b961 --- /dev/null +++ b/Documentation/RelNotes/1.7.3.1.txt @@ -0,0 +1,14 @@ +Git v1.7.3.1 Release Notes +========================== + +Fixes since v1.7.3 +------------------ + + * "git stash show stash@{$n}" was accidentally broken in 1.7.3 ("git + stash show" without any argument still worked, though). + + * "git stash branch $branch stash@{$n}" was accidentally broken in + 1.7.3 and started dropping the named stash even when branch creation + failed. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.3.2.txt b/Documentation/RelNotes/1.7.3.2.txt new file mode 100644 index 0000000000..5c93b85af4 --- /dev/null +++ b/Documentation/RelNotes/1.7.3.2.txt @@ -0,0 +1,5 @@ +Git v1.7.3.2 Release Notes +========================== + +This is primarily to push out many documentation fixes accumulated since +the 1.7.3.1 release. diff --git a/Documentation/RelNotes/1.7.3.3.txt b/Documentation/RelNotes/1.7.3.3.txt new file mode 100644 index 0000000000..9b2b2448df --- /dev/null +++ b/Documentation/RelNotes/1.7.3.3.txt @@ -0,0 +1,54 @@ +Git v1.7.3.3 Release Notes +========================== + +In addition to the usual fixes, this release also includes support for +the new "add.ignoreErrors" name given to the existing "add.ignore-errors" +configuration variable. + +The next version, Git 1.7.4, and future versions, will support both +old and incorrect name and the new corrected name, but without this +backport, users who want to use the new name "add.ignoreErrors" in +their repositories cannot use older versions of Git. + +Fixes since v1.7.3.2 +-------------------- + + * "git apply" segfaulted when a bogus input is fed to it. + + * Running "git cherry-pick --ff" on a root commit segfaulted. + + * "diff", "blame" and friends incorrectly applied textconv filters to + symlinks. + + * Highlighting of whitespace breakage in "diff" output was showing + incorrect amount of whitespaces when blank-at-eol is set and the line + consisted only of whitespaces and a TAB. + + * "diff" was overly inefficient when trying to find the line to use for + the function header (i.e. equivalent to --show-c-function of GNU diff). + + * "git imap-send" depends on libcrypto but our build rule relied on the + linker to implicitly link it via libssl, which was wrong. + + * "git merge-file" can be called from within a subdirectory now. + + * "git repack -f" expanded and recompressed non-delta objects in the + existing pack, which was wasteful. Use new "-F" option if you really + want to (e.g. when changing the pack.compression level). + + * "git rev-list --format="...%x00..." incorrectly chopped its output + at NUL. + + * "git send-email" did not correctly remove duplicate mail addresses from + the Cc: header that appear on the To: header. + + * The completion script (in contrib/completion) ignored lightweight tags + in __git_ps1(). + + * "git-blame" mode (in contrib/emacs) didn't say (require 'format-spec) + even though it depends on it; it didn't work with Emacs 22 or older + unless Gnus is used. + + * "git-p4" (in contrib/) did not correctly handle deleted files. + +Other minor fixes and documentation updates are also included. diff --git a/Documentation/RelNotes/1.7.3.4.txt b/Documentation/RelNotes/1.7.3.4.txt new file mode 100644 index 0000000000..e57f7c176d --- /dev/null +++ b/Documentation/RelNotes/1.7.3.4.txt @@ -0,0 +1,45 @@ +Git v1.7.3.4 Release Notes +========================== + +Fixes since v1.7.3.3 +-------------------- + + * Smart HTTP transport used to incorrectly retry redirected POST + request with GET request. + + * "git apply" did not correctly handle patches that only change modes + if told to apply while stripping leading paths with -p option. + + * "git apply" can deal with patches with timezone formatted with a + colon between the hours and minutes part (e.g. "-08:00" instead of + "-0800"). + + * "git checkout" removed an untracked file "foo" from the working + tree when switching to a branch that contains a tracked path + "foo/bar". Prevent this, just like the case where the conflicting + path were "foo" (c752e7f..7980872d). + + * "git cherry-pick" or "git revert" refused to work when a path that + would be modified by the operation was stat-dirty without a real + difference in the contents of the file. + + * "git diff --check" reported an incorrect line number for added + blank lines at the end of file. + + * "git imap-send" failed to build under NO_OPENSSL. + + * Setting log.decorate configuration variable to "0" or "1" to mean + "false" or "true" did not work. + + * "git push" over dumb HTTP protocol did not work against WebDAV + servers that did not terminate a collection name with a slash. + + * "git tag -v" did not work with GPG signatures in rfc1991 mode. + + * The post-receive-email sample hook was accidentally broken in 1.7.3.3 + update. + + * "gitweb" can sometimes be tricked into parrotting a filename argument + given in a request without properly quoting. + +Other minor fixes and documentation updates are also included. diff --git a/Documentation/RelNotes/1.7.3.5.txt b/Documentation/RelNotes/1.7.3.5.txt new file mode 100644 index 0000000000..40f3ba5795 --- /dev/null +++ b/Documentation/RelNotes/1.7.3.5.txt @@ -0,0 +1,34 @@ +Git 1.7.3.5 Release Notes +========================= + + * The xfuncname pattern used by "git diff" and "git grep" to show the + last notable line in context were broken for python and ruby for a long + time. + + * "git merge" into an unborn branch removed an untracked file "foo" from + the working tree when merged branch had "foo" (this fix was already in + 1.7.3.3 but was omitted from the release notes by mistake). + + * "git status -s" did not quote unprintable characters in paths as + documented. + + * "git am --abort" used to always reset to the commit at the beginning of + the last "am" invocation that has stopped, losing any unrelated commits + that may have been made since then. Now it refrains from doing so and + instead issues a warning. + + * "git blame" incorrectly reused bogusly cached result of textconv + filter for files from the working tree. + + * "git commit" used to abort after the user edited the log message + when the committer information was not correctly set up. It now + aborts before starting the editor. + + * "git commit --date=invalid" used to silently ignore the incorrectly + specified date; it is now diagnosed as an error. + + * "git rebase --skip" to skip the last commit in a series used to fail + to run post-rewrite hook and to copy notes from old commits that have + successfully been rebased so far. Now it do (backmerge ef88ad2). + + * "gitweb" tried to show a wrong feed logo when none was specified. diff --git a/Documentation/RelNotes/1.7.3.txt b/Documentation/RelNotes/1.7.3.txt new file mode 100644 index 0000000000..309c33181f --- /dev/null +++ b/Documentation/RelNotes/1.7.3.txt @@ -0,0 +1,76 @@ +Git v1.7.3 Release Notes +======================== + +Updates since v1.7.2 +-------------------- + + * git-gui, now at version 0.13.0, got various updates and a new + maintainer, Pat Thoyts. + + * Gitweb allows its configuration to change per each request; it used to + read the configuration once upon startup. + + * When git finds a corrupt object, it now reports the file that contains + it. + + * "git checkout -B <it>" is a shorter way to say "git branch -f <it>" + followed by "git checkout <it>". + + * When "git checkout" or "git merge" refuse to proceed in order to + protect local modification to your working tree, they used to stop + after showing just one path that might be lost. They now show all, + in a format that is easier to read. + + * "git clean" learned "-e" ("--exclude") option. + + * Hunk headers produced for C# files by "git diff" and friends show more + relevant context than before. + + * diff.ignoresubmodules configuration variable can be used to squelch the + differences in submodules reported when running commands (e.g. "diff", + "status", etc.) at the superproject level. + + * http.useragent configuration can be used to lie who you are to your + restrictive firewall. + + * "git rebase --strategy <s>" learned "-X" option to pass extra options + that are understood by the chosen merge strategy. + + * "git rebase -i" learned "exec" that you can insert into the insn sheet + to run a command between its steps. + + * "git rebase" between branches that have many binary changes that do + not conflict should be faster. + + * "git rebase -i" peeks into rebase.autosquash configuration and acts as + if you gave --autosquash from the command line. + + +Also contains various documentation updates. + + +Fixes since v1.7.2 +------------------ + +All of the fixes in v1.7.2.X maintenance series are included in this +release, unless otherwise noted. + + * "git merge -s recursive" (which is the default) did not handle cases + where a directory becomes a file (or vice versa) very well. + + * "git fetch" and friends were accidentally broken for url with "+" in + its path, e.g. "git://git.gnome.org/gtk+". + + * "git fetch $url" (i.e. without refspecs) was broken for quite some + time, if the current branch happen to be tracking some remote. + + * "git ls-tree dir dirgarbage", when "dir" was a directory, + incorrectly recursed into "dir". + + * "git note remove" created unnecessary extra commit when named object + did not have any note to begin with. + + * "git rebase" did not work well if you had diff.noprefix configured. + + * "git -c foo=bar subcmd" did not work well for subcmd that is not + implemented as a built-in command. diff --git a/Documentation/RelNotes/1.7.4.1.txt b/Documentation/RelNotes/1.7.4.1.txt new file mode 100644 index 0000000000..79923a6d2f --- /dev/null +++ b/Documentation/RelNotes/1.7.4.1.txt @@ -0,0 +1,27 @@ +Git v1.7.4.1 Release Notes +========================== + +Fixes since v1.7.4 +------------------ + + * On Windows platform, the codepath to spawn a new child process forgot + to first flush the output buffer. + + * "git bundle" did not use OFS_DELTA encoding, making its output a few + per-cent larger than necessarily. + + * The option to tell "git clone" to recurse into the submodules was + misspelled with an underscore "--recurse_submodules". + + * "git diff --cached HEAD" before the first commit does what an end user + would expect (namely, show what would be committed without further "git + add"). + + * "git fast-import" didn't accept the command to ask for "notes" feature + to be present in its input stream, even though it was capable of the + feature. + + * "git fsck" gave up scanning loose object files in directories with + garbage files. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.2.txt b/Documentation/RelNotes/1.7.4.2.txt new file mode 100644 index 0000000000..ef4ce1fcd3 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.2.txt @@ -0,0 +1,58 @@ +Git v1.7.4.2 Release Notes +========================== + +Fixes since v1.7.4.1 +-------------------- + + * Many documentation updates to match "git cmd -h" output and the + git-cmd manual page. + + * We used to keep one file descriptor open for each and every packfile + that we have a mmap window on it (read: "in use"), even when for very + tiny packfiles. We now close the file descriptor early when the entire + packfile fits inside one mmap window. + + * "git bisect visualize" tried to run "gitk" in windowing + environments even when "gitk" is not installed, resulting in a + strange error message. + + * "git clone /no/such/path" did not fail correctly. + + * "git commit" did not correctly error out when the user asked to use a + non existent file as the commit message template. + + * "git diff --stat -B" ran on binary files counted the changes in lines, + which was nonsensical. + + * "git diff -M" opportunistically detected copies, which was not + necessarily a good thing, especially when it is internally run by + recursive merge. + + * "git difftool" didn't tell (g)vimdiff that the files it is reading are + to be opened read-only. + + * "git merge" didn't pay attention to prepare-commit-msg hook, even + though if a merge is conflicted and manually resolved, the subsequent + "git commit" would have triggered the hook, which was inconsistent. + + * "git patch-id" (and commands like "format-patch --ignore-in-upstream" + that use it as their internal logic) handled changes to files that end + with incomplete lines incorrectly. + + * The official value to tell "git push" to push the current branch back + to update the upstream branch it forked from is now called "upstream". + The old name "tracking" is and will be supported. + + * "git submodule update" used to honor the --merge/--rebase option (or + corresponding configuration variables) even for a newly cloned + subproject, which made no sense (so/submodule-no-update-first-time). + + * gitweb's "highlight" interface mishandled tabs. + + * gitweb didn't understand timezones with GMT offset that is not + multiple of a whole hour. + + * gitweb had a few forward-incompatible syntactic constructs and + also used incorrect variable when showing the file mode in a diff. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.3.txt b/Documentation/RelNotes/1.7.4.3.txt new file mode 100644 index 0000000000..02a3d5bdf6 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.3.txt @@ -0,0 +1,32 @@ +Git v1.7.4.3 Release Notes +========================== + +Fixes since v1.7.4.2 +-------------------- + + * "git apply" used to confuse lines updated by previous hunks as lines + that existed before when applying a hunk, contributing misapplication + of patches with offsets. + + * "git branch --track" (and "git checkout --track --branch") used to + allow setting up a random non-branch that does not make sense to follow + as the "upstream". The command correctly diagnoses it as an error. + + * "git checkout $other_branch" silently removed untracked symbolic links + in the working tree that are in the way in order to check out paths + under it from the named branch. + + * "git cvsimport" did not bail out immediately when the cvs server cannot + be reached, spewing unnecessary error messages that complain about the + server response that it never got. + + * "git diff --quiet" did not work very well with the "--diff-filter" + option. + + * "git grep -n" lacked a long-hand synonym --line-number. + + * "git stash apply" reported the result of its operation by running + "git status" from the top-level of the working tree; it should (and + now does) run it from the user's working directory. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.4.txt b/Documentation/RelNotes/1.7.4.4.txt new file mode 100644 index 0000000000..ff06e04a58 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.4.txt @@ -0,0 +1,35 @@ +Git v1.7.4.4 Release Notes +========================== + +Fixes since v1.7.4.3 +-------------------- + + * Compilation of sha1_file.c on BSD platforms were broken due to our + recent use of getrlimit() without including <sys/resource.h>. + + * "git config" did not diagnose incorrect configuration variable names. + + * "git format-patch" did not wrap a long subject line that resulted from + rfc2047 encoding. + + * "git instaweb" should work better again with plackup. + + * "git log --max-count=4 -Sfoobar" now shows 4 commits that changes the + number of occurrences of string "foobar"; it used to scan only for 4 + commits and then emitted only matching ones. + + * "git log --first-parent --boundary $c^..$c" segfaulted on a merge. + + * "git pull" into an empty branch should have behaved as if + fast-forwarding from emptiness to the version being pulled, with + the usual protection against overwriting untracked files. + + * "git submodule" that is run while a merge in the superproject is in + conflicted state tried to process each conflicted submodule up to + three times. + + * "git status" spent all the effort to notice racily-clean index entries + but didn't update the index file to help later operations go faster in + some cases. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.5.txt b/Documentation/RelNotes/1.7.4.5.txt new file mode 100644 index 0000000000..b7a0eeb22f --- /dev/null +++ b/Documentation/RelNotes/1.7.4.5.txt @@ -0,0 +1,4 @@ +Git v1.7.4.5 Release Notes +========================== + +This contains only minor documentation fixes accumulated since 1.7.4.4. diff --git a/Documentation/RelNotes/1.7.4.txt b/Documentation/RelNotes/1.7.4.txt new file mode 100644 index 0000000000..d5bca731b5 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.txt @@ -0,0 +1,156 @@ +Git v1.7.4 Release Notes +======================== + +Updates since v1.7.3 +-------------------- + + * The documentation Makefile now assumes by default asciidoc 8 and + docbook-xsl >= 1.73. If you have older versions, you can set + ASCIIDOC7 and ASCIIDOC_ROFF, respectively. + + * The option parsers of various commands that create new branches (or + rename existing ones to a new name) were too loose and users were + allowed to give a branch a name that begins with a dash by creative + abuse of their command line options, which only led to burning + themselves. The name of a branch cannot begin with a dash now. + + * System-wide fallback default attributes can be stored in + /etc/gitattributes; the core.attributesfile configuration variable can + be used to customize the path to this file. + + * The thread structure generated by "git send-email" has changed + slightly. Setting the cover letter of the latest series as a reply + to the cover letter of the previous series with --in-reply-to used + to make the new cover letter and all the patches replies to the + cover letter of the previous series; this has been changed to make + the patches in the new series replies to the new cover letter. + + * The Bash completion script in contrib/ has been adjusted to be usable with + Bash 4 (options with '=value' didn't complete). It has been also made + usable with zsh. + + * Different pagers can be chosen depending on which subcommand is + being run under the pager, using the "pager.<subcommand>" variable. + + * The hardcoded tab-width of 8 that is used in whitespace breakage checks is now + configurable via the attributes mechanism. + + * Support of case insensitive filesystems (i.e. "core.ignorecase") has + been improved. For example, the gitignore mechanism didn't pay attention + to case insensitivity. + + * The <tree>:<path> syntax for naming a blob in a tree, and the :<path> + syntax for naming a blob in the index (e.g. "master:Makefile", + ":hello.c") have been extended. You can start <path> with "./" to + implicitly have the (sub)directory you are in prefixed to the + lookup. Similarly, ":../Makefile" from a subdirectory would mean + "the Makefile of the parent directory in the index". + + * "git blame" learned the --show-email option to display the e-mail + addresses instead of the names of authors. + + * "git commit" learned the --fixup and --squash options to help later invocation + of interactive rebase. + + * Command line options to "git cvsimport" whose names are in capital + letters (-A, -M, -R and -S) can now be specified as the default in + the .git/config file by their longer names (cvsimport.authorsFile, + cvsimport.mergeRegex, cvsimport.trackRevisions, cvsimport.ignorePaths). + + * "git daemon" can be built in the MinGW environment. + + * "git daemon" can take more than one --listen option to listen to + multiple addresses. + + * "git describe --exact-match" was optimized not to read commit + objects unnecessarily. + + * "git diff" and "git grep" learned what functions and subroutines + in Fortran, Pascal and Perl look like. + + * "git fetch" learned the "--recurse-submodules" option. + + * "git mergetool" tells vim/gvim to show a three-way diff by default + (use vimdiff2/gvimdiff2 as the tool name for old behavior). + + * "git log -G<pattern>" limits the output to commits whose change has + added or deleted lines that match the given pattern. + + * "git read-tree" with no argument as a way to empty the index is + deprecated; we might want to remove it in the future. Users can + use the new --empty option to be more explicit instead. + + * "git repack -f" does not spend cycles to recompress objects in the + non-delta representation anymore (use -F if you really mean it + e.g. after you changed the core.compression variable setting). + + * "git merge --log" used to limit the resulting merge log to 20 + entries; this is now customizable by giving e.g. "--log=47". + + * "git merge" may work better when all files were moved out of a + directory in one branch while a new file is created in place of that + directory in the other branch. + + * "git merge" learned the "--abort" option, synonymous to + "git reset --merge" when a merge is in progress. + + * "git notes" learned the "merge" subcommand to merge notes refs. + In addition to the default manual conflict resolution, there are + also several notes merge strategies for automatically resolving + notes merge conflicts. + + * "git rebase --autosquash" can use SHA-1 object names to name the + commit which is to be fixed up (e.g. "fixup! e83c5163"). + + * The default "recursive" merge strategy learned the --rename-threshold + option to influence the rename detection, similar to the -M option + of "git diff". From the "git merge" frontend, the "-X<strategy option>" + interface, e.g. "git merge -Xrename-threshold=50% ...", can be used + to trigger this. + + * The "recursive" strategy also learned to ignore various whitespace + changes; the most notable is -Xignore-space-at-eol. + + * "git send-email" learned "--to-cmd", similar to "--cc-cmd", to read + the recipient list from a command output. + + * "git send-email" learned to read and use "To:" from its input files. + + * you can extend "git shell", which is often used on boxes that allow + git-only login over ssh as login shell, with a custom set of + commands. + + * The current branch name in "git status" output can be colored differently + from the generic header color by setting the "color.status.branch" variable. + + * "git submodule sync" updates metainformation for all submodules, + not just the ones that have been checked out. + + * gitweb can use a custom 'highlight' command with its configuration file. + + * other gitweb updates. + + +Also contains various documentation updates. + + +Fixes since v1.7.3 +------------------ + +All of the fixes in the v1.7.3.X maintenance series are included in this +release, unless otherwise noted. + + * "git log --author=me --author=her" did not find commits written by + me or by her; instead it looked for commits written by me and by + her, which is impossible. + + * "git push --progress" shows progress indicators now. + + * "git rebase -i" showed a confusing error message when given a + branch name that does not exist. + + * "git repack" places its temporary packs under $GIT_OBJECT_DIRECTORY/pack + instead of $GIT_OBJECT_DIRECTORY/ to avoid cross directory renames. + + * "git submodule update --recursive --other-flags" passes flags down + to its subinvocations. diff --git a/Documentation/RelNotes/1.7.5.1.txt b/Documentation/RelNotes/1.7.5.1.txt new file mode 100644 index 0000000000..c6ebd76d19 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.1.txt @@ -0,0 +1,47 @@ +Git v1.7.5.1 Release Notes +========================== + +Fixes since v1.7.5 +------------------ + + * When an object "$tree:$path" does not exist, if $path does exist in the + subtree of $tree that corresponds to the subdirectory the user is in, + git now suggests using "$tree:./$path" in addition to the advice to use + the full path from the root of the working tree. + + * The "--date=relative" output format used to say "X years, 12 months" + when it should have said "X+1 years". + + * The smart-HTTP transfer was broken in 1.7.5 when the client needs + to issue a small POST (which uses content-length) and then a large + POST (which uses chunked) back to back. + + * "git clean" used to fail on an empty directory that is not readable, + even though rmdir(2) could remove such a directory. Now we attempt it + as the last resort. + + * The "--dirstat" option of "diff" family of commands used to totally + ignore a change that only rearranged lines within a file. Such a + change now counts as at least a minimum but non zero change. + + * The "--dirstat" option of "diff" family of commands used to use the + pathname in the original, instead of the pathname in the result, + when renames are involved. + + * "git pack-object" did not take core.bigfilethreashold into account + (unlike fast-import); now it does. + + * "git reflog" ignored options like "--format=.." on the command line. + + * "git stash apply" used to refuse to work if there was any change in + the working tree, even when the change did not overlap with the change + the stash recorded. + + * "git stash apply @{99999}" was not diagnosed as an error, even when you + did not have that many stash entries. + + * An error message from "git send-email" to diagnose a broken SMTP + connection configuration lacked a space between "hello=<smtp-domain>" + and "port=<smtp-server-port>". + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.2.txt b/Documentation/RelNotes/1.7.5.2.txt new file mode 100644 index 0000000000..951eb7cb08 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.2.txt @@ -0,0 +1,57 @@ +Git v1.7.5.2 Release Notes +========================== + +The release notes to 1.7.5.1 forgot to mention: + + * "git stash -p --no-keep-index" and "git stash --no-keep-index -p" now + mean the same thing. + + * "git upload-pack" (hence "git push" over git native protocol) had a + subtle race condition that could lead to a deadlock. + +Fixes since v1.7.5.1 +-------------------- + + * "git add -p" did not work correctly when a hunk is split and then + one of them was given to the editor. + + * "git add -u" did not resolve a conflict where our history deleted and + their history modified the same file, and the working tree resolved to + keep a file. + + * "git cvsimport" did not know that CVSNT stores its password file in a + location different from the traditional CVS. + + * "git diff-files" did not show the mode information from the working + tree side of an unmerged path correctly. + + * "git diff -M --cached" used to use unmerged path as a possible rename + source candidate, which made no sense. + + * The option name parser in "git fast-import" used prefix matches for + some options where it shouldn't, and accepted non-existent options, + e.g. "--relative-marksmith" or "--forceps". + + * "git format-patch" did not quote RFC822 special characters in the + email address (e.g From: Junio C. Hamano <jch@example.com>, not + From: "Junio C. Hamano" <jch@example.com>). + + * "git format-patch" when run with "--quiet" option used to produce a + nonsense result that consists of alternating empty output. + + * In "git merge", per-branch branch.<name>.mergeoptions configuration + variables did not override the fallback default merge.<option> + configuration variables such as merge.ff, merge.log, etc. + + * "git merge-one-file" did not honor GIT_WORK_TREE settings when + handling a "both sides added, differently" conflict. + + * "git mergetool" did not handle conflicted submoudules gracefully. + + * "git-p4" (in contrib) used a wrong base image while merge a file that + was added on both branches differently. + + * "git rebase -i -p" failed to preserve the history when there is a + redundant merge created with the --no-ff option. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.3.txt b/Documentation/RelNotes/1.7.5.3.txt new file mode 100644 index 0000000000..9c03353af2 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.3.txt @@ -0,0 +1,32 @@ +Git v1.7.5.3 Release Notes +========================== + +Fixes since v1.7.5.2 +-------------------- + + * The bash completion scripts should correctly work using zsh's bash + completion emulation layer now. + + * Setting $(prefix) in config.mak did not affect where etc/gitconfig + file is read from, even though passing it from the command line of + $(MAKE) did. + + * The logic to handle "&" (expand to UNIX username) in GECOS field + miscounted the length of the name it formatted. + + * "git cherry-pick -s resolve" failed to cherry-pick a root commit. + + * "git diff --word-diff" misbehaved when diff.suppress-blank-empty was + in effect. + + * "git log --stdin path" with an input that has additional pathspec + used to corrupt memory. + + * "git send-pack" (hence "git push") over smalt-HTTP protocol could + deadlock when the client side pack-object died early. + + * Compressed tarball gitweb generates used to be made with the timestamp + of the tarball generation; this was bad because snapshot from the same + tree should result in a same tarball. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.4.txt b/Documentation/RelNotes/1.7.5.4.txt new file mode 100644 index 0000000000..cf3f455ced --- /dev/null +++ b/Documentation/RelNotes/1.7.5.4.txt @@ -0,0 +1,21 @@ +Git v1.7.5.4 Release Notes +========================== + +Fixes since v1.7.5.3 +-------------------- + + * The single-key mode of "git add -p" was easily fooled into thinking + that it was told to add everthing ('a') when up-arrow was pressed by + mistake. + + * Setting a git command that uses custom configuration via "-c var=val" + as an alias caused a crash due to a realloc(3) failure. + + * "git diff -C -C" used to disable the rename detection entirely when + there are too many copy candidate paths in the tree; now it falls + back to "-C" when doing so would keep the copy candidate paths + under the rename detection limit. + + * "git rerere" did not diagnose a corrupt MERGE_RR file in some cases. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.txt b/Documentation/RelNotes/1.7.5.txt new file mode 100644 index 0000000000..987919c321 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.txt @@ -0,0 +1,132 @@ +Git v1.7.5 Release Notes +======================== + +Updates since v1.7.4 +-------------------- + + * Various MinGW portability fixes. + + * Various git-p4 enhancements (in contrib). + + * Various vcs-svn, git-svn and gitk enhancements and fixes. + + * Various git-gui updates (0.14.0). + + * Update to more modern HP-UX port. + + * The codebase is getting prepared for i18n/l10n; no translated + strings nor translation mechanism in the code yet, but the strings + are being marked for l10n. + + * The bash completion script can now complete symmetric difference + for "git diff" command, e.g. "git diff ...bra<TAB>". + + * The default minimum length of abbreviated and unique object names + can now be configured by setting the core.abbrev configuration + variable. + + * "git apply -v" reports offset lines when the patch does not apply at + the exact location recorded in the diff output. + + * "git config" used to be also known as "git repo-config", but the old + name is now officially deprecated. + + * "git checkout --detach <commit>" is a more user friendly synonym for + "git checkout <commit>^0". + + * "git checkout" performed on detached HEAD gives a warning and + advice when the commit being left behind will become unreachable from + any branch or tag. + + * "git cherry-pick" and "git revert" can be told to use a custom merge + strategy, similar to "git rebase". + + * "git cherry-pick" remembers which commit failed to apply when it is + stopped by conflicts, making it unnecessary to use "commit -c $commit" + to conclude it. + + * "git cvsimport" bails out immediately when the cvs server cannot be + reached, without spewing unnecessary error messages that complain about + the server response it never got. + + * "git fetch" vs "git upload-pack" transfer learned 'no-done' + protocol extension to save one round-trip after the content + negotiation is done. This saves one HTTP RPC, reducing the overall + latency for a trivial fetch. + + * "git fetch" can be told to recursively fetch submodules on-demand. + + * "git grep -f <filename>" learned to treat "-" as "read from the + standard input stream". + + * "git grep --no-index" did not honor pathspecs correctly, returning + paths outside the specified area. + + * "git init" learned the --separate-git-dir option to allow the git + directory for a new repository created elsewhere and linked via the + gitdir mechanism. This is primarily to help submodule support later + to switch between a branch of superproject that has the submodule + and another that does not. + + * "git log" type commands now understand globbing pathspecs. You + can say "git log -- '*.txt'" for example. + + * "git log" family of commands learned --cherry and --cherry-mark + options that can be used to view two diverged branches while omitting + or highlighting equivalent changes that appear on both sides of a + symmetric difference (e.g. "log --cherry A...B"). + + * A lazy "git merge" that didn't say what to merge used to be an error. + When run on a branch that has an upstream defined, however, the command + now merges from the configured upstream. + + * "git mergetool" learned how to drive "beyond compare 3" as well. + + * "git rerere forget" without pathspec used to forget all the saved + conflicts that relate to the current merge; it now requires you to + give it pathspecs. + + * "git rev-list --objects $revs -- $pathspec" now limits the objects listed + in its output properly with the pathspec, in preparation for narrow + clones. + + * "git push" with no parameters gives better advice messages when + "tracking" is used as the push.default semantics or there is no remote + configured yet. + + * A possible value to the "push.default" configuration variable, + 'tracking', gained a synonym that more naturally describes what it + does, 'upstream'. + + * "git rerere" learned a new subcommand "remaining" that is similar to + "status" and lists the paths that had conflicts which are known to + rerere, but excludes the paths that have already been marked as + resolved in the index from its output. "git mergetool" has been + updated to use this facility. + +Also contains various documentation updates. + + +Fixes since v1.7.4 +------------------ + +All of the fixes in the v1.7.4.X maintenance series are included in this +release, unless otherwise noted. + + * "git fetch" from a client that is mostly following the remote + needlessly told all of its refs to the server for both sides to + compute the set of objects that need to be transferred efficiently, + instead of stopping when the server heard enough. In a project with + many tags, this turns out to be extremely wasteful, especially over + the smart HTTP transport (sp/maint-{upload,fetch}-pack-stop-early~1). + + * "git fetch" run from a repository that uses the same repository as + its alternate object store as the repository it is fetching from + did not tell the server that it already has access to objects + reachable from the refs in their common alternate object store, + causing it to fetch unnecessary objects (jc/maint-fetch-alt). + + * "git remote add --mirror" created a configuration that is suitable for + doing both a mirror fetch and a mirror push at the same time, which + made little sense. We now warn and require the command line to specify + either --mirror=fetch or --mirror=push. diff --git a/Documentation/RelNotes/1.7.6.1.txt b/Documentation/RelNotes/1.7.6.1.txt new file mode 100644 index 0000000000..42e46ab17f --- /dev/null +++ b/Documentation/RelNotes/1.7.6.1.txt @@ -0,0 +1,63 @@ +Git v1.7.6.1 Release Notes +========================== + +Fixes since v1.7.6 +------------------ + + * Various codepaths that invoked zlib deflate/inflate assumed that these + functions can compress or uncompress more than 4GB data in one call on + platforms with 64-bit long, which has been corrected. + + * "git unexecutable" reported that "unexecutable" was not found, even + though the actual error was that "unexecutable" was found but did + not have a proper she-bang line to be executed. + + * Error exits from $PAGER were silently ignored. + + * "git checkout -b <branch>" was confused when attempting to create a + branch whose name ends with "-g" followed by hexadecimal digits, + and refused to work. + + * "git checkout -b <branch>" sometimes wrote a bogus reflog entry, + causing later "git checkout -" to fail. + + * "git diff --cc" learned to correctly ignore binary files. + + * "git diff -c/--cc" mishandled a deletion that resolves a conflict, and + looked in the working tree instead. + + * "git fast-export" forgot to quote pathnames with unsafe characters + in its output. + + * "git fetch" over smart-http transport used to abort when the + repository was updated between the initial connection and the + subsequent object transfer. + + * "git fetch" did not recurse into submodules in subdirectories. + + * "git ls-tree" did not error out when asked to show a corrupt tree. + + * "git pull" without any argument left an extra whitespace after the + command name in its reflog. + + * "git push --quiet" was not really quiet. + + * "git rebase -i -p" incorrectly dropped commits from side branches. + + * "git reset [<commit>] paths..." did not reset the index entry correctly + for unmerged paths. + + * "git submodule add" did not allow a relative repository path when + the superproject did not have any default remote url. + + * "git submodule foreach" failed to correctly give the standard input to + the user-supplied command it invoked. + + * submodules that the user has never showed interest in by running + "git submodule init" was incorrectly marked as interesting by "git + submodule sync". + + * "git submodule update --quiet" was not really quiet. + + * "git tag -l <glob>..." did not take multiple glob patterns from the + command line. diff --git a/Documentation/RelNotes/1.7.6.2.txt b/Documentation/RelNotes/1.7.6.2.txt new file mode 100644 index 0000000000..67ae414965 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.2.txt @@ -0,0 +1,8 @@ +Git v1.7.6.2 Release Notes +========================== + +Fixes since v1.7.6.1 +-------------------- + + * v1.7.6.1 broke "git push --quiet"; it used to be a no-op against an old + version of Git running on the other end, but v1.7.6.1 made it abort. diff --git a/Documentation/RelNotes/1.7.6.3.txt b/Documentation/RelNotes/1.7.6.3.txt new file mode 100644 index 0000000000..95971831b9 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.3.txt @@ -0,0 +1,24 @@ +Git v1.7.6.3 Release Notes +========================== + +Fixes since v1.7.6.2 +-------------------- + + * "git -c var=value subcmd" misparsed the custom configuration when + value contained an equal sign. + + * "git fetch" had a major performance regression, wasting many + needless cycles in a repository where there is no submodules + present. This was especially bad, when there were many refs. + + * "git reflog $refname" did not default to the "show" subcommand as + the documentation advertised the command to do. + + * "git reset" did not leave meaningful log message in the reflog. + + * "git status --ignored" did not show ignored items when there is no + untracked items. + + * "git tag --contains $commit" was unnecessarily inefficient. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.4.txt b/Documentation/RelNotes/1.7.6.4.txt new file mode 100644 index 0000000000..e19acac2da --- /dev/null +++ b/Documentation/RelNotes/1.7.6.4.txt @@ -0,0 +1,32 @@ +Git v1.7.6.4 Release Notes +========================== + +Fixes since v1.7.6.3 +-------------------- + + * The error reporting logic of "git am" when the command is fed a file + whose mail-storage format is unknown was fixed. + + * "git branch --set-upstream @{-1} foo" did not expand @{-1} correctly. + + * "git check-ref-format --print" used to parrot a candidate string that + began with a slash (e.g. /refs/heads/master) without stripping it, to make + the result a suitably normalized string the caller can append to "$GIT_DIR/". + + * "git clone" failed to clone locally from a ".git" file that itself + is not a directory but is a pointer to one. + + * "git clone" from a local repository that borrows from another + object store using a relative path in its objects/info/alternates + file did not adjust the alternates in the resulting repository. + + * "git describe --dirty" did not refresh the index before checking the + state of the working tree files. + + * "git ls-files ../$path" that is run from a subdirectory reported errors + incorrectly when there is no such path that matches the given pathspec. + + * "git mergetool" could loop forever prompting when nothing can be read + from the standard input. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.txt b/Documentation/RelNotes/1.7.6.txt new file mode 100644 index 0000000000..9ec498ea39 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.txt @@ -0,0 +1,136 @@ +Git v1.7.6 Release Notes +======================== + +Updates since v1.7.5 +-------------------- + + * Various git-svn updates. + + * Updates the way content tags are handled in gitweb. Also adds + a UI to choose common timezone for displaying the dates. + + * Similar to branch names, tagnames that begin with "-" are now + disallowed. + + * Clean-up of the C part of i18n (but not l10n---please wait) + continues. + + * The scripting part of the codebase is getting prepared for i18n/l10n. + + * Pushing and pulling from a repository with large number of refs that + point to identical commits are optimized by not listing the same commit + during the common ancestor negotiation exchange with the other side. + + * Adding a file larger than core.bigfilethreshold (defaults to 1/2 Gig) + using "git add" will send the contents straight to a packfile without + having to hold it and its compressed representation both at the same + time in memory. + + * Processes spawned by "[alias] <name> = !process" in the configuration + can inspect GIT_PREFIX environment variable to learn where in the + working tree the original command was invoked. + + * A magic pathspec ":/" tells a command that limits its operation to + the current directory when ran from a subdirectory to work on the + entire working tree. In general, ":/path/to/file" would be relative + to the root of the working tree hierarchy. + + After "git reset --hard; edit Makefile; cd t/", "git add -u" would + be a no-op, but "git add -u :/" would add the updated contents of + the Makefile at the top level. If you want to name a path in the + current subdirectory whose unusual name begins with ":/", you can + name it by "./:/that/path" or by "\:/that/path". + + * "git blame" learned "--abbrev[=<n>]" option to control the minimum + number of hexdigits shown for commit object names. + + * "git blame" learned "--line-porcelain" that is less efficient but is + easier to parse. + + * Aborting "git commit --interactive" discards updates to the index + made during the interactive session. + + * "git commit" learned a "--patch" option to directly jump to the + per-hunk selection UI of the interactive mode. + + * "git diff" and its family of commands learned --dirstat=0 to show + directories that contribute less than 0.1% of changes. + + * "git diff" and its family of commands learned --dirstat=lines mode to + assess damage to the directory based on number of lines in the patch + output, not based on the similarity numbers. + + * "git format-patch" learned "--quiet" option to suppress the output of + the names of generated files. + + * "git format-patch" quotes people's names when it has RFC822 special + characters in it, e.g. "Junio C. Hamano" <jch@example.com>. Earlier + it was up to the user to do this when using its output. + + * "git format-patch" can take an empty --subject-prefix now. + + * "git grep" learned the "-P" option to take pcre regular expressions. + + * "git log" and friends learned a new "--notes" option to replace the + "--show-notes" option. Unlike "--show-notes", "--notes=<ref>" does + not imply showing the default notes. + + * They also learned a log.abbrevCommit configuration variable to augment + the --abbrev-commit command line option. + + * "git ls-remote" learned "--exit-code" option to consider it a + different kind of error when no remote ref to be shown. + + * "git merge" learned "-" as a short-hand for "the previous branch", just + like the way "git checkout -" works. + + * "git merge" uses "merge.ff" configuration variable to decide to always + create a merge commit (i.e. --no-ff, aka merge.ff=no), refuse to create + a merge commit (i.e. --ff-only, aka merge.ff=only). Setting merge.ff=yes + (or not setting it at all) restores the default behaviour of allowing + fast-forward to happen when possible. + + * p4-import (from contrib) learned a new option --preserve-user. + + * "git read-tree -m" learned "--dry-run" option that reports if a merge + would fail without touching the index nor the working tree. + + * "git rebase" that does not specify on top of which branch to rebase + the current branch now uses @{upstream} of the current branch. + + * "git rebase" finished either normally or with --abort did not + update the reflog for HEAD to record the event to come back to + where it started from. + + * "git remote add -t only-this-branch --mirror=fetch" is now allowed. Earlier + a fetch-mode mirror meant mirror everything, but now it only means refs are + not renamed. + + * "git rev-list --count" used with "--cherry-mark" counts the cherry-picked + commits separately, producing more a useful output. + + * "git submodule update" learned "--force" option to get rid of local + changes in submodules and replace them with the up-to-date version. + + * "git status" and friends ignore .gitmodules file while the file is + still in a conflicted state during a merge, to avoid using information + that is not final and possibly corrupt with conflict markers. + +Also contains various documentation updates and minor miscellaneous +changes. + + +Fixes since v1.7.5 +------------------ + +Unless otherwise noted, all the fixes in 1.7.5.X maintenance track are +included in this release. + + * "git config" used to choke with an insanely long line. + (merge ef/maint-strbuf-init later) + + * "git diff --quiet" did not work well with --diff-filter. + (merge jk/diff-not-so-quick later) + + * "git status -z" did not default to --porcelain output format. + (merge bc/maint-status-z-to-use-porcelain later) diff --git a/Documentation/RelNotes/1.7.7.1.txt b/Documentation/RelNotes/1.7.7.1.txt new file mode 100644 index 0000000000..ac9b838e25 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.1.txt @@ -0,0 +1,60 @@ +Git v1.7.7.1 Release Notes +========================== + +Fixes since v1.7.7 +------------------ + + * On some BSD systems, adding +s bit on directories is detrimental + (it is not necessary on BSD to begin with). "git init --shared" + has been updated to take this into account without extra makefile + settings on platforms the Makefile knows about. + + * After incorrectly written third-party tools store a tag object in + HEAD, git diagnosed it as a repository corruption and refused to + proceed in order to avoid spreading the damage. We now gracefully + recover from such a situation by pretending as if the commit that + is pointed at by the tag were in HEAD. + + * "git apply --whitespace=error" did not bother to report the exact + line number in the patch that introduced new blank lines at the end + of the file. + + * "git apply --index" did not check corrupted patch. + + * "git checkout $tree $directory/" resurrected paths locally removed or + modified only in the working tree in $directory/ that did not appear + in $directory of the given $tree. They should have been kept intact. + + * "git diff $tree $path" used to apply the pathspec at the output stage, + reading the whole tree, wasting resources. + + * The code to check for updated submodules during a "git fetch" of the + superproject had an unnecessary quadratic loop. + + * "git fetch" from a large bundle did not enable the progress output. + + * When "git fsck --lost-and-found" found that an empty blob object in the + object store is unreachable, it incorrectly reported an error after + writing the lost blob out successfully. + + * "git filter-branch" did not refresh the index before checking that the + working tree was clean. + + * "git grep $tree" when run with multiple threads had an unsafe access to + the object database that should have been protected with mutex. + + * The "--ancestry-path" option to "git log" and friends misbehaved in a + history with complex criss-cross merges and showed an uninteresting + side history as well. + + * Test t1304 assumed LOGNAME is always set, which may not be true on + some systems. + + * Tests with --valgrind failed to find "mergetool" scriptlets. + + * "git patch-id" miscomputed the patch-id in a patch that has a line longer + than 1kB. + + * When an "exec" insn failed after modifying the index and/or the working + tree during "rebase -i", we now check and warn that the changes need to + be cleaned up. diff --git a/Documentation/RelNotes/1.7.7.2.txt b/Documentation/RelNotes/1.7.7.2.txt new file mode 100644 index 0000000000..e6bbef2f01 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.2.txt @@ -0,0 +1,44 @@ +Git v1.7.7.2 Release Notes +========================== + +Fixes since v1.7.7.1 +-------------------- + + * We used to drop error messages from libcurl on certain kinds of + errors. + + * Error report from smart HTTP transport, when the connection was + broken in the middle of a transfer, showed a useless message on + a corrupt packet. + + * "git fetch --prune" was unsafe when used with refspecs from the + command line. + + * The attribute mechanism did not use case insensitive match when + core.ignorecase was set. + + * "git bisect" did not notice when it failed to update the working tree + to the next commit to be tested. + + * "git config --bool --get-regexp" failed to separate the variable name + and its value "true" when the variable is defined without "= true". + + * "git remote rename $a $b" were not careful to match the remote name + against $a (i.e. source side of the remote nickname). + + * "git mergetool" did not use its arguments as pathspec, but as a path to + the file that may not even have any conflict. + + * "git diff --[num]stat" used to use the number of lines of context + different from the default, potentially giving different results from + "git diff | diffstat" and confusing the users. + + * "git pull" and "git rebase" did not work well even when GIT_WORK_TREE is + set correctly with GIT_DIR if the current directory is outside the working + tree. + + * "git send-email" did not honor the configured hostname when restarting + the HELO/EHLO exchange after switching TLS on. + + * "gitweb" used to produce a non-working link while showing the contents + of a blob, when JavaScript actions are enabled. diff --git a/Documentation/RelNotes/1.7.7.3.txt b/Documentation/RelNotes/1.7.7.3.txt new file mode 100644 index 0000000000..09301f0957 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.3.txt @@ -0,0 +1,19 @@ +Git v1.7.7.3 Release Notes +========================== + +Fixes since v1.7.7.2 +-------------------- + + * Adjust the "quick-install-doc" procedures as preformatted + html/manpage are no longer in the source repository. + + * The logic to optimize the locality of the data in a pack introduced in + 1.7.7 was grossly inefficient. + + * The logic to filter out forked projects in the project list in + "gitweb" was broken for some time. + + * "git branch -m/-M" advertised to update RENAME_REF ref in the + commit log message that introduced the feature but not anywhere in + the documentation, and never did update such a ref anyway. This + undocumented misfeature that did not exist has been excised. diff --git a/Documentation/RelNotes/1.7.7.txt b/Documentation/RelNotes/1.7.7.txt new file mode 100644 index 0000000000..7655cccfaa --- /dev/null +++ b/Documentation/RelNotes/1.7.7.txt @@ -0,0 +1,134 @@ +Git v1.7.7 Release Notes +======================== + +Updates since v1.7.6 +-------------------- + + * The scripting part of the codebase is getting prepared for i18n/l10n. + + * Interix, Cygwin and Minix ports got updated. + + * Various updates to git-p4 (in contrib/), fast-import, and git-svn. + + * Gitweb learned to read from /etc/gitweb-common.conf when it exists, + before reading from gitweb_config.perl or from /etc/gitweb.conf + (this last one is read only when per-repository gitweb_config.perl + does not exist). + + * Various codepaths that invoked zlib deflate/inflate assumed that these + functions can compress or uncompress more than 4GB data in one call on + platforms with 64-bit long, which has been corrected. + + * Git now recognizes loose objects written by other implementations that + use a non-standard window size for zlib deflation (e.g. Agit running on + Android with 4kb window). We used to reject anything that was not + deflated with 32kb window. + + * Interaction between the use of pager and coloring of the output has + been improved, especially when a command that is not built-in was + involved. + + * "git am" learned to pass the "--exclude=<path>" option through to underlying + "git apply". + + * You can now feed many empty lines before feeding an mbox file to + "git am". + + * "git archive" can be told to pass the output to gzip compression and + produce "archive.tar.gz". + + * "git bisect" can be used in a bare repository (provided that the test + you perform per each iteration does not need a working tree, of + course). + + * The length of abbreviated object names in "git branch -v" output + now honors the core.abbrev configuration variable. + + * "git check-attr" can take relative paths from the command line. + + * "git check-attr" learned an "--all" option to list the attributes for a + given path. + + * "git checkout" (both the code to update the files upon checking out a + different branch and the code to checkout a specific set of files) learned + to stream the data from object store when possible, without having to + read the entire contents of a file into memory first. An earlier round + of this code that is not in any released version had a large leak but + now it has been plugged. + + * "git clone" can now take a "--config key=value" option to set the + repository configuration options that affect the initial checkout. + + * "git commit <paths>..." now lets you feed relative pathspecs that + refer to outside your current subdirectory. + + * "git diff --stat" learned a --stat-count option to limit the output of + a diffstat report. + + * "git diff" learned a "--histogram" option to use a different diff + generation machinery stolen from jgit, which might give better + performance. + + * "git diff" had a weird worst case behaviour that can be triggered + when comparing files with potentially many places that could match. + + * "git fetch", "git push" and friends no longer show connection + errors for addresses that couldn't be connected to when at least one + address succeeds (this is arguably a regression but a deliberate + one). + + * "git grep" learned "--break" and "--heading" options, to let users mimic + the output format of "ack". + + * "git grep" learned a "-W" option that shows wider context using the same + logic used by "git diff" to determine the hunk header. + + * Invoking the low-level "git http-fetch" without "-a" option (which + git itself never did---normal users should not have to worry about + this) is now deprecated. + + * The "--decorate" option to "git log" and its family learned to + highlight grafted and replaced commits. + + * "git rebase master topci" no longer spews usage hints after giving + the "fatal: no such branch: topci" error message. + + * The recursive merge strategy implementation got a fairly large + fix for many corner cases that may rarely happen in real world + projects (it has been verified that none of the 16000+ merges in + the Linux kernel history back to v2.6.12 is affected with the + corner case bugs this update fixes). + + * "git stash" learned an "--include-untracked option". + + * "git submodule update" used to stop at the first error updating a + submodule; it now goes on to update other submodules that can be + updated, and reports the ones with errors at the end. + + * "git push" can be told with the "--recurse-submodules=check" option to + refuse pushing of the supermodule, if any of its submodules' + commits hasn't been pushed out to their remotes. + + * "git upload-pack" and "git receive-pack" learned to pretend that only a + subset of the refs exist in a repository. This may help a site to + put many tiny repositories into one repository (this would not be + useful for larger repositories as repacking would be problematic). + + * "git verify-pack" has been rewritten to use the "index-pack" machinery + that is more efficient in reading objects in packfiles. + + * test scripts for gitweb tried to run even when CGI-related perl modules + are not installed; they now exit early when the latter are unavailable. + +Also contains various documentation updates and minor miscellaneous +changes. + + +Fixes since v1.7.6 +------------------ + +Unless otherwise noted, all fixes in the 1.7.6.X maintenance track are +included in this release. + + * "git branch -m" and "git checkout -b" incorrectly allowed the tip + of the branch that is currently checked out updated. diff --git a/Documentation/RelNotes/1.7.8.txt b/Documentation/RelNotes/1.7.8.txt new file mode 100644 index 0000000000..1da562e715 --- /dev/null +++ b/Documentation/RelNotes/1.7.8.txt @@ -0,0 +1,181 @@ +Git v1.7.8 Release Notes (draft) +================================ + +Updates since v1.7.7 +-------------------- + + * Some git-svn, git-gui, git-p4 (in contrib) and msysgit updates. + + * Updates to bash completion scripts. + + * The build procedure has been taught to take advantage of computed + dependency automatically when the complier supports it. + + * The date parser now accepts timezone designators that lack minutes + part and also has a colon between "hh:mm". + + * The contents of the /etc/mailname file, if exists, is used as the + default value of the hostname part of the committer/author e-mail. + + * "git am" learned how to read from patches generated by Hg. + + * "git archive" talking with a remote repository can report errors + from the remote side in a more informative way. + + * "git branch" learned an explicit --list option to ask for branches + listed, optionally with a glob matching pattern to limit its output. + + * "git check-attr" learned "--cached" option to look at .gitattributes + files from the index, not from the working tree. + + * Variants of "git cherry-pick" and "git revert" that take multiple + commits learned to "--continue". + + * "git daemon" gives more human readble error messages to clients + using ERR packets when appropriate. + + * Errors at the network layer is logged by "git daemon". + + * "git diff" learned "--minimal" option to spend extra cycles to come + up with a minimal patch output. + + * "git diff" learned "--function-context" option to show the whole + function as context that was affected by a change. + + * "git difftool" can be told to skip launching the tool for a path by + answering 'n' to its prompt. + + * "git fetch" learned to honor transfer.fsckobjects configuration to + validate the objects that were received from the other end, just like + "git receive-pack" (the receiving end of "git push") does. + + * "git fetch" makes sure that the set of objects it received from the + other end actually completes the history before updating the refs. + "git receive-pack" (the receiving end of "git push") learned to do the + same. + + * "git fetch" learned that fetching/cloning from a regular file on the + filesystem is not necessarily a request to unpack a bundle file; the + file could be ".git" with "gitdir: <path>" in it. + + * "git for-each-ref" learned "%(contents:subject)", "%(contents:body)" + and "%(contents:signature)". The last one is useful for signed tags. + + * "git grep" used to incorrectly pay attention to .gitignore files + scattered in the directory it was working in even when "--no-index" + option was used. It no longer does this. The "--exclude-standard" + option needs to be given to explicitly activate the ignore + mechanism. + + * "git grep" learned "--untracked" option, where given patterns are + searched in untracked (but not ignored) files as well as tracked + files in the working tree, so that matches in new but not yet + added files do not get missed. + + * The recursive merge backend no longer looks for meaningless + existing merges in submodules unless in the outermost merge. + + * "git log" and friends learned "--children" option. + + * "git ls-remote" learned to respond to "-h"(elp) requests. + + * "mediawiki" remote helper can interact with (surprise!) MediaWiki + with "git fetch" & "git push". + + * "git merge" learned the "--edit" option to allow users to edit the + merge commit log message. + + * "git rebase -i" can be told to use special purpose editor suitable + only for its insn sheet via sequence.editor configuration variable. + + * "git send-email" learned to respond to "-h"(elp) requests. + + * "git send-email" allows the value given to sendemail.aliasfile to begin + with "~/" to refer to the $HOME directory. + + * "git send-email" forces use of Authen::SASL::Perl to work around + issues between Authen::SASL::Cyrus and AUTH PLAIN/LOGIN. + + * "git stash" learned "--include-untracked" option to stash away + untracked/ignored cruft from the working tree. + + * "git submodule clone" does not leak an error message to the UI + level unnecessarily anymore. + + * "git submodule update" learned to honor "none" as the value for + submodule.<name>.update to specify that the named submodule should + not be checked out by default. + + * When populating a new submodule directory with "git submodule init", + the $GIT_DIR metainformation directory for submodules is created inside + $GIT_DIR/modules/<name>/ directory of the superproject and referenced + via the gitfile mechanism. This is to make it possible to switch + between commits in the superproject that has and does not have the + submodule in the tree without re-cloning. + + * "git upload-archive" (hence "git archive --remote") can be built + and used on mingw port of Git. + + * "gitweb" leaked unescaped control characters from syntax hiliter + outputs. + + * "gitweb" can be told to give custom string at the end of the HTML + HEAD element. + + * "gitweb" now has its own manual pages. + + +Also contains other documentation updates and minor code cleanups. + + +Fixes since v1.7.7 +------------------ + +Unless otherwise noted, all fixes in the 1.7.7.X maintenance track are +included in this release. + + * HTTP transport did not use pushurl correctly, and also did not tell + what host it is trying to authenticate with when asking for + credentials. + (merge deba493 jk/http-auth later to maint). + + * "git blame" was aborted if started from an uncommitted content and + the path had the textconv filter in effect. + (merge 8518088 ss/blame-textconv-fake-working-tree later to maint). + + * "git branch -m/-M" advertised to update RENAME_REF ref in the + commit log message that introduced the feature but not anywhere in + the documentation, and never did update such a ref anyway. This + undocumented misfeature that did not exist has been excised. + (merge b0eab01 jc/maint-remove-renamed-ref later to maint). + + * Adding many refs to the local repository in one go (e.g. "git fetch" + that fetches many tags) and looking up a ref by name in a repository + with too many refs were unnecessarily slow. + (merge 17d68a54d jp/get-ref-dir-unsorted later to maint). + + * Report from "git commit" on untracked files was confused under + core.ignorecase option. + (merge 395c7356 jk/name-hash-dirent later to maint). + + * "git merge" did not understand ":/<pattern>" as a way to name a commit. + + " "git push" on the receiving end used to call post-receive and post-update + hooks for attempted removal of non-existing refs. + (merge 160b81ed ph/push-to-delete-nothing later to maint). + + * The logic to filter out forked projects in the project list in + "gitweb" was broken for some time. + (merge 53c632f jm/maint-gitweb-filter-forks-fix later to maint). + + * The logic to optimize the locality of the data in a pack introduced in + 1.7.7 was grossly inefficient. + (merge 38d4deb dm/pack-objects-update later to maint). + +--- +exec >/var/tmp/1 +O=v1.7.8-rc0-48-g92622e6 +echo O=$(git describe --always master) +git log --first-parent --oneline --reverse ^$O master +echo +git shortlog --no-merges ^$O master diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c686f8646b..0dbf2c9843 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -7,17 +7,24 @@ Checklist (and a short version for the impatient): before committing - do not check in commented out code or unneeded files - the first line of the commit message should be a short - description and should skip the full stop + description (50 characters is the soft limit, see DISCUSSION + in git-commit(1)), and should skip the full stop - the body should provide a meaningful commit message, which: - - uses the imperative, present tense: "change", - not "changed" or "changes". - - includes motivation for the change, and contrasts - its implementation with previous behaviour - - if you want your work included in git.git, add a - "Signed-off-by: Your Name <you@example.com>" line to the - commit message (or just use the option "-s" when - committing) to confirm that you agree to the Developer's - Certificate of Origin + . explains the problem the change tries to solve, iow, what + is wrong with the current code without the change. + . justifies the way the change solves the problem, iow, why + the result with the change is better. + . alternate solutions considered but discarded, if any. + - describe changes in imperative mood, e.g. "make xyzzy do frotz" + instead of "[This patch] makes xyzzy do frotz" or "[I] changed + xyzzy to do frotz", as if you are giving orders to the codebase + to change its behaviour. + - try to make sure your explanation can be understood without + external resources. Instead of giving a URL to a mailing list + archive, summarize the relevant points of the discussion. + - add a "Signed-off-by: Your Name <you@example.com>" line to the + commit message (or just use the option "-s" when committing) + to confirm that you agree to the Developer's Certificate of Origin - make sure that you have tests for the bug you are fixing - make sure that the test suite passes after your commit @@ -41,6 +48,7 @@ Checklist (and a short version for the impatient): maintainer (gitster@pobox.com) if (and only if) the patch is ready for inclusion. If you use git-send-email(1), please test it first by sending email to yourself. + - see below for instructions specific to your mailer Long version: @@ -53,6 +61,34 @@ But the patch submission requirements are a lot more relaxed here on the technical/contents front, because the core GIT is thousand times smaller ;-). So here is only the relevant bits. +(0) Decide what to base your work on. + +In general, always base your work on the oldest branch that your +change is relevant to. + + - A bugfix should be based on 'maint' in general. If the bug is not + present in 'maint', base it on 'master'. For a bug that's not yet + in 'master', find the topic that introduces the regression, and + base your work on the tip of the topic. + + - A new feature should be based on 'master' in general. If the new + feature depends on a topic that is in 'pu', but not in 'master', + base your work on the tip of that topic. + + - Corrections and enhancements to a topic not yet in 'master' should + be based on the tip of that topic. If the topic has not been merged + to 'next', it's alright to add a note to squash minor corrections + into the series. + + - In the exceptional case that a new feature depends on several topics + not in 'master', start working on 'next' or 'pu' privately and send + out patches for discussion. Before the final merge, you may have to + wait until some of the dependent topics graduate to 'master', and + rebase your work. + +To find the tip of a topic branch, run "git log --first-parent +master..pu" and look for the merge commit. The second parent of this +commit is the tip of the topic branch. (1) Make separate commits for logically separate changes. @@ -62,7 +98,10 @@ your commit head. Instead, always make a commit with complete commit message and generate a series of patches from your repository. It is a good discipline. -Describe the technical detail of the change(s). +Give an explanation for the change(s) that is detailed enough so +that people can judge if it is good thing to do, without reading +the actual patch text to determine how well the code does what +the explanation promises to do. If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces. @@ -71,9 +110,8 @@ help reviewers check the patch, and future maintainers understand the code, are the most beautiful patches. Descriptions that summarise the point in the subject well, and describe the motivation for the change, the approach taken by the change, and if relevant how this -differs substantially from the prior version, can be found on Usenet -archives back into the late 80's. Consider it like good Netiquette, -but for code. +differs substantially from the prior version, are all good things +to have. Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped @@ -96,8 +134,7 @@ Another thing: NULL pointers shall be written as NULL, not as 0. (2) Generate your patch using git tools out of your commits. -git based diff tools (git, Cogito, and StGIT included) generate -unidiff which is the preferred format. +git based diff tools generate unidiff which is the preferred format. You do not have to be afraid to use -M option to "git diff" or "git format-patch", if your patch involves file renames. The @@ -170,17 +207,16 @@ patch, format it as "multipart/signed", not a text/plain message that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is not a text/plain, it's something else. -Note that your maintainer does not necessarily read everything -on the git mailing list. If your patch is for discussion first, -send it "To:" the mailing list, and optionally "cc:" him. If it -is trivially correct or after the list reached a consensus, send -it "To:" the maintainer and optionally "cc:" the list for -inclusion. - -Also note that your maintainer does not actively involve himself in -maintaining what are in contrib/ hierarchy. When you send fixes and -enhancements to them, do not forget to "cc: " the person who primarily -worked on that hierarchy in contrib/. +Unless your patch is a very trivial and an obviously correct one, +first send it with "To:" set to the mailing list, with "cc:" listing +people who are involved in the area you are touching (the output from +"git blame $path" and "git shortlog --no-merges $path" would help to +identify them), to solicit comments and reviews. After the list +reached a consensus that it is a good idea to apply the patch, re-send +it with "To:" set to the maintainer and optionally "cc:" the list for +inclusion. Do not forget to add trailers such as "Acked-by:", +"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as +necessary. (4) Sign your work @@ -237,12 +273,21 @@ the change to its true author (see (2) above). Also notice that a real name is used in the Signed-off-by: line. Please don't hide your real name. -Some people also put extra tags at the end. +If you like, you can put extra tags at the end: + +1. "Reported-by:" is used to credit someone who found the bug that + the patch attempts to fix. +2. "Acked-by:" says that the person who is more familiar with the area + the patch attempts to modify liked the patch. +3. "Reviewed-by:", unlike the other tags, can only be offered by the + reviewer and means that she is completely satisfied that the patch + is ready for application. It is usually offered only after a + detailed review. +4. "Tested-by:" is used to indicate that the person applied the patch + and found it to have the desired effect. -"Acked-by:" says that the patch was reviewed by the person who -is more familiar with the issues and the area the patch attempts -to modify. "Tested-by:" says the patch was tested by the person -and found to have the desired effect. +You can also create your own tag or use one that's in common usage +such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". ------------------------------------------------ An ideal patch flow @@ -298,50 +343,20 @@ MUA specific hints Some of patches I receive or pick up from the list share common patterns of breakage. Please make sure your MUA is set up -properly not to corrupt whitespaces. Here are two common ones -I have seen: - -* Empty context lines that do not have _any_ whitespace. - -* Non empty context lines that have one extra whitespace at the - beginning. - -One test you could do yourself if your MUA is set up correctly is: - -* Send the patch to yourself, exactly the way you would, except - To: and Cc: lines, which would not contain the list and - maintainer address. - -* Save that patch to a file in UNIX mailbox format. Call it say - a.patch. - -* Try to apply to the tip of the "master" branch from the - git.git public repository: - - $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply - $ git checkout test-apply - $ git reset --hard - $ git am a.patch +properly not to corrupt whitespaces. -If it does not apply correctly, there can be various reasons. +See the DISCUSSION section of git-format-patch(1) for hints on +checking your patch by mailing it to yourself and applying with +git-am(1). -* Your patch itself does not apply cleanly. That is _bad_ but - does not have much to do with your MUA. Please rebase the - patch appropriately. - -* Your MUA corrupted your patch; "am" would complain that - the patch does not apply. Look at .git/rebase-apply/ subdirectory and - see what 'patch' file contains and check for the common - corruption patterns mentioned above. - -* While you are at it, check what are in 'info' and - 'final-commit' files as well. If what is in 'final-commit' is - not exactly what you would want to see in the commit log - message, it is very likely that your maintainer would end up - hand editing the log message when he applies your patch. - Things like "Hi, this is my first patch.\n", if you really - want to put in the patch e-mail, should come after the - three-dash line that signals the end of the commit message. +While you are at it, check the resulting commit log message from +a trial run of applying the patch. If what is in the resulting +commit is not exactly what you would want to see, it is very +likely that your maintainer would end up hand editing the log +message when he applies your patch. Things like "Hi, this is my +first patch.\n", if you really want to put in the patch e-mail, +should come after the three-dash line that signals the end of the +commit message. Pine @@ -397,89 +412,10 @@ that or Gentoo did it.) So you need to set the it. -Thunderbird ------------ - -(A Large Angry SCM) - -By default, Thunderbird will both wrap emails as well as flag them as -being 'format=flowed', both of which will make the resulting email unusable -by git. - -Here are some hints on how to successfully submit patches inline using -Thunderbird. - -There are two different approaches. One approach is to configure -Thunderbird to not mangle patches. The second approach is to use -an external editor to keep Thunderbird from mangling the patches. - -Approach #1 (configuration): - -This recipe is current as of Thunderbird 2.0.0.19. Three steps: - 1. Configure your mail server composition as plain text - Edit...Account Settings...Composition & Addressing, - uncheck 'Compose Messages in HTML'. - 2. Configure your general composition window to not wrap - Edit..Preferences..Composition, wrap plain text messages at 0 - 3. Disable the use of format=flowed - Edit..Preferences..Advanced..Config Editor. Search for: - mailnews.send_plaintext_flowed - toggle it to make sure it is set to 'false'. - -After that is done, you should be able to compose email as you -otherwise would (cut + paste, git-format-patch | git-imap-send, etc), -and the patches should not be mangled. - -Approach #2 (external editor): - -This recipe appears to work with the current [*1*] Thunderbird from Suse. - -The following Thunderbird extensions are needed: - AboutConfig 0.5 - http://aboutconfig.mozdev.org/ - External Editor 0.7.2 - http://globs.org/articles.php?lng=en&pg=8 - -1) Prepare the patch as a text file using your method of choice. - -2) Before opening a compose window, use Edit->Account Settings to -uncheck the "Compose messages in HTML format" setting in the -"Composition & Addressing" panel of the account to be used to send the -patch. [*2*] +Thunderbird, KMail, GMail +------------------------- -3) In the main Thunderbird window, _before_ you open the compose window -for the patch, use Tools->about:config to set the following to the -indicated values: - mailnews.send_plaintext_flowed => false - mailnews.wraplength => 0 - -4) Open a compose window and click the external editor icon. - -5) In the external editor window, read in the patch file and exit the -editor normally. - -6) Back in the compose window: Add whatever other text you wish to the -message, complete the addressing and subject fields, and press send. - -7) Optionally, undo the about:config/account settings changes made in -steps 2 & 3. - - -[Footnotes] -*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse -9.3 professional updates. - -*2* It may be possible to do this with about:config and the following -settings but I haven't tried, yet. - mail.html_compose => false - mail.identity.default.compose_html => false - mail.identity.id?.compose_html => false - -(Lukas Sandström) - -There is a script in contrib/thunderbird-patch-inline which can help -you include patches with Thunderbird in an easy way. To use it, do the -steps above and then use the script as the external editor. +See the MUA-SPECIFIC HINTS section of git-format-patch(1). Gnus ---- @@ -494,58 +430,3 @@ characters (most notably in people's names), and also whitespaces (fatal in patches). Running 'C-u g' to display the message in raw form before using '|' to run the pipe can work this problem around. - - -KMail ------ - -This should help you to submit patches inline using KMail. - -1) Prepare the patch as a text file. - -2) Click on New Mail. - -3) Go under "Options" in the Composer window and be sure that -"Word wrap" is not set. - -4) Use Message -> Insert file... and insert the patch. - -5) Back in the compose window: add whatever other text you wish to the -message, complete the addressing and subject fields, and press send. - - -Gmail ------ - -GMail does not appear to have any way to turn off line wrapping in the web -interface, so this will mangle any emails that you send. You can however -use any IMAP email client to connect to the google imap server, and forward -the emails through that. Just make sure to disable line wrapping in that -email client. Alternatively, use "git send-email" instead. - -Submitting properly formatted patches via Gmail is simple now that -IMAP support is available. First, edit your ~/.gitconfig to specify your -account settings: - -[imap] - folder = "[Gmail]/Drafts" - host = imaps://imap.gmail.com - user = user@gmail.com - pass = p4ssw0rd - port = 993 - sslverify = false - -You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error -that the "Folder doesn't exist". - -Next, ensure that your Gmail settings are correct. In "Settings" the -"Use Unicode (UTF-8) encoding for outgoing messages" should be checked. - -Once your commits are ready to send to the mailing list, run the following -command to send the patch emails to your Gmail Drafts folder. - - $ git format-patch -M --stdout origin/master | git imap-send - -Go to your Gmail account, open the Drafts folder, find the patch email, fill -in the To: and CC: fields and send away! - diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 87a90f2c3f..aea8627be0 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -16,8 +16,11 @@ plus=+ caret=^ startsb=[ endsb=] +backslash=\ tilde=~ +apostrophe=' backtick=` +litdd=-- ifdef::backend-docbook[] [linkgit-inlinemacro] diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 4833cac4b9..d4a51da464 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -52,6 +52,11 @@ of lines before or after the line given by <start>. --porcelain:: Show in a format designed for machine consumption. +--line-porcelain:: + Show the porcelain format, but output commit information for + each line, not just the first time a commit is referenced. + Implies --porcelain. + --incremental:: Show the result incrementally in a format designed for machine consumption. @@ -79,22 +84,23 @@ of lines before or after the line given by <start>. of the --date option at linkgit:git-log[1]. -M|<num>|:: - Detect moving lines in the file as well. When a commit - moves a block of lines in a file (e.g. the original file - has A and then B, and the commit changes it to B and - then A), the traditional 'blame' algorithm typically blames - the lines that were moved up (i.e. B) to the parent and - assigns blame to the lines that were moved down (i.e. A) - to the child commit. With this option, both groups of lines - are blamed on the parent. + Detect moved or copied lines within a file. When a commit + moves or copies a block of lines (e.g. the original file + has A and then B, and the commit changes it to B and then + A), the traditional 'blame' algorithm notices only half of + the movement and typically blames the lines that were moved + up (i.e. B) to the parent and assigns blame to the lines that + were moved down (i.e. A) to the child commit. With this + option, both groups of lines are blamed on the parent by + running extra passes of inspection. + <num> is optional but it is the lower bound on the number of -alphanumeric characters that git must detect as moving +alphanumeric characters that git must detect as moving/copying within a file for it to associate those lines with the parent -commit. +commit. The default value is 20. -C|<num>|:: - In addition to `-M`, detect lines copied from other + In addition to `-M`, detect lines moved or copied from other files that were modified in the same commit. This is useful when you reorganize your program and move code around across files. When this option is given twice, @@ -104,10 +110,11 @@ commit. looks for copies from other files in any commit. + <num> is optional but it is the lower bound on the number of -alphanumeric characters that git must detect as moving +alphanumeric characters that git must detect as moving/copying between files for it to associate those lines with the parent -commit. +commit. And the default value is 40. If there are more than one +`-C` options given, the <num> argument of the last `-C` will +take effect. -h:: ---help:: Show help message. diff --git a/Documentation/config.txt b/Documentation/config.txt index 2d6775c135..5a841da6d4 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -45,9 +45,10 @@ lines. Variables may belong directly to a section or to a given subsection. You can have `[section]` if you have `[section "subsection"]`, but you don't need to. -There is also a case insensitive alternative `[section.subsection]` syntax. -In this syntax, subsection names follow the same restrictions as for section -names. +There is also a deprecated `[section.subsection]` syntax. With this +syntax, the subsection name is converted to lower-case and is also +compared case sensitively. These subsection names follow the same +restrictions as section names. All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form @@ -62,9 +63,9 @@ Internal whitespace within a variable value is retained verbatim. The values following the equals sign in variable assign are all either a string, an integer, or a boolean. Boolean values may be given as yes/no, -0/1, true/false or on/off. Case is not significant in boolean values, when +1/0, true/false or on/off. Case is not significant in boolean values, when converting value to the canonical form using '--bool' type specifier; -'git-config' will ensure that the output is "true" or "false". +'git config' will ensure that the output is "true" or "false". String values may be entirely or partially enclosed in double quotes. You need to enclose variable values in double quotes if you want to @@ -128,13 +129,26 @@ advice.*:: when writing commit messages. Default: true. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to - merge to avoid overwritting local changes. + merge to avoid overwriting local changes. Default: true. + resolveConflict:: + Advices shown by various commands when conflicts + prevent the operation from being performed. + Default: true. + implicitIdentity:: + Advice on how to set your identity configuration when + your information is guessed from the system username and + domain name. Default: true. + + detachedHead:: + Advice shown when you used linkgit::git-checkout[1] to + move to the detach HEAD state, to instruct how to create + a local branch after the fact. Default: true. -- core.fileMode:: If false, the executable bit differences between the index and - the working copy are ignored; useful on broken filesystems like FAT. + the working tree are ignored; useful on broken filesystems like FAT. See linkgit:git-update-index[1]. + The default is true, except linkgit:git-clone[1] or linkgit:git-init[1] @@ -166,7 +180,7 @@ is created. core.trustctime:: If false, the ctime differences between the index and the - working copy are ignored; useful when the inode change time + working tree are ignored; useful when the inode change time is regularly modified by something outside Git (file system crawlers and some backup systems). See linkgit:git-update-index[1]. True by default. @@ -183,20 +197,17 @@ core.quotepath:: quoted without `-z` regardless of the setting of this variable. -core.autocrlf:: - If true, makes git convert `CRLF` at the end of lines in text files to - `LF` when reading from the filesystem, and convert in reverse when - writing to the filesystem. The variable can be set to - 'input', in which case the conversion happens only while - reading from the filesystem but files are written out with - `LF` at the end of lines. A file is considered - "text" (i.e. be subjected to the autocrlf mechanism) based on - the file's `crlf` attribute, or if `crlf` is unspecified, - based on the file's contents. See linkgit:gitattributes[5]. +core.eol:: + Sets the line ending type to use in the working directory for + files that have the `text` property set. Alternatives are + 'lf', 'crlf' and 'native', which uses the platform's native + line ending. The default value is `native`. See + linkgit:gitattributes[5] for more information on end-of-line + conversion. core.safecrlf:: - If true, makes git check if converting `CRLF` as controlled by - `core.autocrlf` is reversible. Git will verify if a command + If true, makes git check if converting `CRLF` is reversible when + end-of-line conversion is active. Git will verify if a command modifies a file in the work tree either directly or indirectly. For example, committing a file followed by checking out the same file should yield the original file in the work tree. If @@ -206,7 +217,7 @@ core.safecrlf:: irreversible conversion but continue the operation. + CRLF conversion bears a slight chance of corrupting data. -autocrlf=true will convert CRLF to LF during commit and LF to +When it is enabled, git will convert CRLF to LF during commit and LF to CRLF during checkout. A file that contains a mixture of LF and CRLF before the commit cannot be recreated by git. For text files this is the right thing to do: it corrects line endings @@ -230,15 +241,25 @@ converting CRLFs corrupts data. + Note, this safety check does not mean that a checkout will generate a file identical to the original file for a different setting of -`core.autocrlf`, but only for the current one. For example, a text -file with `LF` would be accepted with `core.autocrlf=input` and could -later be checked out with `core.autocrlf=true`, in which case the +`core.eol` and `core.autocrlf`, but only for the current one. For +example, a text file with `LF` would be accepted with `core.eol=lf` +and could later be checked out with `core.eol=crlf`, in which case the resulting file would contain `CRLF`, although the original file contained `LF`. However, in both work trees the line endings would be consistent, that is either all `LF` or all `CRLF`, but never mixed. A file with mixed line endings would be reported by the `core.safecrlf` mechanism. +core.autocrlf:: + Setting this variable to "true" is almost the same as setting + the `text` attribute to "auto" on all files except that text + files are not guaranteed to be normalized: files that contain + `CRLF` in the repository will not be touched. Use this + setting if you want to have `CRLF` line endings in your + working directory even though the repository does not have + normalized line endings. This variable can be set to 'input', + in which case no output conversion is performed. + core.symlinks:: If false, symbolic links are checked out as small plain files that contain the link text. linkgit:git-update-index[1] and @@ -272,7 +293,7 @@ core.ignoreStat:: If true, commands which modify both the working tree and the index will mark the updated paths with the "assume unchanged" bit in the index. These marked files are then assumed to stay unchanged in the - working copy, until you mark them otherwise manually - Git will not + working tree, until you mark them otherwise manually - Git will not detect the file changes by lstat() calls. This is useful on systems where those are very slow, such as Microsoft Windows. See linkgit:git-update-index[1]. @@ -297,24 +318,26 @@ false), while all other repositories are assumed to be bare (bare = true). core.worktree:: - Set the path to the root of the work tree. + Set the path to the root of the working tree. This can be overridden by the GIT_WORK_TREE environment - variable and the '--work-tree' command line option. It can be - an absolute path or a relative path to the .git directory, - either specified by --git-dir or GIT_DIR, or automatically - discovered. - If --git-dir or GIT_DIR are specified but none of + variable and the '--work-tree' command line option. + The value can be an absolute path or relative to the path to + the .git directory, which is either specified by --git-dir + or GIT_DIR, or automatically discovered. + If --git-dir or GIT_DIR is specified but none of --work-tree, GIT_WORK_TREE and core.worktree is specified, - the current working directory is regarded as the root of the - work tree. + the current working directory is regarded as the top level + of your working tree. + Note that this variable is honored even when set in a configuration -file in a ".git" subdirectory of a directory, and its value differs +file in a ".git" subdirectory of a directory and its value differs from the latter directory (e.g. "/path/to/.git/config" has core.worktree set to "/different/path"), which is most likely a -misconfiguration. Running git commands in "/path/to" directory will +misconfiguration. Running git commands in the "/path/to" directory will still use "/different/path" as the root of the work tree and can cause -great confusion to the users. +confusion unless you know what you are doing (e.g. you are creating a +read-only snapshot of the same index to a location different from the +repository's usual working tree). core.logAllRefUpdates:: Enable the reflog. Updates to a ref <ref> is logged to the file @@ -322,7 +345,9 @@ core.logAllRefUpdates:: SHA1, the date/time and the reason of the update, but only when the file exists. If this configuration variable is set to true, missing "$GIT_DIR/logs/<ref>" - file is automatically created for branch heads. + file is automatically created for branch heads (i.e. under + refs/heads/), remote refs (i.e. under refs/remotes/), + note refs (i.e. under refs/notes/), and the symbolic ref HEAD. + This information can be used to determine what commit was the tip of a branch "2 days ago". @@ -398,7 +423,7 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. core.deltaBaseCacheLimit:: Maximum number of bytes to reserve for caching base objects - that multiple deltafied objects reference. By storing the + that may be referenced by multiple deltified objects. By storing the entire decompressed base objects in a cache Git is able to avoid unpacking and decompressing frequently used base objects multiple times. @@ -409,6 +434,18 @@ You probably do not need to adjust this value. + Common unit suffixes of 'k', 'm', or 'g' are supported. +core.bigFileThreshold:: + Files larger than this size are stored deflated, without + attempting delta compression. Storing large files without + delta compression avoids excessive memory usage, at the + slight expense of increased disk usage. ++ +Default is 512 MiB on all platforms. This should be reasonable +for most projects as source code and other text files can still +be delta compressed, but larger binary media files won't be. ++ +Common unit suffixes of 'k', 'm', or 'g' are supported. + core.excludesfile:: In addition to '.gitignore' (per-directory) and '.git/info/exclude', git looks into this file for patterns @@ -416,12 +453,33 @@ core.excludesfile:: to the value of `$HOME` and "{tilde}user/" to the specified user's home directory. See linkgit:gitignore[5]. +core.askpass:: + Some commands (e.g. svn and http interfaces) that interactively + ask for a password can be told to use an external program given + via the value of this variable. Can be overridden by the 'GIT_ASKPASS' + environment variable. If not set, fall back to the value of the + 'SSH_ASKPASS' environment variable or, failing that, a simple password + prompt. The external program shall be given a suitable prompt as + command line argument and write the password on its STDOUT. + +core.attributesfile:: + In addition to '.gitattributes' (per-directory) and + '.git/info/attributes', git looks into this file for attributes + (see linkgit:gitattributes[5]). Path expansions are made the same + way as for `core.excludesfile`. + core.editor:: Commands such as `commit` and `tag` that lets you edit messages by launching an editor uses the value of this variable when it is set, and the environment variable `GIT_EDITOR` is not set. See linkgit:git-var[1]. +sequence.editor:: + Text editor used by `git rebase -i` for editing the rebase insn file. + The value is meant to be interpreted by the shell when it is used. + It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable. + When not configured the default commit message editor is used instead. + core.pager:: The command that git will use to paginate output. Can be overridden with the `GIT_PAGER` environment @@ -442,8 +500,8 @@ core.pager:: core.whitespace:: A comma separated list of common whitespace problems to - notice. 'git-diff' will use `color.diff.whitespace` to - highlight them, and 'git-apply --whitespace=error' will + notice. 'git diff' will use `color.diff.whitespace` to + highlight them, and 'git apply --whitespace=error' will consider them as errors. You can prefix `-` to disable any of them (e.g. `-trailing-space`): + @@ -454,6 +512,8 @@ core.whitespace:: 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). +* `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 (enabled by default). * `trailing-space` is a short-hand to cover both `blank-at-eol` and @@ -462,6 +522,9 @@ core.whitespace:: part of the line terminator, i.e. with it, `trailing-space` does not trigger if the character before such a carriage-return is not a whitespace (not enabled by default). +* `tabwidth=<n>` tells how many character positions a tab occupies; this + is relevant for `indent-with-non-tab` and when git fixes `tab-in-indent` + errors. The default tab width is 8. Allowed values are 1 to 63. core.fsyncobjectfiles:: This boolean will enable 'fsync()' when writing object files. @@ -491,25 +554,31 @@ check that makes sure that existing object files will not get overwritten. core.notesRef:: When showing commit messages, also show notes which are stored in - the given ref. This ref is expected to contain files named - after the full SHA-1 of the commit they annotate. -+ -If such a file exists in the given ref, the referenced blob is read, and -appended to the commit message, separated by a "Notes:" line. If the -given ref itself does not exist, it is not an error, but means that no -notes should be printed. + the given ref. The ref must be fully qualified. If the given + ref does not exist, it is not an error but means that no + notes should be printed. + -This setting defaults to "refs/notes/commits", and can be overridden by -the `GIT_NOTES_REF` environment variable. +This setting defaults to "refs/notes/commits", and it can be overridden by +the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1]. core.sparseCheckout:: Enable "sparse checkout" feature. See section "Sparse checkout" in linkgit:git-read-tree[1] for more information. +core.abbrev:: + Set the length object names are abbreviated to. If unspecified, + many commands abbreviate to 7 hexdigits, which may not be enough + for abbreviated object names to stay unique for sufficiently long + time. + add.ignore-errors:: - Tells 'git-add' to continue adding files when some files cannot be +add.ignoreErrors:: + Tells 'git add' to continue adding files when some files cannot be added due to indexing errors. Equivalent to the '--ignore-errors' - option of linkgit:git-add[1]. + option of linkgit:git-add[1]. Older versions of git accept only + `add.ignore-errors`, which does not follow the usual naming + convention for configuration variables. Newer versions of git + honor `add.ignoreErrors` as well. alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. @@ -527,39 +596,49 @@ it will be treated as a shell command. For example, defining "gitk --all --not ORIG_HEAD". Note that shell commands will be executed from the top-level directory of a repository, which may not necessarily be the current directory. +'GIT_PREFIX' is set as returned by running 'git rev-parse --show-prefix' +from the original current directory. See linkgit:git-rev-parse[1]. + +am.keepcr:: + If true, git-am will call git-mailsplit for patches in mbox format + with parameter '--keep-cr'. In this case git-mailsplit will + not remove `\r` from lines ending with `\r\n`. Can be overridden + by giving '--no-keep-cr' from the command line. + See linkgit:git-am[1], linkgit:git-mailsplit[1]. apply.ignorewhitespace:: - When set to 'change', tells 'git-apply' to ignore changes in + When set to 'change', tells 'git apply' to ignore changes in whitespace, in the same way as the '--ignore-space-change' option. - When set to one of: no, none, never, false tells 'git-apply' to + When set to one of: no, none, never, false tells 'git apply' to respect all whitespace differences. See linkgit:git-apply[1]. apply.whitespace:: - Tells 'git-apply' how to handle whitespaces, in the same way + Tells 'git apply' how to handle whitespaces, in the same way as the '--whitespace' option. See linkgit:git-apply[1]. branch.autosetupmerge:: - Tells 'git-branch' and 'git-checkout' to set up new branches + Tells 'git branch' and 'git checkout' to set up new branches so that linkgit:git-pull[1] will appropriately merge from the starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` and `--no-track` options. The valid settings are: `false` -- no automatic setup is done; `true` -- automatic setup is done when the - starting point is a remote branch; `always` -- automatic setup is - done when the starting point is either a local branch or remote + starting point is a remote-tracking branch; `always` -- + automatic setup is done when the starting point is either a + local branch or remote-tracking branch. This option defaults to true. branch.autosetuprebase:: - When a new branch is created with 'git-branch' or 'git-checkout' + When a new branch is created with 'git branch' or 'git checkout' that tracks another branch, this variable tells git to set up pull to rebase instead of merge (see "branch.<name>.rebase"). When `never`, rebase is never automatically set to true. When `local`, rebase is set to true for tracked branches of other local branches. When `remote`, rebase is set to true for tracked branches of - remote branches. + remote-tracking branches. When `always`, rebase will be set to true for all tracking branches. See "branch.autosetupmerge" for details on how to set up a @@ -567,24 +646,24 @@ branch.autosetuprebase:: This option defaults to never. branch.<name>.remote:: - When in branch <name>, it tells 'git-fetch' and 'git-push' which + When in branch <name>, it tells 'git fetch' and 'git push' which remote to fetch from/push to. It defaults to `origin` if no remote is configured. `origin` is also used if you are not on any branch. branch.<name>.merge:: Defines, together with branch.<name>.remote, the upstream branch - for the given branch. It tells 'git-fetch'/'git-pull' which - branch to merge and can also affect 'git-push' (see push.default). - When in branch <name>, it tells 'git-fetch' the default + for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which + branch to merge and can also affect 'git push' (see push.default). + When in branch <name>, it tells 'git fetch' the default refspec to be marked for merging in FETCH_HEAD. The value is handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by "branch.<name>.remote". - The merge information is used by 'git-pull' (which at first calls - 'git-fetch') to lookup the default branch for merging. Without - this option, 'git-pull' defaults to merge the first refspec fetched. + The merge information is used by 'git pull' (which at first calls + 'git fetch') to lookup the default branch for merging. Without + this option, 'git pull' defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. - If you wish to setup 'git-pull' so that it merges into <name> from + If you wish to setup 'git pull' so that it merges into <name> from another branch in the local repository, you can point branch.<name>.merge to the desired branch, and use the special setting `.` (a period) for branch.<name>.remote. @@ -606,7 +685,7 @@ branch.<name>.rebase:: browser.<tool>.cmd:: Specify the command to invoke the specified browser. The specified command is evaluated in shell with the URLs passed - as arguments. (See linkgit:git-web--browse[1].) + as arguments. (See linkgit:git-web{litdd}browse[1].) browser.<tool>.path:: Override the path for the given tool that may be used to @@ -626,7 +705,7 @@ color.branch:: color.branch.<slot>:: Use customized color for branch coloration. `<slot>` is one of `current` (the current branch), `local` (a local branch), - `remote` (a tracking branch in refs/remotes/), `plain` (other + `remote` (a remote-tracking branch in refs/remotes/), `plain` (other refs). + The value for these configuration variables is a list of colors (at most @@ -638,9 +717,16 @@ second is the background. The position of the attribute, if any, doesn't matter. color.diff:: - When set to `always`, always use colors in patch. - When false (or `never`), never. When set to `true` or `auto`, use - colors only when the output is to the terminal. Defaults to false. + Whether to use ANSI escape sequences to add color to patches. + If this is set to `always`, linkgit:git-diff[1], + linkgit:git-log[1], and linkgit:git-show[1] will use color + for all patches. If it is set to `true` or `auto`, those + commands will only use color when output is to the terminal. + Defaults to false. ++ +This does not affect linkgit:git-format-patch[1] nor the +'git-diff-{asterisk}' plumbing commands. Can be overridden on the +command line with the `--color[=<when>]` option. color.diff.<slot>:: Use customized color for diff colorization. `<slot>` specifies @@ -651,24 +737,39 @@ color.diff.<slot>:: (highlighting whitespace errors). The values of these variables may be specified as in color.branch.<slot>. +color.decorate.<slot>:: + Use customized color for 'git log --decorate' output. `<slot>` is one + of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local + branches, remote-tracking branches, tags, stash and HEAD, respectively. + color.grep:: When set to `always`, always highlight matches. When `false` (or `never`), never. When set to `true` or `auto`, use color only when the output is written to the terminal. Defaults to `false`. -color.grep.external:: - The string value of this variable is passed to an external 'grep' - command as a command line option if match highlighting is turned - on. If set to an empty string, no option is passed at all, - turning off coloring for external 'grep' calls; this is the default. - For GNU grep, set it to `--color=always` to highlight matches even - when a pager is used. - -color.grep.match:: - Use customized color for matches. The value of this variable - may be specified as in color.branch.<slot>. It is passed using - the environment variables 'GREP_COLOR' and 'GREP_COLORS' when - calling an external 'grep'. +color.grep.<slot>:: + Use customized color for grep colorization. `<slot>` specifies which + part of the line to use the specified color, and is one of ++ +-- +`context`;; + non-matching text in context lines (when using `-A`, `-B`, or `-C`) +`filename`;; + filename prefix (when not using `-h`) +`function`;; + function name lines (when using `-p`) +`linenumber`;; + line number prefix (when using `-n`) +`match`;; + matching text +`selected`;; + non-matching text in selected lines +`separator`;; + separators between fields on a line (`:`, `-`, and `=`) + and between hunks (`--`) +-- ++ +The values of these variables may be specified as in color.branch.<slot>. color.interactive:: When set to `always`, always use colors for interactive prompts @@ -677,7 +778,7 @@ color.interactive:: colors only when the output is to the terminal. Defaults to false. color.interactive.<slot>:: - Use customized color for 'git-add --interactive' + Use customized color for 'git add --interactive' output. `<slot>` may be `prompt`, `header`, `help` or `error`, for four distinct types of normal output from interactive commands. The values of these variables may be specified as @@ -704,19 +805,24 @@ color.status.<slot>:: one of `header` (the header text of the status message), `added` or `updated` (files which are added but not committed), `changed` (files which are changed but not added in the index), - `untracked` (files which are not tracked by git), or + `untracked` (files which are not tracked by git), + `branch` (the current branch), or `nobranch` (the color the 'no branch' warning is shown in, defaulting to red). The values of these variables may be specified as in color.branch.<slot>. color.ui:: - When set to `always`, always use colors in all git commands which - are capable of colored output. When false (or `never`), never. When - set to `true` or `auto`, use colors only when the output is to the - terminal. When more specific variables of color.* are set, they always - take precedence over this setting. Defaults to false. - -commit.status + This variable determines the default value for variables such + as `color.diff` and `color.grep` that control the use of color + per command family. Its scope will expand as more commands learn + configuration to set a default for the `--color` option. Set it + to `always` if you want all output not intended for machine + consumption to use color, to `true` or `auto` if you want such + output to use color when written to the terminal, or to `false` or + `never` if you prefer git commands not to use color unless enabled + explicitly with some other configuration or the `--color` option. + +commit.status:: A boolean to enable/disable inclusion of status information in the commit message template when using an editor to prepare the commit message. Defaults to true. @@ -726,59 +832,7 @@ commit.template:: "{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the specified user's home directory. -diff.autorefreshindex:: - When using 'git-diff' to compare with work tree - files, do not consider stat-only change as changed. - Instead, silently run `git update-index --refresh` to - update the cached stat information for paths whose - contents in the work tree match the contents in the - index. This option defaults to true. Note that this - affects only 'git-diff' Porcelain, and not lower level - 'diff' commands such as 'git-diff-files'. - -diff.external:: - If this config variable is set, diff generation is not - performed using the internal diff machinery, but using the - given command. Can be overridden with the `GIT_EXTERNAL_DIFF' - environment variable. The command is called with parameters - as described under "git Diffs" in linkgit:git[1]. Note: if - you want to use an external diff program only on a subset of - your files, you might want to use linkgit:gitattributes[5] instead. - -diff.mnemonicprefix:: - If set, 'git-diff' uses a prefix pair that is different from the - standard "a/" and "b/" depending on what is being compared. When - this configuration is in effect, reverse diff output also swaps - the order of the prefixes: -'git-diff';; - compares the (i)ndex and the (w)ork tree; -'git-diff HEAD';; - compares a (c)ommit and the (w)ork tree; -'git diff --cached';; - compares a (c)ommit and the (i)ndex; -'git-diff HEAD:file1 file2';; - compares an (o)bject and a (w)ork tree entity; -'git diff --no-index a b';; - compares two non-git things (1) and (2). - -diff.renameLimit:: - The number of files to consider when performing the copy/rename - detection; equivalent to the 'git-diff' option '-l'. - -diff.renames:: - Tells git to detect renames. If set to any boolean value, it - will enable basic rename detection. If set to "copies" or - "copy", it will detect copies, as well. - -diff.suppressBlankEmpty:: - A boolean to inhibit the standard behavior of printing a space - before each empty output line. Defaults to false. - -diff.tool:: - Controls which diff tool is used. `diff.tool` overrides - `merge.tool` when used by linkgit:git-difftool[1] and has - the same valid values as `merge.tool` minus "tortoisemerge" - and plus "kompare". +include::diff-config.txt[] difftool.<tool>.path:: Override the path for the given tool. This is useful in case @@ -801,6 +855,22 @@ diff.wordRegex:: sequences that match the regular expression are "words", all other characters are *ignorable* whitespace. +fetch.recurseSubmodules:: + This option can be either set to a boolean value or to 'on-demand'. + Setting it to a boolean changes the behavior of fetch and pull to + unconditionally recurse into submodules when set to true or to not + recurse at all when set to false. When set to 'on-demand' (the default + value), fetch and pull will only recurse into a populated submodule + when its superproject retrieves a commit that updates the submodule's + reference. + +fetch.fsckObjects:: + If it is set to true, git-fetch-pack will check all fetched + objects. It will abort in the case of a malformed object or a + broken link. The result of an abort are only dangling objects. + Defaults to false. If not set, the value of `transfer.fsckObjects` + is used instead. + fetch.unpackLimit:: If the number of objects fetched over the git native transfer is below this @@ -830,14 +900,22 @@ format.headers:: Additional email headers to include in a patch to be submitted by mail. See linkgit:git-format-patch[1]. +format.to:: format.cc:: - Additional "Cc:" headers to include in a patch to be submitted - by mail. See the --cc option in linkgit:git-format-patch[1]. + Additional recipients to include in a patch to be submitted + by mail. See the --to and --cc options in + linkgit:git-format-patch[1]. format.subjectprefix:: The default for format-patch is to output files with the '[PATCH]' subject prefix. Use this variable to change that prefix. +format.signature:: + The default for format-patch is to output a signature containing + the git version number. Use this variable to change that default. + Set this variable to the empty string ("") to suppress + signature generation. + format.suffix:: The default for format-patch is to output files with the suffix `.patch`. Use this variable to change that suffix (make sure to @@ -849,7 +927,7 @@ format.pretty:: linkgit:git-whatchanged[1]. format.thread:: - The default threading style for 'git-format-patch'. Can be + The default threading style for 'git format-patch'. Can be a boolean value, or `shallow` or `deep`. `shallow` threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the @@ -865,10 +943,20 @@ format.signoff:: the rights to submit this work under the same open source license. Please see the 'SubmittingPatches' document for further discussion. +filter.<driver>.clean:: + The command which is used to convert the content of a worktree + file to a blob upon checkin. See linkgit:gitattributes[5] for + details. + +filter.<driver>.smudge:: + The command which is used to convert the content of a blob + object to a worktree file upon checkout. See + linkgit:gitattributes[5] for details. + gc.aggressiveWindow:: The window size parameter used in the delta compression - algorithm used by 'git-gc --aggressive'. This defaults - to 10. + algorithm used by 'git gc --aggressive'. This defaults + to 250. gc.auto:: When there are approximately more than this many loose @@ -887,33 +975,39 @@ gc.packrefs:: Running `git pack-refs` in a repository renders it unclonable by Git versions prior to 1.5.1.2 over dumb transports such as HTTP. This variable determines whether - 'git gc' runs `git pack-refs`. This can be set to "nobare" + 'git gc' runs `git pack-refs`. This can be set to `notbare` to enable it within all non-bare repos or it can be set to a boolean value. The default is `true`. gc.pruneexpire:: - When 'git-gc' is run, it will call 'prune --expire 2.weeks.ago'. + When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'. Override the grace period with this config variable. The value "now" may be used to disable this grace period and always prune unreachable objects immediately. gc.reflogexpire:: - 'git-reflog expire' removes reflog entries older than - this time; defaults to 90 days. +gc.<pattern>.reflogexpire:: + 'git reflog expire' removes reflog entries older than + this time; defaults to 90 days. With "<pattern>" (e.g. + "refs/stash") in the middle the setting applies only to + the refs that match the <pattern>. gc.reflogexpireunreachable:: - 'git-reflog expire' removes reflog entries older than +gc.<ref>.reflogexpireunreachable:: + 'git reflog expire' removes reflog entries older than this time and are not reachable from the current tip; - defaults to 30 days. + defaults to 30 days. With "<pattern>" (e.g. "refs/stash") + in the middle, the setting applies only to the refs that + match the <pattern>. gc.rerereresolved:: Records of conflicted merge you resolved earlier are - kept for this many days when 'git-rerere gc' is run. + kept for this many days when 'git rerere gc' is run. The default is 60 days. See linkgit:git-rerere[1]. gc.rerereunresolved:: Records of conflicted merge you have not resolved are - kept for this many days when 'git-rerere gc' is run. + kept for this many days when 'git rerere gc' is run. The default is 15 days. See linkgit:git-rerere[1]. gitcvs.commitmsgannotation:: @@ -929,13 +1023,15 @@ gitcvs.logfile:: various stuff. See linkgit:git-cvsserver[1]. gitcvs.usecrlfattr:: - If true, the server will look up the `crlf` attribute for - files to determine the '-k' modes to use. If `crlf` is set, - the '-k' mode will be left blank, so cvs clients will - treat it as text. If `crlf` is explicitly unset, the file + If true, the server will look up the end-of-line conversion + attributes for files to determine the '-k' modes to use. If + the attributes force git to treat a file as text, + the '-k' mode will be left blank so CVS clients will + treat it as text. If they suppress text conversion, the file will be set with '-kb' mode, which suppresses any newline munging - the client might otherwise do. If `crlf` is not specified, - then 'gitcvs.allbinary' is used. See linkgit:gitattributes[5]. + the client might otherwise do. If the attributes do not allow + the file type to be determined, then 'gitcvs.allbinary' is + used. See linkgit:gitattributes[5]. gitcvs.allbinary:: This is used if 'gitcvs.usecrlfattr' does not resolve @@ -982,6 +1078,29 @@ All gitcvs variables except for 'gitcvs.usecrlfattr' and is one of "ext" and "pserver") to make them apply only for the given access method. +gitweb.category:: +gitweb.description:: +gitweb.owner:: +gitweb.url:: + See linkgit:gitweb[1] for description. + +gitweb.avatar:: +gitweb.blame:: +gitweb.grep:: +gitweb.highlight:: +gitweb.patches:: +gitweb.pickaxe:: +gitweb.remote_heads:: +gitweb.showsizes:: +gitweb.snapshot:: + See linkgit:gitweb.conf[5] for description. + +grep.lineNumber:: + If set to true, enable '-n' option by default. + +grep.extendedRegexp:: + If set to true, enable '--extended-regexp' option by default. + gui.commitmsgwidth:: Defines how wide the commit message window is in the linkgit:git-gui[1]. "75" is the default. @@ -1008,7 +1127,7 @@ gui.newbranchtemplate:: linkgit:git-gui[1]. gui.pruneduringfetch:: - "true" if linkgit:git-gui[1] should prune tracking branches when + "true" if linkgit:git-gui[1] should prune remote-tracking branches when performing a fetch. The default value is "false". gui.trustmtime:: @@ -1021,7 +1140,7 @@ gui.spellingdictionary:: off. gui.fastcopyblame:: - If true, 'git gui blame' uses '-C' instead of '-C -C' for original + If true, 'git gui blame' uses `-C` instead of `-C -C` for original location detection. It makes blame significantly faster on huge repositories at the expense of less thorough copy detection. @@ -1110,6 +1229,14 @@ http.proxy:: environment variable (see linkgit:curl[1]). This can be overridden on a per-remote basis; see remote.<name>.proxy +http.cookiefile:: + File containing previously stored cookie lines which should be used + in the git http session, if they match the server. The file format + of the file to read cookies from should be plain HTTP headers or + the Netscape/Mozilla cookie file format (see linkgit:curl[1]). + NOTE that the file specified with http.cookiefile is only used as + input. No cookies will be stored in the file. + http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment @@ -1171,6 +1298,15 @@ http.noEPSV:: support EPSV mode. Can be overridden by the 'GIT_CURL_FTP_NO_EPSV' environment variable. Default is false (curl will use EPSV). +http.useragent:: + The HTTP USER_AGENT string presented to an HTTP server. The default + value represents the version of the client git such as git/1.7.1. + This option allows you to override this value to a more common value + such as Mozilla/4.0. This may be necessary, for instance, if + connecting through a firewall that restricts HTTP connections to a set + of common USER_AGENT strings (but not including those like git/1.7.1). + Can be overridden by the 'GIT_HTTP_USER_AGENT' environment variable. + i18n.commitEncoding:: Character encoding the commit messages are stored in; git itself does not care per se, but this information is necessary e.g. when @@ -1180,12 +1316,16 @@ i18n.commitEncoding:: i18n.logOutputEncoding:: Character encoding the commit messages are converted to when - running 'git-log' and friends. + running 'git log' and friends. imap:: The configuration variables in the 'imap' section are described in linkgit:git-imap-send[1]. +init.templatedir:: + Specify the directory from which templates will be copied. + (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) + instaweb.browser:: Specify the program that will be used to browse your working repository in gitweb. See linkgit:git-instaweb[1]. @@ -1199,7 +1339,9 @@ instaweb.local:: be bound to the local IP (127.0.0.1). instaweb.modulepath:: - The module path for an apache httpd used by linkgit:git-instaweb[1]. + The default module path for linkgit:git-instaweb[1] to use + instead of /usr/lib/apache2/modules. Only used if httpd + is Apache. instaweb.port:: The port number to bind the gitweb httpd to. See @@ -1208,15 +1350,30 @@ instaweb.port:: interactive.singlekey:: In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). - Currently this is used only by the `\--patch` mode of - linkgit:git-add[1]. Note that this setting is silently - ignored if portable keystroke input is not available. + Currently this is used by the `\--patch` mode of + linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1], + linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this + setting is silently ignored if portable keystroke input + is not available. + +log.abbrevCommit:: + If true, makes linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] assume `\--abbrev-commit`. You may + override this option with `\--no-abbrev-commit`. log.date:: - Set default date-time mode for the log command. Setting log.date - value is similar to using 'git-log'\'s --date option. The value is one of the - following alternatives: {relative,local,default,iso,rfc,short}. - See linkgit:git-log[1]. + Set the default date-time mode for the 'log' command. + Setting a value for log.date is similar to using 'git log''s + `\--date` option. Possible values are `relative`, `local`, + `default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1] + for details. + +log.decorate:: + Print out the ref names of any commits that are shown by the log + command. If 'short' is specified, the ref name prefixes 'refs/heads/', + 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is + specified, the full ref name (including prefix) will be printed. + This is the same as the log commands '--decorate' option. log.showroot:: If true, the initial commit will be shown as a big creation event. @@ -1286,6 +1443,54 @@ mergetool.keepTemporaries:: mergetool.prompt:: Prompt before each invocation of the merge resolution program. +notes.displayRef:: + The (fully qualified) refname from which to show notes when + showing commit messages. The value of this variable can be set + to a glob, in which case notes from all matching refs will be + shown. You may also specify this configuration variable + several times. A warning will be issued for refs that do not + exist, but a glob that does not match any refs is silently + ignored. ++ +This setting can be overridden with the `GIT_NOTES_DISPLAY_REF` +environment variable, which must be a colon separated list of refs or +globs. ++ +The effective value of "core.notesRef" (possibly overridden by +GIT_NOTES_REF) is also implicitly added to the list of refs to be +displayed. + +notes.rewrite.<command>:: + When rewriting commits with <command> (currently `amend` or + `rebase`) and this variable is set to `true`, git + automatically copies your notes from the original to the + rewritten commit. Defaults to `true`, but see + "notes.rewriteRef" below. + +notes.rewriteMode:: + When copying notes during a rewrite (see the + "notes.rewrite.<command>" option), determines what to do if + the target commit already has a note. Must be one of + `overwrite`, `concatenate`, or `ignore`. Defaults to + `concatenate`. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` +environment variable. + +notes.rewriteRef:: + When copying notes during a rewrite, specifies the (fully + qualified) ref whose notes should be copied. The ref may be a + glob, in which case notes in all matching refs will be copied. + You may also specify this configuration several times. ++ +Does not have a default value; you must configure this variable to +enable note rewriting. Set it to `refs/notes/commits` to enable +rewriting for the default commit notes. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_REF` +environment variable, which must be a colon separated list of refs or +globs. + pack.window:: The size of the window used by linkgit:git-pack-objects[1] when no window size is given on the command line. Defaults to 10. @@ -1308,6 +1513,10 @@ pack.compression:: not set, defaults to -1, the zlib default, which is "a default compromise between speed and compression (currently equivalent to level 6)." ++ +Note that changing the compression level will not automatically recompress +all existing objects. You can force recompression by passing the -F option +to linkgit:git-repack[1]. pack.deltaCacheSize:: The maximum memory in bytes used for caching deltas in @@ -1354,17 +1563,32 @@ you can use linkgit:git-index-pack[1] on the *.pack file to regenerate the `{asterisk}.idx` file. pack.packSizeLimit:: - The default maximum size of a pack. This setting only affects - packing to a file, i.e. the git:// protocol is unaffected. It - can be overridden by the `\--max-pack-size` option of - linkgit:git-repack[1]. + The maximum size of a pack. This setting only affects + packing to a file when repacking, i.e. the git:// protocol + is unaffected. It can be overridden by the `\--max-pack-size` + option of linkgit:git-repack[1]. The minimum size allowed is + limited to 1 MiB. The default is unlimited. + Common unit suffixes of 'k', 'm', or 'g' are + supported. pager.<cmd>:: - Allows turning on or off pagination of the output of a - particular git subcommand when writing to a tty. If - `\--paginate` or `\--no-pager` is specified on the command line, - it takes precedence over this option. To disable pagination for - all commands, set `core.pager` or `GIT_PAGER` to `cat`. + If the value is boolean, turns on or off pagination of the + output of a particular git subcommand when writing to a tty. + Otherwise, turns on pagination for the subcommand using the + pager specified by the value of `pager.<cmd>`. If `\--paginate` + or `\--no-pager` is specified on the command line, it takes + precedence over this option. To disable pagination for all + commands, set `core.pager` or `GIT_PAGER` to `cat`. + +pretty.<name>:: + Alias for a --pretty= format string, as specified in + linkgit:git-log[1]. Any aliases defined here can be used just + as the built-in pretty formats could. For example, + running `git config pretty.changelog "format:{asterisk} %H %s"` + would cause the invocation `git log --pretty=changelog` + to be equivalent to running `git log "--pretty=format:{asterisk} %H %s"`. + Note that an alias with the same name as a built-in format + will be silently ignored. pull.octopus:: The default merge strategy to use when pulling multiple branches @@ -1379,17 +1603,21 @@ push.default:: no refspec is implied by any of the options given on the command line. Possible values are: + -* `nothing` do not push anything. -* `matching` push all matching branches. +* `nothing` - do not push anything. +* `matching` - push all matching branches. All branches having the same name in both ends are considered to be matching. This is the default. -* `tracking` push the current branch to its upstream branch. -* `current` push the current branch to a branch of the same name. +* `upstream` - push the current branch to its upstream branch. +* `tracking` - deprecated synonym for `upstream`. +* `current` - push the current branch to a branch of the same name. rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. +rebase.autosquash:: + If set to true enable '--autosquash' option by default. + receive.autogc:: By default, git-receive-pack will run "git-gc --auto" after receiving data from git-push and updating refs. You can stop @@ -1399,7 +1627,8 @@ receive.fsckObjects:: If it is set to true, git-receive-pack will check all received objects. It will abort in the case of a malformed object or a broken link. The result of an abort are only dangling objects. - Defaults to false. + Defaults to false. If not set, the value of `transfer.fsckObjects` + is used instead. receive.unpackLimit:: If the number of objects received in a push is below this @@ -1415,14 +1644,18 @@ receive.denyDeletes:: If set to true, git-receive-pack will deny a ref update that deletes the ref. Use this to prevent such a ref deletion via a push. +receive.denyDeleteCurrent:: + If set to true, git-receive-pack will deny a ref update that + deletes the currently checked out branch of a non-bare repository. + receive.denyCurrentBranch:: - If set to true or "refuse", receive-pack will deny a ref update + If set to true or "refuse", git-receive-pack will deny a ref update to the currently checked out branch of a non-bare repository. Such a push is potentially dangerous because it brings the HEAD out of sync with the index and working tree. If set to "warn", print a warning of such a push to stderr, but allow the push to proceed. If set to false or "ignore", allow such pushes with no - message. Defaults to "warn". + message. Defaults to "refuse". receive.denyNonFastForwards:: If set to true, git-receive-pack will deny a ref update which is @@ -1478,7 +1711,11 @@ remote.<name>.uploadpack:: remote.<name>.tagopt:: Setting this value to \--no-tags disables automatic tag following when - fetching from remote <name> + fetching from remote <name>. Setting it to \--tags will fetch every + tag from remote <name>, even if they are not reachable from remote + branch heads. Passing these flags directly to linkgit:git-fetch[1] can + override this setting. See options \--tags and \--no-tags of + linkgit:git-fetch[1]. remote.<name>.vcs:: Setting this to a value <vcs> will cause git to interact with @@ -1542,8 +1779,10 @@ sendemail.smtppass:: sendemail.suppresscc:: sendemail.suppressfrom:: sendemail.to:: +sendemail.smtpdomain:: sendemail.smtpserver:: sendemail.smtpserverport:: +sendemail.smtpserveroption:: sendemail.smtpuser:: sendemail.thread:: sendemail.validate:: @@ -1572,15 +1811,51 @@ status.showUntrackedFiles:: the untracked files. Possible values are: + -- - - 'no' - Show no untracked files - - 'normal' - Shows untracked files and directories - - 'all' - Shows also individual files in untracked directories. +* `no` - Show no untracked files. +* `normal` - Show untracked files and directories. +* `all` - Show also individual files in untracked directories. -- + If this variable is not specified, it defaults to 'normal'. This variable can be overridden with the -u|--untracked-files option of linkgit:git-status[1] and linkgit:git-commit[1]. +status.submodulesummary:: + Defaults to false. + If this is set to a non zero number or true (identical to -1 or an + unlimited number), the submodule summary will be enabled and a + summary of commits for modified submodules will be shown (see + --summary-limit option of linkgit:git-submodule[1]). + +submodule.<name>.path:: +submodule.<name>.url:: +submodule.<name>.update:: + The path within this project, URL, and the updating strategy + for a submodule. These variables are initially populated + by 'git submodule init'; edit them to override the + URL and other values found in the `.gitmodules` file. See + linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. + +submodule.<name>.fetchRecurseSubmodules:: + This option can be used to control recursive fetching of this + submodule. It can be overridden by using the --[no-]recurse-submodules + command line option to "git fetch" and "git pull". + This setting will override that from in the linkgit:gitmodules[5] + file. + +submodule.<name>.ignore:: + Defines under what circumstances "git status" and the diff family show + a submodule as modified. When set to "all", it will never be considered + modified, "dirty" will ignore all changes to the submodules work tree and + takes only differences between the HEAD of the submodule and the commit + recorded in the superproject into account. "untracked" will additionally + let submodules with modified tracked files in their work tree show up. + Using "none" (the default when this option is not set) also shows + submodules that have untracked files in their work tree as changed. + This setting overrides any setting made in .gitmodules for this submodule, + both settings can be overridden on the command line by using the + "--ignore-submodules" option. + tar.umask:: This variable can be used to restrict the permission bits of tar archive entries. The default is 0002, which turns off the @@ -1588,6 +1863,11 @@ tar.umask:: archiving user's umask will be used instead. See umask(2) and linkgit:git-archive[1]. +transfer.fsckObjects:: + When `fetch.fsckObjects` or `receive.fsckObjects` are + not set, the value of this variable is used instead. + Defaults to false. + transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are not set, the value of this variable is used instead. diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt new file mode 100644 index 0000000000..1aed79e7dc --- /dev/null +++ b/Documentation/diff-config.txt @@ -0,0 +1,136 @@ +diff.autorefreshindex:: + When using 'git diff' to compare with work tree + files, do not consider stat-only change as changed. + Instead, silently run `git update-index --refresh` to + update the cached stat information for paths whose + contents in the work tree match the contents in the + index. This option defaults to true. Note that this + affects only 'git diff' Porcelain, and not lower level + 'diff' commands such as 'git diff-files'. + +diff.dirstat:: + A comma separated list of `--dirstat` parameters specifying the + default behavior of the `--dirstat` option to linkgit:git-diff[1]` + and friends. The defaults can be overridden on the command line + (using `--dirstat=<param1,param2,...>`). The fallback defaults + (when not changed by `diff.dirstat`) are `changes,noncumulative,3`. + The following parameters are available: ++ +-- +`changes`;; + Compute the dirstat numbers by counting the lines that have been + removed from the source, or added to the destination. This ignores + the amount of pure code movements within a file. In other words, + rearranging lines in a file is not counted as much as other changes. + This is the default behavior when no parameter is given. +`lines`;; + Compute the dirstat numbers by doing the regular line-based diff + analysis, and summing the removed/added line counts. (For binary + files, count 64-byte chunks instead, since binary files have no + natural concept of lines). This is a more expensive `--dirstat` + behavior than the `changes` behavior, but it does count rearranged + lines within a file as much as other changes. The resulting output + is consistent with what you get from the other `--*stat` options. +`files`;; + Compute the dirstat numbers by counting the number of files changed. + Each changed file counts equally in the dirstat analysis. This is + the computationally cheapest `--dirstat` behavior, since it does + not have to look at the file contents at all. +`cumulative`;; + Count changes in a child directory for the parent directory as well. + Note that when using `cumulative`, the sum of the percentages + reported may exceed 100%. The default (non-cumulative) behavior can + be specified with the `noncumulative` parameter. +<limit>;; + An integer parameter specifies a cut-off percent (3% by default). + Directories contributing less than this percentage of the changes + are not shown in the output. +-- ++ +Example: The following will count changed files, while ignoring +directories with less than 10% of the total amount of changed files, +and accumulating child directory counts in the parent directories: +`files,10,cumulative`. + +diff.external:: + If this config variable is set, diff generation is not + performed using the internal diff machinery, but using the + given command. Can be overridden with the `GIT_EXTERNAL_DIFF' + environment variable. The command is called with parameters + as described under "git Diffs" in linkgit:git[1]. Note: if + you want to use an external diff program only on a subset of + your files, you might want to use linkgit:gitattributes[5] instead. + +diff.ignoreSubmodules:: + Sets the default value of --ignore-submodules. Note that this + affects only 'git diff' Porcelain, and not lower level 'diff' + commands such as 'git diff-files'. 'git checkout' also honors + this setting when reporting uncommitted changes. + +diff.mnemonicprefix:: + If set, 'git diff' uses a prefix pair that is different from the + standard "a/" and "b/" depending on what is being compared. When + this configuration is in effect, reverse diff output also swaps + the order of the prefixes: +`git diff`;; + compares the (i)ndex and the (w)ork tree; +`git diff HEAD`;; + compares a (c)ommit and the (w)ork tree; +`git diff --cached`;; + compares a (c)ommit and the (i)ndex; +`git diff HEAD:file1 file2`;; + compares an (o)bject and a (w)ork tree entity; +`git diff --no-index a b`;; + compares two non-git things (1) and (2). + +diff.noprefix:: + If set, 'git diff' does not show any source or destination prefix. + +diff.renameLimit:: + The number of files to consider when performing the copy/rename + detection; equivalent to the 'git diff' option '-l'. + +diff.renames:: + Tells git to detect renames. If set to any boolean value, it + will enable basic rename detection. If set to "copies" or + "copy", it will detect copies, as well. + +diff.suppressBlankEmpty:: + A boolean to inhibit the standard behavior of printing a space + before each empty output line. Defaults to false. + +diff.<driver>.command:: + The custom diff driver command. See linkgit:gitattributes[5] + for details. + +diff.<driver>.xfuncname:: + The regular expression that the diff driver should use to + recognize the hunk header. A built-in pattern may also be used. + See linkgit:gitattributes[5] for details. + +diff.<driver>.binary:: + Set this option to true to make the diff driver treat files as + binary. See linkgit:gitattributes[5] for details. + +diff.<driver>.textconv:: + The command that the diff driver should call to generate the + text-converted version of a file. The result of the + conversion is used to generate a human-readable diff. See + linkgit:gitattributes[5] for details. + +diff.<driver>.wordregex:: + The regular expression that the diff driver should use to + split words in a line. See linkgit:gitattributes[5] for + details. + +diff.<driver>.cachetextconv:: + Set this option to true to make the diff driver cache the text + conversion outputs. See linkgit:gitattributes[5] for details. + +diff.tool:: + The diff tool to be used by linkgit:git-difftool[1]. This + option overrides `merge.tool`, and has the same valid built-in + values as `merge.tool` minus "tortoisemerge" and plus + "kompare". Any other value is treated as a custom diff tool, + and there must be a corresponding `difftool.<tool>.cmd` + option. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index b71712473e..15c7e794f4 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -19,7 +19,7 @@ git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]:: git-diff-files [<pattern>...]:: compares the index and the files on the filesystem. -The "git-diff-tree" command begins its ouput by printing the hash of +The "git-diff-tree" command begins its output by printing the hash of what is being compared. After that, all the commands print one output line per changed file. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 0f25ba7e38..c57460c03d 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -9,16 +9,15 @@ patch file. You can customize the creation of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables. What the -p option produces is slightly different from the traditional -diff format. +diff format: -1. It is preceded with a "git diff" header, that looks like - this: +1. It is preceded with a "git diff" header that looks like this: diff --git a/file1 b/file2 + The `a/` and `b/` filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion, -`/dev/null` is _not_ used in place of `a/` or `b/` filenames. +`/dev/null` is _not_ used in place of the `a/` or `b/` filenames. + When rename/copy is involved, `file1` and `file2` show the name of the source file of the rename/copy and the name of @@ -37,26 +36,51 @@ the file that rename/copy produces, respectively. similarity index <number> dissimilarity index <number> index <hash>..<hash> <mode> - -3. TAB, LF, double quote and backslash characters in pathnames - are represented as `\t`, `\n`, `\"` and `\\`, respectively. - If there is need for such substitution then the whole - pathname is put in double quotes. - ++ +File modes are printed as 6-digit octal numbers including the file type +and file permission bits. ++ +Path names in extended headers do not include the `a/` and `b/` prefixes. ++ The similarity index is the percentage of unchanged lines, and the dissimilarity index is the percentage of changed lines. It is a rounded down integer, followed by a percent sign. The similarity index value of 100% is thus reserved for two equal files, while 100% dissimilarity means that no line from the old file made it into the new one. ++ +The index line includes the SHA-1 checksum before and after the change. +The <mode> is included if the file mode does not change; otherwise, +separate lines indicate the old and the new mode. + +3. TAB, LF, double quote and backslash characters in pathnames + are represented as `\t`, `\n`, `\"` and `\\`, respectively. + If there is need for such substitution then the whole + pathname is put in double quotes. + +4. All the `file1` files in the output refer to files before the + commit, and all the `file2` files refer to files after the commit. + It is incorrect to apply each change to each file sequentially. For + example, this patch will swap a and b: + + diff --git a/a b/b + rename from a + rename to b + diff --git a/b b/a + rename from b + rename to a combined diff format -------------------- -"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or -'--cc' option to produce 'combined diff'. For showing a merge commit -with "git log -p", this is the default format. +Any diff-generating command can take the `-c` or `--cc` option to +produce a 'combined diff' when showing a merge. This is the default +format when showing merges with linkgit:git-diff[1] or +linkgit:git-show[1]. Note also that you can give the `-m' option to any +of these commands to force generation of diffs with individual parents +of a merge. + A 'combined diff' format looks like this: ------------ diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 8707d0e740..9f7cba2be6 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -21,6 +21,7 @@ endif::git-format-patch[] ifndef::git-format-patch[] -p:: -u:: +--patch:: Generate patch (see section on generating patches). {git-diff? This is the default.} endif::git-format-patch[] @@ -44,14 +45,24 @@ ifndef::git-format-patch[] Synonym for `-p --raw`. endif::git-format-patch[] +--minimal:: + Spend extra time to make sure the smallest possible + diff is produced. + --patience:: Generate a diff using the "patience diff" algorithm. ---stat[=width[,name-width]]:: +--stat[=<width>[,<name-width>[,<count>]]]:: Generate a diffstat. You can override the default - output width for 80-column terminal by `--stat=width`. + output width for 80-column terminal by `--stat=<width>`. The width of the filename part can be controlled by giving another width to it separated by a comma. + By giving a third parameter `<count>`, you can limit the + output to the first `<count>` lines, followed by + `...` if there are more. ++ +These parameters can also be set individually with `--stat-width=<width>`, +`--stat-name-width=<name-width>` and `--stat-count=<count>`. --numstat:: Similar to `\--stat`, but shows number of added and @@ -65,15 +76,49 @@ endif::git-format-patch[] number of modified files, as well as number of added and deleted lines. ---dirstat[=limit]:: - Output the distribution of relative amount of changes (number of lines added or - removed) for each sub-directory. Directories with changes below - a cut-off percent (3% by default) are not shown. The cut-off percent - can be set with `--dirstat=limit`. Changes in a child directory is not - counted for the parent directory, unless `--cumulative` is used. - ---dirstat-by-file[=limit]:: - Same as `--dirstat`, but counts changed files instead of lines. +--dirstat[=<param1,param2,...>]:: + Output the distribution of relative amount of changes for each + sub-directory. The behavior of `--dirstat` can be customized by + passing it a comma separated list of parameters. + The defaults are controlled by the `diff.dirstat` configuration + variable (see linkgit:git-config[1]). + The following parameters are available: ++ +-- +`changes`;; + Compute the dirstat numbers by counting the lines that have been + removed from the source, or added to the destination. This ignores + the amount of pure code movements within a file. In other words, + rearranging lines in a file is not counted as much as other changes. + This is the default behavior when no parameter is given. +`lines`;; + Compute the dirstat numbers by doing the regular line-based diff + analysis, and summing the removed/added line counts. (For binary + files, count 64-byte chunks instead, since binary files have no + natural concept of lines). This is a more expensive `--dirstat` + behavior than the `changes` behavior, but it does count rearranged + lines within a file as much as other changes. The resulting output + is consistent with what you get from the other `--*stat` options. +`files`;; + Compute the dirstat numbers by counting the number of files changed. + Each changed file counts equally in the dirstat analysis. This is + the computationally cheapest `--dirstat` behavior, since it does + not have to look at the file contents at all. +`cumulative`;; + Count changes in a child directory for the parent directory as well. + Note that when using `cumulative`, the sum of the percentages + reported may exceed 100%. The default (non-cumulative) behavior can + be specified with the `noncumulative` parameter. +<limit>;; + An integer parameter specifies a cut-off percent (3% by default). + Directories contributing less than this percentage of the changes + are not shown in the output. +-- ++ +Example: The following will count changed files, while ignoring +directories with less than 10% of the total amount of changed files, +and accumulating child directory counts in the parent directories: +`--dirstat=files,10,cumulative`. --summary:: Output a condensed summary of extended header information @@ -94,8 +139,8 @@ Also, when `--raw` or `--numstat` has been given, do not munge pathnames and use NULs as output field terminators. endif::git-log[] ifndef::git-log[] - When `--raw` or `--numstat` has been given, do not munge - pathnames and use NULs as output field terminators. + When `--raw`, `--numstat`, `--name-only` or `--name-status` has been + given, do not munge pathnames and use NULs as output field terminators. endif::git-log[] + Without this option, each pathname output will have TAB, LF, double quotes, @@ -117,18 +162,55 @@ any of those replacements occurred. option and lists the commits in that commit range like the 'summary' option of linkgit:git-submodule[1] does. ---color:: +--color[=<when>]:: Show colored diff. + The value must be `always` (the default for `<when>`), `never`, or `auto`. + The default value is `never`. +ifdef::git-diff[] + It can be changed by the `color.ui` and `color.diff` + configuration settings. +endif::git-diff[] --no-color:: - Turn off colored diff, even when the configuration file - gives the default to color output. + Turn off colored diff. +ifdef::git-diff[] + This can be used to override configuration settings. +endif::git-diff[] + It is the same as `--color=never`. ---color-words[=<regex>]:: - Show colored word diff, i.e., color words which have changed. - By default, words are separated by whitespace. +--word-diff[=<mode>]:: + Show a word diff, using the <mode> to delimit changed words. + By default, words are delimited by whitespace; see + `--word-diff-regex` below. The <mode> defaults to 'plain', and + must be one of: ++ +-- +color:: + Highlight changed words using only colors. Implies `--color`. +plain:: + Show words as `[-removed-]` and `{+added+}`. Makes no + attempts to escape the delimiters if they appear in the input, + so the output may be ambiguous. +porcelain:: + Use a special line-based format intended for script + consumption. Added/removed/unchanged runs are printed in the + usual unified diff format, starting with a `+`/`-`/` ` + character at the beginning of the line and extending to the + end of the line. Newlines in the input are represented by a + tilde `~` on a line of its own. +none:: + Disable word diff again. +-- ++ +Note that despite the name of the first mode, color is used to +highlight the changed parts in all modes if enabled. + +--word-diff-regex=<regex>:: + Use <regex> to decide what a word is, instead of considering + runs of non-whitespace to be a word. Also implies + `--word-diff` unless it was already enabled. + -When a <regex> is specified, every non-overlapping match of the +Every non-overlapping match of the <regex> is considered a word. Anything between these matches is considered whitespace and ignored(!) for the purposes of finding differences. You may want to append `|[^[:space:]]` to your regular @@ -140,6 +222,10 @@ The regex can also be set via a diff driver or configuration option, see linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings. + +--color-words[=<regex>]:: + Equivalent to `--word-diff=color` plus (if a regex was + specified) `--word-diff-regex=<regex>`. endif::git-format-patch[] --no-renames:: @@ -148,10 +234,14 @@ endif::git-format-patch[] ifndef::git-format-patch[] --check:: - Warn if changes introduce trailing whitespace - or an indent that uses a space before a tab. Exits with - non-zero status if problems are found. Not compatible with - --exit-code. + Warn if changes introduce whitespace errors. What are + considered whitespace errors is controlled by `core.whitespace` + configuration. By default, trailing whitespaces (including + lines that solely consist of whitespaces) and a space character + that is immediately followed by a tab character inside the + initial indent of the line are considered whitespace errors. + Exits with non-zero status if problems are found. Not compatible + with --exit-code. endif::git-format-patch[] --full-index:: @@ -171,28 +261,49 @@ endif::git-format-patch[] the diff-patch output format. Non default number of digits can be specified with `--abbrev=<n>`. --B:: - Break complete rewrite changes into pairs of delete and create. - --M:: +-B[<n>][/<m>]:: +--break-rewrites[=[<n>][/<m>]]:: + Break complete rewrite changes into pairs of delete and + create. This serves two purposes: ++ +It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number `m` controls this aspect of the -B +option (defaults to 60%). `-B/70%` specifies that less than 30% of the +original should remain in the result for git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines). ++ +When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number `n` controls this aspect of +the -B option (defaults to 50%). `-B20%` specifies that a change with +addition and deletion compared to 20% or more of the file's size are +eligible for being picked up as a possible source of a rename to +another file. + +-M[<n>]:: +--find-renames[=<n>]:: +ifndef::git-log[] Detect renames. - --C:: +endif::git-log[] +ifdef::git-log[] + If generating diffs, detect and report renames for each commit. + For following files across renames while traversing history, see + `--follow`. +endif::git-log[] + If `n` is specified, it is a threshold on the similarity + index (i.e. amount of addition/deletions compared to the + file's size). For example, `-M90%` means git should consider a + delete/add pair to be a rename if more than 90% of the file + hasn't changed. + +-C[<n>]:: +--find-copies[=<n>]:: Detect copies as well as renames. See also `--find-copies-harder`. - -ifndef::git-format-patch[] ---diff-filter=[ACDMRTUXB*]:: - Select only files that are Added (`A`), Copied (`C`), - Deleted (`D`), Modified (`M`), Renamed (`R`), have their - type (i.e. regular file, symlink, submodule, ...) changed (`T`), - are Unmerged (`U`), are - Unknown (`X`), or have had their pairing Broken (`B`). - Any combination of the filter characters may be used. - When `*` (All-or-none) is added to the combination, all - paths are selected if there is any file that matches - other criteria in the comparison; if there is no file - that matches other criteria, nothing is selected. -endif::git-format-patch[] + If `n` is specified, it has the same meaning as for `-M<n>`. --find-copies-harder:: For performance reasons, by default, `-C` option finds copies only @@ -203,6 +314,19 @@ endif::git-format-patch[] projects, so use it with caution. Giving more than one `-C` option has the same effect. +-D:: +--irreversible-delete:: + Omit the preimage for deletes, i.e. print only the header but not + the diff between the preimage and `/dev/null`. The resulting patch + is not meant to be applied with `patch` nor `git apply`; this is + solely for people who want to just concentrate on reviewing the + text after the change. In addition, the output obviously lack + enough information to apply such a patch in reverse, even manually, + hence the name of the option. ++ +When used together with `-B`, omit also the preimage in the deletion part +of a delete/create pair. + -l<num>:: The `-M` and `-C` options require O(n^2) processing time where n is the number of potential rename/copy targets. This @@ -211,14 +335,30 @@ endif::git-format-patch[] number. ifndef::git-format-patch[] +--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]:: + Select only files that are Added (`A`), Copied (`C`), + Deleted (`D`), Modified (`M`), Renamed (`R`), have their + type (i.e. regular file, symlink, submodule, ...) changed (`T`), + are Unmerged (`U`), are + Unknown (`X`), or have had their pairing Broken (`B`). + Any combination of the filter characters (including none) can be used. + When `*` (All-or-none) is added to the combination, all + paths are selected if there is any file that matches + other criteria in the comparison; if there is no file + that matches other criteria, nothing is selected. + -S<string>:: Look for differences that introduce or remove an instance of <string>. Note that this is different than the string simply appearing in diff output; see the 'pickaxe' entry in linkgit:gitdiffcore[7] for more details. +-G<regex>:: + Look for differences whose added or removed line matches + the given <regex>. + --pickaxe-all:: - When `-S` finds a change, show all the changes in that + When `-S` or `-G` finds a change, show all the changes in that changeset, not just the files that contain the change in <string>. @@ -268,7 +408,12 @@ endif::git-format-patch[] Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other. +-W:: +--function-context:: + Show whole surrounding functions of changes. + ifndef::git-format-patch[] +ifndef::git-log[] --exit-code:: Make the program exit with codes similar to diff(1). That is, it exits with 1 if there were differences and @@ -276,6 +421,7 @@ ifndef::git-format-patch[] --quiet:: Disable all output of the program. Implies `--exit-code`. +endif::git-log[] endif::git-format-patch[] --ext-diff:: @@ -286,8 +432,29 @@ endif::git-format-patch[] --no-ext-diff:: Disallow external diff drivers. ---ignore-submodules:: - Ignore changes to submodules in the diff generation. +--textconv:: +--no-textconv:: + Allow (or disallow) external text conversion filters to be run + when comparing binary files. See linkgit:gitattributes[5] for + details. Because textconv filters are typically a one-way + conversion, the resulting diff is suitable for human + consumption, but cannot be applied. For this reason, textconv + filters are enabled by default only for linkgit:git-diff[1] and + linkgit:git-log[1], but not for linkgit:git-format-patch[1] or + diff plumbing commands. + +--ignore-submodules[=<when>]:: + Ignore changes to submodules in the diff generation. <when> can be + either "none", "untracked", "dirty" or "all", which is the default + Using "none" will consider the submodule modified when it either contains + untracked or modified files or its HEAD differs from the commit recorded + in the superproject and can be used to override any settings of the + 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When + "untracked" is used submodules are not considered dirty when they only + contain untracked content (but they are still scanned for modified + content). Using "dirty" ignores all changes to the work tree of submodules, + only changes to the commits stored in the superproject are shown (this was + the behavior until 1.7.0). Using "all" hides all changes to submodules. --src-prefix=<prefix>:: Show the given source prefix instead of "a/". diff --git a/Documentation/docbook.xsl b/Documentation/docbook.xsl index 9a6912c641..da8b05b922 100644 --- a/Documentation/docbook.xsl +++ b/Documentation/docbook.xsl @@ -1,5 +1,8 @@ <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> - <xsl:output method="html" encoding="UTF-8" indent="no" /> + <xsl:output method="html" + encoding="UTF-8" indent="no" + doctype-public="-//W3C//DTD HTML 4.01//EN" + doctype-system="http://www.w3.org/TR/html4/strict.dtd" /> </xsl:stylesheet> diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index 9310b650d3..ae413e52a5 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -1,13 +1,8 @@ Everyday GIT With 20 Commands Or So =================================== -<<Basic Repository>> commands are needed by people who have a -repository --- that is everybody, because every working tree of -git is a repository. - -In addition, <<Individual Developer (Standalone)>> commands are -essential for anybody who makes a commit, even for somebody who -works alone. +<<Individual Developer (Standalone)>> commands are essential for +anybody who makes a commit, even for somebody who works alone. If you work with other people, you will need commands listed in the <<Individual Developer (Participant)>> section as well. @@ -20,46 +15,6 @@ administrators who are responsible for the care and feeding of git repositories. -Basic Repository[[Basic Repository]] ------------------------------------- - -Everybody uses these commands to maintain git repositories. - - * linkgit:git-init[1] or linkgit:git-clone[1] to create a - new repository. - - * linkgit:git-fsck[1] to check the repository for errors. - - * linkgit:git-gc[1] to do common housekeeping tasks such as - repack and prune. - -Examples -~~~~~~~~ - -Check health and remove cruft.:: -+ ------------- -$ git fsck <1> -$ git count-objects <2> -$ git gc <3> ------------- -+ -<1> running without `\--full` is usually cheap and assures the -repository health reasonably well. -<2> check how many loose objects there are and how much -disk space is wasted by not repacking. -<3> repacks the local repository and performs other housekeeping tasks. - -Repack a small project into single pack.:: -+ ------------- -$ git gc <1> ------------- -+ -<1> pack all the objects reachable from the refs into one pack, -then remove the other packs. - - Individual Developer (Standalone)[[Individual Developer (Standalone)]] ---------------------------------------------------------------------- @@ -67,6 +22,8 @@ A standalone individual developer does not exchange patches with other people, and works alone in a single repository, using the following commands. + * linkgit:git-init[1] to create a new repository. + * linkgit:git-show-branch[1] to see where you are. * linkgit:git-log[1] to see what happened. @@ -223,12 +180,12 @@ directory; clone from it to start a repository on the satellite machine. <2> clone sets these configuration variables by default. It arranges `git pull` to fetch and store the branches of mothership -machine to local `remotes/origin/*` tracking branches. +machine to local `remotes/origin/*` remote-tracking branches. <3> arrange `git push` to push local `master` branch to `remotes/satellite/master` branch of the mothership machine. <4> push will stash our work away on `remotes/satellite/master` -tracking branch on the mothership machine. You could use this as -a back-up method. +remote-tracking branch on the mothership machine. You could use this +as a back-up method. <5> on mothership machine, merge the work done on the satellite machine into the master branch. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index ab6419fe6e..39d326abc6 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -19,7 +19,7 @@ endif::git-pull[] -f:: --force:: - When 'git-fetch' is used with `<rbranch>:<lbranch>` + When 'git fetch' is used with `<rbranch>:<lbranch>` refspec, it refuses to update the local branch `<lbranch>` unless the remote branch `<rbranch>` it fetches is a descendant of `<lbranch>`. This option @@ -34,8 +34,9 @@ ifndef::git-pull[] Allow several <repository> and <group> arguments to be specified. No <refspec>s may be specified. +-p:: --prune:: - After fetching, remove any remote tracking branches which + After fetching, remove any remote-tracking branches which no longer exist on the remote. endif::git-pull[] @@ -48,8 +49,11 @@ ifndef::git-pull[] endif::git-pull[] By default, tags that point at objects that are downloaded from the remote repository are fetched and stored locally. - This option disables this automatic tag following. + This option disables this automatic tag following. The default + behavior for a remote may be specified with the remote.<name>.tagopt + setting. See linkgit:git-config[1]. +ifndef::git-pull[] -t:: --tags:: Most of the tags are fetched automatically as branch @@ -57,20 +61,51 @@ endif::git-pull[] objects reachable from the branch heads that are being tracked will not be fetched by this mechanism. This flag lets all tags and their associated objects be - downloaded. + downloaded. The default behavior for a remote may be + specified with the remote.<name>.tagopt setting. See + linkgit:git-config[1]. + +--recurse-submodules[=yes|on-demand|no]:: + This option controls if and under what conditions new commits of + populated submodules should be fetched too. It can be used as a + boolean option to completely disable recursion when set to 'no' or to + unconditionally recurse into all populated submodules when set to + 'yes', which is the default when this option is used without any + value. Use 'on-demand' to only recurse into a populated submodule + when the superproject retrieves a commit that updates the submodule's + reference to a commit that isn't already in the local submodule + clone. + +--no-recurse-submodules:: + Disable recursive fetching of submodules (this has the same effect as + using the '--recurse-submodules=no' option). + +--submodule-prefix=<path>:: + Prepend <path> to paths printed in informative messages + such as "Fetching submodule foo". This option is used + internally when recursing over submodules. + +--recurse-submodules-default=[yes|on-demand]:: + This option is used internally to temporarily provide a + non-negative default value for the --recurse-submodules + option. All other methods of configuring fetch's submodule + recursion (such as settings in linkgit:gitmodules[5] and + linkgit:git-config[1]) override this option, as does + specifying --[no-]recurse-submodules directly. +endif::git-pull[] -u:: --update-head-ok:: - By default 'git-fetch' refuses to update the head which + By default 'git fetch' refuses to update the head which corresponds to the current branch. This flag disables the - check. This is purely for the internal use for 'git-pull' - to communicate with 'git-fetch', and unless you are + check. This is purely for the internal use for 'git pull' + to communicate with 'git fetch', and unless you are implementing your own Porcelain you are not supposed to use it. --upload-pack <upload-pack>:: When given, and the repository to fetch from is handled - by 'git-fetch-pack', '--exec=<upload-pack>' is passed to + by 'git fetch-pack', '--exec=<upload-pack>' is passed to the command to specify non-default path for the command run on the other end. @@ -78,9 +113,16 @@ ifndef::git-pull[] -q:: --quiet:: Pass --quiet to git-fetch-pack and silence any other internally - used git commands. + used git commands. Progress is not reported to the standard error + stream. -v:: --verbose:: Be verbose. endif::git-pull[] + +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if the + standard error stream is not directed to a terminal. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 1f1b19996b..9c1d395722 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -10,7 +10,8 @@ SYNOPSIS [verse] 'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N] - [--refresh] [--ignore-errors] [--] [<filepattern>...] + [--refresh] [--ignore-errors] [--ignore-missing] [--] + [<filepattern>...] DESCRIPTION ----------- @@ -39,7 +40,7 @@ The `git add` command will not add ignored files by default. If any ignored files were explicitly specified on the command line, `git add` will fail with a list of ignored files. Ignored files reached by directory recursion or filename globbing performed by Git (quote your -globs before the shell) will be silently ignored. The `add` command can +globs before the shell) will be silently ignored. The 'git add' command can be used to add ignored files with the `-f` (force) option. Please see linkgit:git-commit[1] for alternative ways to add content to a @@ -57,7 +58,8 @@ OPTIONS -n:: --dry-run:: - Don't actually add the file(s), just show if they exist. + Don't actually add the file(s), just show if they exist and/or will + be ignored. -v:: --verbose:: @@ -90,9 +92,11 @@ See ``Interactive mode'' for details. edit it. After the editor was closed, adjust the hunk headers and apply the patch to the index. + -*NOTE*: Obviously, if you change anything else than the first character -on lines beginning with a space or a minus, the patch will no longer -apply. +The intent of this option is to pick and choose lines of the patch to +apply, or even to modify the contents of lines to be staged. This can be +quicker and more flexible than using the interactive hunk selector. +However, it is easy to confuse oneself and create a patch that does not +apply to the index. See EDITING PATCHES below. -u:: --update:: @@ -130,6 +134,14 @@ subdirectories. If some files could not be added because of errors indexing them, do not abort the operation, but continue adding the others. The command shall still exit with non-zero status. + The configuration variable `add.ignoreErrors` can be set to + true to make this the default behaviour. + +--ignore-missing:: + This option can only be used together with --dry-run. By using + this option the user can check if any of the given files would + be ignored, no matter if they are already present in the work + tree or not. \--:: This option can be used to separate command-line options from @@ -149,14 +161,14 @@ those in info/exclude. See linkgit:gitrepository-layout[5]. EXAMPLES -------- -* Adds content from all `\*.txt` files under `Documentation` directory +* Adds content from all `*.txt` files under `Documentation` directory and its subdirectories: + ------------ -$ git add Documentation/\\*.txt +$ git add Documentation/\*.txt ------------ + -Note that the asterisk `\*` is quoted from the shell in this +Note that the asterisk `*` is quoted from the shell in this example; this lets the command include the files from subdirectories of `Documentation/` directory. @@ -212,7 +224,7 @@ binary so line count cannot be shown) and there is no difference between indexed copy and the working tree version (if the working tree version were also different, 'binary' would have been shown in place of 'nothing'). The -other file, git-add--interactive.perl, has 403 lines added +other file, git-add{litdd}interactive.perl, has 403 lines added and 35 lines deleted if you commit what is in the index, but working tree file has further modifications (one addition and one deletion). @@ -262,13 +274,14 @@ patch:: This lets you choose one path out of a 'status' like selection. After choosing the path, it presents the diff between the index and the working tree file and asks you if you want to stage - the change of each hunk. You can say: + the change of each hunk. You can select one of the following + options and type return: y - stage this hunk n - do not stage this hunk - q - quit, do not stage this hunk nor any of the remaining ones - a - stage this and all the remaining hunks in the file - d - do not stage this hunk nor any of the remaining hunks in the file + q - quit; do not stage this hunk nor any of the remaining ones + a - stage this hunk and all later hunks in the file + d - do not stage this hunk nor any of the later hunks in the file g - select a hunk to go to / - search for a hunk matching the given regex j - leave this hunk undecided, see next undecided hunk @@ -281,12 +294,87 @@ patch:: + After deciding the fate for all hunks, if there is any hunk that was chosen, the index is updated with the selected hunks. ++ +You can omit having to type return here, by setting the configuration +variable `interactive.singlekey` to `true`. diff:: This lets you review what will be committed (i.e. between HEAD and index). + +EDITING PATCHES +--------------- + +Invoking `git add -e` or selecting `e` from the interactive hunk +selector will open a patch in your editor; after the editor exits, the +result is applied to the index. You are free to make arbitrary changes +to the patch, but note that some changes may have confusing results, or +even result in a patch that cannot be applied. If you want to abort the +operation entirely (i.e., stage nothing new in the index), simply delete +all lines of the patch. The list below describes some common things you +may see in a patch, and which editing operations make sense on them. + +-- +added content:: + +Added content is represented by lines beginning with "{plus}". You can +prevent staging any addition lines by deleting them. + +removed content:: + +Removed content is represented by lines beginning with "-". You can +prevent staging their removal by converting the "-" to a " " (space). + +modified content:: + +Modified content is represented by "-" lines (removing the old content) +followed by "{plus}" lines (adding the replacement content). You can +prevent staging the modification by converting "-" lines to " ", and +removing "{plus}" lines. Beware that modifying only half of the pair is +likely to introduce confusing changes to the index. +-- + +There are also more complex operations that can be performed. But beware +that because the patch is applied only to the index and not the working +tree, the working tree will appear to "undo" the change in the index. +For example, introducing a new line into the index that is in neither +the HEAD nor the working tree will stage the new line for commit, but +the line will appear to be reverted in the working tree. + +Avoid using these constructs, or do so with extreme caution. + +-- +removing untouched content:: + +Content which does not differ between the index and working tree may be +shown on context lines, beginning with a " " (space). You can stage +context lines for removal by converting the space to a "-". The +resulting working tree file will appear to re-add the content. + +modifying existing content:: + +One can also modify context lines by staging them for removal (by +converting " " to "-") and adding a "{plus}" line with the new content. +Similarly, one can modify "{plus}" lines for existing additions or +modifications. In all cases, the new modification will appear reverted +in the working tree. + +new content:: + +You may also add new content that does not exist in the patch; simply +add new lines, each starting with "{plus}". The addition will appear +reverted in the working tree. +-- + +There are also several operations which should be avoided entirely, as +they will make the patch impossible to apply: + +* adding context (" ") or removal ("-") lines +* deleting context or removal lines +* modifying the contents of context or removal lines + SEE ALSO -------- linkgit:git-status[1] @@ -296,14 +384,6 @@ linkgit:git-mv[1] linkgit:git-commit[1] linkgit:git-update-index[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 67ad5da9cc..887466d777 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,13 +9,14 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git am' [--signoff] [--keep] [--utf8 | --no-utf8] +'git am' [--signoff] [--keep] [--keep-cr | --no-keep-cr] [--utf8 | --no-utf8] [--3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] - [--reject] [-q | --quiet] [--scissors | --no-scissors] - [<mbox> | <Maildir>...] -'git am' (--skip | --resolved | --abort) + [--exclude=<path>] [--reject] [-q | --quiet] + [--scissors | --no-scissors] + [(<mbox> | <Maildir>)...] +'git am' (--continue | --skip | --abort) DESCRIPTION ----------- @@ -25,7 +26,7 @@ current branch. OPTIONS ------- -<mbox>|<Maildir>...:: +(<mbox>|<Maildir>)...:: The list of mailbox files to read patches from. If you do not supply this argument, the command reads from the standard input. If you supply directories, they will be treated as Maildirs. @@ -37,14 +38,21 @@ OPTIONS -k:: --keep:: - Pass `-k` flag to 'git-mailinfo' (see linkgit:git-mailinfo[1]). + Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + +--keep-cr:: +--no-keep-cr:: + With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) + with the same option, to prevent it from stripping CR at the end of + lines. `am.keepcr` configuration variable can be used to specify the + default behaviour. `--no-keep-cr` is useful to override `am.keepcr`. -c:: --scissors:: Remove everything in body before a scissors line (see linkgit:git-mailinfo[1]). ----no-scissors:: +--no-scissors:: Ignore scissors lines (see linkgit:git-mailinfo[1]). -q:: @@ -53,7 +61,7 @@ OPTIONS -u:: --utf8:: - Pass `-u` flag to 'git-mailinfo' (see linkgit:git-mailinfo[1]). + Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). The proposed commit log message taken from the e-mail is re-coded into UTF-8 encoding (configuration variable `i18n.commitencoding` can be used to specify project's @@ -63,7 +71,7 @@ This was optional in prior versions of git, but now it is the default. You can use `--no-utf8` to override this. --no-utf8:: - Pass `-n` flag to 'git-mailinfo' (see + Pass `-n` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). -3:: @@ -80,8 +88,9 @@ default. You can use `--no-utf8` to override this. -C<n>:: -p<n>:: --directory=<dir>:: +--exclude=<path>:: --reject:: - These flags are passed to the 'git-apply' (see linkgit:git-apply[1]) + These flags are passed to the 'git apply' (see linkgit:git-apply[1]) program that applies the patch. @@ -107,6 +116,7 @@ default. You can use `--no-utf8` to override this. Skip the current patch. This is only meaningful when restarting an aborted patch. +--continue:: -r:: --resolved:: After a patch failure (e.g. attempting to apply @@ -121,7 +131,7 @@ default. You can use `--no-utf8` to override this. to the screen before exiting. This overrides the standard message informing you to use `--resolved` or `--skip` to handle the failure. This is solely - for internal use between 'git-rebase' and 'git-am'. + for internal use between 'git rebase' and 'git am'. --abort:: Restore the original branch and abort the patching operation. @@ -165,9 +175,9 @@ aborts in the middle. You can recover from this in one of two ways: the index file to bring it into a state that the patch should have produced. Then run the command with the '--resolved' option. -The command refuses to process new mailboxes while the `.git/rebase-apply` -directory exists, so if you decide to start over from scratch, -run `rm -f -r .git/rebase-apply` before running the command with mailbox +The command refuses to process new mailboxes until the current +operation is finished, so if you decide to start over from scratch, +run `git am --abort` before running the command with mailbox names. Before any patches are applied, ORIG_HEAD is set to the tip of the @@ -181,15 +191,6 @@ SEE ALSO -------- linkgit:git-apply[1]. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index 0590eec056..05fd482b74 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -7,6 +7,7 @@ git-annotate - Annotate file lines with commit information SYNOPSIS -------- +[verse] 'git annotate' [options] file [revision] DESCRIPTION @@ -27,10 +28,6 @@ SEE ALSO -------- linkgit:git-blame[1] -AUTHOR ------- -Written by Ryan Anderson <ryan@michonline.com>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index c2528a7654..afd2c9ae59 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -12,20 +12,24 @@ SYNOPSIS 'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] - [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached] + [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached] [--ignore-space-change | --ignore-whitespace ] - [--whitespace=<nowarn|warn|fix|error|error-all>] - [--exclude=PATH] [--include=PATH] [--directory=<root>] + [--whitespace=(nowarn|warn|fix|error|error-all)] + [--exclude=<path>] [--include=<path>] [--directory=<root>] [--verbose] [<patch>...] DESCRIPTION ----------- Reads the supplied diff output (i.e. "a patch") and applies it to files. With the `--index` option the patch is also applied to the index, and -with the `--cache` option the patch is only applied to the index. +with the `--cached` option the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a git repository. +This command applies the patch but does not create a commit. Use +linkgit:git-am[1] to create commits from patches generated by +linkgit:git-format-patch[1] and/or received by email. + OPTIONS ------- <patch>...:: @@ -69,7 +73,7 @@ OPTIONS without using the working tree. This implies `--index`. --build-fake-ancestor=<file>:: - Newer 'git-diff' output has embedded 'index information' + Newer 'git diff' output has embedded 'index information' for each blob to help identify the original version that the patch applies to. When this flag is given, and if the original versions of the blobs are available locally, @@ -83,7 +87,7 @@ the information is read from the current index instead. Apply the patch in reverse. --reject:: - For atomicity, 'git-apply' by default fails the whole patch and + For atomicity, 'git apply' by default fails the whole patch and does not touch the working tree when some of the hunks do not apply. This option makes it apply the parts of the patch that are applicable, and leave the @@ -109,7 +113,7 @@ any of those replacements occurred. ever ignored. --unidiff-zero:: - By default, 'git-apply' expects that the patch being + By default, 'git apply' expects that the patch being applied is a unified diff with at least one line of context. This provides good safety measures, but breaks down when applying a diff generated with `--unified=0`. To bypass these @@ -120,7 +124,7 @@ discouraged. --apply:: If you use any of the options marked "Turns off - 'apply'" above, 'git-apply' reads and outputs the + 'apply'" above, 'git apply' reads and outputs the requested information without actually applying the patch. Give this flag after those flags to also apply the patch. @@ -229,7 +233,7 @@ apply.whitespace:: Submodules ---------- -If the patch contains any changes to submodules then 'git-apply' +If the patch contains any changes to submodules then 'git apply' treats these changes as follows. If `--index` is specified (explicitly or implicitly), then the submodule @@ -242,13 +246,9 @@ If `--index` is not specified, then the submodule commits in the patch are ignored and only the absence or presence of the corresponding subdirectory is checked and (if possible) updated. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano +SEE ALSO +-------- +linkgit:git-am[1]. GIT --- diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index c7a6e3ec05..f4504ba9bf 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -29,22 +29,22 @@ branches that have different roots, it will refuse to run. In that case, edit your <archive/branch> parameters to define clearly the scope of the import. -'git-archimport' uses `tla` extensively in the background to access the +'git archimport' uses `tla` extensively in the background to access the Arch repository. Make sure you have a recent version of `tla` available in the path. `tla` must -know about the repositories you pass to 'git-archimport'. +know about the repositories you pass to 'git archimport'. -For the initial import, 'git-archimport' expects to find itself in an empty +For the initial import, 'git archimport' expects to find itself in an empty directory. To follow the development of a project that uses Arch, rerun -'git-archimport' with the same parameters as the initial import to perform +'git archimport' with the same parameters as the initial import to perform incremental imports. -While 'git-archimport' will try to create sensible branch names for the +While 'git archimport' will try to create sensible branch names for the archives that it imports, it is also possible to specify git branch names manually. To do so, write a git branch name after each <archive/branch> parameter, separated by a colon. This way, you can shorten the Arch branch names and convert Arch jargon to git jargon, for example mapping a -"PROJECT--devo--VERSION" branch to "master". +"PROJECT{litdd}devo{litdd}VERSION" branch to "master". Associating multiple Arch branches to one git branch is possible; the result will make the most sense only if no commits are made to the first @@ -84,9 +84,9 @@ OPTIONS -o:: Use this for compatibility with old-style branch names used by - earlier versions of 'git-archimport'. Old-style branch names - were category--branch, whereas new-style branch names are - archive,category--branch--version. In both cases, names given + earlier versions of 'git archimport'. Old-style branch names + were category{litdd}branch, whereas new-style branch names are + archive,category{litdd}branch{litdd}version. In both cases, names given on the command-line will override the automatically-generated ones. @@ -107,14 +107,6 @@ OPTIONS Archive/branch identifier in a format that `tla log` understands. -Author ------- -Written by Martin Langhoff <martin@catalyst.net.nz>. - -Documentation --------------- -Documentation by Junio C Hamano, Martin Langhoff and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index e57979198b..ac7006e640 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] [-o | --output=<file>] [--worktree-attributes] [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> - [path...] + [<path>...] DESCRIPTION ----------- @@ -21,13 +21,13 @@ structure for the named tree, and writes it out to the standard output. If <prefix> is specified it is prepended to the filenames in the archive. -'git-archive' behaves differently when given a tree ID versus when +'git archive' behaves differently when given a tree ID versus when given a commit ID or tag ID. In the first case the current time is used as the modification time of each file in the archive. In the latter case the commit time as recorded in the referenced commit object is used instead. Additionally the commit ID is stored in a global extended pax header if the tar format is used; it can be extracted -using 'git-get-tar-commit-id'. In ZIP files it is stored as a file +using 'git get-tar-commit-id'. In ZIP files it is stored as a file comment. OPTIONS @@ -73,7 +73,7 @@ OPTIONS <tree-ish>:: The tree or commit to produce an archive for. -path:: +<path>:: Without an optional path parameter, all files and subdirectories of the current working directory are included in the archive. If one or more paths are specified, only these are included. @@ -98,7 +98,27 @@ tar.umask:: tar archive entries. The default is 0002, which turns off the world write bit. The special value "user" indicates that the archiving user's umask will be used instead. See umask(2) for - details. + details. If `--remote` is used then only the configuration of + the remote repository takes effect. + +tar.<format>.command:: + This variable specifies a shell command through which the tar + output generated by `git archive` should be piped. The command + is executed using the shell with the generated tar file on its + standard input, and should produce the final output on its + standard output. Any compression-level options will be passed + to the command (e.g., "-9"). An output file with the same + extension as `<format>` will be use this format if no other + format is given. ++ +The "tar.gz" and "tgz" formats are defined automatically and default to +`gzip -cn`. You may override them with custom commands. + +tar.<format>.remote:: + If true, enable `<format>` for use by remote clients via + linkgit:git-upload-archive[1]. Defaults to false for + user-defined formats, but true for the "tar.gz" and "tgz" + formats. ATTRIBUTES ---------- @@ -112,47 +132,61 @@ export-subst:: expand several placeholders when adding this file to an archive. See linkgit:gitattributes[5] for details. +Note that attributes are by default taken from the `.gitattributes` files +in the tree that is being archived. If you want to tweak the way the +output is generated after the fact (e.g. you committed without adding an +appropriate export-ignore in its `.gitattributes`), adjust the checked out +`.gitattributes` file as necessary and use `--worktree-attributes` +option. Alternatively you can keep necessary attributes that should apply +while archiving any tree in your `$GIT_DIR/info/attributes` file. + EXAMPLES -------- -git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -):: +`git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)`:: Create a tar archive that contains the contents of the latest commit on the current branch, and extract it in the `/var/tmp/junk` directory. -git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz:: +`git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a compressed tarball for v1.4.0 release. -git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz:: +`git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz`:: + + Same as above, but using the builtin tar.gz handling. + +`git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0`:: + + Same as above, but the format is inferred from the output file. + +`git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz`:: Create a compressed tarball for v1.4.0 release, but without a global extended pax header. -git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip:: +`git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip`:: Put everything in the current head's Documentation/ directory into 'git-1.4.0-docs.zip', with the prefix 'git-docs/'. -git archive -o latest.zip HEAD:: +`git archive -o latest.zip HEAD`:: Create a Zip archive that contains the contents of the latest commit on the current branch. Note that the output format is inferred by the extension of the output file. +`git config tar.tar.xz.command "xz -c"`:: + + Configure a "tar.xz" format for making LZMA-compressed tarfiles. + You can use it specifying `--format=tar.xz`, or by creating an + output file like `-o foo.tar.xz`. + SEE ALSO -------- linkgit:gitattributes[5] -Author ------- -Written by Franck Bui-Huu and Rene Scharfe. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 6b7b2e5497..8a2ba37904 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -799,7 +799,7 @@ fixed in the "main" branch by commit "F"? The result of such a bisection would be that we would find that H is the first bad commit, when in fact it's B. So that would be wrong! -And yes it's can happen in practice that people working on one branch +And yes it can happen in practice that people working on one branch are not aware that people working on another branch fixed a bug! It could also happen that F fixed more than one bug or that it is a revert of some big development effort that was not ready to be @@ -873,7 +873,7 @@ c * N * T + b * M * log2(M) tests where c is the number of rounds of test (so a small constant) and b is the ratio of bug per commit (hopefully a small constant too). -So of course it's much better as it's O(N \* T) vs O(N \* T \* M) if +So of course it's much better as it's O(N * T) vs O(N * T * M) if you would test everything after each commit. This means that test suites are good to prevent some bugs from being @@ -971,7 +971,7 @@ logical change in each commit. The smaller the changes in your commit, the most effective "git bisect" will be. And you will probably need "git bisect" less in the first place, as small changes are easier to review even if they are -only reviewed by the commiter. +only reviewed by the committer. Another good idea is to have good commit messages. They can be very helpful to understand why some changes were made. diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index c39d957c3a..e4f46bc18d 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -8,6 +8,7 @@ git-bisect - Find by binary search the change that introduced a bug SYNOPSIS -------- +[verse] 'git bisect' <subcommand> <options> DESCRIPTION @@ -16,7 +17,7 @@ The command takes various subcommands, and different options depending on the subcommand: git bisect help - git bisect start [<bad> [<good>...]] [--] [<paths>...] + git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] git bisect bad [<rev>] git bisect good [<rev>...] git bisect skip [(<rev>|<range>)...] @@ -241,7 +242,12 @@ exit(3) manual page), as the value is chopped with "& 0377". The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current -revision will be skipped (see `git bisect skip` above). +revision will be skipped (see `git bisect skip` above). 125 was chosen +as the highest sensible value to use for this purpose, because 126 and 127 +are used by POSIX shells to signal specific error status (127 is for +command not found, 126 is for command found but not executable---these +details do not matter, as they are normal errors in the script, as far as +"bisect run" is concerned). You may often find that during a bisect session you want to have temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a @@ -257,6 +263,19 @@ rewind the tree to the pristine state. Finally the script should exit with the status of the real test to let the "git bisect run" command loop determine the eventual outcome of the bisect session. +OPTIONS +------- +--no-checkout:: ++ +Do not checkout the new working tree at each iteration of the bisection +process. Instead just update a special reference named 'BISECT_HEAD' to make +it point to the commit that should be tested. ++ +This option may be useful when the test you would perform in each step +does not require a checked out tree. ++ +If the repository is bare, `--no-checkout` is assumed. + EXAMPLES -------- @@ -274,61 +293,87 @@ $ git bisect start HEAD origin -- # HEAD is bad, origin is good $ git bisect run make test # "make test" builds and tests ------------ -* Automatically bisect a broken test suite: +* Automatically bisect a broken test case: + ------------ $ cat ~/test.sh #!/bin/sh -make || exit 125 # this skips broken builds -make test # "make test" runs the test suite -$ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good +make || exit 125 # this skips broken builds +~/check_test_case.sh # does the test case pass? +$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 $ git bisect run ~/test.sh ------------ + Here we use a "test.sh" custom script. In this script, if "make" fails, we skip the current commit. +"check_test_case.sh" should "exit 0" if the test case passes, +and "exit 1" otherwise. + -It is safer to use a custom script outside the repository to prevent -interactions between the bisect, make and test processes and the -script. -+ -"make test" should "exit 0", if the test suite passes, and -"exit 1" otherwise. +It is safer if both "test.sh" and "check_test_case.sh" are +outside the repository to prevent interactions between the bisect, +make and test processes and the scripts. -* Automatically bisect a broken test case: +* Automatically bisect with temporary modifications (hot-fix): + ------------ $ cat ~/test.sh #!/bin/sh -make || exit 125 # this skips broken builds -~/check_test_case.sh # does the test case passes ? -$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 -$ git bisect run ~/test.sh + +# tweak the working tree by merging the hot-fix branch +# and then attempt a build +if git merge --no-commit hot-fix && + make +then + # run project specific test and report its status + ~/check_test_case.sh + status=$? +else + # tell the caller this is untestable + status=125 +fi + +# undo the tweak to allow clean flipping to the next commit +git reset --hard + +# return control +exit $status ------------ + -Here "check_test_case.sh" should "exit 0" if the test case passes, -and "exit 1" otherwise. -+ -It is safer if both "test.sh" and "check_test_case.sh" scripts are -outside the repository to prevent interactions between the bisect, -make and test processes and the scripts. +This applies modifications from a hot-fix branch before each test run, +e.g. in case your build or test environment changed so that older +revisions may need a fix which newer ones have already. (Make sure the +hot-fix branch is based off a commit which is contained in all revisions +which you are bisecting, so that the merge does not pull in too much, or +use `git cherry-pick` instead of `git merge`.) -* Automatically bisect a broken test suite: +* Automatically bisect a broken test case: + ------------ $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" ------------ + -Does the same as the previous example, but on a single line. +This shows that you can do without a run script if you write the test +on a single line. + +* Locate a good region of the object graph in a damaged repository ++ +------------ +$ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout +$ git bisect run sh -c ' + GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) && + git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ && + git pack-objects --stdout >/dev/null <tmp.$$ + rc=$? + rm -f tmp.$$ + test $rc = 0' -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> +------------ ++ +In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that +has at least one parent whose reachable graph is fully traversable in the sense +required by 'git pack objects'. -Documentation -------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. SEE ALSO -------- diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index b786471dd8..9516914236 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,8 +8,8 @@ git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- [verse] -'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-p] [-w] [--incremental] [-L n,m] - [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] +'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L n,m] + [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file> DESCRIPTION @@ -21,7 +21,7 @@ last modified the line. Optionally, start annotating from the given revision. The command can also limit the range of lines annotated. 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" +replaced; you need to use a tool such as 'git diff' or the "pickaxe" interface briefly mentioned in the following paragraph. Apart from supporting file annotation, git also supports searching the @@ -49,7 +49,7 @@ include::blame-options.txt[] file (see `-M`). The first number listed is the score. This is the number of alphanumeric characters detected as having been moved between or within files. This must be above - a certain threshold for 'git-blame' to consider those lines + a certain threshold for 'git blame' to consider those lines of code to have been moved. -f:: @@ -65,10 +65,19 @@ include::blame-options.txt[] -s:: Suppress the author name and timestamp from the output. +-e:: +--show-email:: + Show the author email instead of author name (Default: off). + -w:: Ignore whitespace when comparing the parent's version and the child's to find where the lines came from. +--abbrev=<n>:: + Instead of using the default 7+1 hexadecimal digits as the + abbreviated object name, use <n>+1 digits. Note that 1 column + is used for a caret to mark the boundary commit. + THE PORCELAIN FORMAT -------------------- @@ -96,11 +105,24 @@ The contents of the actual line is output after the above header, prefixed by a TAB. This is to allow adding more header elements later. +The porcelain format generally suppresses commit information that has +already been seen. For example, two lines that are blamed to the same +commit will both be shown, but the details for that commit will be shown +only once. This is more efficient, but may require more state be kept by +the reader. The `--line-porcelain` option can be used to output full +commit information for each line, allowing simpler (but less efficient) +usage like: + + # count the number of lines attributed to each author + git blame --line-porcelain file | + sed -n 's/^author //p' | + sort | uniq -c | sort -rn + SPECIFYING RANGES ----------------- -Unlike 'git-blame' and 'git-annotate' in older versions of git, the extent +Unlike 'git blame' and 'git annotate' in older versions of git, the extent of the annotation can be limited to both line ranges and revision ranges. When you are interested in finding the origin for lines 40-60 for file `foo`, you can use the `-L` option like so @@ -118,7 +140,7 @@ which limits the annotation to the body of the `hello` subroutine. When you are not interested in changes older than version v2.6.18, or changes older than 3 weeks, you can use revision -range specifiers similar to 'git-rev-list': +range specifiers similar to 'git rev-list': git blame v2.6.18.. -- foo git blame --since=3.weeks -- foo @@ -194,10 +216,6 @@ SEE ALSO -------- linkgit:git-annotate[1] -AUTHOR ------- -Written by Junio C Hamano <gitster@pobox.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 0e836809c2..f46013c91f 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,10 +8,10 @@ git-branch - List, create, or delete branches SYNOPSIS -------- [verse] -'git branch' [--color | --no-color] [-r | -a] - [-v [--abbrev=<length> | --no-abbrev]] - [(--merged | --no-merged | --contains) [<commit>]] -'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>] +'git branch' [--color[=<when>] | --no-color] [-r | -a] + [--list] [-v [--abbrev=<length> | --no-abbrev]] + [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] +'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> 'git branch' (-d | -D) [-r] <branchname>... @@ -20,7 +20,11 @@ DESCRIPTION With no arguments, existing branches are listed and the current branch will be highlighted with an asterisk. Option `-r` causes the remote-tracking -branches to be listed, and option `-a` shows both. +branches to be listed, and option `-a` shows both. This list mode is also +activated by the `--list` option (see below). +<pattern> restricts the output to matching branches, the pattern is a shell +wildcard (i.e., matched using fnmatch(3)) +Multiple patterns may be given; if any of them matches, the tag is shown. With `--contains`, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the @@ -37,11 +41,12 @@ Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout <newbranch>" to switch to the new branch. -When a local branch is started off a remote branch, git sets up the -branch so that 'git-pull' will appropriately merge from -the remote branch. This behavior may be changed via the global +When a local branch is started off a remote-tracking branch, git sets up the +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. +overridden by using the `--track` and `--no-track` options, and +changed later using `git branch --set-upstream`. With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match @@ -55,7 +60,7 @@ has a reflog then the reflog will also be deleted. Use -r together with -d to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist -in the remote repository or if 'git-fetch' was configured not to fetch +in the remote repository or if 'git fetch' was configured not to fetch them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a way to clean up all obsolete remote-tracking branches. @@ -63,49 +68,67 @@ way to clean up all obsolete remote-tracking branches. OPTIONS ------- -d:: - Delete a branch. The branch must be fully merged in HEAD. +--delete:: + Delete a branch. The branch must be fully merged in its + upstream branch, or in `HEAD` if no upstream was set with + `--track` or `--set-upstream`. -D:: Delete a branch irrespective of its merged status. -l:: +--create-reflog:: Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@\{yesterday}". + Note that in non-bare repositories, reflogs are usually + enabled by default by the `core.logallrefupdates` config option. -f:: --force:: Reset <branchname> to <startpoint> if <branchname> exists - already. Without `-f` 'git-branch' refuses to change an existing branch. + already. Without `-f` 'git branch' refuses to change an existing branch. -m:: +--move:: Move/rename a branch and the corresponding reflog. -M:: Move/rename a branch even if the new branch name already exists. ---color:: - Color branches to highlight current, local, and remote branches. +--color[=<when>]:: + Color branches to highlight current, local, and + remote-tracking branches. + The value must be always (the default), never, or auto. --no-color:: Turn off branch colors, even when the configuration file gives the default to color output. + Same as `--color=never`. -r:: +--remotes:: List or delete (if used with -d) the remote-tracking branches. -a:: +--all:: List both remote-tracking branches and local branches. +--list:: + Activate the list mode. `git branch <pattern>` would try to create a branch, + use `git branch --list <pattern>` to list matching branches. + -v:: --verbose:: - Show sha1 and commit subject line for each head, along with + 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. --abbrev=<length>:: Alter the sha1's minimum display length in the output listing. - The default value is 7. + The default value is 7 and can be overridden by the `core.abbrev` + config option. --no-abbrev:: Display the full sha1s in the output listing rather than abbreviating them. @@ -119,16 +142,22 @@ OPTIONS it directs `git pull` without arguments to pull from the upstream when the new branch is checked out. + -This behavior is the default when the start point is a remote branch. +This behavior is the default when the start point is a remote-tracking branch. Set the branch.autosetupmerge configuration variable to `false` if you want `git checkout` and `git branch` to always behave as if '--no-track' were given. Set it to `always` if you want this behavior when the -start-point is either a local or remote branch. +start-point is either a local or remote-tracking branch. --no-track:: Do not set up "upstream" configuration, even if the branch.autosetupmerge configuration variable is true. +--set-upstream:: + If specified branch does not exist yet or if '--force' has been + given, acts exactly like '--track'. Otherwise sets up configuration + like '--track' would when creating the branch, except that where + branch points to is not changed. + --contains <commit>:: Only list branches which contain the specified commit. @@ -218,14 +247,6 @@ linkgit:git-remote[1], link:user-manual.html#what-is-a-branch[``Understanding history: What is a branch?''] in the Git User's Manual. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index c3a066e60c..92b01ec25d 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -9,10 +9,10 @@ git-bundle - Move objects and refs by archive SYNOPSIS -------- [verse] -'git bundle' create <file> <git-rev-list args> +'git bundle' create <file> <git-rev-list-args> 'git bundle' verify <file> -'git bundle' list-heads <file> [refname...] -'git bundle' unbundle <file> [refname...] +'git bundle' list-heads <file> [<refname>...] +'git bundle' unbundle <file> [<refname>...] DESCRIPTION ----------- @@ -21,9 +21,9 @@ Some workflows require that one or more branches of development on one machine be replicated on another machine, but the two machines cannot be directly connected, and therefore the interactive git protocols (git, ssh, rsync, http) cannot be used. This command provides support for -'git-fetch' and 'git-pull' to operate by packaging objects and references +'git fetch' and 'git pull' to operate by packaging objects and references in an archive at the originating machine, then importing those into -another repository using 'git-fetch' and 'git-pull' +another repository using 'git fetch' and 'git pull' after moving the archive by some means (e.g., by sneakernet). As no direct connection between the repositories exists, the user must specify a basis for the bundle that is held by the destination repository: the @@ -34,57 +34,58 @@ OPTIONS ------- create <file>:: - Used to create a bundle named 'file'. This requires the - 'git-rev-list' arguments to define the bundle contents. + Used to create a bundle named 'file'. This requires the + 'git-rev-list-args' arguments to define the bundle contents. verify <file>:: - Used to check that a bundle file is valid and will apply - cleanly to the current repository. This includes checks on the - bundle format itself as well as checking that the prerequisite - commits exist and are fully linked in the current repository. - 'git-bundle' prints a list of missing commits, if any, and exits - with a non-zero status. + Used to check that a bundle file is valid and will apply + cleanly to the current repository. This includes checks on the + bundle format itself as well as checking that the prerequisite + commits exist and are fully linked in the current repository. + 'git bundle' prints a list of missing commits, if any, and exits + with a non-zero status. list-heads <file>:: - Lists the references defined in the bundle. If followed by a - list of references, only references matching those given are - printed out. + Lists the references defined in the bundle. If followed by a + list of references, only references matching those given are + printed out. unbundle <file>:: - Passes the objects in the bundle to 'git-index-pack' - for storage in the repository, then prints the names of all - defined references. If a list of references is given, only - references matching those in the list are printed. This command is - really plumbing, intended to be called only by 'git-fetch'. - -[git-rev-list-args...]:: - A list of arguments, acceptable to 'git-rev-parse' and - 'git-rev-list', that specifies the specific objects and references - to transport. For example, `master\~10..master` causes the - current master reference to be packaged along with all objects - added since its 10th ancestor commit. There is no explicit - limit to the number of references and objects that may be - packaged. - - -[refname...]:: - A list of references used to limit the references reported as - available. This is principally of use to 'git-fetch', which - expects to receive only those references asked for and not - necessarily everything in the pack (in this case, 'git-bundle' acts - like 'git-fetch-pack'). + Passes the objects in the bundle to 'git index-pack' + for storage in the repository, then prints the names of all + defined references. If a list of references is given, only + references matching those in the list are printed. This command is + really plumbing, intended to be called only by 'git fetch'. + +<git-rev-list-args>:: + A list of arguments, acceptable to 'git rev-parse' and + 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES + below), that specifies the specific objects and references + to transport. For example, `master{tilde}10..master` causes the + current master reference to be packaged along with all objects + added since its 10th ancestor commit. There is no explicit + limit to the number of references and objects that may be + packaged. + + +[<refname>...]:: + A list of references used to limit the references reported as + available. This is principally of use to 'git fetch', which + expects to receive only those references asked for and not + necessarily everything in the pack (in this case, 'git bundle' acts + like 'git fetch-pack'). SPECIFYING REFERENCES --------------------- -'git-bundle' will only package references that are shown by -'git-show-ref': this includes heads, tags, and remote heads. References -such as `master\~1` cannot be packaged, but are perfectly suitable for +'git bundle' will only package references that are shown by +'git show-ref': this includes heads, tags, and remote heads. References +such as `master{tilde}1` cannot be packaged, but are perfectly suitable for defining the basis. More than one reference may be packaged, and more than one basis can be specified. The objects packaged are those not contained in the union of the given bases. Each basis can be -specified explicitly (e.g. `^master\~10`), or implicitly (e.g. -`master\~10..master`, `--since=10.days.ago master`). +specified explicitly (e.g. `^master{tilde}10`), or implicitly (e.g. +`master{tilde}10..master`, `--since=10.days.ago master`). It is very important that the basis used be held by the destination. It is okay to err on the side of caution, causing the bundle file @@ -154,7 +155,7 @@ machineB$ git pull If you know up to what commit the intended recipient repository should have the necessary objects, you can use that knowledge to specify the basis, giving a cut-off point to limit the revisions and objects that go -in the resulting bundle. The previous example used lastR2bundle tag +in the resulting bundle. The previous example used the lastR2bundle tag for this purpose, but you can use any other options that you would give to the linkgit:git-log[1] command. Here are more examples: @@ -194,16 +195,12 @@ references when fetching: $ git fetch mybundle master:localRef ---------------- -You can also see what references it offers. +You can also see what references it offers: ---------------- $ git ls-remote mybundle ---------------- -Author ------- -Written by Mark Levedahl <mdl123@verizon.net> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 58c8d65772..2fb95bbd19 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -9,14 +9,15 @@ git-cat-file - Provide content or type and size information for repository objec SYNOPSIS -------- [verse] -'git cat-file' (-t | -s | -e | -p | <type>) <object> +'git cat-file' (-t | -s | -e | -p | <type> | --textconv ) <object> 'git cat-file' (--batch | --batch-check) < <list-of-objects> DESCRIPTION ----------- In its first form, the command provides the content or the type of an object in the repository. The type is required unless '-t' or '-p' is used to find the -object type, or '-s' is used to find the object size. +object type, or '-s' is used to find the object size, or '--textconv' is used +(which implies type "blob"). In the second form, a list of objects (separated by linefeeds) is provided on stdin, and the SHA1, type, and size of each object is printed on stdout. @@ -26,7 +27,7 @@ OPTIONS <object>:: The name of the object to show. For a more complete list of ways to spell object names, see - the "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + the "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. -t:: Instead of the content, show the object type identified by @@ -51,6 +52,11 @@ OPTIONS or to ask for a "blob" with <object> being a tag object that points at it. +--textconv:: + Show the content as transformed by a textconv filter. In this case, + <object> has be of the form <treeish>:<path>, or :<path> in order + to apply the filter to the content recorded in the index at <path>. + --batch:: Print the SHA1, type, size, and contents of each object provided on stdin. May not be combined with any other options or arguments. @@ -94,14 +100,6 @@ for each object specified on stdin that does not exist in the repository: <object> SP missing LF ------------ -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 50824e3a2d..5abdbaa51c 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -9,8 +9,8 @@ git-check-attr - Display gitattributes information SYNOPSIS -------- [verse] -'git check-attr' attr... [--] pathname... -'git check-attr' --stdin [-z] attr... < <list-of-paths> +'git check-attr' [-a | --all | attr...] [--] pathname... +'git check-attr' --stdin [-z] [-a | --all | attr...] < <list-of-paths> DESCRIPTION ----------- @@ -19,6 +19,14 @@ For every pathname, this command will list if each attribute is 'unspecified', OPTIONS ------- +-a, --all:: + List all attributes that are associated with the specified + paths. If this option is used, then 'unspecified' attributes + will not be included in the output. + +--cached:: + Consider `.gitattributes` in the index only, ignoring the working tree. + --stdin:: Read file names from stdin instead of from the command-line. @@ -28,8 +36,11 @@ OPTIONS \--:: Interpret all preceding arguments as attributes and all following - arguments as path names. If not supplied, only the first argument will - be treated as an attribute. + arguments as path names. + +If none of `--stdin`, `--all`, or `--` is used, the first argument +will be treated as an attribute and the rest of the arguments as +pathnames. OUTPUT ------ @@ -69,6 +80,13 @@ org/example/MyClass.java: diff: java org/example/MyClass.java: myAttr: set --------------- +* Listing all attributes for a file: +--------------- +$ git check-attr --all -- org/example/MyClass.java +org/example/MyClass.java: diff: java +org/example/MyClass.java: myAttr: set +--------------- + * Listing an attribute for multiple files: --------------- $ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java @@ -86,15 +104,6 @@ SEE ALSO -------- linkgit:gitattributes[5]. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by James Bowes. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 0aeef24780..103e7b128d 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -8,8 +8,9 @@ git-check-ref-format - Ensures that a reference name is well formed SYNOPSIS -------- [verse] -'git check-ref-format' <refname> -'git check-ref-format' --print <refname> +'git check-ref-format' [--normalize] + [--[no-]allow-onelevel] [--refspec-pattern] + <refname> 'git check-ref-format' --branch <branchname-shorthand> DESCRIPTION @@ -18,37 +19,47 @@ Checks if a given 'refname' is acceptable, and exits with a non-zero status if it is not. A reference is used in git to specify branches and tags. A -branch head is stored under the `$GIT_DIR/refs/heads` directory, and -a tag is stored under the `$GIT_DIR/refs/tags` directory. git -imposes the following rules on how references are named: +branch head is stored in the `refs/heads` hierarchy, while +a tag is stored in the `refs/tags` hierarchy of the ref namespace +(typically in `$GIT_DIR/refs/heads` and `$GIT_DIR/refs/tags` +directories or, as entries in file `$GIT_DIR/packed-refs` +if refs are packed by `git gc`). + +git imposes the following rules on how references are named: . They can include slash `/` for hierarchical (directory) grouping, but no slash-separated component can begin with a - dot `.`. + dot `.` or end with the sequence `.lock`. . They must contain at least one `/`. This enforces the presence of a category like `heads/`, `tags/` etc. but the actual names are not - restricted. + restricted. If the `--allow-onelevel` option is used, this rule + is waived. . They cannot have two consecutive dots `..` anywhere. . They cannot have ASCII control characters (i.e. bytes whose values are lower than \040, or \177 `DEL`), space, tilde `~`, - caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`, - or open bracket `[` anywhere. + caret `{caret}`, or colon `:` anywhere. + +. They cannot have question-mark `?`, asterisk `{asterisk}`, or open + bracket `[` anywhere. See the `--refspec-pattern` option below for + an exception to this rule. -. They cannot end with a slash `/` nor a dot `.`. +. They cannot begin or end with a slash `/` or contain multiple + consecutive slashes (see the `--normalize` option below for an + exception to this rule) -. They cannot end with the sequence `.lock`. +. They cannot end with a dot `.`. . They cannot contain a sequence `@{`. -- They cannot contain a `\\`. +. They cannot contain a `\`. These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoids ambiguities in certain -reference name expressions (see linkgit:git-rev-parse[1]): +reference name expressions (see linkgit:gitrevisions[7]): . A double-dot `..` is often used as in `ref1..ref2`, and in some contexts this notation means `{caret}ref1 ref2` (i.e. not in @@ -60,20 +71,40 @@ reference name expressions (see linkgit:git-rev-parse[1]): . A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s value and store it in dstref" in fetch and push operations. It may also be used to select a specific object such as with - 'git-cat-file': "git cat-file blob v1.3.3:refs.c". + 'git cat-file': "git cat-file blob v1.3.3:refs.c". . at-open-brace `@{` is used as a notation to access a reflog entry. -With the `--print` option, if 'refname' is acceptable, it prints the -canonicalized name of a hypothetical reference with that name. That is, -it prints 'refname' with any extra `/` characters removed. - With the `--branch` option, it expands the ``previous branch syntax'' `@{-n}`. For example, `@{-1}` is a way to refer the last branch you were on. This option should be used by porcelains to accept this syntax anywhere a branch name is expected, so they can act as if you typed the branch name. +OPTIONS +------- +--allow-onelevel:: +--no-allow-onelevel:: + Controls whether one-level refnames are accepted (i.e., + refnames that do not contain multiple `/`-separated + components). The default is `--no-allow-onelevel`. + +--refspec-pattern:: + Interpret <refname> as a reference name pattern for a refspec + (as used with remote repositories). If this option is + enabled, <refname> is allowed to contain a single `{asterisk}` + in place of a one full pathname component (e.g., + `foo/{asterisk}/bar` but not `foo/bar{asterisk}`). + +--normalize:: + Normalize 'refname' by removing any leading slash (`/`) + characters and collapsing runs of adjacent slashes between + name components into a single slash. Iff the normalized + refname is valid then print it to standard output and exit + with a status of 0. (`--print` is a deprecated way to spell + `--normalize`.) + + EXAMPLES -------- @@ -86,7 +117,7 @@ $ git check-ref-format --branch @{-1} * Determine the reference name to use for a new branch: + ------------ -$ ref=$(git check-ref-format --print "refs/heads/$newbranch") || +$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") || die "we do not like '$newbranch' as a branch name." ------------ diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 62d84836b8..4d33e7be0f 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -13,7 +13,7 @@ SYNOPSIS [--stage=<number>|all] [--temp] [-z] [--stdin] - [--] [<file>]\* + [--] [<file>...] DESCRIPTION ----------- @@ -88,7 +88,7 @@ $ find . -name '*.h' -print0 | xargs -0 git checkout-index -f -- which will force all existing `*.h` files to be replaced with their cached copies. If an empty command line implied "all", then this would force-refresh everything in the index, which was not the point. But -since 'git-checkout-index' accepts --stdin it would be faster to use: +since 'git checkout-index' accepts --stdin it would be faster to use: ---------------- $ find . -name '*.h' -print0 | git checkout-index -f -z --stdin @@ -102,7 +102,7 @@ Using `--` is probably a good policy in scripts. Using --temp or --stage=all --------------------------- When `--temp` is used (or implied by `--stage=all`) -'git-checkout-index' will create a temporary file for each index +'git checkout-index' will create a temporary file for each index entry being checked out. The index will not be updated with stat information. These options can be useful if the caller needs all stages of all unmerged entries so that the unmerged files can be @@ -147,9 +147,9 @@ To update and refresh only the files already checked out:: $ git checkout-index -n -f -a && git update-index --ignore-missing --refresh ---------------- -Using 'git-checkout-index' to "export an entire tree":: +Using 'git checkout-index' to "export an entire tree":: The prefix ability basically makes it trivial to use - 'git-checkout-index' as an "export as tree" function. + 'git checkout-index' as an "export as tree" function. Just read the desired tree into the index, and do: + ---------------- @@ -172,18 +172,6 @@ $ git checkout-index --prefix=.merged- Makefile This will check out the currently cached copy of `Makefile` into the file `.merged-Makefile`. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - - -Documentation --------------- -Documentation by David Greaves, -Junio C Hamano and the git-list <git@vger.kernel.org>. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 37c1810e3f..c0a96e6c1e 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -9,39 +9,60 @@ SYNOPSIS -------- [verse] 'git checkout' [-q] [-f] [-m] [<branch>] -'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>] +'git checkout' [-q] [-f] [-m] [--detach] [<commit>] +'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... -'git checkout' --patch [<tree-ish>] [--] [<paths>...] +'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...] DESCRIPTION ----------- - -When <paths> are not given, this command switches branches by -updating the index, working tree, and HEAD to reflect the specified +Updates files in the working tree to match the version in the index +or the specified tree. If no paths are given, 'git checkout' will +also update `HEAD` to set the specified branch as the current branch. -If `-b` is given, a new branch is created and checked out, as if -linkgit:git-branch[1] were called; in this case you can -use the --track or --no-track options, which will be passed to `git -branch`. As a convenience, --track without `-b` implies branch -creation; see the description of --track below. - -When <paths> or --patch are given, this command does *not* switch -branches. It updates the named paths in the working tree from -the index file, or from a named <tree-ish> (most often a commit). In -this case, the `-b` and `--track` options are meaningless and giving -either of them results in an error. The <tree-ish> argument can be -used to specify a specific tree-ish (i.e. commit, tag or tree) -to update the index for the given paths before updating the -working tree. - -The index may contain unmerged entries after a failed merge. By -default, if you try to check out such an entry from the index, the +'git checkout' [<branch>]:: +'git checkout' -b|-B <new_branch> [<start point>]:: +'git checkout' [--detach] [<commit>]:: + + This form switches branches by updating the index, working + tree, and HEAD to reflect the specified branch or commit. ++ +If `-b` is given, a new branch is created as if linkgit:git-branch[1] +were called and then checked out; in this case you can +use the `--track` or `--no-track` options, which will be passed to +'git branch'. As a convenience, `--track` without `-b` implies branch +creation; see the description of `--track` below. ++ +If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it +is reset. This is the transactional equivalent of ++ +------------ +$ git branch -f <branch> [<start point>] +$ git checkout <branch> +------------ ++ +that is to say, the branch is not reset/created unless "git checkout" is +successful. + +'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...:: + + When <paths> or `--patch` are given, 'git checkout' does *not* + switch branches. It updates the named paths in the working tree + from the index file or from a named <tree-ish> (most often a + commit). In this case, the `-b` and `--track` options are + meaningless and giving either of them results in an error. The + <tree-ish> argument can be used to specify a specific tree-ish + (i.e. commit, tag or tree) to update the index for the given + paths before updating the working tree. ++ +The index may contain unmerged entries because of a previous failed merge. +By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. -Using -f will ignore these unmerged entries. The contents from a +Using `-f` will ignore these unmerged entries. The contents from a specific side of the merge can be checked out of the index by -using --ours or --theirs. With -m, changes made to the working tree -file can be discarded to recreate the original conflicted merge result. +using `--ours` or `--theirs`. With `-m`, changes made to the working tree +file can be discarded to re-create the original conflicted merge result. OPTIONS ------- @@ -67,13 +88,19 @@ entries; instead, unmerged entries are ignored. Create a new branch named <new_branch> and start it at <start_point>; see linkgit:git-branch[1] for details. +-B:: + Creates the branch <new_branch> and start it at <start_point>; + if it already exists, then reset it to <start_point>. This is + equivalent to running "git branch" with "-f"; see + linkgit:git-branch[1] for details. + -t:: --track:: When creating a new branch, set up "upstream" configuration. See "--track" in linkgit:git-branch[1] for details. + If no '-b' option is given, the name of the new branch will be -derived from the remote branch. If "remotes/" or "refs/remotes/" +derived from the remote-tracking branch. If "remotes/" or "refs/remotes/" is prefixed it is stripped away, and then the part up to the next slash (which would be the nickname of the remote) is removed. This would tell us to use "hack" as the local branch when branching @@ -90,6 +117,38 @@ explicitly give a name with '-b' in such a case. Create the new branch's reflog; see linkgit:git-branch[1] for details. +--detach:: + Rather than checking out a branch to work on it, check out a + commit for inspection and discardable experiments. + This is the default behavior of "git checkout <commit>" when + <commit> is not a branch name. See the "DETACHED HEAD" section + below for details. + +--orphan:: + 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 + history totally disconnected from all the other branches and + commits. ++ +The index and the working tree are adjusted as if you had previously run +"git checkout <start_point>". This allows you to start a new history +that records a set of paths similar to <start_point> by easily running +"git commit -a" to make the root commit. ++ +This can be useful when you want to publish the tree from a commit +without exposing its full history. You might want to do this to publish +an open source branch of a project whose current tree is "clean", but +whose full history contains proprietary or otherwise encumbered bits of +code. ++ +If you want to start a disconnected history that records a set of paths +that is totally different from the one of <start_point>, then you should +clear the index and the working tree right after creating the orphan +branch by running "git rm -rf ." from the top level of the working tree. +Afterwards you will be ready to prepare your new files, repopulating the +working tree, by copying them from elsewhere, extracting a tarball, etc. + -m:: --merge:: When switching branches, @@ -124,7 +183,8 @@ the conflicted merge in the specified paths. working tree (and if a <tree-ish> was specified, the index). + This means that you can use `git checkout -p` to selectively discard -edits from your current working tree. +edits from your current working tree. See the ``Interactive Mode'' +section of linkgit:git-add[1] to learn how to operate the `\--patch` mode. <branch>:: Branch to checkout; if it refers to a branch (i.e., a name that, @@ -136,6 +196,10 @@ edits from your current working tree. As a special case, the `"@\{-N\}"` syntax for the N-th last branch checks out the branch (instead of detaching). You may also specify `-` which is synonymous with `"@\{-1\}"`. ++ +As a further special case, you may use `"A\...B"` as a shortcut for the +merge base of `A` and `B` if there is exactly one merge base. You can +leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. <new_branch>:: Name for the new branch. @@ -150,42 +214,140 @@ checks out the branch (instead of detaching). You may also specify -Detached HEAD +DETACHED HEAD ------------- +HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each +branch refers to a specific commit. Let's look at a repo with three +commits, one of them tagged, and with branch 'master' checked out: -It is sometimes useful to be able to 'checkout' a commit that is -not at the tip of one of your branches. The most obvious -example is to check out the commit at a tagged official release -point, like this: +------------ + HEAD (refers to branch 'master') + | + v +a---b---c branch 'master' (refers to commit 'c') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ + +When a commit is created in this state, the branch is updated to refer to +the new commit. Specifically, 'git commit' creates a new commit 'd', whose +parent is commit 'c', and then updates branch 'master' to refer to new +commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers +to commit 'd': ------------ -$ git checkout v2.6.18 +$ edit; git add; git commit + + HEAD (refers to branch 'master') + | + v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') ------------ -Earlier versions of git did not allow this and asked you to -create a temporary branch using the `-b` option, but starting from -version 1.5.0, the above command 'detaches' your HEAD from the -current branch and directly points at the commit named by the tag -(`v2.6.18` in the example above). +It is sometimes useful to be able to checkout a commit that is not at +the tip of any named branch, or even to create a new commit that is not +referenced by a named branch. Let's look at what happens when we +checkout commit 'b' (here we show two ways this may be done): -You can use all git commands while in this state. You can use -`git reset --hard $othercommit` to further move around, for -example. You can make changes and create a new commit on top of -a detached HEAD. You can even create a merge by using `git -merge $othercommit`. +------------ +$ git checkout v2.0 # or +$ git checkout master^^ + + HEAD (refers to commit 'b') + | + v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ -The state you are in while your HEAD is detached is not recorded -by any branch (which is natural --- you are not on any branch). -What this means is that you can discard your temporary commits -and merges by switching back to an existing branch (e.g. `git -checkout master`), and a later `git prune` or `git gc` would -garbage-collect them. If you did this by mistake, you can ask -the reflog for HEAD where you were, e.g. +Notice that regardless of which checkout command we use, HEAD now refers +directly to commit 'b'. This is known as being in detached HEAD state. +It means simply that HEAD refers to a specific commit, as opposed to +referring to a named branch. Let's see what happens when we create a commit: ------------ -$ git log -g -2 HEAD +$ edit; git add; git commit + + HEAD (refers to commit 'e') + | + v + e + / +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') ------------ +There is now a new commit 'e', but it is referenced only by HEAD. We can +of course add yet another commit in this state: + +------------ +$ edit; git add; git commit + + HEAD (refers to commit 'f') + | + v + e---f + / +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ + +In fact, we can perform all the normal git operations. But, let's look +at what happens when we then checkout master: + +------------ +$ git checkout master + + HEAD (refers to branch 'master') + e---f | + / v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ + +It is important to realize that at this point nothing refers to commit +'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted +by the routine git garbage collection process, unless we create a reference +before that happens. If we have not yet moved away from commit 'f', +any of these will create a reference to it: + +------------ +$ git checkout -b foo <1> +$ git branch foo <2> +$ git tag foo <3> +------------ + +<1> creates a new branch 'foo', which refers to commit 'f', and then +updates HEAD to refer to branch 'foo'. In other words, we'll no longer +be in detached HEAD state after this command. + +<2> similarly creates a new branch 'foo', which refers to commit 'f', +but leaves HEAD detached. + +<3> creates a new tag 'foo', which refers to commit 'f', +leaving HEAD detached. + +If we have moved away from commit 'f', then we must first recover its object +name (typically by using git reflog), and then we can create a reference to +it. For example, to see the last two commits to which HEAD referred, we +can use either of these commands: + +------------ +$ git reflog -2 HEAD # or +$ git log -g -2 HEAD +------------ EXAMPLES -------- @@ -226,7 +388,7 @@ the above checkout would fail like this: + ------------ $ git checkout mytopic -fatal: Entry 'frotz' not uptodate. Cannot merge. +error: You have local changes to 'frotz'; not switching branches. ------------ + You can give the `-m` flag to the command, which would try a @@ -261,15 +423,6 @@ $ edit frotz $ git add frotz ------------ - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index b764130d26..2660a842fc 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -3,34 +3,61 @@ git-cherry-pick(1) NAME ---- -git-cherry-pick - Apply the change introduced by an existing commit +git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS -------- -'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] <commit> +[verse] +'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>... +'git cherry-pick' --reset +'git cherry-pick' --continue DESCRIPTION ----------- -Given one existing commit, apply the change the patch introduces, and record a -new commit that records it. This requires your working tree to be clean (no -modifications from the HEAD commit). + +Given one or more existing commits, apply the change each one +introduces, recording a new commit for each. This requires your +working tree to be clean (no modifications from the HEAD commit). + +When it is not obvious how to apply a change, the following +happens: + +1. The current branch and `HEAD` pointer stay at the last commit + successfully made. +2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that + introduced the change that is difficult to apply. +3. Paths in which the change applied cleanly are updated both + in the index file and in your working tree. +4. For conflicting paths, the index file records up to three + versions, as described in the "TRUE MERGE" section of + linkgit:git-merge[1]. The working tree files will include + a description of the conflict bracketed by the usual + conflict markers `<<<<<<<` and `>>>>>>>`. +5. No other modifications are made. + +See linkgit:git-merge[1] for some hints on resolving such +conflicts. OPTIONS ------- -<commit>:: - Commit to cherry-pick. - For a more complete list of ways to spell commits, see the - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. +<commit>...:: + Commits to cherry-pick. + For a more complete list of ways to spell commits, see + linkgit:gitrevisions[7]. + Sets of commits can be passed but no traversal is done by + default, as if the '--no-walk' option was specified, see + linkgit:git-rev-list[1]. -e:: --edit:: - With this option, 'git-cherry-pick' will let you edit the commit + With this option, 'git cherry-pick' will let you edit the commit message prior to committing. -x:: - When recording the commit, append to the original commit - message a note that indicates which commit this change - was cherry-picked from. Append the note only for cherry + When recording the commit, append a line that says + "(cherry picked from commit ...)" to the original commit + message in order to indicate which commit this change was + cherry-picked from. This is done only for cherry picks without conflicts. Do not use this option if you are cherry-picking from your private branch because the information is useless to the recipient. If on the @@ -55,10 +82,10 @@ OPTIONS -n:: --no-commit:: - Usually the command automatically creates a commit. - This flag applies the change necessary to cherry-pick - the named commit to your working tree and the index, - but does not make the commit. In addition, when this + Usually the command automatically creates a sequence of commits. + This flag applies the changes necessary to cherry-pick + each named commit to your working tree and the index, + without making any commit. In addition, when this option is used, your index does not have to match the HEAD commit. The cherry-pick is done against the beginning state of your index. @@ -70,14 +97,91 @@ effect to your index in a row. --signoff:: Add Signed-off-by line at the end of the commit message. +--ff:: + If the current HEAD is the same as the parent of the + cherry-pick'ed commit, then a fast forward to this commit will + be performed. + +--strategy=<strategy>:: + Use the given merge strategy. Should only be used once. + See the MERGE STRATEGIES section in linkgit:git-merge[1] + for details. + +-X<option>:: +--strategy-option=<option>:: + Pass the merge strategy-specific option through to the + merge strategy. See linkgit:git-merge[1] for details. + +SEQUENCER SUBCOMMANDS +--------------------- +include::sequencer.txt[] + +EXAMPLES +-------- +`git cherry-pick master`:: + + Apply the change introduced by the commit at the tip of the + master branch and create a new commit with this change. + +`git cherry-pick ..master`:: +`git cherry-pick ^HEAD master`:: -Author ------- -Written by Junio C Hamano <gitster@pobox.com> + Apply the changes introduced by all commits that are ancestors + of master but not of HEAD to produce new commits. -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +`git cherry-pick master{tilde}4 master{tilde}2`:: + + Apply the changes introduced by the fifth and third last + commits pointed to by master and create 2 new commits with + these changes. + +`git cherry-pick -n master~1 next`:: + + Apply to the working tree and the index the changes introduced + by the second last commit pointed to by master and by the last + commit pointed to by next, but do not create any commit with + these changes. + +`git cherry-pick --ff ..next`:: + + If history is linear and HEAD is an ancestor of next, update + the working tree and advance the HEAD pointer to match next. + Otherwise, apply the changes introduced by those commits that + are in next but not HEAD to the current branch, creating a new + commit for each new change. + +`git rev-list --reverse master \-- README | git cherry-pick -n --stdin`:: + + Apply the changes introduced by all commits on the master + branch that touched README to the working tree and index, + so the result can be inspected and made into a single new + commit if suitable. + +The following sequence attempts to backport a patch, bails out because +the code the patch applies to has changed too much, and then tries +again, this time exercising more care about matching up context lines. + +------------ +$ git cherry-pick topic^ <1> +$ git diff <2> +$ git reset --merge ORIG_HEAD <3> +$ git cherry-pick -Xpatience topic^ <4> +------------ +<1> apply the change that would be shown by `git show topic^`. +In this example, the patch does not apply cleanly, so +information about the conflict is written to the index and +working tree and no new commit results. +<2> summarize changes to be reconciled +<3> cancel the cherry-pick. In other words, return to the +pre-cherry-pick state, preserving any local modifications you had in +the working tree. +<4> try to apply the change introduced by `topic^` again, +spending extra time to avoid mistakes based on incorrectly matching +context lines. + +SEE ALSO +-------- +linkgit:git-revert[1] GIT --- diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 7deefdae8f..f6c19c734d 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -7,6 +7,7 @@ git-cherry - Find commits not merged upstream SYNOPSIS -------- +[verse] 'git cherry' [-v] [<upstream> [<head> [<limit>]]] DESCRIPTION @@ -14,7 +15,7 @@ DESCRIPTION The changeset (or "diff") of each commit between the fork-point and <head> is compared against each commit between the fork-point and <upstream>. The commits are compared with their 'patch id', obtained from -the 'git-patch-id' program. +the 'git patch-id' program. Every commit that doesn't exist in the <upstream> branch has its id (sha1) reported, prefixed by a symbol. The ones that have @@ -37,8 +38,8 @@ to and including <limit> are not reported: \__*__*__<limit>__-__+__> <head> -Because 'git-cherry' compares the changeset rather than the commit id -(sha1), you can use 'git-cherry' to find out if a commit you made locally +Because 'git cherry' compares the changeset rather than the commit id +(sha1), you can use 'git cherry' to find out if a commit you made locally has been applied <upstream> under a different commit id. For example, this will happen if you're feeding patches <upstream> via email rather than pushing or pulling commits directly. @@ -63,14 +64,6 @@ SEE ALSO -------- linkgit:git-patch-id[1] -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.txt index 670cb02b6c..c7a11c36c1 100644 --- a/Documentation/git-citool.txt +++ b/Documentation/git-citool.txt @@ -7,6 +7,7 @@ git-citool - Graphical alternative to git-commit SYNOPSIS -------- +[verse] 'git citool' DESCRIPTION @@ -14,19 +15,11 @@ DESCRIPTION A Tcl/Tk based graphical interface to review modified files, stage them into the index, enter a commit message and record the new commit onto the current branch. This interface is an alternative -to the less interactive 'git-commit' program. +to the less interactive 'git commit' program. -'git-citool' is actually a standard alias for `git gui citool`. +'git citool' is actually a standard alias for `git gui citool`. See linkgit:git-gui[1] for more details. -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by Shawn O. Pearce <spearce@spearce.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 9d291bdd26..79fb984144 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git clean' [-d] [-f] [-n] [-q] [-x | -X] [--] <path>... +'git clean' [-d] [-f] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... DESCRIPTION ----------- @@ -33,8 +33,8 @@ OPTIONS -f:: --force:: - If the git configuration specifies clean.requireForce as true, - 'git-clean' will refuse to run unless given -f or -n. + If the git configuration variable clean.requireForce is not set + to false, 'git clean' will refuse to run unless given -f or -n. -n:: --dry-run:: @@ -45,22 +45,24 @@ OPTIONS Be quiet, only report errors, but not the files that are successfully removed. +-e <pattern>:: +--exclude=<pattern>:: + In addition to those found in .gitignore (per directory) and + $GIT_DIR/info/exclude, also consider these patterns to be in the + set of the ignore rules in effect. + -x:: - Don't use the ignore rules. This allows removing all untracked + Don't use the standard ignore rules read from .gitignore (per + directory) and $GIT_DIR/info/exclude, but do still use the ignore + rules given with `-e` options. This allows removing all untracked files, including build products. This can be used (possibly in - conjunction with 'git-reset') to create a pristine + conjunction with 'git reset') to create a pristine working directory to test a clean build. -X:: Remove only files ignored by git. This may be useful to rebuild everything from scratch, but keep manually created files. - -Author ------- -Written by Pavel Roskin <proski@gnu.org> - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index f43c8b2c08..4b8b26b75e 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -12,7 +12,9 @@ SYNOPSIS 'git clone' [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] - [--depth <depth>] [--recursive] [--] <repository> [<directory>] + [--separate-git-dir <git dir>] + [--depth <depth>] [--recursive|--recurse-submodules] [--] <repository> + [<directory>] DESCRIPTION ----------- @@ -29,7 +31,7 @@ arguments will in addition merge the remote master branch into the current master branch, if any. This default configuration is achieved by creating references to -the remote branch heads under `$GIT_DIR/refs/remotes/origin` and +the remote branch heads under `refs/remotes/origin` and by initializing `remote.origin.url` and `remote.origin.fetch` configuration variables. @@ -102,7 +104,8 @@ objects from the source repository into a pack in the cloned repository. --verbose:: -v:: - Run verbosely. + Run verbosely. Does not affect the reporting of progress status + to the standard error stream. --progress:: Progress status is reported on the standard error stream @@ -127,7 +130,12 @@ objects from the source repository into a pack in the cloned repository. configuration variables are created. --mirror:: - Set up a mirror of the remote repository. This implies `--bare`. + Set up a mirror of the source repository. This implies `--bare`. + Compared to `--bare`, `--mirror` not only maps local branches of the + source to local branches of the target, it maps all refs (including + remote-tracking branches, notes etc.) and sets up a refspec configuration such + that all these refs are overwritten by a `git remote update` in the + target repository. --origin <name>:: -o <name>:: @@ -149,8 +157,18 @@ objects from the source repository into a pack in the cloned repository. --template=<template_directory>:: Specify the directory from which templates will be used; - if unset the templates are taken from the installation - defined default, typically `/usr/share/git-core/templates`. + (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) + +--config <key>=<value>:: +-c <key>=<value>:: + Set a configuration variable in the newly-created repository; + this takes effect immediately after the repository is + initialized, but before the remote history is fetched or any + files checked out. The key is in the same format as expected by + linkgit:git-config[1] (e.g., `core.eol=true`). If multiple + values are given for the same key, each value will be written to + the config file. This makes it safe, for example, to add + additional fetch refspecs to the origin remote. --depth <depth>:: Create a 'shallow' clone with a history truncated to the @@ -162,6 +180,7 @@ objects from the source repository into a pack in the cloned repository. as patches. --recursive:: +--recurse-submodules:: After the clone is created, initialize all submodules within, using their default settings. This is equivalent to running `git submodule update --init --recursive` immediately after @@ -169,6 +188,14 @@ objects from the source repository into a pack in the cloned repository. repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) +--separate-git-dir=<git dir>:: + Instead of placing the cloned repository where it is supposed + to be, place the cloned repository at the specified directory, + then make a filesytem-agnostic git symbolic link to there. + The result is git repository can be separated from working + tree. + + <repository>:: The (possibly remote) repository to clone from. See the <<URLS,URLS>> section below for more information on specifying @@ -187,7 +214,7 @@ include::urls.txt[] Examples -------- -Clone from upstream:: +* Clone from upstream: + ------------ $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 @@ -196,7 +223,7 @@ $ make ------------ -Make a local clone that borrows from the current directory, without checking things out:: +* Make a local clone that borrows from the current directory, without checking things out: + ------------ $ git clone -l -s -n . ../copy @@ -205,7 +232,7 @@ $ git show-branch ------------ -Clone from upstream while borrowing from an existing local directory:: +* Clone from upstream while borrowing from an existing local directory: + ------------ $ git clone --reference my2.6 \ @@ -215,31 +242,20 @@ $ cd my2.7 ------------ -Create a bare repository to publish your changes to the public:: +* Create a bare repository to publish your changes to the public: + ------------ $ git clone --bare -l /home/proj/.git /pub/scm/proj.git ------------ -Create a repository on the kernel.org machine that borrows from Linus:: +* Create a repository on the kernel.org machine that borrows from Linus: + ------------ $ git clone --bare -l -s /pub/scm/.../torvalds/linux-2.6.git \ /pub/scm/.../me/subsys-2.6.git ------------ - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 4fec5d5e38..02133d5fc9 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -8,7 +8,8 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- -'git commit-tree' <tree> [-p <parent commit>]\* < changelog +[verse] +'git commit-tree' <tree> [(-p <parent commit>)...] < changelog DESCRIPTION ----------- @@ -67,10 +68,12 @@ if set: In case (some of) these environment variables are not set, the information is taken from the configuration items user.name and user.email, or, if not -present, system user name and fully qualified hostname. +present, system user name and the hostname used for outgoing mail (taken +from `/etc/mailname` and falling back to the fully qualified hostname when +that file does not exist). A commit comment is read from stdin. If a changelog -entry is not provided via "<" redirection, 'git-commit-tree' will just wait +entry is not provided via "<" redirection, 'git commit-tree' will just wait for one to be entered and terminated with ^D. include::date-formats.txt[] @@ -89,19 +92,14 @@ Discussion include::i18n.txt[] +FILES +----- +/etc/mailname + SEE ALSO -------- linkgit:git-write-tree[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index d3a2dec21e..5cc84a1391 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,11 +8,12 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] [--dry-run] - [(-c | -C) <commit>] [-F <file> | -m <msg>] [--reset-author] - [--allow-empty] [--no-verify] [-e] [--author=<author>] - [--date=<date>] [--cleanup=<mode>] [--status | --no-status] [--] - [[-i | -o ]<file>...] +'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] + [--dry-run] [(-c | -C | --fixup | --squash) <commit>] + [-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>...] DESCRIPTION ----------- @@ -21,11 +22,11 @@ with a log message from the user describing the changes. The content to be added can be specified in several ways: -1. by using 'git-add' to incrementally "add" changes to the +1. by using 'git add' to incrementally "add" changes to the index before using the 'commit' command (Note: even modified files must be "added"); -2. by using 'git-rm' to remove files from the working tree +2. by using 'git rm' to remove files from the working tree and the index, again before using the 'commit' command; 3. by listing files as arguments to the 'commit' command, in which @@ -39,16 +40,17 @@ The content to be added can be specified in several ways: that have been removed from the working tree, and then perform the actual commit; -5. by using the --interactive switch with the 'commit' command to decide one - by one which files should be part of the commit, before finalizing the - operation. Currently, this is done by invoking 'git-add --interactive'. +5. by using the --interactive or --patch switches with the 'commit' command + to decide one by one which files or hunks should be part of the commit, + before finalizing the operation. See the ``Interactive Mode`` section of + linkgit:git-add[1] to learn how to operate these modes. The `--dry-run` option can be used to obtain a summary of what is included by any of the above for the next commit by giving the same set of parameters (options and paths). If you make a commit and then find a mistake immediately after -that, you can recover from it with 'git-reset'. +that, you can recover from it with 'git reset'. OPTIONS @@ -59,6 +61,12 @@ OPTIONS been modified and deleted, but new files you have not told git about are not affected. +-p:: +--patch:: + Use the interactive patch selection interface to chose + which changes to commit. See linkgit:git-add[1] for + details. + -C <commit>:: --reuse-message=<commit>:: Take an existing commit object, and reuse the log message @@ -70,10 +78,24 @@ OPTIONS Like '-C', but with '-c' the editor is invoked, so that the user can further edit the commit message. +--fixup=<commit>:: + Construct a commit message for use with `rebase --autosquash`. + The commit message will be the subject line from the specified + commit with a prefix of "fixup! ". See linkgit:git-rebase[1] + for details. + +--squash=<commit>:: + Construct a commit message for use with `rebase --autosquash`. + The commit message subject line is taken from the specified + commit with a prefix of "squash! ". Can be used with additional + commit message options (`-m`/`-c`/`-C`/`-F`). See + linkgit:git-rebase[1] for details. + --reset-author:: - When used with -C/-c/--amend options, declare that the - authorship of the resulting commit now belongs of the committer. - This also renews the author timestamp. + When used with -C/-c/--amend options, or when committing after a + a conflicting cherry-pick, declare that the authorship of the + resulting commit now belongs of the committer. This also renews + the author timestamp. --short:: When doing a dry-run, give the output in the short-format. See @@ -95,10 +117,11 @@ OPTIONS read the message from the standard input. --author=<author>:: - Override the author name used in the commit. You can use the - standard `A U Thor <author@example.com>` format. Otherwise, - an existing commit that matches the given string and its author - name is used. + Override the commit author. Specify an explicit author using the + standard `A U Thor <author@example.com>` format. Otherwise <author> + is assumed to be a pattern and is used to search for an existing + commit by that author (i.e. rev-list --all -i --author=<author>); + the commit author is then copied from the first such commit found. --date=<date>:: Override the author date used in the commit. @@ -129,7 +152,13 @@ OPTIONS Usually recording a commit that has the exact same tree as its sole parent commit is a mistake, and the command prevents you from making such a commit. This option bypasses the safety, and - is primarily for use by foreign scm interface scripts. + is primarily for use by foreign SCM interface scripts. + +--allow-empty-message:: + Like --allow-empty this command is primarily for use by foreign + SCM interface scripts. It allows you to create a commit with an + empty commit message without using plumbing commands like + linkgit:git-commit-tree[1]. --cleanup=<mode>:: This option sets how the commit message is cleaned up. @@ -185,7 +214,7 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) Make a commit only from the paths specified on the command line, disregarding any contents that have been staged so far. This is the default mode of operation of - 'git-commit' if any paths are given on the command line, + 'git commit' if any paths are given on the command line, in which case this option can be omitted. If this option is specified together with '--amend', then no paths need to be specified, which can be used to amend @@ -194,20 +223,20 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) -u[<mode>]:: --untracked-files[=<mode>]:: - Show untracked files (Default: 'all'). + Show untracked files. + -The mode parameter is optional, and is used to specify -the handling of untracked files. The possible options are: +The mode parameter is optional (defaults to 'all'), and is used to +specify the handling of untracked files; when -u is not used, the +default is 'normal', i.e. show untracked files and directories. ++ +The possible options are: + --- - 'no' - Show no untracked files - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. --- + -See linkgit:git-config[1] for configuration variable -used to change the default for when the option is not -specified. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. -v:: --verbose:: @@ -253,10 +282,10 @@ EXAMPLES -------- When recording your own work, the contents of modified files in your working tree are temporarily stored to a staging area -called the "index" with 'git-add'. A file can be +called the "index" with 'git add'. A file can be reverted back, only in the index but not in the working tree, -to that of the last commit with `git reset HEAD -- <file>`, -which effectively reverts 'git-add' and prevents the changes to +to that of the last commit with `git reset HEAD \-- <file>`, +which effectively reverts 'git add' and prevents the changes to this file from participating in the next commit. After building the state to be committed incrementally with these commands, `git commit` (without any pathname parameter) is used to record what @@ -312,13 +341,13 @@ $ git commit this second commit would record the changes to `hello.c` and `hello.h` as expected. -After a merge (initiated by 'git-merge' or 'git-pull') stops +After a merge (initiated by 'git merge' or 'git pull') stops because of conflicts, cleanly merged paths are already staged to be committed for you, and paths that conflicted are left in unmerged state. You would have to first -check which paths are conflicting with 'git-status' +check which paths are conflicting with 'git status' and after fixing them manually in your working tree, you would -stage the result as usual with 'git-add': +stage the result as usual with 'git add': ------------ $ git status | grep unmerged @@ -376,12 +405,6 @@ linkgit:git-mv[1], linkgit:git-merge[1], linkgit:git-commit-tree[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com> - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 263292809d..e7ecf5d803 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -38,7 +38,7 @@ you want to handle the lines that do *not* match the regex, just prepend a single exclamation mark in front (see also <<EXAMPLES>>). The type specifier can be either '--int' or '--bool', to make -'git-config' ensure that the variable(s) are of the given type and +'git config' ensure that the variable(s) are of the given type and convert the value to the canonical form (simple decimal number for int, a "true" or "false" string for bool), or '--path', which does some path expansion (see '--path' below). If no type specifier is passed, no @@ -50,16 +50,18 @@ The default is to assume the config file of the current repository, .git/config unless defined otherwise with GIT_DIR and GIT_CONFIG (see <<FILES>>). -This command will fail if: +This command will fail (with exit code ret) if: -. The config file is invalid, -. Can not write to the config file, -. no section was provided, -. the section or key is invalid, -. you try to unset an option which does not exist, -. you try to unset/set an option for which multiple lines match, or -. you use '--global' option without $HOME being properly set. +. 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). +On success, the command returns the exit code 0. OPTIONS ------- @@ -125,16 +127,16 @@ See also <<FILES>>. List all variables set in config file. --bool:: - 'git-config' will ensure that the output is "true" or "false" + 'git config' will ensure that the output is "true" or "false" --int:: - 'git-config' will ensure that the output is a simple + 'git config' will ensure that the output is a simple decimal number. An optional value suffix of 'k', 'm', or 'g' in the config file will cause the value to be multiplied by 1024, 1048576, or 1073741824 prior to output. --bool-or-int:: - 'git-config' will ensure that the output matches the format of + 'git config' will ensure that the output matches the format of either --bool or --int, as described above. --path:: @@ -181,7 +183,7 @@ FILES ----- If not set explicitly with '--file', there are three files where -'git-config' will search for configuration options: +'git config' will search for configuration options: $GIT_DIR/config:: Repository specific configuration file. (The filename is @@ -198,12 +200,12 @@ $(prefix)/etc/gitconfig:: If no further options are given, all reading options will read all of these files that are available. If the global or the system-wide configuration file are not available they will be ignored. If the repository configuration -file is not available or readable, 'git-config' will exit with a non-zero +file is not available or readable, 'git config' will exit with a non-zero error code. However, in neither case will an error message be issued. All writing options will per default write to the repository specific configuration file. Note that this also affects options like '--replace-all' -and '--unset'. *'git-config' will only ever change one file at a time*. +and '--unset'. *'git config' will only ever change one file at a time*. You can override these rules either by command line options or by environment variables. The '--global' and the '--system' options will limit the file used @@ -336,15 +338,6 @@ echo "${WS}your whitespace color or blue reverse${RESET}" include::config.txt[] - -Author ------- -Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> - -Documentation --------------- -Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 6bc1c21e62..23c80cea64 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -7,6 +7,7 @@ git-count-objects - Count unpacked number of objects and their disk consumption SYNOPSIS -------- +[verse] 'git count-objects' [-v] DESCRIPTION @@ -25,15 +26,6 @@ OPTIONS and number of objects that can be removed by running `git prune-packed`. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index abaaf273bb..7f79cec3f8 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,6 +8,7 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- +[verse] 'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID @@ -27,7 +28,7 @@ by default. Supports file additions, removals, and commits that affect binary files. -If the commit is a merge commit, you must tell 'git-cvsexportcommit' what +If the commit is a merge commit, you must tell 'git cvsexportcommit' what parent the changeset should be done against. OPTIONS @@ -112,14 +113,6 @@ $ cd ~/project_cvs_checkout $ git cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git cvsexportcommit -c -p -v ------------ -Author ------- -Written by Martin Langhoff <martin@catalyst.net.nz> and others. - -Documentation --------------- -Documentation by Martin Langhoff <martin@catalyst.net.nz> and others. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 614e769f4e..6695ab3b4b 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -13,7 +13,7 @@ SYNOPSIS [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] - [-r <remote>] [<CVS_module>] + [-r <remote>] [-R] [<CVS_module>] DESCRIPTION @@ -28,9 +28,9 @@ At least version 2.1 is required. Please see the section <<issues,ISSUES>> for further reference. You should *never* do any work of your own on the branches that are -created by 'git-cvsimport'. By default initial import will create and populate a +created by 'git cvsimport'. By default initial import will create and populate a "master" branch from the CVS repository's main branch which you're free -to work with; after that, you need to 'git-merge' incremental imports, or +to work with; after that, you need to 'git merge' incremental imports, or any CVS branches, yourself. It is advisable to specify a named remote via -r to separate and protect the incoming branches. @@ -49,13 +49,13 @@ OPTIONS -d <CVSROOT>:: The root of the CVS archive. May be local (a simple path) or remote; currently, only the :local:, :ext: and :pserver: access methods - are supported. If not given, 'git-cvsimport' will try to read it + are supported. If not given, 'git cvsimport' will try to read it from `CVS/Root`. If no such file exists, it checks for the `CVSROOT` environment variable. <CVS_module>:: The CVS module you want to import. Relative to <CVSROOT>. - If not given, 'git-cvsimport' tries to read it from + If not given, 'git cvsimport' tries to read it from `CVS/Repository`. -C <target-dir>:: @@ -65,14 +65,14 @@ OPTIONS -r <remote>:: The git remote to import this CVS repository into. Moves all CVS branches into remotes/<remote>/<branch> - akin to the way 'git-clone' uses 'origin' by default. + akin to the way 'git clone' uses 'origin' by default. -o <branch-for-HEAD>:: When no remote is specified (via -r) the 'HEAD' branch from CVS is imported to the 'origin' branch within the git repository, as 'HEAD' already has a special meaning for git. When a remote is specified the 'HEAD' branch is named - remotes/<remote>/master mirroring 'git-clone' behaviour. + remotes/<remote>/master mirroring 'git clone' behaviour. Use this option if you want to import into a different branch. + @@ -145,17 +145,33 @@ This option can be used several times to provide several detection regexes. --------- + -'git-cvsimport' will make it appear as those authors had +'git cvsimport' will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly all along. + For convenience, this data is saved to `$GIT_DIR/cvs-authors` each time the '-A' option is provided and read from that same -file each time 'git-cvsimport' is run. +file each time 'git cvsimport' is run. + It is not recommended to use this feature if you intend to export changes back to CVS again later with -'git-cvsexportcommit'. +'git cvsexportcommit'. + +-R:: + Generate a `$GIT_DIR/cvs-revisions` file containing a mapping from CVS + revision numbers to newly-created Git commit IDs. The generated file + will contain one line for each (filename, revision) pair imported; + each line will look like ++ +--------- +src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7 +--------- ++ +The revision data is appended to the file if it already exists, for use when +doing incremental imports. ++ +This option may be useful if you have CVS revision numbers stored in commit +messages, bug-tracking systems, email archives, and the like. -h:: Print a short usage message and exit. @@ -172,7 +188,7 @@ ISSUES ------ Problems related to timestamps: - * If timestamps of commits in the cvs repository are not stable enough + * If timestamps of commits in the CVS repository are not stable enough to be used for ordering commits changes may show up in the wrong order. * If any files were ever "cvs import"ed more than once (e.g., import of @@ -185,7 +201,7 @@ Problems related to branches: * Branches on which no commits have been made are not imported. * All files from the branching point are added to a branch even if - never added in cvs. + never added in CVS. * This applies to files added to the source branch *after* a daughter branch was created: if previously no commit was made on the daughter branch they will erroneously be added to the daughter branch in git. @@ -201,15 +217,6 @@ more stable in practice: * cvs2git (part of cvs2svn), `http://cvs2svn.tigris.org` * parsecvs, `http://cgit.freedesktop.org/~keithp/parsecvs` -Author ------- -Written by Matthias Urlichs <smurf@smurf.noris.de>, with help from -various participants of the git-list <git@vger.kernel.org>. - -Documentation --------------- -Documentation by Matthias Urlichs <smurf@smurf.noris.de>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index fbab29550a..827bc988ed 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -22,7 +22,7 @@ cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver Usage: [verse] -'git cvsserver' [options] [pserver|server] [<directory> ...] +'git-cvsserver' [options] [pserver|server] [<directory> ...] OPTIONS ------- @@ -72,9 +72,6 @@ plugin. Most functionality works fine with both of these clients. LIMITATIONS ----------- -Currently cvsserver works over SSH connections for read/write clients, and -over pserver for anonymous CVS access. - CVS clients cannot tag, branch or perform GIT merges. 'git-cvsserver' maps GIT branches to CVS modules. This is very different @@ -84,7 +81,7 @@ one or more directories. INSTALLATION ------------ -1. If you are going to offer anonymous CVS access via pserver, add a line in +1. If you are going to offer CVS access via pserver, add a line in /etc/inetd.conf like + -- @@ -101,6 +98,38 @@ looks like cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver ------ + +Only anonymous access is provided by pserve by default. To commit you +will have to create pserver accounts, simply add a gitcvs.authdb +setting in the config file of the repositories you want the cvsserver +to allow writes to, for example: + +------ + + [gitcvs] + authdb = /etc/cvsserver/passwd + +------ +The format of these files is username followed by the crypted password, +for example: + +------ + myuser:$1Oyx5r9mdGZ2 + myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./ +------ +You can use the 'htpasswd' facility that comes with Apache to make these +files, but Apache's MD5 crypt method differs from the one used by most C +library's crypt() function, so don't use the -m option. + +Alternatively you can produce the password with perl's crypt() operator: +----- + perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password +----- + +Then provide your password via the pserver method, for example: +------ + cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name> +------ No special setup is needed for SSH access, other than having GIT tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename 'git-cvsserver' to `cvs`. @@ -206,7 +235,7 @@ them write access to the directory, too. The database can not be reliably regenerated in a consistent form after the branch it is tracking has changed. Example: For merged branches, 'git-cvsserver' only tracks -one branch of development, and after a 'git-merge' an +one branch of development, and after a 'git merge' an incrementally updated database may track a different branch than a database regenerated from scratch, causing inconsistent CVS revision numbers. `git-cvsserver` has no way of knowing which @@ -223,7 +252,7 @@ Configuring database backend 'git-cvsserver' uses the Perl DBI module. Please also read its documentation if changing these variables, especially -about `DBI->connect()`. +about `DBI\->connect()`. gitcvs.dbname:: Database name. The exact meaning depends on the @@ -309,7 +338,7 @@ To get a checkout with the Eclipse CVS client: Protocol notes: If you are using anonymous access via pserver, just select that. Those using SSH access should choose the 'ext' protocol, and configure 'ext' access on the Preferences->Team->CVS->ExtConnection pane. Set CVS_SERVER to -"'git cvsserver'". Note that password support is not good when using 'ext', +"`git cvsserver`". Note that password support is not good when using 'ext', you will definitely want to have SSH keys setup. Alternatively, you can just use the non-standard extssh protocol that Eclipse @@ -337,19 +366,16 @@ CRLF Line Ending Conversions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default the server leaves the '-k' mode blank for all files, -which causes the cvs client to treat them as a text files, subject -to crlf conversion on some platforms. +which causes the CVS client to treat them as a text files, subject +to end-of-line conversion on some platforms. -You can make the server use `crlf` attributes to set the '-k' modes -for files by setting the `gitcvs.usecrlfattr` config variable. -In this case, if `crlf` is explicitly unset ('-crlf'), then the -server will set '-kb' mode for binary files. If `crlf` is set, -then the '-k' mode will explicitly be left blank. See -also linkgit:gitattributes[5] for more information about the `crlf` -attribute. +You can make the server use the end-of-line conversion attributes to +set the '-k' modes for files by setting the `gitcvs.usecrlfattr` +config variable. See linkgit:gitattributes[5] for more information +about end-of-line conversion. Alternatively, if `gitcvs.usecrlfattr` config is not enabled -or if the `crlf` attribute is unspecified for a filename, then +or the attributes do not allow automatic detection for a filename, then the server uses the `gitcvs.allbinary` config for the default setting. If `gitcvs.allbinary` is set, then file not otherwise specified will default to '-kb' mode. Otherwise the '-k' mode @@ -365,22 +391,6 @@ Dependencies ------------ 'git-cvsserver' depends on DBD::SQLite. -Copyright and Authors ---------------------- - -This program is copyright The Open University UK - 2006. - -Authors: - -- Martyn Smith <martyn@catalyst.net.nz> -- Martin Langhoff <martin@catalyst.net.nz> - -with ideas and patches from participants of the git-list <git@vger.kernel.org>. - -Documentation --------------- -Documentation by Martyn Smith <martyn@catalyst.net.nz>, Martin Langhoff <martin@catalyst.net.nz>, and Matthias Urlichs <smurf@smurf.noris.de>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index a85121c689..31b28fc29f 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -9,15 +9,15 @@ SYNOPSIS -------- [verse] 'git daemon' [--verbose] [--syslog] [--export-all] - [--timeout=n] [--init-timeout=n] [--max-connections=n] - [--strict-paths] [--base-path=path] [--base-path-relaxed] - [--user-path | --user-path=path] - [--interpolated-path=pathtemplate] - [--reuseaddr] [--detach] [--pid-file=file] - [--enable=service] [--disable=service] - [--allow-override=service] [--forbid-override=service] - [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]] - [directory...] + [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] + [--strict-paths] [--base-path=<path>] [--base-path-relaxed] + [--user-path | --user-path=<path>] + [--interpolated-path=<pathtemplate>] + [--reuseaddr] [--detach] [--pid-file=<file>] + [--enable=<service>] [--disable=<service>] + [--allow-override=<service>] [--forbid-override=<service>] + [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]] + [<directory>...] DESCRIPTION ----------- @@ -28,40 +28,40 @@ that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any git directory that hasn't explicitly been marked for export this way (unless the '--export-all' parameter is specified). If you -pass some directory paths as 'git-daemon' arguments, you can further restrict +pass some directory paths as 'git daemon' arguments, you can further restrict the offers to a whitelist comprising of those. By default, only `upload-pack` service is enabled, which serves -'git-fetch-pack' and 'git-ls-remote' clients, which are invoked -from 'git-fetch', 'git-pull', and 'git-clone'. +'git fetch-pack' and 'git ls-remote' clients, which are invoked +from 'git fetch', 'git pull', and 'git clone'. This is ideally suited for read-only updates, i.e., pulling from git repositories. -An `upload-archive` also exists to serve 'git-archive'. +An `upload-archive` also exists to serve 'git archive'. OPTIONS ------- --strict-paths:: Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. - 'git-daemon' will refuse to start when this option is enabled and no + 'git daemon' will refuse to start when this option is enabled and no whitelist is specified. ---base-path=path:: +--base-path=<path>:: Remap all the path requests as relative to the given path. - This is sort of "GIT root" - if you run 'git-daemon' with + This is sort of "GIT root" - if you run 'git daemon' with '--base-path=/srv/git' on example.com, then if you later try to pull - 'git://example.com/hello.git', 'git-daemon' will interpret the path + 'git://example.com/hello.git', 'git daemon' will interpret the path as '/srv/git/hello.git'. --base-path-relaxed:: If --base-path is enabled and repo lookup fails, with this option - 'git-daemon' will attempt to lookup without prefixing the base path. + 'git daemon' will attempt to lookup without prefixing the base path. This is useful for switching to --base-path usage, while still allowing the old paths. ---interpolated-path=pathtemplate:: +--interpolated-path=<pathtemplate>:: To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template supports %H for the target hostname as supplied by the client but @@ -78,29 +78,31 @@ OPTIONS --inetd:: Have the server run as an inetd service. Implies --syslog. - Incompatible with --port, --listen, --user and --group options. + Incompatible with --detach, --port, --listen, --user and --group + options. ---listen=host_or_ipaddr:: +--listen=<host_or_ipaddr>:: Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 is not supported, then --listen=hostname is also not supported and --listen must be given an IPv4 address. + Can be given more than once. Incompatible with '--inetd' option. ---port=n:: +--port=<n>:: Listen on an alternative port. Incompatible with '--inetd' option. ---init-timeout=n:: - Timeout between the moment the connection is established and the - client request is received (typically a rather low value, since +--init-timeout=<n>:: + Timeout (in seconds) between the moment the connection is established + and the client request is received (typically a rather low value, since that should be basically immediate). ---timeout=n:: - Timeout for specific client sub-requests. This includes the time - it takes for the server to process the sub-request and the time spent - waiting for the next client's request. +--timeout=<n>:: + Timeout (in seconds) for specific client sub-requests. This includes + the time it takes for the server to process the sub-request and the + time spent waiting for the next client's request. ---max-connections=n:: +--max-connections=<n>:: Maximum number of concurrent clients, defaults to 32. Set it to zero for no limit. @@ -109,7 +111,7 @@ OPTIONS --verbose, thus by default only error conditions will be logged. --user-path:: ---user-path=path:: +--user-path=<path>:: Allow {tilde}user notation to be used in requests. When specified with no parameter, requests to git://host/{tilde}alice/foo is taken as a request to access @@ -129,12 +131,12 @@ OPTIONS --detach:: Detach from the shell. Implies --syslog. ---pid-file=file:: +--pid-file=<file>:: Save the process id in 'file'. Ignored when the daemon is run under `--inetd`. ---user=user:: ---group=group:: +--user=<user>:: +--group=<group>:: Change daemon's uid and gid before entering the service loop. When only `--user` is given without `--group`, the primary group ID for the user is used. The values of @@ -143,22 +145,32 @@ OPTIONS + Giving these options is an error when used with `--inetd`; use the facility of inet daemon to achieve the same before spawning -'git-daemon' if needed. +'git daemon' if needed. ---enable=service:: ---disable=service:: +--enable=<service>:: +--disable=<service>:: Enable/disable the service site-wide per default. Note that a service disabled site-wide can still be enabled per repository if it is marked overridable and the repository enables the service with a configuration item. ---allow-override=service:: ---forbid-override=service:: +--allow-override=<service>:: +--forbid-override=<service>:: Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services are overridable. +--informative-errors:: +--no-informative-errors:: + When informative errors are turned on, git-daemon will report + more verbose errors to the client, differentiating conditions + like "no such repository" from "repository not exported". This + is more convenient for clients, but may leak information about + the existence of unexported repositories. When informative + errors are not enabled, all errors report "access denied" to the + client. The default is --no-informative-errors. + <directory>:: A directory to add to the whitelist of allowed directories. Unless --strict-paths is specified this will also include subdirectories @@ -169,24 +181,24 @@ SERVICES These services can be globally enabled/disabled using the command line options of this command. If a finer-grained -control is desired (e.g. to allow 'git-archive' to be run +control is desired (e.g. to allow 'git archive' to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or disable them. upload-pack:: - This serves 'git-fetch-pack' and 'git-ls-remote' + This serves 'git fetch-pack' and 'git ls-remote' clients. It is enabled by default, but a repository can disable it by setting `daemon.uploadpack` configuration item to `false`. upload-archive:: - This serves 'git-archive --remote'. It is disabled by + This serves 'git archive --remote'. It is disabled by default, but a repository can enable it by setting `daemon.uploadarch` configuration item to `true`. receive-pack:: - This serves 'git-send-pack' clients, allowing anonymous + This serves 'git send-pack' clients, allowing anonymous push. It is disabled by default, as there is _no_ authentication in the protocol (in other words, anybody can push anything into the repository, including removal @@ -204,8 +216,8 @@ $ grep 9418 /etc/services git 9418/tcp # Git Version Control System ------------ -'git-daemon' as inetd server:: - To set up 'git-daemon' as an inetd service that handles any +'git daemon' as inetd server:: + To set up 'git daemon' as an inetd service that handles any repository under the whitelisted set of directories, /pub/foo and /pub/bar, place an entry like the following into /etc/inetd all on one line: @@ -217,8 +229,8 @@ git 9418/tcp # Git Version Control System ------------------------------------------------ -'git-daemon' as inetd server for virtual hosts:: - To set up 'git-daemon' as an inetd service that handles +'git daemon' as inetd server for virtual hosts:: + To set up 'git daemon' as an inetd service that handles repositories for different virtual hosts, `www.example.com` and `www.example.org`, place an entry like the following into `/etc/inetd` all on one line: @@ -240,8 +252,8 @@ clients, a symlink from `/software` into the appropriate default repository could be made as well. -'git-daemon' as regular daemon for virtual hosts:: - To set up 'git-daemon' as a regular, non-inetd service that +'git daemon' as regular daemon for virtual hosts:: + To set up 'git daemon' as a regular, non-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this: + @@ -258,7 +270,7 @@ Repositories can still be accessed by hostname though, assuming they correspond to these IP addresses. selectively enable/disable services per repository:: - To enable 'git-archive --remote' and disable 'git-fetch' against + To enable 'git archive --remote' and disable 'git fetch' against a repository, have the following in the configuration file in the repository (that is the file 'config' next to 'HEAD', 'refs' and 'objects'). @@ -272,22 +284,11 @@ selectively enable/disable services per repository:: ENVIRONMENT ----------- -'git-daemon' will set REMOTE_ADDR to the IP address of the client +'git daemon' will set REMOTE_ADDR to the IP address of the client that connected to it, if the IP address is available. REMOTE_ADDR will be available in the environment of hooks called when services are performed. - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki -<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 78b9808aa3..039cce2e98 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -37,7 +37,7 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref found in `.git/refs/`. This option enables matching - any known branch, remote branch, or lightweight tag. + any known branch, remote-tracking branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag @@ -105,8 +105,11 @@ The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". The hash suffix is "-g" + 7-char abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). +The "g" prefix stands for "git" and is used to allow describing the version of +a software depending on the SCM the software is managed with. This is useful +in an environment where people may use different SCMs. -Doing a 'git-describe' on a tag-name will just show the tag name: +Doing a 'git describe' on a tag-name will just show the tag name: [torvalds@g5 git]$ git describe v1.0.4 v1.0.4 @@ -136,13 +139,13 @@ be sufficient to disambiguate these commits. SEARCH STRATEGY --------------- -For each committish supplied, 'git-describe' will first look for +For each committish supplied, 'git describe' will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match is found, its name will be output and searching will stop. -If an exact match was not found, 'git-describe' will walk back +If an exact match was not found, 'git describe' will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an abbreviation of the input committish's SHA1. @@ -153,17 +156,6 @@ selected and output. Here fewest commits different is defined as the number of commits which would be shown by `git log tag..input` will be the smallest number of commits possible. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, but somewhat -butchered by Junio C Hamano <gitster@pobox.com>. Later significantly -updated by Shawn Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 4ef03578eb..906774f0f7 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -8,6 +8,7 @@ git-diff-files - Compares files in the working tree and the index SYNOPSIS -------- +[verse] 'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] DESCRIPTION @@ -15,7 +16,7 @@ DESCRIPTION Compares the files in the working tree and the index. When paths are specified, compares only those named paths. Otherwise all entries in the index are compared. The output format is the -same as for 'git-diff-index' and 'git-diff-tree'. +same as for 'git diff-index' and 'git diff-tree'. OPTIONS ------- @@ -46,15 +47,6 @@ omit diff output for unmerged entries and just show "Unmerged". include::diff-format.txt[] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 8b9ed29299..c0b7c581ad 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -8,6 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi SYNOPSIS -------- +[verse] 'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] DESCRIPTION @@ -31,7 +32,7 @@ include::diff-options.txt[] -m:: By default, files recorded in the index but not checked out are reported as deleted. This flag makes - 'git-diff-index' say that all non-checked-out files are up + 'git diff-index' say that all non-checked-out files are up to date. include::diff-format.txt[] @@ -48,7 +49,7 @@ Cached Mode If '--cached' is specified, it allows you to ask: show me the differences between HEAD and the current index - contents (the ones I'd write using 'git-write-tree') + contents (the ones I'd write using 'git write-tree') For example, let's say that you have worked on your working directory, updated some files in the index and are ready to commit. You want to see exactly @@ -60,7 +61,7 @@ object and compare it that way, and to do that, you just do Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had done an `update-index` to make that effective in the index file. `git diff-files` wouldn't show anything at all, since the index file -matches my working directory. But doing a 'git-diff-index' does: +matches my working directory. But doing a 'git diff-index' does: torvalds@ppc970:~/git> git diff-index --cached HEAD -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c @@ -69,10 +70,10 @@ matches my working directory. But doing a 'git-diff-index' does: You can see easily that the above is a rename. In fact, `git diff-index --cached` *should* always be entirely equivalent to -actually doing a 'git-write-tree' and comparing that. Except this one is much +actually doing a 'git write-tree' and comparing that. Except this one is much nicer for the case where you just want to check where you are. -So doing a 'git-diff-index --cached' is basically very useful when you are +So doing a `git diff-index --cached` is basically very useful when you are asking yourself "what have I already marked for being committed, and what's the difference to a previous tree". @@ -80,35 +81,35 @@ Non-cached Mode --------------- The "non-cached" mode takes a different approach, and is potentially the more useful of the two in that what it does can't be emulated with -a 'git-write-tree' + 'git-diff-tree'. Thus that's the default mode. +a 'git write-tree' + 'git diff-tree'. Thus that's the default mode. The non-cached version asks the question: show me the differences between HEAD and the currently checked out tree - index contents _and_ files that aren't up-to-date which is obviously a very useful question too, since that tells you what -you *could* commit. Again, the output matches the 'git-diff-tree -r' +you *could* commit. Again, the output matches the 'git diff-tree -r' output to a tee, but with a twist. The twist is that if some file doesn't match the index, we don't have a backing store thing for it, and we use the magic "all-zero" sha1 to show that. So let's say that you have edited `kernel/sched.c`, but -have not actually done a 'git-update-index' on it yet - there is no +have not actually done a 'git update-index' on it yet - there is no "object" associated with the new state, and you get: - torvalds@ppc970:~/v2.6/linux> git diff-index HEAD - *100644->100664 blob 7476bb......->000000...... kernel/sched.c + torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD + :100644 100664 7476bb... 000000... kernel/sched.c i.e., it shows that the tree has changed, and that `kernel/sched.c` has is not up-to-date and may contain new stuff. The all-zero sha1 means that to get the real diff, you need to look at the object in the working directory directly rather than do an object-to-object diff. -NOTE: As with other commands of this type, 'git-diff-index' does not +NOTE: As with other commands of this type, 'git diff-index' does not actually look at the contents of the file at all. So maybe `kernel/sched.c` hasn't actually changed, and it's just that you touched it. In either case, it's a note that you need to -'git-update-index' it to make the index be in sync. +'git update-index' it to make the index be in sync. NOTE: You can have a mixture of files show up as "has been updated" and "is still dirty in the working directory" together. You can always @@ -116,15 +117,6 @@ tell which file is in which state, since the "has been updated" ones show a valid sha1, and the "not in sync with the index" ones will always have the special all-zero sha1. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index f2cef1260b..1439486e40 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -20,7 +20,7 @@ Compares the content and mode of the blobs found via two tree objects. If there is only one <tree-ish> given, the commit is compared with its parents (see --stdin below). -Note that 'git-diff-tree' can use the tree encapsulated in a commit object. +Note that 'git diff-tree' can use the tree encapsulated in a commit object. OPTIONS ------- @@ -67,25 +67,25 @@ The following flags further affect the behavior when comparing commits (but not trees). -m:: - By default, 'git-diff-tree --stdin' does not show + By default, 'git diff-tree --stdin' does not show differences for merge commits. With this flag, it shows differences to that commit from all of its parents. See also '-c'. -s:: - By default, 'git-diff-tree --stdin' shows differences, + By default, 'git diff-tree --stdin' shows differences, either in machine-readable form (without '-p') or in patch form (with '-p'). This output can be suppressed. It is only useful with '-v' flag. -v:: - This flag causes 'git-diff-tree --stdin' to also show + This flag causes 'git diff-tree --stdin' to also show the commit message before the differences. include::pretty-options.txt[] --no-commit-id:: - 'git-diff-tree' outputs a line with the commit ID when + 'git diff-tree' outputs a line with the commit ID when applicable. This flag suppressed the commit ID output. -c:: @@ -138,8 +138,8 @@ so it can be used to name subdirectories. An example of normal usage is: - torvalds@ppc970:~/git> git diff-tree 5319e4...... - *100664->100664 blob ac348b.......->a01513....... git-fsck-objects.c + torvalds@ppc970:~/git> git diff-tree --abbrev 5319e4 + :100664 100664 ac348b... a01513... git-fsck-objects.c which tells you that the last commit changed just one file (it's from this one: @@ -162,15 +162,6 @@ in case you care). include::diff-format.txt[] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 0ac711230e..f8d0819113 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,12 +8,17 @@ git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS -------- -'git diff' [<common diff options>] <commit>{0,2} [--] [<path>...] +[verse] +'git diff' [options] [<commit>] [--] [<path>...] +'git diff' [options] --cached [<commit>] [--] [<path>...] +'git diff' [options] <commit> <commit> [--] [<path>...] +'git diff' [options] [--no-index] [--] <path> <path> DESCRIPTION ----------- -Show changes between two trees, a tree and the working tree, a -tree and the index file, or the index file and the working tree. +Show changes between the working tree and the index or a tree, changes +between the index and a tree, changes between two trees, or changes +between two files on disk. 'git diff' [--options] [--] [<path>...]:: @@ -23,9 +28,9 @@ tree and the index file, or the index file and the working tree. further add to the index but you still haven't. You can stage these changes by using linkgit:git-add[1]. + -If exactly two paths are given, and at least one is untracked, -compare the two files / directories. This behavior can be -forced by --no-index. +If exactly two paths are given and at least one points outside +the current repository, 'git diff' will compare the two files / +directories. This behavior can be forced by --no-index. 'git diff' [--options] --cached [<commit>] [--] [<path>...]:: @@ -33,6 +38,8 @@ forced by --no-index. commit relative to the named <commit>. Typically you would want comparison with the latest commit, so if you do not give <commit>, it defaults to HEAD. + If HEAD does not exist (e.g. unborned branches) and + <commit> is not given, it shows all staged changes. --staged is a synonym of --cached. 'git diff' [--options] <commit> [--] [<path>...]:: @@ -64,15 +71,16 @@ forced by --no-index. Just in case if you are doing something exotic, it should be noted that all of the <commit> in the above description, except -for the last two forms that use ".." notations, can be any -<tree-ish>. +in the last two forms that use ".." notations, can be any +<tree>. The third form ('git diff <commit> <commit>') can also +be used to compare two <blob> objects. For a more complete list of ways to spell <commit>, see -"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. +"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. However, "diff" is about comparing two _endpoints_, not ranges, and the range notations ("<commit>..<commit>" and "<commit>\...<commit>") do not mean a range as defined in the -"SPECIFYING RANGES" section in linkgit:git-rev-parse[1]. +"SPECIFYING RANGES" section in linkgit:gitrevisions[7]. OPTIONS ------- @@ -157,14 +165,14 @@ $ git diff -R <2> rewrites (very expensive). <2> Output diff in reverse. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +diff(1), +linkgit:git-difftool[1], +linkgit:git-log[1], +linkgit:gitdiffcore[7], +linkgit:git-format-patch[1], +linkgit:git-apply[1] GIT --- diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 8e9aed67d7..a03515f1ec 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -7,13 +7,15 @@ git-difftool - Show changes using common diff tools SYNOPSIS -------- -'git difftool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<'git diff' options>] +[verse] +'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...] DESCRIPTION ----------- -'git-difftool' is a git command that allows you to compare and edit files +'git difftool' is a git command that allows you to compare and edit files between revisions using common diff tools. 'git difftool' is a frontend -to 'git-diff' and accepts the same options and arguments. +to 'git diff' and accepts the same options and arguments. See +linkgit:git-diff[1]. OPTIONS ------- @@ -30,44 +32,61 @@ OPTIONS --tool=<tool>:: Use the diff tool specified by <tool>. Valid merge tools are: - kdiff3, kompare, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, - ecmerge, diffuse, opendiff, p4merge and araxis. + araxis, bc3, diffuse, emerge, ecmerge, gvimdiff, kdiff3, + kompare, meld, opendiff, p4merge, tkdiff, vimdiff and xxdiff. + -If a diff tool is not specified, 'git-difftool' +If a diff tool is not specified, 'git difftool' will use the configuration variable `diff.tool`. If the -configuration variable `diff.tool` is not set, 'git-difftool' +configuration variable `diff.tool` is not set, 'git difftool' will pick a suitable default. + You can explicitly provide a full path to the tool by setting the configuration variable `difftool.<tool>.path`. For example, you can configure the absolute path to kdiff3 by setting -`difftool.kdiff3.path`. Otherwise, 'git-difftool' assumes the +`difftool.kdiff3.path`. Otherwise, 'git difftool' assumes the tool is available in PATH. + Instead of running one of the known diff tools, -'git-difftool' can be customized to run an alternative program +'git difftool' can be customized to run an alternative program by specifying the command line to invoke in a configuration variable `difftool.<tool>.cmd`. + -When 'git-difftool' is invoked with this tool (either through the +When 'git difftool' is invoked with this tool (either through the `-t` or `--tool` option or the `diff.tool` configuration variable) the configured command line will be invoked with the following variables available: `$LOCAL` is set to the name of the temporary file containing the contents of the diff pre-image and `$REMOTE` is set to the name of the temporary file containing the contents -of the diff post-image. `$BASE` is provided for compatibility -with custom merge tool commands and has the same value as `$LOCAL`. +of the diff post-image. `$MERGED` is the name of the file which is +being compared. `$BASE` is provided for compatibility +with custom merge tool commands and has the same value as `$MERGED`. + +-x <command>:: +--extcmd=<command>:: + Specify a custom command for viewing diffs. + 'git-difftool' ignores the configured defaults and runs + `$command $LOCAL $REMOTE` when this option is specified. + Additionally, `$BASE` is set in the environment. + +-g:: +--gui:: + When 'git-difftool' is invoked with the `-g` or `--gui` option + the default diff tool will be read from the configured + `diff.guitool` variable instead of `diff.tool`. See linkgit:git-diff[1] for the full list of supported options. CONFIG VARIABLES ---------------- -'git-difftool' falls back to 'git-mergetool' config variables when the +'git difftool' falls back to 'git mergetool' config variables when the difftool equivalents have not been defined. diff.tool:: The default diff tool to use. +diff.guitool:: + The default diff tool to use when `--gui` is specified. + difftool.<tool>.path:: Override the path for the given tool. This is useful in case your tool is not in the PATH. @@ -91,15 +110,6 @@ linkgit:git-mergetool[1]:: linkgit:git-config[1]:: Get and set repository or global options - -AUTHOR ------- -Written by David Aguilar <davvid@gmail.com>. - -Documentation --------------- -Documentation by David Aguilar and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 75b06f33e7..f37eada63a 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -8,23 +8,24 @@ git-fast-export - Git data exporter SYNOPSIS -------- +[verse] 'git fast-export [options]' | 'git fast-import' DESCRIPTION ----------- This program dumps the given revisions in a form suitable to be piped -into 'git-fast-import'. +into 'git fast-import'. You can use it as a human-readable bundle replacement (see linkgit:git-bundle[1]), or as a kind of an interactive -'git-filter-branch'. +'git filter-branch'. OPTIONS ------- --progress=<n>:: Insert 'progress' statements every <n> objects, to be shown by - 'git-fast-import' during import. + 'git fast-import' during import. --signed-tags=(verbatim|warn|strip|abort):: Specify how to handle signed tags. Since any transformation @@ -37,7 +38,7 @@ unsigned, with 'verbatim', they will be silently exported and with 'warn', they will be exported, but you will see a warning. --tag-of-filtered-object=(abort|drop|rewrite):: - Specify how to handle tags whose tagged objectis filtered out. + Specify how to handle tags whose tagged object is filtered out. Since revisions and files to export can be limited by path, tagged objects may be filtered completely. + @@ -82,6 +83,10 @@ marks the same across runs. allow that. So fake a tagger to be able to fast-import the output. +--use-done-feature:: + Start the stream with a 'feature done' stanza, and terminate + it with a 'done' command. + --no-data:: Skip output of blob objects and instead refer to blobs via their original SHA-1 hash. This is useful when rewriting the @@ -90,10 +95,16 @@ marks the same across runs. resulting stream can only be used by a repository which already contains the necessary objects. -[git-rev-list-args...]:: - A list of arguments, acceptable to 'git-rev-parse' and - 'git-rev-list', that specifies the specific objects and references - to export. For example, `master\~10..master` causes the +--full-tree:: + This option will cause fast-export to issue a "deleteall" + directive for each commit followed by a full list of all files + in the commit (as opposed to just listing the files which are + different from the commit's first parent). + +[<git-rev-list-args>...]:: + A list of arguments, acceptable to 'git rev-parse' and + 'git rev-list', that specifies the specific objects and references + to export. For example, `master{tilde}10..master` causes the current master reference to be exported along with all objects added since its 10th ancestor commit. @@ -125,19 +136,10 @@ referenced by that revision range contains the string Limitations ----------- -Since 'git-fast-import' cannot tag trees, you will not be +Since 'git fast-import' cannot tag trees, you will not be able to export the linux-2.6.git repository completely, as it contains a tag referencing a tree instead of a commit. - -Author ------- -Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>. - -Documentation --------------- -Documentation by Johannes E. Schindelin <johannes.schindelin@gmx.de>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index ae87f09227..ec6ef31197 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -8,6 +8,7 @@ git-fast-import - Backend for fast Git data importers SYNOPSIS -------- +[verse] frontend | 'git fast-import' [options] DESCRIPTION @@ -15,7 +16,7 @@ DESCRIPTION This program is usually not what the end user wants to run directly. Most end users want to use one of the existing frontend programs, which parses a specific type of foreign source and feeds the contents -stored there to 'git-fast-import'. +stored there to 'git fast-import'. fast-import reads a mixed command/data stream from standard input and writes one or more packfiles directly into the current repository. @@ -24,7 +25,7 @@ updated branch and tag refs, fully updating the current repository with the newly imported data. The fast-import backend itself can import into an empty repository (one that -has already been initialized by 'git-init') or incrementally +has already been initialized by 'git init') or incrementally update an existing populated repository. Whether or not incremental imports are supported from a particular foreign source depends on the frontend program in use. @@ -44,11 +45,14 @@ OPTIONS not contain the old commit). --max-pack-size=<n>:: - Maximum size of each output packfile, expressed in MiB. - The default is 4096 (4 GiB) as that is the maximum allowed - packfile size (due to file format limitations). Some - importers may wish to lower this, such as to ensure the - resulting packfiles fit on CDs. + Maximum size of each output packfile. + The default is unlimited. + +--big-file-threshold=<n>:: + Maximum size of a blob that fast-import will attempt to + create a delta for, expressed in bytes. The default is 512m + (512 MiB). Some importers may wish to lower this on systems + with constrained memory. --depth=<n>:: Maximum delta depth, for blob and tree deltification. @@ -75,8 +79,12 @@ OPTIONS set of marks. If a mark is defined to different values, the last file wins. +--import-marks-if-exists=<file>:: + Like --import-marks but instead of erroring out, silently + skips the file if it does not exist. + --relative-marks:: - After specifying --relative-marks= the paths specified + After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. In git-fast-import this means that the paths are relative @@ -86,9 +94,20 @@ OPTIONS --no-relative-marks:: Negates a previous --relative-marks. Allows for combining relative and non-relative marks by interweaving - --(no-)-relative-marks= with the --(import|export)-marks= + --(no-)-relative-marks with the --(import|export)-marks= options. +--cat-blob-fd=<fd>:: + Specify the file descriptor that will be written to + when the `cat-blob` command is encountered in the stream. + The default behaviour is to write to `stdout`. + +--done:: + Require a `done` command at the end of the stream. + This option might be useful for detecting errors that + cause the frontend to terminate before it has started to + write a stream. + --export-pack-edges=<file>:: After creating a packfile, print a line of data to <file> listing the filename of the packfile and the last @@ -96,7 +115,7 @@ OPTIONS This information may be useful after importing projects whose total object set exceeds the 4 GiB packfile limit, as these commits can be used as edge points during calls - to 'git-pack-objects'. + to 'git pack-objects'. --quiet:: Disable all non-fatal output, making fast-import silent when it @@ -138,9 +157,9 @@ an ideal situation, given that most conversion tools are throw-away Parallel Operation ------------------ -Like 'git-push' or 'git-fetch', imports handled by fast-import are safe to +Like 'git push' or 'git fetch', imports handled by fast-import are safe to run alongside parallel `git repack -a -d` or `git gc` invocations, -or any other Git operation (including 'git-prune', as loose objects +or any other Git operation (including 'git prune', as loose objects are never used by fast-import). fast-import does not lock the branch or tag refs it is actively importing. @@ -152,7 +171,7 @@ fast-forward update, fast-import will skip updating that ref and instead prints a warning message. fast-import will always attempt to update all branch refs, and does not stop on the first failure. -Branch updates can be forced with \--force, but its recommended that +Branch updates can be forced with \--force, but it's recommended that this only be used on an otherwise quiet repository. Using \--force is not necessary for an initial import into an empty repository. @@ -184,7 +203,8 @@ especially when a higher level language such as Perl, Python or Ruby is being used. fast-import is very strict about its input. Where we say SP below we mean -*exactly* one space. Likewise LF means one (and only one) linefeed. +*exactly* one space. Likewise LF means one (and only one) linefeed +and HT one (and only one) horizontal tab. Supplying additional whitespace characters will cause unexpected results, such as branch names or file names with leading or trailing spaces in their name, or early termination of fast-import when it encounters @@ -234,7 +254,7 @@ variation in formatting will cause fast-import to reject the value. + An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git parser is accurate, but a little on the lenient side. It is the -same parser used by 'git-am' when applying patches +same parser used by 'git am' when applying patches received from email. + Some malformed strings may be accepted as valid dates. In some of @@ -267,10 +287,10 @@ is always copied into the identity string at the time it is being created by fast-import. There is no way to specify a different time or timezone. + -This particular format is supplied as its short to implement and +This particular format is supplied as it's short to implement and may be useful to a process that wants to create a new commit right now, without needing to use a working directory or -'git-update-index'. +'git update-index'. + If separate `author` and `committer` commands are used in a `commit` the timestamps may not match, as the system clock will be polled @@ -317,6 +337,21 @@ and control the current import process. More detailed discussion standard output. This command is optional and is not needed to perform an import. +`done`:: + Marks the end of the stream. This command is optional + unless the `done` feature was requested using the + `--done` command line option or `feature done` command. + +`cat-blob`:: + Causes fast-import to print a blob in 'cat-file --batch' + format to the file descriptor set with `--cat-blob-fd` or + `stdout` if unspecified. + +`ls`:: + Causes fast-import to print a line describing a directory + entry in 'ls-tree' format to the file descriptor set with + `--cat-blob-fd` or `stdout` if unspecified. + `feature`:: Require that fast-import supports the specified feature, or abort if it does not. @@ -390,8 +425,8 @@ Here `<name>` is the person's display name (for example (``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) and greater-than (\x3e) symbols. These are required to delimit the email address from the other fields in the line. Note that -`<name>` is free-form and may contain any sequence of bytes, except -`LT` and `LF`. It is typically UTF-8 encoded. +`<name>` and `<email>` are free-form and may contain any sequence +of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded. The time of the change is specified by `<when>` using the date format that was selected by the \--date-format=<fmt> command line option. @@ -420,7 +455,7 @@ quoting or escaping syntax is supported within `<committish>`. Here `<committish>` is any of the following: * The name of an existing branch already in fast-import's internal branch - table. If fast-import doesn't know the name, its treated as a SHA-1 + table. If fast-import doesn't know the name, it's treated as a SHA-1 expression. * A mark reference, `:<idnum>`, where `<idnum>` is the mark number. @@ -436,7 +471,7 @@ Marks must be declared (via `mark`) before they can be used. * A complete 40 byte or abbreviated commit SHA-1 in hex. * Any valid Git SHA-1 expression that resolves to a commit. See - ``SPECIFYING REVISIONS'' in linkgit:git-rev-parse[1] for details. + ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[7] for details. The special case of restarting an incremental import from the current branch value should be written as: @@ -479,9 +514,11 @@ External data format:: 'M' SP <mode> SP <dataref> SP <path> LF .... + -Here `<dataref>` can be either a mark reference (`:<idnum>`) +Here usually `<dataref>` must be either a mark reference (`:<idnum>`) set by a prior `blob` command, or a full 40-byte SHA-1 of an -existing Git blob object. +existing Git blob object. If `<mode>` is `040000`` then +`<dataref>` must be the full 40-byte SHA-1 of an existing +Git tree object or a mark reference set with `--import-marks`. Inline data format:: The data content for the file has not been supplied yet. @@ -506,6 +543,8 @@ in octal. Git only supports the following modes: * `160000`: A gitlink, SHA-1 of the object refers to a commit in another repository. Git links can only be specified by SHA or through a commit mark. They are used to implement submodules. +* `040000`: A subdirectory. Subdirectories can only be specified by + SHA or through a tree mark set with `--import-marks`. In both formats `<path>` is the complete path of the file to be added (if not already existing) or modified (if already existing). @@ -525,6 +564,8 @@ The value of `<path>` must be in canonical form. That is it must not: * contain the special component `.` or `..` (e.g. `foo/./bar` and `foo/../bar` are invalid). +The root of the tree can be represented by an empty string as `<path>`. + It is recommended that `<path>` always be encoded using UTF-8. `filedelete` @@ -619,9 +660,14 @@ paths for a commit are encouraged to do so. `notemodify` ^^^^^^^^^^^^ -Included in a `commit` command to add a new note (annotating a given -commit) or change the content of an existing note. This command has -two different means of specifying the content of the note. +Included in a `commit` `<notes_ref>` command to add a new note +annotating a `<committish>` or change this annotation contents. +Internally it is similar to filemodify 100644 on `<committish>` +path (maybe split into subdirectories). It's not advised to +use any other commands to write to the `<notes_ref>` tree except +`filedeleteall` to delete all existing notes in this tree. +This command has two different means of specifying the content +of the note. External data format:: The data content for the note was already supplied by a prior @@ -713,7 +759,7 @@ recommended, as the frontend does not (easily) have access to the complete set of bytes which normally goes into such a signature. If signing is required, create lightweight tags from within fast-import with `reset`, then create the annotated versions of those tags offline -with the standard 'git-tag' process. +with the standard 'git tag' process. `reset` ~~~~~~~ @@ -759,7 +805,7 @@ assigned mark. The mark command is optional here as some frontends have chosen to generate the Git SHA-1 for the blob on their own, and feed that -directly to `commit`. This is typically more work than its worth +directly to `commit`. This is typically more work than it's worth however, as marks are inexpensive to store and easy to use. `data` @@ -869,34 +915,132 @@ Placing a `progress` command immediately after a `checkpoint` will inform the reader when the `checkpoint` has been completed and it can safely access the refs that fast-import updated. -`feature` -~~~~~~~~~ -Require that fast-import supports the specified feature, or abort if -it does not. +`cat-blob` +~~~~~~~~~~ +Causes fast-import to print a blob to a file descriptor previously +arranged with the `--cat-blob-fd` argument. The command otherwise +has no impact on the current import; its main purpose is to +retrieve blobs that may be in fast-import's memory but not +accessible from the target repository. .... - 'feature' SP <feature> LF + 'cat-blob' SP <dataref> LF .... -The <feature> part of the command may be any string matching -^[a-zA-Z][a-zA-Z-]*$ and should be understood by fast-import. +The `<dataref>` can be either a mark reference (`:<idnum>`) +set previously or a full 40-byte SHA-1 of a Git blob, preexisting or +ready to be written. -Feature work identical as their option counterparts with the -exception of the import-marks feature, see below. +Output uses the same format as `git cat-file --batch`: -The following features are currently supported: +==== + <sha1> SP 'blob' SP <size> LF + <contents> LF +==== -* date-format -* import-marks -* export-marks -* relative-marks -* no-relative-marks -* force +This command can be used anywhere in the stream that comments are +accepted. In particular, the `cat-blob` command can be used in the +middle of a commit but not in the middle of a `data` command. + +`ls` +~~~~ +Prints information about the object at a path to a file descriptor +previously arranged with the `--cat-blob-fd` argument. This allows +printing a blob from the active commit (with `cat-blob`) or copying a +blob or tree from a previous commit for use in the current one (with +`filemodify`). + +The `ls` command can be used anywhere in the stream that comments are +accepted, including the middle of a commit. + +Reading from the active commit:: + This form can only be used in the middle of a `commit`. + The path names a directory entry within fast-import's + active commit. The path must be quoted in this case. ++ +.... + 'ls' SP <path> LF +.... -The import-marks behaves differently from when it is specified as -commandline option in that only one "feature import-marks" is allowed -per stream. Also, any --import-marks= specified on the commandline -will override those from the stream (if any). +Reading from a named tree:: + The `<dataref>` can be a mark reference (`:<idnum>`) or the + full 40-byte SHA-1 of a Git tag, commit, or tree object, + preexisting or waiting to be written. + The path is relative to the top level of the tree + named by `<dataref>`. ++ +.... + 'ls' SP <dataref> SP <path> LF +.... + +See `filemodify` above for a detailed description of `<path>`. + +Output uses the same format as `git ls-tree <tree> {litdd} <path>`: + +==== + <mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF +==== + +The <dataref> represents the blob, tree, or commit object at <path> +and can be used in later 'cat-blob', 'filemodify', or 'ls' commands. + +If there is no file or subtree at that path, 'git fast-import' will +instead report + +==== + missing SP <path> LF +==== + +`feature` +~~~~~~~~~ +Require that fast-import supports the specified feature, or abort if +it does not. + +.... + 'feature' SP <feature> ('=' <argument>)? LF +.... + +The <feature> part of the command may be any one of the following: + +date-format:: +export-marks:: +relative-marks:: +no-relative-marks:: +force:: + Act as though the corresponding command-line option with + a leading '--' was passed on the command line + (see OPTIONS, above). + +import-marks:: +import-marks-if-exists:: + Like --import-marks except in two respects: first, only one + "feature import-marks" or "feature import-marks-if-exists" + command is allowed per stream; second, an --import-marks= + or --import-marks-if-exists command-line option overrides + any of these "feature" commands in the stream; third, + "feature import-marks-if-exists" like a corresponding + command-line option silently skips a nonexistent file. + +cat-blob:: +ls:: + Require that the backend support the 'cat-blob' or 'ls' command. + Versions of fast-import not supporting the specified command + will exit with a message indicating so. + This lets the import error out early with a clear message, + rather than wasting time on the early part of an import + before the unsupported command is detected. + +notes:: + Require that the backend support the 'notemodify' (N) + subcommand to the 'commit' command. + Versions of fast-import not supporting notes will exit + with a message indicating so. + +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. `option` ~~~~~~~~ @@ -923,8 +1067,18 @@ not be passed as option: * date-format * import-marks * export-marks +* cat-blob-fd * force +`done` +~~~~~~ +If the `done` feature is not in use, treated as if EOF was read. +This can be used to tell fast-import to finish early. + +If the `--done` command line option or `feature done` command is +in use, the `done` command is mandatory and marks the end of the +stream. + Crash Reports ------------- If fast-import is supplied invalid input it will terminate with a @@ -1070,7 +1224,7 @@ is not `refs/heads/TAG_FIXUP`). When committing fixups, consider using `merge` to connect the commit(s) which are supplying file revisions to the fixup branch. -Doing so will allow tools such as 'git-blame' to track +Doing so will allow tools such as 'git blame' to track through the real commit history and properly annotate the source files. @@ -1099,7 +1253,7 @@ Repacking Historical Data ~~~~~~~~~~~~~~~~~~~~~~~~~ If you are repacking very old imported data (e.g. older than the last year), consider expending some extra CPU time and supplying -\--window=50 (or higher) when you run 'git-repack'. +\--window=50 (or higher) when you run 'git repack'. This will take longer, but will also produce a smaller packfile. You only need to expend the effort once, and everyone using your project will benefit from the smaller repository. @@ -1223,14 +1377,13 @@ and lazy loading of subtrees, allows fast-import to efficiently import projects with 2,000+ branches and 45,114+ files in a very limited memory footprint (less than 2.7 MiB per active branch). - -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by Shawn O. Pearce <spearce@spearce.org>. +Signals +------- +Sending *SIGUSR1* to the 'git fast-import' process ends the current +packfile early, simulating a `checkpoint` command. The impatient +operator can use this facility to peek at the objects and refs from an +import in progress, at the cost of some added running time and worse +compression. GIT --- diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 47448da22e..ed1bdaacd1 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -8,17 +8,18 @@ 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>...] DESCRIPTION ----------- -Usually you would want to use 'git-fetch', which is a +Usually you would want to use 'git fetch', which is a higher level wrapper of this command, instead. Invokes 'git-upload-pack' on a possibly remote repository and asks it to send objects missing from this repository, to update the named heads. The list of commits available locally -is found out by scanning local $GIT_DIR/refs/ and sent to +is found out by scanning the local refs/ hierarchy and sent to 'git-upload-pack' running on the other end. This command degenerates to download everything to complete the @@ -33,19 +34,19 @@ OPTIONS -q:: --quiet:: - Pass '-q' flag to 'git-unpack-objects'; this makes the + Pass '-q' flag to 'git unpack-objects'; this makes the cloning process less verbose. -k:: --keep:: - Do not invoke 'git-unpack-objects' on received data, but + Do not invoke 'git unpack-objects' on received data, but create a single packfile out of it instead, and store it in the object database. If provided twice then the pack is locked against repacking. --thin:: - Spend extra cycles to minimize the number of objects to be sent. - Use it on slower connection. + Fetch a "thin" pack, which records objects in deltified form based + on objects not included in the pack to reduce network traffic. --include-tag:: If the remote side supports it, annotated tags objects will @@ -90,15 +91,6 @@ OPTIONS $GIT_DIR (e.g. "HEAD", "refs/heads/master"). When unspecified, update from all heads the remote side has. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 9b9e5686e4..b41d7c1de1 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -8,13 +8,11 @@ git-fetch - Download objects and refs from another repository SYNOPSIS -------- -'git fetch' <options> <repository> <refspec>... - -'git fetch' <options> <group> - -'git fetch' --multiple <options> [<repository> | <group>]... - -'git fetch' --all <options> +[verse] +'git fetch' [<options>] [<repository> [<refspec>...]] +'git fetch' [<options>] <group> +'git fetch' --multiple [<options>] [(<repository> | <group>)...] +'git fetch' --all [<options>] DESCRIPTION @@ -24,9 +22,9 @@ along with the objects necessary to complete them. The ref names and their object names of fetched refs are stored in `.git/FETCH_HEAD`. This information is left for a later merge -operation done by 'git-merge'. +operation done by 'git merge'. -When <refspec> stores the fetched result in tracking branches, +When <refspec> stores the fetched result in remote-tracking branches, the tags that point at these branches are automatically followed. This is done by first fetching from the remote using the given <refspec>s, and if the repository has objects that are @@ -34,7 +32,7 @@ pointed by remote tags that it does not yet have, then fetch those missing tags. If the other end has tags that point at branches you are not interested in, you will not get them. -'git fetch' can fetch from either a single named repository, or +'git fetch' can fetch from either a single named repository, or from several repositories at once if <group> is given and there is a remotes.<group> entry in the configuration file. (See linkgit:git-config[1]). @@ -76,20 +74,19 @@ The `pu` branch will be updated even if it is does not fast-forward, because it is prefixed with a plus sign; `tmp` will not be. +BUGS +---- +Using --recurse-submodules can only fetch new commits in already checked +out submodules right now. When e.g. upstream added a new submodule in the +just fetched commits of the superproject the submodule itself can not be +fetched, making it impossible to check out that submodule later without +having to do a fetch again. This is expected to be fixed in a future git +version. + SEE ALSO -------- linkgit:git-pull[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com> - -Documentation -------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 394a77a35f..0f2f117383 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,8 +32,9 @@ 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`. If you have any grafts -defined, running this command will make them permanent. +*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +If you have any grafts or replacement refs defined, running this command +will make them permanent. *WARNING*! The rewritten history will have different object names for all the objects and will not converge with the original branch. You will not @@ -81,7 +82,7 @@ OPTIONS This filter may be used if you only need to modify the environment in which the commit will be performed. Specifically, you might want to rewrite the author/committer name/email/time environment - variables (see linkgit:git-commit[1] for details). Do not forget + variables (see linkgit:git-commit-tree[1] for details). Do not forget to re-export the variables. --tree-filter <command>:: @@ -116,8 +117,8 @@ OPTIONS --commit-filter <command>:: This is the filter for performing the commit. If this filter is specified, it will be called instead of the - 'git-commit-tree' command, with arguments of the form - "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on + 'git commit-tree' command, with arguments of the form + "<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]" and the log message on stdin. The commit id is expected on stdout. + As a special extension, the commit filter may emit multiple @@ -127,10 +128,10 @@ have all of them as parents. You can use the 'map' convenience function in this filter, and other convenience functions, too. For example, calling 'skip_commit "$@"' will leave out the current commit (but not its changes! If you want -that, use 'git-rebase' instead). +that, use 'git rebase' instead). + -You can also use the 'git_commit_non_empty_tree "$@"' instead of -'git commit-tree "$@"' if you don't wish to keep commits with a single parent +You can also use the `git_commit_non_empty_tree "$@"` instead of +`git commit-tree "$@"` if you don't wish to keep commits with a single parent and that makes no change to the tree. --tag-name-filter <command>:: @@ -159,18 +160,7 @@ to other tags will be rewritten to point to the underlying commit. --subdirectory-filter <directory>:: Only look at the history which touches the given subdirectory. The result will contain that directory (and only that) as its - project root. Implies --remap-to-ancestor. - ---remap-to-ancestor:: - Rewrite refs to the nearest rewritten ancestor instead of - ignoring them. -+ -Normally, positive refs on the command line are only changed if the -commit they point to was rewritten. However, you can limit the extent -of this rewriting by using linkgit:rev-list[1] arguments, e.g., path -limiters. Refs pointing to such excluded commits would then normally -be ignored. With this option, they are instead rewritten to point at -the nearest ancestor that was not excluded. + project root. Implies <<Remap_to_ancestor>>. --prune-empty:: Some kind of filters will generate empty commits, that left the tree @@ -179,7 +169,7 @@ the nearest ancestor that was not excluded. and only one parent, it will hence keep merges points. Also, this option is not compatible with the use of '--commit-filter'. Though you just need to use the function 'git_commit_non_empty_tree "$@"' instead - of the 'git commit-tree "$@"' idiom in your commit filter to make that + of the `git commit-tree "$@"` idiom in your commit filter to make that happen. --original <namespace>:: @@ -196,15 +186,26 @@ the nearest ancestor that was not excluded. -f:: --force:: - 'git-filter-branch' refuses to start with an existing temporary + 'git filter-branch' refuses to start with an existing temporary directory or when there are already refs starting with 'refs/original/', unless forced. <rev-list options>...:: - Arguments for 'git-rev-list'. All positive refs included by + Arguments for 'git rev-list'. All positive refs included by these options are rewritten. You may also specify options such as '--all', but you must use '--' to separate them from - the 'git-filter-branch' options. + the 'git filter-branch' options. Implies <<Remap_to_ancestor>>. + + +[[Remap_to_ancestor]] +Remap to ancestor +~~~~~~~~~~~~~~~~~ + +By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the +set of revisions which get rewritten. However, positive refs on the command +line are distinguished: we don't let them be excluded by such limiters. For +this purpose, they are instead rewritten to point at the nearest ancestor that +was not excluded. Examples @@ -221,7 +222,7 @@ However, if the file is absent from the tree of some commit, a simple `rm filename` will fail for that tree and commit. Thus you may instead want to use `rm -f filename` as the script. -Using `\--index-filter` with 'git-rm' yields a significantly faster +Using `\--index-filter` with 'git rm' yields a significantly faster version. Like with using `rm filename`, `git rm --cached filename` will fail if the file is absent from the tree of a commit. If you want to "completely forget" a file, it does not matter when it entered @@ -303,7 +304,7 @@ and all children of the merge will become merge commits with P1,P2 as their parents instead of the merge commit. You can rewrite the commit log messages using `--msg-filter`. For -example, 'git-svn-id' strings in a repository created by 'git-svn' can +example, 'git svn-id' strings in a repository created by 'git svn' can be removed this way: ------------------------------------------------------- @@ -314,7 +315,7 @@ 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 +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 @@ -330,7 +331,7 @@ git filter-branch --msg-filter ' *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'. +interactive mode of 'git rebase'. Consider this history: @@ -358,10 +359,10 @@ To move the whole tree into a subdirectory, or remove it from there: --------------------------------------------------------------- git filter-branch --index-filter \ - 'git ls-files -s | sed "s-\t-&newsubdir/-" | + 'git ls-files -s | sed "s-\t\"*-&newsubdir/-" | GIT_INDEX_FILE=$GIT_INDEX_FILE.new \ git update-index --index-info && - mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD + mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD --------------------------------------------------------------- @@ -405,16 +406,6 @@ warned. (or if your git-gc is not new enough to support arguments to `\--prune`, use `git repack -ad; git prune` instead). - -Author ------- -Written by Petr "Pasky" Baudis <pasky@suse.cz>, -and the git list <git@vger.kernel.org> - -Documentation --------------- -Documentation by Petr Baudis and the git list. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index a586950b48..32aff954a2 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,14 +9,14 @@ git-fmt-merge-msg - Produce a merge commit message SYNOPSIS -------- [verse] -'git fmt-merge-msg' [--log | --no-log] <$GIT_DIR/FETCH_HEAD -'git fmt-merge-msg' [--log | --no-log] -F <file> +'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] <$GIT_DIR/FETCH_HEAD +'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -F <file> DESCRIPTION ----------- Takes the list of merged objects on stdin and produces a suitable commit message to be used for the merge commit, usually to be -passed as the '<merge-message>' argument of 'git-merge'. +passed as the '<merge-message>' argument of 'git merge'. This command is intended mostly for internal use by scripts automatically invoking 'git merge'. @@ -24,10 +24,12 @@ automatically invoking 'git merge'. OPTIONS ------- ---log:: +--log[=<n>]:: In addition to branch names, populate the log message with one-line descriptions from the actual commits that are being - merged. + merged. At most <n> commits from each merge parent will be + used (20 if <n> is omitted). This overrides the `merge.log` + configuration variable. --no-log:: Do not list one-line descriptions from the actual commits being @@ -38,6 +40,11 @@ OPTIONS Synonyms to --log and --no-log; these are deprecated and will be removed in the future. +-m <message>:: +--message <message>:: + Use <message> instead of the branch names for the first line + of the log message. For use with `--log`. + -F <file>:: --file <file>:: Take the list of merged objects from <file> instead of @@ -47,8 +54,10 @@ CONFIGURATION ------------- merge.log:: - Whether to include summaries of merged commits in newly - merge commit messages. False by default. + In addition to branch names, populate the log message with at + most the specified number of one-line descriptions from the + actual commits that are being merged. Defaults to false, and + true is a synonym for 20. merge.summary:: Synonym to `merge.log`; this is deprecated and will be removed in @@ -58,15 +67,6 @@ SEE ALSO -------- linkgit:git-merge[1] - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 8dc873fd44..c872b883ba 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] - [--sort=<key>]\* [--format=<format>] [<pattern>...] + [(--sort=<key>)...] [--format=<format>] [<pattern>...] DESCRIPTION ----------- @@ -82,10 +82,11 @@ objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). objectsize:: - The size of the object (the same as 'git-cat-file -s' reports). + The size of the object (the same as 'git cat-file -s' reports). objectname:: The object name (aka SHA-1). + For a non-ambiguous abbreviation of the object name append `:short`. upstream:: The name of a local ref which can be considered ``upstream'' @@ -100,9 +101,10 @@ Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. -The first line of the message in a commit and tag object is -`subject`, the remaining lines are `body`. The whole message -is `contents`. +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`. For sorting purposes, fields with numeric values sort in numeric order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). @@ -122,7 +124,7 @@ EXAMPLES -------- An example directly producing formatted text. Show the most recent -3 tagged commits:: +3 tagged commits: ------------ #!/bin/sh @@ -139,7 +141,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads:: +demonstrating the use of --shell. List the prefixes of all heads: ------------ #!/bin/sh @@ -153,7 +155,7 @@ done A bit more elaborate report on tags, demonstrating that the format -may be an entire script:: +may be an entire script: ------------ #!/bin/sh @@ -203,3 +205,15 @@ eval=`git for-each-ref --shell --format="$fmt" \ refs/tags` eval "$eval" ------------ + +Author +------ +Written by Junio C Hamano <gitster@pobox.com>. + +Documentation +------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index f1fd0df08a..6ea9be775c 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -13,13 +13,14 @@ SYNOPSIS [--no-thread | --thread[=<style>]] [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] + [--signature=<signature> | --no-signature] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] - [--cc=<email>] - [--cover-letter] + [--to=<email>] [--cc=<email>] + [--cover-letter] [--quiet] [<common diff options>] [ <since> | <revision range> ] @@ -29,7 +30,7 @@ DESCRIPTION Prepare each commit with its patch in one file per commit, formatted to resemble UNIX mailbox format. The output of this command is convenient for e-mail submission or -for use with 'git-am'. +for use with 'git am'. There are two ways to specify which commits to operate on. @@ -38,7 +39,7 @@ There are two ways to specify which commits to operate on. that leads to the <since> to be output. 2. Generic <revision range> expression (see "SPECIFYING - REVISIONS" section in linkgit:git-rev-parse[1]) means the + REVISIONS" section in linkgit:gitrevisions[7]) means the commits in the specified range. The first rule takes precedence in the case of a single <commit>. To @@ -73,7 +74,7 @@ OPTIONS include::diff-options.txt[] -<n>:: - Limits the number of patches to prepare. + Prepare patches from the topmost <n> commits. -o <dir>:: --output-directory <dir>:: @@ -162,20 +163,37 @@ will want to ensure that threading is disabled for `git send-email`. allows for useful naming of a patch series, and can be combined with the `--numbered` option. +--to=<email>:: + Add a `To:` header to the email headers. This is in addition + to any configured headers, and may be used multiple times. + The negated form `--no-to` discards all `To:` headers added so + far (from config or command line). + --cc=<email>:: Add a `Cc:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. + The negated form `--no-cc` discards all `Cc:` headers added so + far (from config or command line). --add-header=<header>:: Add an arbitrary header to the email headers. This is in addition to any configured headers, and may be used multiple times. - For example, `--add-header="Organization: git-foo"` + For example, `--add-header="Organization: git-foo"`. + The negated form `--no-add-header` discards *all* (`To:`, + `Cc:`, and custom) headers added so far from config or command + line. --cover-letter:: In addition to the patches, generate a cover letter file containing the shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--[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 + signature option is omitted the signature defaults to the git version + number. + --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is @@ -185,6 +203,9 @@ will want to ensure that threading is disabled for `git send-email`. Note that the leading character does not have to be a dot; for example, you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. +--quiet:: + Do not print the names of the generated files to standard output. + --no-binary:: Do not output contents of changes in binary files, instead display a notice that those files changed. Patches generated @@ -202,8 +223,8 @@ CONFIGURATION ------------- You can specify extra mail header lines to be added to each message, defaults for the subject prefix and file suffix, number patches when -outputting more than one patch, add "Cc:" headers, configure attachments, -and sign off patches with configuration variables. +outputting more than one patch, add "To" or "Cc:" headers, configure +attachments, and sign off patches with configuration variables. ------------ [format] @@ -211,17 +232,245 @@ and sign off patches with configuration variables. subjectprefix = CHANGE suffix = .txt numbered = auto + to = <email> cc = <email> attach [ = mime-boundary-string ] signoff = true ------------ +DISCUSSION +---------- + +The patch produced by 'git format-patch' is in UNIX mailbox format, +with a fixed "magic" time stamp to indicate that the file is output +from format-patch rather than a real mailbox, like so: + +------------ +From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001 +From: Tony Luck <tony.luck@intel.com> +Date: Tue, 13 Jul 2010 11:42:54 -0700 +Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?= + =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?= +MIME-Version: 1.0 +Content-Type: text/plain; charset=UTF-8 +Content-Transfer-Encoding: 8bit + +arch/arm config files were slimmed down using a python script +(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment) + +Do the same for ia64 so we can have sleek & trim looking +... +------------ + +Typically it will be placed in a MUA's drafts folder, edited to add +timely commentary that should not go in the changelog after the three +dashes, and then sent as a message whose body, in our example, starts +with "arch/arm config files were...". On the receiving end, readers +can save interesting patches in a UNIX mailbox and apply them with +linkgit:git-am[1]. + +When a patch is part of an ongoing discussion, the patch generated by +'git format-patch' can be tweaked to take advantage of the 'git am +--scissors' feature. After your response to the discussion comes a +line that consists solely of "`-- >8 --`" (scissors and perforation), +followed by the patch with unnecessary header fields removed: + +------------ +... +> So we should do such-and-such. + +Makes sense to me. How about this patch? + +-- >8 -- +Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet + +arch/arm config files were slimmed down using a python script +... +------------ + +When sending a patch this way, most often you are sending your own +patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you +should omit `From:` and `Date:` lines from the patch file. The patch +title is likely to be different from the subject of the discussion the +patch is in response to, so it is likely that you would want to keep +the Subject: line, like the example above. + +Checking for patch corruption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Many mailers if not set up properly will corrupt whitespace. Here are +two common types of corruption: + +* Empty context lines that do not have _any_ whitespace. + +* Non-empty context lines that have one extra whitespace at the + beginning. + +One way to test if your MUA is set up correctly is: + +* Send the patch to yourself, exactly the way you would, except + with To: and Cc: lines that do not contain the list and + maintainer address. + +* Save that patch to a file in UNIX mailbox format. Call it a.patch, + say. + +* Apply it: + + $ git fetch <project> master:test-apply + $ git checkout test-apply + $ git reset --hard + $ git am a.patch + +If it does not apply correctly, there can be various reasons. + +* The patch itself does not apply cleanly. That is _bad_ but + does not have much to do with your MUA. You might want to rebase + the patch with linkgit:git-rebase[1] before regenerating it in + this case. + +* The MUA corrupted your patch; "am" would complain that + the patch does not apply. Look in the .git/rebase-apply/ subdirectory and + see what 'patch' file contains and check for the common + corruption patterns mentioned above. + +* While at it, check the 'info' and 'final-commit' files as well. + If what is in 'final-commit' is not exactly what you would want to + see in the commit log message, it is very likely that the + receiver would end up hand editing the log message when applying + your patch. Things like "Hi, this is my first patch.\n" in the + patch e-mail should come after the three-dash line that signals + the end of the commit message. + +MUA-SPECIFIC HINTS +------------------ +Here are some hints on how to successfully submit patches inline using +various mailers. + +GMail +~~~~~ +GMail does not have any way to turn off line wrapping in the web +interface, so it will mangle any emails that you send. You can however +use "git send-email" and send your patches through the GMail SMTP server, or +use any IMAP email client to connect to the google IMAP server and forward +the emails through that. + +For hints on using 'git send-email' to send your patches through the +GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1]. + +For hints on submission using the IMAP interface, see the EXAMPLE +section of linkgit:git-imap-send[1]. + +Thunderbird +~~~~~~~~~~~ +By default, Thunderbird will both wrap emails as well as flag +them as being 'format=flowed', both of which will make the +resulting email unusable by git. + +There are three different approaches: use an add-on to turn off line wraps, +configure Thunderbird to not mangle patches, or use +an external editor to keep Thunderbird from mangling the patches. + +Approach #1 (add-on) +^^^^^^^^^^^^^^^^^^^^ + +Install the Toggle Word Wrap add-on that is available from +https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ +It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu +that you can tick off. Now you can compose the message as you otherwise do +(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to +insert line breaks manually in any text that you type. + +Approach #2 (configuration) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Three steps: + +1. Configure your mail server composition as plain text: + Edit...Account Settings...Composition & Addressing, + uncheck "Compose Messages in HTML". + +2. Configure your general composition window to not wrap. ++ +In Thunderbird 2: +Edit..Preferences..Composition, wrap plain text messages at 0 ++ +In Thunderbird 3: +Edit..Preferences..Advanced..Config Editor. Search for +"mail.wrap_long_lines". +Toggle it to make sure it is set to `false`. + +3. Disable the use of format=flowed: +Edit..Preferences..Advanced..Config Editor. Search for +"mailnews.send_plaintext_flowed". +Toggle it to make sure it is set to `false`. + +After that is done, you should be able to compose email as you +otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc), +and the patches will not be mangled. + +Approach #3 (external editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following Thunderbird extensions are needed: +AboutConfig from http://aboutconfig.mozdev.org/ and +External Editor from http://globs.org/articles.php?lng=en&pg=8 + +1. Prepare the patch as a text file using your method of choice. + +2. Before opening a compose window, use Edit->Account Settings to + uncheck the "Compose messages in HTML format" setting in the + "Composition & Addressing" panel of the account to be used to + send the patch. + +3. In the main Thunderbird window, 'before' you open the compose + window for the patch, use Tools->about:config to set the + following to the indicated values: ++ +---------- + mailnews.send_plaintext_flowed => false + mailnews.wraplength => 0 +---------- + +4. Open a compose window and click the external editor icon. + +5. In the external editor window, read in the patch file and exit + the editor normally. + +Side note: it may be possible to do step 2 with +about:config and the following settings but no one's tried yet. + +---------- + mail.html_compose => false + mail.identity.default.compose_html => false + mail.identity.id?.compose_html => false +---------- + +There is a script in contrib/thunderbird-patch-inline which can help +you include patches with Thunderbird in an easy way. To use it, do the +steps above and then use the script as the external editor. + +KMail +~~~~~ +This should help you to submit patches inline using KMail. + +1. Prepare the patch as a text file. + +2. Click on New Mail. + +3. Go under "Options" in the Composer window and be sure that + "Word wrap" is not set. + +4. Use Message -> Insert file... and insert the patch. + +5. Back in the compose window: add whatever other text you wish to the + message, complete the addressing and subject fields, and press send. + + EXAMPLES -------- * Extract commits between revisions R1 and R2, and apply them on top of -the current branch using 'git-am' to cherry-pick them: +the current branch using 'git am' to cherry-pick them: + ------------ $ git format-patch -k --stdout R1..R2 | git am -3 -k @@ -266,15 +515,6 @@ SEE ALSO -------- linkgit:git-am[1], linkgit:git-send-email[1] - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt index 965a8279c1..eec4bdb600 100644 --- a/Documentation/git-fsck-objects.txt +++ b/Documentation/git-fsck-objects.txt @@ -8,6 +8,7 @@ git-fsck-objects - Verifies the connectivity and validity of the objects in the SYNOPSIS -------- +[verse] 'git fsck-objects' ... DESCRIPTION @@ -15,3 +16,7 @@ DESCRIPTION This is a synonym for linkgit:git-fsck[1]. Please refer to the documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 6fe9484da3..a2a508dc28 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -21,12 +21,12 @@ OPTIONS <object>:: An object to treat as the head of an unreachability trace. + -If no objects are given, 'git-fsck' defaults to using the +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. --unreachable:: - Print out objects that exist but that aren't readable from any + Print out objects that exist but that aren't reachable from any of the reference nodes. --root:: @@ -76,7 +76,7 @@ It tests SHA1 and general object sanity, and it does full tracking of the resulting reachability and everything else. It prints out any corruption it finds (missing or bad objects), and if you use the '--unreachable' flag it will also print out objects that exist but -that aren't readable from any of the specified head nodes. +that aren't reachable from any of the specified head nodes. So for example @@ -85,7 +85,7 @@ So for example will do quite a _lot_ of verification on the tree. There are a few extra validity tests to be added (make sure that tree objects are -sorted properly etc), but on the whole if 'git-fsck' is happy, you +sorted properly etc), but on the whole if 'git fsck' is happy, you do have a valid tree. Any corrupt objects you will have to find in backups or other archives @@ -123,9 +123,6 @@ dangling <type> <object>:: The <type> object <object>, is present in the database but never 'directly' used. A dangling commit could be a root node. -warning: git-fsck: tree <tree> has full pathnames in it:: - And it shouldn't... - sha1 mismatch <object>:: The database has an object who's sha1 doesn't match the database value. @@ -143,14 +140,6 @@ GIT_INDEX_FILE:: GIT_ALTERNATE_OBJECT_DIRECTORIES:: used to specify additional object database roots (usually unset) -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 4cd9cdf905..815afcb922 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -8,6 +8,7 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- +[verse] 'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] DESCRIPTION @@ -15,13 +16,13 @@ DESCRIPTION Runs a number of housekeeping tasks within the current repository, such as compressing file revisions (to reduce disk space and increase performance) and removing unreachable objects which may have been -created from prior invocations of 'git-add'. +created from prior invocations of 'git add'. Users are encouraged to run this task on a regular basis within each repository to maintain good disk space utilization and good operating performance. -Some git commands may automatically run 'git-gc'; see the `--auto` flag +Some git commands may automatically run 'git gc'; see the `--auto` flag below for details. If you know what you're doing and all you want is to disable this behavior permanently without further considerations, just do: @@ -33,15 +34,15 @@ OPTIONS ------- --aggressive:: - Usually 'git-gc' runs very quickly while providing good disk + Usually 'git gc' runs very quickly while providing good disk space utilization and performance. This option will cause - 'git-gc' to more aggressively optimize the repository at the expense + 'git gc' to more aggressively optimize the repository at the expense of taking much more time. The effects of this optimization are persistent, so this option only needs to be used occasionally; every few hundred changesets or so. --auto:: - With this option, 'git-gc' checks whether any housekeeping is + With this option, 'git gc' checks whether any housekeeping is required; if not, it exits without performing any work. Some git commands run `git gc --auto` after performing operations that could create many loose objects. @@ -50,13 +51,13 @@ Housekeeping is required if there are too many loose objects or too many packs in the repository. If the number of loose objects exceeds the value of the `gc.auto` configuration variable, then all loose objects are combined into a single pack using -'git-repack -d -l'. Setting the value of `gc.auto` to 0 +`git repack -d -l`. Setting the value of `gc.auto` to 0 disables automatic packing of loose objects. + If the number of packs exceeds the value of `gc.autopacklimit`, then existing packs (except those marked with a `.keep` file) are consolidated into a single pack by using the `-A` option of -'git-repack'. Setting `gc.autopacklimit` to 0 disables +'git repack'. Setting `gc.autopacklimit` to 0 disables automatic consolidation of packs. --prune=<date>:: @@ -88,6 +89,16 @@ commits prior to the amend or rebase occurring. Since these changes are not part of the current project most users will want to expire them sooner. This option defaults to '30 days'. +The above two configuration variables can be given to a pattern. For +example, this sets non-default expiry values only to remote-tracking +branches: + +------------ +[gc "refs/remotes/*"] + reflogExpire = never + reflogexpireUnreachable = 3 days +------------ + The optional configuration variable 'gc.rerereresolved' indicates how long records of conflicted merge you resolved earlier are kept. This defaults to 60 days. @@ -97,7 +108,7 @@ how long records of conflicted merge you have not resolved are kept. This defaults to 15 days. The optional configuration variable 'gc.packrefs' determines if -'git-gc' runs 'git-pack-refs'. This can be set to "nobare" to enable +'git gc' runs 'git pack-refs'. This can be set to "notbare" to enable it within all non-bare repos or it can be set to a boolean value. This defaults to true. @@ -116,10 +127,10 @@ default is "2 weeks ago". Notes ----- -'git-gc' tries very hard to be safe about the garbage it collects. In +'git gc' tries very hard to be safe about the garbage it collects. In particular, it will keep not only objects referenced by your current set -of branches and tags, but also objects referenced by the index, remote -tracking branches, refs saved by 'git-filter-branch' in +of branches and tags, but also objects referenced by the index, +remote-tracking branches, refs saved by 'git filter-branch' in refs/original/, or reflogs (which may reference commits in branches that were later amended or rewound). @@ -127,6 +138,13 @@ If you are expecting some objects to be collected and they aren't, check all of those locations and decide whether it makes sense in your case to remove those references. +HOOKS +----- + +The 'git gc --auto' command will run the 'pre-auto-gc' hook. See +linkgit:githooks[5] for more information. + + SEE ALSO -------- linkgit:git-prune[1] @@ -134,10 +152,6 @@ linkgit:git-reflog[1] linkgit:git-repack[1] linkgit:git-rerere[1] -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 84f23ee525..1e2a20dd26 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -8,29 +8,21 @@ git-get-tar-commit-id - Extract commit ID from an archive created using git-arch SYNOPSIS -------- +[verse] 'git get-tar-commit-id' < <tarfile> DESCRIPTION ----------- Acts as a filter, extracting the commit ID stored in archives created by -'git-archive'. It reads only the first 1024 bytes of input, thus its +'git archive'. It reads only the first 1024 bytes of input, thus its runtime is not influenced by the size of <tarfile> very much. -If no commit ID is found, 'git-get-tar-commit-id' quietly exists with a +If no commit ID is found, 'git get-tar-commit-id' quietly exists with a return code of 1. This can happen if <tarfile> had not been created -using 'git-archive' or if the first parameter of 'git-archive' had been +using 'git archive' or if the first parameter of 'git archive' had been a tree ID instead of a commit ID or tag. - -Author ------- -Written by Rene Scharfe <rene.scharfe@lsrfire.ath.cx> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 8c700200f5..15d6711d46 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -9,32 +9,60 @@ git-grep - Print lines matching a pattern SYNOPSIS -------- [verse] -'git grep' [--cached] - [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp] +'git grep' [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp] [-v | --invert-match] [-h|-H] [--full-name] [-E | --extended-regexp] [-G | --basic-regexp] - [-F | --fixed-strings] [-n] + [-P | --perl-regexp] + [-F | --fixed-strings] [-n | --line-number] [-l | --files-with-matches] [-L | --files-without-match] + [(-O | --open-files-in-pager) [<pager>]] [-z | --null] - [-c | --count] [--all-match] + [-c | --count] [--all-match] [-q | --quiet] [--max-depth <depth>] - [--color | --no-color] + [--color[=<when>] | --no-color] [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> - [--and|--or|--not|(|)|-e <pattern>...] [<tree>...] - [--] [<path>...] + [--and|--or|--not|(|)|-e <pattern>...] + [ [--exclude-standard] [--cached | --no-index | --untracked] | <tree>...] + [--] [<pathspec>...] DESCRIPTION ----------- -Look for specified patterns in the working tree files, blobs -registered in the index file, or given tree objects. +Look for specified patterns in the tracked files in the work tree, blobs +registered in the index file, or blobs in given tree objects. + + +CONFIGURATION +------------- + +grep.lineNumber:: + If set to true, enable '-n' option by default. + +grep.extendedRegexp:: + If set to true, enable '--extended-regexp' option by default. OPTIONS ------- --cached:: - Instead of searching in the working tree files, check - the blobs registered in the index file. + Instead of searching tracked files in the working tree, search + blobs registered in the index file. + +--no-index:: + Search files in the current directory that is not managed by git. + +--untracked:: + In addition to searching in the tracked files in the working + tree, search also in untracked files. + +--no-exclude-standard:: + Also search in ignored files by not honoring the `.gitignore` + mechanism. Only useful with `--untracked`. + +--exclude-standard:: + Do not pay attention to ignored files specified via the `.gitignore` + mechanism. Only useful when searching files in the current directory + with `--no-index`. -a:: --text:: @@ -49,7 +77,7 @@ OPTIONS Don't match the pattern in binary files. --max-depth <depth>:: - For each pathspec given on command line, descend at most <depth> + For each <pathspec> given on command line, descend at most <depth> levels of directories. A negative value means no limit. -w:: @@ -83,12 +111,18 @@ OPTIONS Use POSIX extended/basic regexp for patterns. Default is to use basic regexp. +-P:: +--perl-regexp:: + Use Perl-compatible regexp for patterns. Requires libpcre to be + compiled in. + -F:: --fixed-strings:: Use fixed strings for patterns (don't interpret pattern as a regex). -n:: +--line-number:: Prefix the line number to matching lines. -l:: @@ -98,8 +132,15 @@ OPTIONS --files-without-match:: Instead of showing every matched line, show only the names of files that contain (or do not contain) matches. - For better compatibility with 'git-diff', --name-only is a - synonym for --files-with-matches. + For better compatibility with 'git diff', `--name-only` is a + synonym for `--files-with-matches`. + +-O [<pager>]:: +--open-files-in-pager [<pager>]:: + Open the matching files in the pager (not the output of 'grep'). + If the pager happens to be "less" or "vi", and the user + specified only one pattern, the first file is positioned at + the first match automatically. -z:: --null:: @@ -111,21 +152,21 @@ OPTIONS Instead of showing every matched line, show the number of lines that match. ---color:: +--color[=<when>]:: Show colored matches. + The value must be always (the default), never, or auto. --no-color:: Turn off match highlighting, even when the configuration file gives the default to color output. + Same as `--color=never`. --[ABC] <context>:: - Show `context` trailing (`A` -- after), or leading (`B` - -- before), or both (`C` -- context) lines, and place a - line containing `--` between contiguous groups of - matches. +--break:: + Print an empty line between matches from different files. --<num>:: - A shortcut for specifying -C<num>. +--heading:: + Show the filename above the matches in that file instead of + at the start of each shown line. -p:: --show-function:: @@ -135,12 +176,35 @@ OPTIONS patch hunk headers (see 'Defining a custom hunk-header' in linkgit:gitattributes[5]). +-<num>:: +-C <num>:: +--context <num>:: + Show <num> leading and trailing lines, and place a line + containing `--` between contiguous groups of matches. + +-A <num>:: +--after-context <num>:: + Show <num> trailing lines, and place a line containing + `--` between contiguous groups of matches. + +-B <num>:: +--before-context <num>:: + Show <num> leading lines, and place a line containing + `--` between contiguous groups of matches. + +-W:: +--function-context:: + Show the surrounding text from the previous line containing a + function name up to the one before the next function name, + effectively showing the whole function in which the match was + found. + -f <file>:: Read patterns from <file>, one per line. -e:: The next parameter is the pattern. This option has to be - used for patterns starting with - and should be used in + used for patterns starting with `-` and should be used in scripts passing user input to grep. Multiple patterns are combined by 'or'. @@ -158,35 +222,38 @@ OPTIONS this flag is specified to limit the match to files that have lines to match all of them. -`<tree>...`:: - Search blobs in the trees for specified patterns. +-q:: +--quiet:: + Do not output matched lines; instead, exit with status 0 when + there is a match and with non-zero status when there isn't. + +<tree>...:: + Instead of searching tracked files in the working tree, search + blobs in the given trees. \--:: Signals the end of options; the rest of the parameters - are <path> limiters. + are <pathspec> limiters. +<pathspec>...:: + If given, limit the search to paths matching at least one pattern. + Both leading paths match and glob(7) patterns are supported. -Example -------- +Examples +-------- + +`git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}`:: + Looks for `time_t` in all tracked .c and .h files in the working + directory and its subdirectories. -git grep -e \'#define\' --and \( -e MAX_PATH -e PATH_MAX \):: +`git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \)`:: Looks for a line that has `#define` and either `MAX_PATH` or `PATH_MAX`. -git grep --all-match -e NODE -e Unexpected:: +`git grep --all-match -e NODE -e Unexpected`:: Looks for a line that has `NODE` or `Unexpected` in files that have lines that match both. -Author ------- -Originally written by Linus Torvalds <torvalds@osdl.org>, later -revamped by Junio C Hamano. - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index d0bc98b852..0041994443 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -7,23 +7,24 @@ git-gui - A portable graphical interface to Git SYNOPSIS -------- +[verse] 'git gui' [<command>] [arguments] DESCRIPTION ----------- -A Tcl/Tk based graphical user interface to Git. 'git-gui' focuses +A Tcl/Tk based graphical user interface to Git. 'git gui' focuses on allowing users to make changes to their repository by making new commits, amending existing ones, creating branches, performing local merges, and fetching/pushing to remote repositories. -Unlike 'gitk', 'git-gui' focuses on commit generation +Unlike 'gitk', 'git gui' focuses on commit generation and single file annotation and does not show project history. It does however supply menu actions to start a 'gitk' session from -within 'git-gui'. +within 'git gui'. -'git-gui' is known to work on all popular UNIX systems, Mac OS X, +'git gui' is known to work on all popular UNIX systems, Mac OS X, and Windows (under both Cygwin and MSYS). To the extent possible -OS specific user interface guidelines are followed, making 'git-gui' +OS specific user interface guidelines are followed, making 'git gui' a fairly native interface for users. COMMANDS @@ -38,18 +39,18 @@ browser:: browser are opened in the blame viewer. citool:: - Start 'git-gui' and arrange to make exactly one commit before + Start 'git gui' and arrange to make exactly one commit before exiting and returning to the shell. The interface is limited to only commit actions, slightly reducing the application's startup time and simplifying the menubar. version:: - Display the currently running version of 'git-gui'. + Display the currently running version of 'git gui'. Examples -------- -git gui blame Makefile:: +`git gui blame Makefile`:: Show the contents of the file 'Makefile' in the current working directory, and provide annotations for both the @@ -58,41 +59,41 @@ git gui blame Makefile:: uncommitted changes (if any) are explicitly attributed to 'Not Yet Committed'. -git gui blame v0.99.8 Makefile:: +`git gui blame v0.99.8 Makefile`:: Show the contents of 'Makefile' in revision 'v0.99.8' and provide annotations for each line. Unlike the above example the file is read from the object database and not the working directory. -git gui blame --line=100 Makefile:: +`git gui blame --line=100 Makefile`:: Loads annotations as described above and automatically scrolls the view to center on line '100'. -git gui citool:: +`git gui citool`:: Make one commit and return to the shell when it is complete. This command returns a non-zero exit code if the window was closed in any way other than by making a commit. -git gui citool --amend:: +`git gui citool --amend`:: Automatically enter the 'Amend Last Commit' mode of the interface. -git gui citool --nocommit:: +`git gui citool --nocommit`:: Behave as normal citool, but instead of making a commit simply terminate with a zero exit code. It still checks that the index does not contain any unmerged entries, so you can use it as a GUI version of linkgit:git-mergetool[1] -git citool:: +`git citool`:: Same as `git gui citool` (above). -git gui browser maint:: +`git gui browser maint`:: Show a browser for the tree of the 'maint' branch. Files selected in the browser can be viewed with the internal @@ -103,15 +104,15 @@ SEE ALSO linkgit:gitk[1]:: The git repository browser. Shows branches, commit history and file differences. gitk is the utility started by - 'git-gui''s Repository Visualize actions. + 'git gui''s Repository Visualize actions. Other ----- -'git-gui' is actually maintained as an independent project, but stable +'git gui' is actually maintained as an independent project, but stable versions are distributed as part of the Git suite for the convenience of end users. -A 'git-gui' development repository can be obtained from: +A 'git gui' development repository can be obtained from: git clone git://repo.or.cz/git-gui.git @@ -121,14 +122,6 @@ or or browsed online at http://repo.or.cz/w/git-gui.git/[]. -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by Shawn O. Pearce <spearce@spearce.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 0af40cfb85..4b0a502e8e 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>... -'git hash-object' [-t <type>] [-w] --stdin-paths < <list-of-paths> +'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] < <list-of-paths> DESCRIPTION ----------- @@ -18,7 +18,7 @@ Computes the object ID value for an object with specified type with the contents of the named file (which can be outside of the work tree), and optionally writes the resulting object into the object database. Reports its object ID to its standard output. -This is used by 'git-cvsimport' to update the index +This is used by 'git cvsimport' to update the index without modifying files in the work tree. When <type> is not specified, it defaults to "blob". @@ -49,18 +49,10 @@ OPTIONS --no-filters:: Hash the contents as is, ignoring any input filter that would - have been chosen by the attributes mechanism, including crlf + have been chosen by the attributes mechanism, including the end-of-line conversion. If the file is read from standard input then this is always implied, unless the --path option is given. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index d9b9c34b3a..9e0b3f6811 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -7,6 +7,7 @@ git-help - display help information about git SYNOPSIS -------- +[verse] 'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND] DESCRIPTION @@ -55,9 +56,9 @@ other display programs (see below). + The web browser can be specified using the configuration variable 'help.browser', or 'web.browser' if the former is not set. If none of -these config variables is set, the 'git-web--browse' helper script -(called by 'git-help') will pick a suitable default. See -linkgit:git-web--browse[1] for more information about this. +these config variables is set, the 'git web{litdd}browse' helper script +(called by 'git help') will pick a suitable default. See +linkgit:git-web{litdd}browse[1] for more information about this. CONFIGURATION VARIABLES ----------------------- @@ -67,7 +68,7 @@ help.format If no command line option is passed, the 'help.format' configuration variable will be checked. The following values are supported for this -variable; they make 'git-help' behave as their corresponding command +variable; they make 'git help' behave as their corresponding command line option: * "man" corresponds to '-m|--man', @@ -80,7 +81,7 @@ help.browser, web.browser and browser.<tool>.path The 'help.browser', 'web.browser' and 'browser.<tool>.path' will also be checked if the 'web' format is chosen (either by command line option or configuration variable). See '-w|--web' in the OPTIONS -section above and linkgit:git-web--browse[1]. +section above and linkgit:git-web{litdd}browse[1]. man.viewer ~~~~~~~~~~ @@ -122,7 +123,7 @@ man.<tool>.path You can explicitly provide a full path to your preferred man viewer by setting the configuration variable 'man.<tool>.path'. For example, you can configure the absolute path to konqueror by setting -'man.konqueror.path'. Otherwise, 'git-help' assumes the tool is +'man.konqueror.path'. Otherwise, 'git help' assumes the tool is available in PATH. man.<tool>.cmd @@ -171,17 +172,6 @@ $ git config --global web.browser firefox as they are probably more user specific than repository specific. See linkgit:git-config[1] for more information about this. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> and the git-list -<git@vger.kernel.org>. - -Documentation -------------- -Initial documentation was part of the linkgit:git[1] man page. -Christian Couder <chriscool@tuxfamily.org> extracted and rewrote it a -little. Maintenance is done by the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index c8fe08a0c4..f4e0741c11 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -8,13 +8,13 @@ git-http-backend - Server side implementation of Git over HTTP SYNOPSIS -------- [verse] -'git-http-backend' +'git http-backend' DESCRIPTION ----------- A simple CGI program to serve the contents of a Git repository to Git clients accessing the repository over http:// and https:// protocols. -The program supports clients fetching using both the smart HTTP protcol +The program supports clients fetching using both the smart HTTP protocol and the backwards-compatible dumb HTTP protocol, as well as clients pushing using the smart HTTP protocol. @@ -24,10 +24,10 @@ that hasn't explicitly been marked for export this way (unless the GIT_HTTP_EXPORT_ALL environmental variable is set). By default, only the `upload-pack` service is enabled, which serves -'git-fetch-pack' and 'git-ls-remote' clients, which are invoked from -'git-fetch', 'git-pull', and 'git-clone'. If the client is authenticated, -the `receive-pack` service is enabled, which serves 'git-send-pack' -clients, which is invoked from 'git-push'. +'git fetch-pack' and 'git ls-remote' clients, which are invoked from +'git fetch', 'git pull', and 'git clone'. If the client is authenticated, +the `receive-pack` service is enabled, which serves 'git send-pack' +clients, which is invoked from 'git push'. SERVICES -------- @@ -35,7 +35,7 @@ These services can be enabled/disabled using the per-repository configuration file: http.getanyfile:: - This serves older Git clients which are unable to use the + This serves Git clients older than version 1.6.6 that are unable to use the upload pack service. When enabled, clients are able to read any file within the repository, including objects that are no longer reachable from a branch but are still present. @@ -43,12 +43,12 @@ http.getanyfile:: by setting this configuration item to `false`. http.uploadpack:: - This serves 'git-fetch-pack' and 'git-ls-remote' clients. + This serves 'git fetch-pack' and 'git ls-remote' clients. It is enabled by default, but a repository can disable it by setting this configuration item to `false`. http.receivepack:: - This serves 'git-send-pack' clients, allowing push. It is + This serves 'git send-pack' clients, allowing push. It is disabled by default for anonymous users, and enabled by default for users authenticated by the web server. It can be disabled by setting this item to `false`, or enabled for all @@ -56,11 +56,11 @@ http.receivepack:: URL TRANSLATION --------------- -To determine the location of the repository on disk, 'git-http-backend' +To determine the location of the repository on disk, 'git http-backend' concatenates the environment variables PATH_INFO, which is set automatically by the web server, and GIT_PROJECT_ROOT, which must be set manually in the web server configuration. If GIT_PROJECT_ROOT is not -set, 'git-http-backend' reads PATH_TRANSLATED, which is also set +set, 'git http-backend' reads PATH_TRANSLATED, which is also set automatically by the web server. EXAMPLES @@ -104,7 +104,7 @@ directive around the repository, or one of its parent directories: ---------------------------------------------------------------- + To serve gitweb at the same url, use a ScriptAliasMatch to only -those URLs that 'git-http-backend' can handle, and forward the +those URLs that 'git http-backend' can handle, and forward the rest to gitweb: + ---------------------------------------------------------------- @@ -119,6 +119,14 @@ ScriptAliasMatch \ ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ ---------------------------------------------------------------- ++ +To serve multiple repositories from different linkgit:gitnamespaces[7] in a +single repository: ++ +---------------------------------------------------------------- +SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1 +ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1 +---------------------------------------------------------------- Accelerated static Apache 2.x:: Similar to the above, but Apache can be used to return static @@ -153,7 +161,7 @@ ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ ENVIRONMENT ----------- -'git-http-backend' relies upon the CGI environment variables set +'git http-backend' relies upon the CGI environment variables set by the invoking web server, including: * PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED) diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index e7c796155f..070cd1e6ed 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -8,12 +8,16 @@ git-http-fetch - Download from a remote git repository via HTTP SYNOPSIS -------- +[verse] 'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url> DESCRIPTION ----------- Downloads a remote git repository via HTTP. +*NOTE*: use of this command without -a is deprecated. The -a +behaviour will become the default in a future release. + OPTIONS ------- commit-id:: @@ -35,7 +39,7 @@ commit-id:: --stdin:: Instead of a commit id on the command line (which is not expected in this - case), 'git-http-fetch' expects lines on stdin in the format + case), 'git http-fetch' expects lines on stdin in the format <commit-id>['\t'<filename-as-in--w>] @@ -43,14 +47,6 @@ commit-id:: Verify that everything reachable from target is fetched. Used after an earlier fetch is interrupted. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index ddf7a18dc4..2e67362bd4 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -8,6 +8,7 @@ git-http-push - Push objects over HTTP/DAV to another repository SYNOPSIS -------- +[verse] 'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] DESCRIPTION @@ -91,15 +92,6 @@ With '--force', the fast-forward check is disabled for all refs. Optionally, a <ref> parameter can be prefixed with a plus '+' sign to disable the fast-forward check only on that ref. - -Author ------- -Written by Nick Hengeveld <nickh@reactrix.com> - -Documentation --------------- -Documentation by Nick Hengeveld - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index d016dafd49..875d2831a5 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -8,15 +8,18 @@ git-imap-send - Send a collection of patches from stdin to an IMAP folder SYNOPSIS -------- +[verse] 'git imap-send' DESCRIPTION ----------- -This command uploads a mailbox generated with 'git-format-patch' +This command uploads a mailbox generated with 'git format-patch' into an IMAP drafts folder. This allows patches to be sent as other email is when using mail clients that cannot read mailbox -files directly. +files directly. The command also works with any general mailbox +in which emails have the fields "From", "Date", and "Subject" in +that order. Typical usage is something like: @@ -71,6 +74,10 @@ imap.preformattedHTML:: option causes Thunderbird to send the patch as a plain/text, format=fixed email. Default is `false`. +imap.authMethod:: + Specify authenticate method for authentication with IMAP server. + Current supported method is 'CRAM-MD5' only. + Examples ~~~~~~~~ @@ -105,6 +112,31 @@ Using direct mode with SSL: .......................... +EXAMPLE +------- +To submit patches using GMail's IMAP interface, first, edit your ~/.gitconfig +to specify your account settings: + +--------- +[imap] + folder = "[Gmail]/Drafts" + host = imaps://imap.gmail.com + user = user@gmail.com + port = 993 + sslverify = false +--------- + +You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error +that the "Folder doesn't exist". + +Once the commits are ready to be sent, run the following command: + + $ git format-patch --cover-letter -M --stdout origin/master | git imap-send + +Just make sure to disable line wrapping in the email client (GMail's web +interface will wrap lines no matter what, so you need to use a real +IMAP client). + CAUTION ------- It is still your responsibility to make sure that the email message @@ -118,19 +150,9 @@ Thunderbird in particular is known to be problematic. Thunderbird users may wish to visit this web page for more information: http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email - -BUGS ----- -Doesn't handle lines starting with "From " in the message body. - - -Author ------- -Derived from isync 1.0.1 by Mike McCormack. - -Documentation --------------- -Documentation by Mike McCormack +SEE ALSO +-------- +linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5) GIT --- diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 4b5c743c1e..909687fed4 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -43,30 +43,26 @@ OPTIONS a default name determined from the pack content. If <pack-file> is not specified consider using --keep to prevent a race condition between this process and - 'git-repack'. + 'git repack'. --fix-thin:: - It is possible for 'git-pack-objects' to build - "thin" pack, which records objects in deltified form based on - objects not included in the pack to reduce network traffic. - Those objects are expected to be present on the receiving end - and they must be included in the pack for that pack to be self - contained and indexable. Without this option any attempt to - index a thin pack will fail. This option only makes sense in - conjunction with --stdin. + Fix a "thin" pack produced by `git pack-objects --thin` (see + linkgit:git-pack-objects[1] for details) by adding the + excluded objects the deltified objects are based on to the + pack. This option only makes sense in conjunction with --stdin. --keep:: Before moving the index into its final destination create an empty .keep file for the associated pack file. This option is usually necessary with --stdin to prevent a - simultaneous 'git-repack' process from deleting + simultaneous 'git repack' process from deleting the newly constructed pack and index before refs can be updated to use objects contained in the pack. ---keep='why':: +--keep=<msg>:: Like --keep create a .keep file before moving the index into its final destination, but rather than creating an empty file - place 'why' followed by an LF into the .keep file. The 'why' + place '<msg>' followed by an LF into the .keep file. The '<msg>' message can later be searched for within all .keep files to locate any which have outlived their usefulness. @@ -86,18 +82,9 @@ Once the index has been created, the list of object names is sorted and the SHA1 hash of that list is printed to stdout. If --stdin was also used then this is prefixed by either "pack\t", or "keep\t" if a new .keep file was successfully created. This is useful to remove a -.keep file used as a lock to prevent the race with 'git-repack' +.keep file used as a lock to prevent the race with 'git repack' mentioned above. - -Author ------- -Written by Sergey Vlasov <vsu@altlinux.ru> - -Documentation -------------- -Documentation by Sergey Vlasov - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index eba3cb4998..a21e346789 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -8,7 +8,8 @@ git-init-db - Creates an empty git repository SYNOPSIS -------- -'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--shared[=<permissions>]] +[verse] +'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]] DESCRIPTION @@ -16,3 +17,7 @@ DESCRIPTION This is a synonym for linkgit:git-init[1]. Please refer to the documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index f081b24d9d..9ac2bbaa56 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -8,9 +8,33 @@ git-init - Create an empty git repository or reinitialize an existing one SYNOPSIS -------- -'git init' [-q | --quiet] [--bare] [--template=<template_directory>] [--shared[=<permissions>]] [directory] +[verse] +'git init' [-q | --quiet] [--bare] [--template=<template_directory>] + [--separate-git-dir <git dir>] + [--shared[=<permissions>]] [directory] +DESCRIPTION +----------- + +This command creates an empty git repository - basically a `.git` +directory with subdirectories for `objects`, `refs/heads`, +`refs/tags`, and template files. An initial `HEAD` file that +references the HEAD of the master branch is also created. + +If the `$GIT_DIR` environment variable is set then it specifies a path +to use instead of `./.git` for the base of the repository. + +If the object storage directory is specified via the +`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories +are created underneath - otherwise the default `$GIT_DIR/objects` +directory is used. + +Running 'git init' in an existing repository is safe. It will not +overwrite things that are already there. The primary reason for +rerunning 'git init' is to pick up newly added templates (or to move +the repository to another place if --separate-git-dir is given). + OPTIONS ------- @@ -28,16 +52,19 @@ current working directory. --template=<template_directory>:: -Provide the directory from which templates will be used. The default template -directory is `/usr/share/git-core/templates`. +Specify the directory from which templates will be used. (See the "TEMPLATE +DIRECTORY" section below.) + +--separate-git-dir=<git dir>:: -When specified, `<template_directory>` is used as the source of the template -files rather than the default. The template files include some directory -structure, some suggested "exclude patterns", and copies of non-executing -"hook" files. The suggested patterns and hook files are all modifiable and -extensible. +Instead of initializing the repository where it is supposed to be, +place a filesytem-agnostic git symbolic link there, pointing to the +specified git path, and initialize a git repository at the path. The +result is git repository can be separated from working tree. If this +is reinitialization, the repository will be moved to the specified +path. ---shared[={false|true|umask|group|all|world|everybody|0xxx}]:: +--shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: Specify that the git repository is to be shared amongst several users. This allows users belonging to the same group to push into that @@ -80,32 +107,25 @@ line, the command is run inside the directory (possibly after creating it). -- -DESCRIPTION ------------ -This command creates an empty git repository - basically a `.git` directory -with subdirectories for `objects`, `refs/heads`, `refs/tags`, and -template files. -An initial `HEAD` file that references the HEAD of the master branch -is also created. +TEMPLATE DIRECTORY +------------------ -If the `$GIT_DIR` environment variable is set then it specifies a path -to use instead of `./.git` for the base of the repository. +The template directory contains files and directories that will be copied to +the `$GIT_DIR` after it is created. + +The template directory used will (in order): -If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY` -environment variable then the sha1 directories are created underneath - -otherwise the default `$GIT_DIR/objects` directory is used. + - The argument given with the `--template` option. -Running 'git-init' in an existing repository is safe. It will not overwrite -things that are already there. The primary reason for rerunning 'git-init' -is to pick up newly added templates. + - The contents of the `$GIT_TEMPLATE_DIR` environment variable. -Note that 'git-init' is the same as 'git-init-db'. The command -was primarily meant to initialize the object database, but over -time it has become responsible for setting up the other aspects -of the repository, such as installing the default hooks and -setting the configuration variables. The old name is retained -for backward compatibility reasons. + - The `init.templatedir` configuration variable. + - The default template directory: `/usr/share/git-core/templates`. + +The default template directory includes some directory structure, some +suggested "exclude patterns", and copies of sample "hook" files. +The suggested patterns and hook files are all modifiable and extensible. EXAMPLES -------- @@ -121,15 +141,6 @@ $ git add . <2> <1> prepare /path/to/my/codebase/.git directory <2> add all existing file to the index - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 0771f25443..f3eef510f2 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -29,7 +29,7 @@ OPTIONS The HTTP daemon command-line that will be executed. Command-line options may be specified here, and the configuration file will be added at the end of the command-line. - Currently apache2, lighttpd, mongoose and webrick are supported. + Currently apache2, lighttpd, mongoose, plackup and webrick are supported. (Default: lighttpd) -m:: @@ -44,23 +44,26 @@ OPTIONS -b:: --browser:: The web browser that should be used to view the gitweb - page. This will be passed to the 'git-web--browse' helper + page. This will be passed to the 'git web{litdd}browse' helper script along with the URL of the gitweb instance. See - linkgit:git-web--browse[1] for more information about this. If + linkgit:git-web{litdd}browse[1] for more information about this. If the script fails, the URL will be printed to stdout. +start:: --start:: - Start the httpd instance and exit. This does not generate - any of the configuration files for spawning a new instance. + Start the httpd instance and exit. Regenerate configuration files + as necessary for spawning a new instance. +stop:: --stop:: Stop the httpd instance and exit. This does not generate any of the configuration files for spawning a new instance, nor does it close the browser. +restart:: --restart:: - Restart the httpd instance and exit. This does not generate - any of the configuration files for spawning a new instance. + Restart the httpd instance and exit. Regenerate configuration files + as necessary for spawning a new instance. CONFIGURATION ------------- @@ -79,15 +82,11 @@ You may specify configuration in your .git/config If the configuration variable 'instaweb.browser' is not set, 'web.browser' will be used instead if it is defined. See -linkgit:git-web--browse[1] for more information about this. +linkgit:git-web{litdd}browse[1] for more information about this. -Author ------- -Written by Eric Wong <normalperson@yhbt.net> - -Documentation --------------- -Documentation by Eric Wong <normalperson@yhbt.net>. +SEE ALSO +-------- +linkgit:gitweb[1] GIT --- diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 3d79de11ec..249fc878ec 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -8,36 +8,39 @@ git-log - Show commit logs SYNOPSIS -------- +[verse] 'git log' [<options>] [<since>..<until>] [[\--] <path>...] DESCRIPTION ----------- Shows the commit logs. -The command takes options applicable to the 'git-rev-list' +The command takes options applicable to the 'git rev-list' command to control what is shown and how, and options applicable to -the 'git-diff-*' commands to control how the changes +the 'git diff-*' commands to control how the changes each commit introduces are shown. OPTIONS ------- -:git-log: 1 -include::diff-options.txt[] - -<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 `HEAD`, i.e. the tip of the current branch. For a more complete list of ways to spell <since> - and <until>, see "SPECIFYING REVISIONS" section in - linkgit:git-rev-parse[1]. + and <until>, see linkgit:gitrevisions[7]. ---decorate[=short|full]:: +--follow:: + Continue listing the history of a file beyond renames + (works only for a single file). + +--no-decorate:: +--decorate[=short|full|no]:: Print out the ref names of any commits that are shown. If 'short' is specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is specified, the @@ -54,9 +57,9 @@ include::diff-options.txt[] paths. With this, the full diff is shown for commits that touch the specified paths; this means that "<path>..." limits only commits, and doesn't limit diff for those commits. - ---follow:: - Continue listing the history of a file beyond renames. ++ +Note that this affects all diff-based output types, e.g. those +produced by --stat etc. --log-size:: Before the log message print out its size in bytes. Intended @@ -66,60 +69,122 @@ include::diff-options.txt[] its size is not included. [\--] <path>...:: - Show only commits that affect any of the specified paths. To - prevent confusion with options and branch names, paths may need - to be prefixed with "\-- " to separate them from options or - refnames. - + Show only commits that are enough to explain how the files + that match the specified paths came to be. See "History + Simplification" below for details and other simplification + modes. ++ +To prevent confusion with options and branch names, paths may need to +be prefixed with "\-- " to separate them from options or refnames. include::rev-list-options.txt[] include::pretty-formats.txt[] +Common diff options +------------------- + +:git-log: 1 +include::diff-options.txt[] + include::diff-generate-patch.txt[] Examples -------- -git log --no-merges:: +`git log --no-merges`:: Show the whole commit history, but skip any merges -git log v2.6.12.. include/scsi drivers/scsi:: +`git log v2.6.12.. include/scsi drivers/scsi`:: Show all commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -git log --since="2 weeks ago" \-- gitk:: +`git log --since="2 weeks ago" \-- gitk`:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named 'gitk' -git log --name-status release..test:: +`git log --name-status release..test`:: Show the commits that are in the "test" branch but not yet in the "release" branch, along with the list of paths each commit modifies. -git log --follow builtin-rev-list.c:: +`git log --follow builtin-rev-list.c`:: Shows the commits that changed builtin-rev-list.c, including those commits that occurred before the file was given its present name. +`git log --branches --not --remotes=origin`:: + + Shows all commits that are in any of local branches but not in + any of remote-tracking branches for 'origin' (what you have that + origin doesn't). + +`git log master --not --remotes=*/master`:: + + Shows all commits that are in local master but not in any remote + repository master branches. + +`git log -p -m --first-parent`:: + + Shows the history including change diffs, but only from the + "main branch" perspective, skipping commits that come from merged + branches, and showing full diffs of changes introduced by the merges. + This makes sense only when following a strict policy of merging all + topic branches when staying on a single integration branch. + + Discussion ---------- include::i18n.txt[] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +Configuration +------------- + +See linkgit:git-config[1] for core variables and linkgit:git-diff[1] +for settings related to diff generation. + +format.pretty:: + Default for the `--format` option. (See "PRETTY FORMATS" above.) + Defaults to "medium". + +i18n.logOutputEncoding:: + Encoding to use when displaying logs. (See "Discussion", above.) + Defaults to the value of `i18n.commitEncoding` if set, UTF-8 + otherwise. + +log.date:: + Default format for human-readable dates. (Compare the + `--date` option.) Defaults to "default", which means to write + dates like `Sat May 8 19:35:34 2010 -0500`. + +log.showroot:: + If `false`, 'git log' and related commands will not treat the + initial commit as a big creation event. Any root commits in + `git log -p` output would be shown without a diff attached. + The default is `true`. + +mailmap.file:: + See linkgit:git-shortlog[1]. + +notes.displayRef:: + Which refs, in addition to the default set by `core.notesRef` + or 'GIT_NOTES_REF', to read notes from when showing commit + messages with the 'log' family of commands. See + linkgit:git-notes[1]. ++ +May be an unabbreviated ref name or a glob and may be specified +multiple times. A warning will be issued for refs that do not exist, +but a glob that does not match any refs is silently ignored. ++ +This setting can be disabled by the `--no-notes` option, +overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, +and overridden by the `--notes=<ref>` option. GIT --- diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index 602b8d5d4d..c406a11001 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -7,6 +7,7 @@ git-lost-found - Recover lost refs that luckily have not yet been pruned SYNOPSIS -------- +[verse] 'git lost-found' DESCRIPTION @@ -67,15 +68,6 @@ $ git rev-parse not-lost-anymore 1ef2b196d909eed523d4f3c9bf54b78cdd6843c6 ------------ -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 98f3b9e758..4b28292811 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -10,14 +10,14 @@ SYNOPSIS -------- [verse] 'git ls-files' [-z] [-t] [-v] - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\* - (-[c|d|o|i|s|u|k|m])\* + (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* + (-[c|d|o|i|s|u|k|m])* [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] - [--full-name] [--abbrev] [--] [<file>]\* + [--full-name] [--abbrev] [--] [<file>...] DESCRIPTION ----------- @@ -79,15 +79,16 @@ OPTIONS -x <pattern>:: --exclude=<pattern>:: - Skips files matching pattern. - Note that pattern is a shell wildcard pattern. + Skip untracked files matching pattern. + Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS + below for more information. -X <file>:: --exclude-from=<file>:: - exclude patterns are read from <file>; 1 per line. + Read exclude patterns from <file>; 1 per line. --exclude-per-directory=<file>:: - read additional exclude patterns that apply only to the + Read additional exclude patterns that apply only to the directory and its subdirectories in <file>. --exclude-standard:: @@ -106,8 +107,16 @@ OPTIONS with `-s` or `-u` options does not make any sense. -t:: - Identify the file status with the following tags (followed by - a space) at the start of each line: + This feature is semi-deprecated. For scripting purpose, + linkgit:git-status[1] `--porcelain` and + linkgit:git-diff-files[1] `--name-status` are almost always + superior alternatives, and users should look at + linkgit:git-status[1] `--short` or linkgit:git-diff[1] + `--name-status` for more user-friendly alternatives. ++ +This option identifies the file status with the following tags (followed by +a space) at the start of each line: + H:: cached S:: skip-worktree M:: unmerged @@ -132,6 +141,12 @@ OPTIONS lines, show only a partial prefix. Non default number of digits can be specified with --abbrev=<n>. +--debug:: + After each line that describes a file, add more data about its + cache entry. This is intended to show as much information as + possible for manual inspection; the exact format may change at + any time. + \--:: Do not interpret any more arguments as options. @@ -141,12 +156,12 @@ OPTIONS Output ------ -show files just outputs the filename unless '--stage' is specified in +'git ls-files' just outputs the filenames unless '--stage' is specified in which case it outputs: [<tag> ]<mode> <object> <stage> <file> -'git-ls-files --unmerged' and 'git-ls-files --stage' can be used to examine +'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine detailed information on unmerged paths. For an unmerged path, instead of recording a single mode/SHA1 pair, @@ -163,7 +178,7 @@ respectively. Exclude Patterns ---------------- -'git-ls-files' can use a list of "exclude patterns" when +'git ls-files' can use a list of "exclude patterns" when traversing the directory tree and finding files to show when the flags --others or --ignored are specified. linkgit:gitignore[5] specifies the format of exclude patterns. @@ -178,8 +193,8 @@ These exclude patterns come from these places, in order: file containing a list of patterns. Patterns are ordered in the same order they appear in the file. - 3. command line flag --exclude-per-directory=<name> specifies - a name of the file in each directory 'git-ls-files' + 3. The command line flag --exclude-per-directory=<name> specifies + a name of the file in each directory 'git ls-files' examines, normally `.gitignore`. Files in deeper directories take precedence. Patterns are ordered in the same order they appear in the files. @@ -194,15 +209,6 @@ SEE ALSO -------- linkgit:git-read-tree[1], linkgit:gitignore[5] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index abe7bf9ff9..7a9b86a58a 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] - <repository> <refs>... + [--exit-code] <repository> [<refs>...] DESCRIPTION ----------- @@ -36,6 +36,12 @@ OPTIONS SSH and where the SSH daemon does not use the PATH configured by the user. +--exit-code:: + Exit with status "2" when no matching refs are found in the remote + repository. Usually the command exits with status "0" to indicate + it successfully talked with the remote repository, whether it + found any matching refs. + <repository>:: Location of the repository. The shorthand defined in $GIT_DIR/branches/ can be used. Use "." (dot) to list references in @@ -67,10 +73,6 @@ EXAMPLES c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index c3fdccb4c2..16e87fd6dd 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -10,8 +10,8 @@ SYNOPSIS -------- [verse] 'git ls-tree' [-d] [-r] [-t] [-l] [-z] - [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]] - <tree-ish> [paths...] + [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]] + <tree-ish> [<path>...] DESCRIPTION ----------- @@ -19,16 +19,16 @@ Lists the contents of a given tree object, like what "/bin/ls -a" does in the current working directory. Note that: - the behaviour is slightly different from that of "/bin/ls" in that the - 'paths' denote just a list of patterns to match, e.g. so specifying + '<path>' denotes just a list of patterns to match, e.g. so specifying directory name (without '-r') will behave differently, and order of the arguments does not matter. - - the behaviour is similar to that of "/bin/ls" in that the 'paths' is + - the behaviour is similar to that of "/bin/ls" in that the '<path>' is taken as relative to the current working directory. E.g. when you are in a directory 'sub' that has a directory 'dir', you can run 'git ls-tree -r HEAD dir' to list the contents of the tree (that is 'sub/dir' in 'HEAD'). You don't want to give a tree that is not at the - root level (e.g. 'git ls-tree -r HEAD:sub dir') in this case, as that + root level (e.g. `git ls-tree -r HEAD:sub dir`) in this case, as that would result in asking for 'sub/sub/dir' in the 'HEAD' commit. However, the current working directory can be ignored by passing --full-tree option. @@ -72,7 +72,7 @@ OPTIONS Do not limit the listing to the current working directory. Implies --full-name. -paths:: +[<path>...]:: When paths are given, show them (note that this isn't really raw pathnames, but rather a list of patterns to match). Otherwise implicitly uses the root level of the tree as the sole path argument. @@ -84,7 +84,7 @@ Output Format Unless the `-z` option is used, TAB, LF, and backslash characters in pathnames are represented as `\t`, `\n`, and `\\`, respectively. -This output format is compatible with what '--index-info --stdin' of +This output format is compatible with what `--index-info --stdin` of 'git update-index' expects. When the `-l` option is used, format changes to @@ -95,18 +95,6 @@ Object size identified by <object> is given in bytes, and right-justified with minimum width of 7 characters. Object size is given only for blobs (file) entries; for other entries `-` character is used in place of size. - -Author ------- -Written by Petr Baudis <pasky@suse.cz> -Completely rewritten from scratch by Junio C Hamano <gitster@pobox.com>, -another major rewrite by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list -<git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index b81ac98cf0..51dc325748 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -8,6 +8,7 @@ git-mailinfo - Extracts patch and authorship from a single e-mail message SYNOPSIS -------- +[verse] 'git mailinfo' [-k|-b] [-u | --encoding=<encoding> | -n] [--scissors] <msg> <patch> @@ -16,7 +17,7 @@ DESCRIPTION Reads a single e-mail message from the standard input, and writes the commit log message in <msg> file, and the patches in <patch> file. The author name, e-mail and e-mail subject are -written out to the standard output to be used by 'git-am' +written out to the standard output to be used by 'git am' to create a commit. It is usually not necessary to use this command directly. See linkgit:git-am[1] instead. @@ -30,7 +31,7 @@ OPTIONS whitespaces, (3) '[' up to ']', typically '[PATCH]', and then prepends "[PATCH] ". This flag forbids this munging, and is most useful when used to read back - 'git-format-patch -k' output. + 'git format-patch -k' output. -b:: When -k is not in effect, all leading strings bracketed with '[' @@ -40,16 +41,16 @@ OPTIONS -u:: The commit log message, author name and author email are taken from the e-mail, and after minimally decoding MIME - transfer encoding, re-coded in UTF-8 by transliterating + transfer encoding, re-coded in the charset specified by + i18n.commitencoding (defaulting to UTF-8) by transliterating them. This used to be optional but now it is the default. + Note that the patch is always used as-is without charset conversion, even with this flag. --encoding=<encoding>:: - Similar to -u but if the local convention is different - from what is specified by i18n.commitencoding, this flag - can be used to override it. + Similar to -u. But when re-coding, the charset specified here is + used instead of the one specified by i18n.commitencoding or UTF-8. -n:: Disable all charset re-coding of the metadata. @@ -80,17 +81,6 @@ This can enabled by default with the configuration option mailinfo.scissors. <patch>:: The patch extracted from e-mail. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index 5cc94ec53d..4d1b871d96 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -7,7 +7,8 @@ git-mailsplit - Simple UNIX mbox splitter program SYNOPSIS -------- -'git mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>|<Maildir>...] +[verse] +'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...] DESCRIPTION ----------- @@ -43,15 +44,8 @@ OPTIONS Skip the first <nn> numbers, for example if -f3 is specified, start the numbering with 0004. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -and Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +--keep-cr:: + Do not remove `\r` from lines ending with `\r\n`. GIT --- diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index ce5b369985..b295bf8330 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -8,7 +8,10 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- +[verse] 'git merge-base' [-a|--all] <commit> <commit>... +'git merge-base' [-a|--all] --octopus <commit>... +'git merge-base' --independent <commit>... DESCRIPTION ----------- @@ -20,17 +23,33 @@ that does not have any better common ancestor is a 'best common ancestor', i.e. a 'merge base'. Note that there can be more than one merge base for a pair of commits. -Among the two commits to compute the merge base from, one is specified by -the first commit argument on the command line; the other commit is a -(possibly hypothetical) commit that is a merge across all the remaining -commits on the command line. As the most common special case, specifying only -two commits on the command line means computing the merge base between -the given two commits. +OPERATION MODE +-------------- + +As the most common special case, specifying only two commits on the +command line means computing the merge base between the given two commits. + +More generally, among the two commits to compute the merge base from, +one is specified by the first commit argument on the command line; +the other commit is a (possibly hypothetical) commit that is a merge +across all the remaining commits on the command line. As a consequence, the 'merge base' is not necessarily contained in each of the commit arguments if more than two commits are specified. This is different from linkgit:git-show-branch[1] when used with the `--merge-base` option. +--octopus:: + Compute the best common ancestors of all supplied commits, + in preparation for an n-way merge. This mimics the behavior + of 'git show-branch --merge-base'. + +--independent:: + Instead of printing merge bases, print a minimal subset of + the supplied commits with the same ancestors. In other words, + among the commits given, list those which cannot be reached + from any other. This mimics the behavior of 'git show-branch + --independent'. + OPTIONS ------- -a:: @@ -75,6 +94,9 @@ and the result of `git merge-base A M` is '1'. Commit '2' is also a common ancestor between 'A' and 'M', but '1' is a better common ancestor, because '2' is an ancestor of '1'. Hence, '2' is not a merge base. +The result of `git merge-base --octopus A B C` is '2', because '2' is +the best common ancestor of all commits. + When the history involves criss-cross merges, there can be more than one 'best' common ancestor for two commits. For example, with this topology: @@ -88,13 +110,11 @@ both '1' and '2' are merge-bases of A and B. Neither one is better than the other (both are 'best' merge bases). When the `--all` option is not given, it is unspecified which best one is output. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +See also +-------- +linkgit:git-rev-list[1], +linkgit:git-show-branch[1], +linkgit:git-merge[1] GIT --- diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 303537357b..d7db2a3737 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -10,20 +10,21 @@ SYNOPSIS -------- [verse] 'git merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]] - [-p|--stdout] [-q|--quiet] <current-file> <base-file> <other-file> + [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>] + <current-file> <base-file> <other-file> DESCRIPTION ----------- -'git-merge-file' incorporates all changes that lead from the `<base-file>` +'git merge-file' incorporates all changes that lead from the `<base-file>` to `<other-file>` into `<current-file>`. The result ordinarily goes into -`<current-file>`. 'git-merge-file' is useful for combining separate changes +`<current-file>`. 'git merge-file' is useful for combining separate changes to an original. Suppose `<base-file>` is the original, and both `<current-file>` and `<other-file>` are modifications of `<base-file>`, -then 'git-merge-file' combines both changes. +then 'git merge-file' combines both changes. A conflict occurs if both `<current-file>` and `<other-file>` have changes -in a common segment of lines. If a conflict is found, 'git-merge-file' +in a common segment of lines. If a conflict is found, 'git merge-file' normally outputs a warning and brackets the conflict with lines containing <<<<<<< and >>>>>>> markers. A typical conflict will look like this: @@ -34,12 +35,15 @@ normally outputs a warning and brackets the conflict with lines containing >>>>>>> B If there are conflicts, the user should edit the result and delete one of -the alternatives. +the alternatives. When `--ours`, `--theirs`, or `--union` option is in effect, +however, these conflicts are resolved favouring lines from `<current-file>`, +lines from `<other-file>`, or lines from both respectively. The length of the +conflict markers can be given with the `--marker-size` option. The exit value of this program is negative on error, and the number of conflicts otherwise. If the merge was clean, the exit value is 0. -'git-merge-file' is designed to be a minimal clone of RCS 'merge'; that is, it +'git merge-file' is designed to be a minimal clone of RCS 'merge'; that is, it implements all of RCS 'merge''s functionality which is needed by linkgit:git[1]. @@ -62,31 +66,26 @@ OPTIONS -q:: Quiet; do not warn about conflicts. +--ours:: +--theirs:: +--union:: + Instead of leaving conflicts in the file, resolve conflicts + favouring our (or their or both) side of the lines. + EXAMPLES -------- -git merge-file README.my README README.upstream:: +`git merge-file README.my README README.upstream`:: combines the changes of README.my and README.upstream since README, tries to merge them and writes the result into README.my. -git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345:: +`git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345`:: merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels `a` and `c` instead of `tmp/a123` and `tmp/c345`. - -Author ------- -Written by Johannes Schindelin <johannes.schindelin@gmx.de> - - -Documentation --------------- -Documentation by Johannes Schindelin and the git-list <git@vger.kernel.org>, -with parts copied from the original documentation of RCS 'merge'. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 123e6d024a..e0df1b3340 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,7 +8,8 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- -'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*) +[verse] +'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) DESCRIPTION ----------- @@ -36,14 +37,14 @@ OPTIONS failure usually indicates conflicts during the merge). This is for porcelains which might want to emit custom messages. -If 'git-merge-index' is called with multiple <file>s (or -a) then it +If 'git merge-index' is called with multiple <file>s (or -a) then it processes them in turn only stopping if merge returns a non-zero exit code. Typically this is run with a script calling git's imitation of the 'merge' command from the RCS package. -A sample script called 'git-merge-one-file' is included in the +A sample script called 'git merge-one-file' is included in the distribution. ALERT ALERT ALERT! The git "merge object order" is different from the @@ -68,19 +69,10 @@ or This is added AA in the branch B. fatal: merge program failed -where the latter example shows how 'git-merge-index' will stop trying to +where the latter example shows how 'git merge-index' will stop trying to merge once anything has returned an error (i.e., `cat` returned an error for the AA file, because it didn't exist in the original, and thus -'git-merge-index' didn't even try to merge the MM thing). - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -One-shot merge by Petr Baudis <pasky@ucw.cz> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +'git merge-index' didn't even try to merge the MM thing). GIT --- diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt index dc8a96adb0..04e803d5d3 100644 --- a/Documentation/git-merge-one-file.txt +++ b/Documentation/git-merge-one-file.txt @@ -8,21 +8,13 @@ git-merge-one-file - The standard helper program to use with git-merge-index SYNOPSIS -------- -'git-merge-one-file' +[verse] +'git merge-one-file' DESCRIPTION ----------- -This is the standard helper program to use with 'git-merge-index' -to resolve a merge after the trivial merge done with 'git-read-tree -m'. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, -Junio C Hamano <gitster@pobox.com> and Petr Baudis <pasky@suse.cz>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +This is the standard helper program to use with 'git merge-index' +to resolve a merge after the trivial merge done with 'git read-tree -m'. GIT --- diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index f869a7f00f..c5f84b6495 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -8,6 +8,7 @@ git-merge-tree - Show three-way merge without touching index SYNOPSIS -------- +[verse] 'git merge-tree' <base-tree> <branch1> <branch2> DESCRIPTION @@ -23,14 +24,6 @@ merge results outside of the index, and stuff the results back into the index. For this reason, the output from the command omits entries that match the <branch1> tree. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index e886c2ef54..e2e6aba17e 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -9,117 +9,167 @@ git-merge - Join two or more development histories together SYNOPSIS -------- [verse] -'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... - [-m <msg>] <remote>... -'git merge' <msg> HEAD <remote>... +'git merge' [-n] [--stat] [--no-commit] [--squash] + [-s <strategy>] [-X <strategy-option>] + [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] +'git merge' <msg> HEAD <commit>... +'git merge' --abort DESCRIPTION ----------- -This is the top-level interface to the merge machinery -which drives multiple merge strategy scripts. +Incorporates changes from the named commits (since the time their +histories diverged from the current branch) into the current +branch. This command is used by 'git pull' to incorporate changes +from another repository and can be used by hand to merge changes +from one branch into another. -The second syntax (<msg> `HEAD` <remote>) is supported for -historical reasons. Do not use it from the command line or in -new scripts. It is the same as `git merge -m <msg> <remote>`. +Assume the following history exists and the current branch is +"`master`": +------------ + A---B---C topic + / + D---E---F---G master +------------ -OPTIONS -------- -include::merge-options.txt[] +Then "`git merge topic`" will replay the changes made on the +`topic` branch since it diverged from `master` (i.e., `E`) until +its current commit (`C`) on top of `master`, and record the result +in a new commit along with the names of the two parent commits and +a log message from the user describing the changes. --m <msg>:: - Set the commit message to be used for the merge commit (in - case one is created). The 'git fmt-merge-msg' command can be - used to give a good default for automated 'git merge' - invocations. +------------ + A---B---C topic + / \ + D---E---F---G---H master +------------ -<remote>...:: - Other branch heads to merge into our branch. You need at - least one <remote>. Specifying more than one <remote> - obviously means you are trying an Octopus. +The second syntax (<msg> `HEAD` <commit>...) is supported for +historical reasons. Do not use it from the command line or in +new scripts. It is the same as `git merge -m <msg> <commit>...`. -include::merge-strategies.txt[] +The third syntax ("`git merge --abort`") can only be run after the +merge has resulted in conflicts. 'git merge --abort' will abort the +merge process and try to reconstruct the pre-merge state. However, +if there were uncommitted changes when the merge started (and +especially if those changes were further modified after the merge +was started), 'git merge --abort' will in some cases be unable to +reconstruct the original (pre-merge) changes. Therefore: +*Warning*: Running 'git merge' with uncommitted changes is +discouraged: while possible, it leaves you in a state that is hard to +back out of in the case of a conflict. -If you tried a merge which resulted in complex conflicts and -want to start over, you can recover with 'git-reset'. -CONFIGURATION -------------- -include::merge-config.txt[] +OPTIONS +------- +include::merge-options.txt[] -branch.<name>.mergeoptions:: - Sets default options for merging into branch <name>. The syntax and - supported options are the same as those of 'git merge', but option - values containing whitespace characters are currently not supported. +-m <msg>:: + Set the commit message to be used for the merge commit (in + case one is created). ++ +If `--log` is specified, a shortlog of the commits being merged +will be appended to the specified message. ++ +The 'git fmt-merge-msg' command can be +used to give a good default for automated 'git merge' +invocations. + +--rerere-autoupdate:: +--no-rerere-autoupdate:: + Allow the rerere mechanism to update the index with the + result of auto-conflict resolution if possible. + +--abort:: + Abort the current conflict resolution process, and + try to reconstruct the pre-merge state. ++ +If there were uncommitted worktree changes present when the merge +started, 'git merge --abort' will in some cases be unable to +reconstruct these changes. It is therefore recommended to always +commit or stash your changes before running 'git merge'. ++ +'git merge --abort' is equivalent to 'git reset --merge' when +`MERGE_HEAD` is present. -HOW MERGE WORKS ---------------- - -A merge is always between the current `HEAD` and one or more -commits (usually, branch head or tag), and the index file must -match the tree of `HEAD` commit (i.e. the contents of the last commit) -when it starts out. In other words, `git diff --cached HEAD` must -report no changes. (One exception is when the changed index -entries are already in the same state that would result from -the merge anyway.) - -Three kinds of merge can happen: - -* The merged commit is already contained in `HEAD`. This is the - simplest case, called "Already up-to-date." - -* `HEAD` is already contained in the merged commit. This is the - most common case especially when invoked from 'git pull': - you are tracking an upstream repository, have committed no local - changes and now you want to update to a newer upstream revision. - Your `HEAD` (and the index) is updated to point at the merged - commit, without creating an extra merge commit. This is - called "Fast-forward". - -* Both the merged commit and `HEAD` are independent and must be - tied together by a merge commit that has both of them as its parents. - The rest of this section describes this "True merge" case. - -The chosen merge strategy merges the two commits into a single -new source tree. -When things merge cleanly, this is what happens: - -1. The results are updated both in the index file and in your - working tree; -2. Index file is written out as a tree; -3. The tree gets committed; and -4. The `HEAD` pointer gets advanced. - -Because of 2., we require that the original state of the index -file matches exactly the current `HEAD` commit; otherwise we -will write out your local changes already registered in your -index file along with the merge result, which is not good. -Because 1. involves only those paths differing between your -branch and the remote branch you are pulling from during the -merge (which is typically a fraction of the whole tree), you can -have local modifications in your working tree as long as they do -not overlap with what the merge updates. - -When there are conflicts, the following happens: - -1. `HEAD` stays the same. - -2. Cleanly merged paths are updated both in the index file and +<commit>...:: + Commits, usually other branch heads, to merge into our branch. + Specifying more than one commit will create a merge with + 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 +that the current branch is configured to use as its upstream. +See also the configuration section of this manual page. + + +PRE-MERGE CHECKS +---------------- + +Before applying outside changes, you should get your own work in +good shape and committed locally, so it will not be clobbered if +there are conflicts. See also linkgit:git-stash[1]. +'git pull' and 'git merge' will stop without doing anything when +local uncommitted changes overlap with files that 'git pull'/'git +merge' may need to update. + +To avoid recording unrelated changes in the merge commit, +'git pull' and 'git merge' will also abort if there are any changes +registered in the index relative to the `HEAD` commit. (One +exception is when the changed index entries are in the state that +would result from the merge already.) + +If all named commits are already ancestors of `HEAD`, 'git merge' +will exit early with the message "Already up-to-date." + +FAST-FORWARD MERGE +------------------ + +Often the current branch head is an ancestor of the named commit. +This is the most common case especially when invoked from 'git +pull': you are tracking an upstream repository, you have committed +no local changes, and now you want to update to a newer upstream +revision. In this case, a new commit is not needed to store the +combined history; instead, the `HEAD` (along with the index) is +updated to point at the named commit, without creating an extra +merge commit. + +This behavior can be suppressed with the `--no-ff` option. + +TRUE MERGE +---------- + +Except in a fast-forward merge (see above), the branches to be +merged must be tied together by a merge commit that has both of them +as its parents. + +A merged version reconciling the changes from all branches to be +merged is committed, and your `HEAD`, index, and working tree are +updated to it. It is possible to have modifications in the working +tree as long as they do not overlap; the update will preserve them. + +When it is not obvious how to reconcile the changes, the following +happens: + +1. The `HEAD` pointer stays the same. +2. The `MERGE_HEAD` ref is set to point to the other branch head. +3. Paths that merged cleanly are updated both in the index file and in your working tree. - -3. For conflicting paths, the index file records up to three - versions; stage1 stores the version from the common ancestor, - stage2 from `HEAD`, and stage3 from the remote branch (you +4. For conflicting paths, the index file records up to three + versions: stage 1 stores the version from the common ancestor, + stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you can inspect the stages with `git ls-files -u`). The working tree files contain the result of the "merge" program; i.e. 3-way - merge results with familiar conflict markers `<<< === >>>`. - -4. No other changes are done. In particular, the local + merge results with familiar conflict markers `<<<` `===` `>>>`. +5. No other changes are made. In particular, the local modifications you had before you started merge will stay the same and the index entries for them stay as they were, i.e. matching `HEAD`. +If you tried a merge which resulted in complex conflicts and +want to start over, you can recover with `git merge --abort`. + HOW CONFLICTS ARE PRESENTED --------------------------- @@ -189,28 +239,30 @@ After seeing a conflict, you can do two things: * Decide not to merge. The only clean-ups you need are to reset the index file to the `HEAD` commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; 'git-reset --hard' can - be used for this. + up working tree changes made by 2. and 3.; `git merge --abort` + can be used for this. * Resolve the conflicts. Git will mark the conflicts in the working tree. Edit the files into shape and - 'git-add' them to the index. Use 'git-commit' to seal the deal. + 'git add' them to the index. Use 'git commit' to seal the deal. You can work through the conflict with a number of tools: - * Use a mergetool. 'git mergetool' to launch a graphical + * Use a mergetool. `git mergetool` to launch a graphical mergetool which will work you through the merge. - * Look at the diffs. 'git diff' will show a three-way diff, - highlighting changes from both the HEAD and remote versions. + * Look at the diffs. `git diff` will show a three-way diff, + highlighting changes from both the `HEAD` and `MERGE_HEAD` + versions. - * Look at the diffs on their own. 'git log --merge -p <path>' - will show diffs first for the HEAD version and then the - remote version. + * Look at the diffs from each branch. `git log --merge -p <path>` + will show diffs first for the `HEAD` version and then the + `MERGE_HEAD` version. - * Look at the originals. 'git show :1:filename' shows the - common ancestor, 'git show :2:filename' shows the HEAD - version and 'git show :3:filename' shows the remote version. + * Look at the originals. `git show :1:filename` shows the + common ancestor, `git show :2:filename` shows the `HEAD` + version, and `git show :3:filename` shows the `MERGE_HEAD` + version. EXAMPLES @@ -245,6 +297,17 @@ changes into a merge commit. Small fixups like bumping release/version name would be acceptable. +include::merge-strategies.txt[] + +CONFIGURATION +------------- +include::merge-config.txt[] + +branch.<name>.mergeoptions:: + Sets default options for merging into branch <name>. The syntax and + supported options are the same as those of 'git merge', but option + values containing whitespace characters are currently not supported. + SEE ALSO -------- linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], @@ -254,15 +317,6 @@ linkgit:git-diff[1], linkgit:git-ls-files[1], linkgit:git-add[1], linkgit:git-rm[1], linkgit:git-mergetool[1] -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt index 78eb03f0ae..f98a41b87c 100644 --- a/Documentation/git-mergetool--lib.txt +++ b/Documentation/git-mergetool--lib.txt @@ -1,5 +1,5 @@ -git-mergetool--lib(1) -===================== +git-mergetool{litdd}lib(1) +========================== NAME ---- @@ -7,7 +7,8 @@ git-mergetool--lib - Common git merge tool shell scriptlets SYNOPSIS -------- -'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool--lib"' +[verse] +'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool{litdd}lib"' DESCRIPTION ----------- @@ -16,11 +17,11 @@ This is not a command the end user would want to run. Ever. This documentation is meant for people who are studying the Porcelain-ish scripts and/or are writing new ones. -The 'git-mergetool--lib' scriptlet is designed to be sourced (using +The 'git-mergetool{litdd}lib' scriptlet is designed to be sourced (using `.`) by other shell scripts to set up functions for working with git merge tools. -Before sourcing 'git-mergetool--lib', your script must set `TOOL_MODE` +Before sourcing 'git-mergetool{litdd}lib', your script must set `TOOL_MODE` to define the operation mode for the functions listed below. 'diff' and 'merge' are valid values. @@ -41,14 +42,6 @@ run_merge_tool:: '$MERGED', '$LOCAL', '$REMOTE', and '$BASE' must be defined for use by the merge tool. -Author ------- -Written by David Aguilar <davvid@gmail.com> - -Documentation --------------- -Documentation by David Aguilar and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 4a6f7f3a2d..2a49de7cfe 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -7,18 +7,20 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts SYNOPSIS -------- -'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]... +[verse] +'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...] DESCRIPTION ----------- Use `git mergetool` to run one of several merge utilities to resolve -merge conflicts. It is typically run after 'git-merge'. +merge conflicts. It is typically run after 'git merge'. If one or more <file> parameters are given, the merge tool program will -be run to resolve differences on each file. If no <file> names are -specified, 'git-mergetool' will run the merge tool program on every file -with merge conflicts. +be run to resolve differences on each file (skipping those without +conflicts). Specifying a directory will include all unresolved files in +that path. If no <file> names are specified, 'git mergetool' will run +the merge tool program on every file with merge conflicts. OPTIONS ------- @@ -26,26 +28,26 @@ OPTIONS --tool=<tool>:: Use the merge resolution program specified by <tool>. Valid merge tools are: - kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, - diffuse, tortoisemerge, opendiff, p4merge and araxis. + araxis, bc3, diffuse, ecmerge, emerge, gvimdiff, kdiff3, + meld, opendiff, p4merge, tkdiff, tortoisemerge, vimdiff and xxdiff. + -If a merge resolution program is not specified, 'git-mergetool' +If a merge resolution program is not specified, 'git mergetool' will use the configuration variable `merge.tool`. If the -configuration variable `merge.tool` is not set, 'git-mergetool' +configuration variable `merge.tool` is not set, 'git mergetool' will pick a suitable default. + You can explicitly provide a full path to the tool by setting the configuration variable `mergetool.<tool>.path`. For example, you can configure the absolute path to kdiff3 by setting -`mergetool.kdiff3.path`. Otherwise, 'git-mergetool' assumes the +`mergetool.kdiff3.path`. Otherwise, 'git mergetool' assumes the tool is available in PATH. + Instead of running one of the known merge tool programs, -'git-mergetool' can be customized to run an alternative program +'git mergetool' can be customized to run an alternative program by specifying the command line to invoke in a configuration variable `mergetool.<tool>.cmd`. + -When 'git-mergetool' is invoked with this tool (either through the +When 'git mergetool' is invoked with this tool (either through the `-t` or `--tool` option or the `merge.tool` configuration variable) the configured command line will be invoked with `$BASE` set to the name of a temporary file containing the common base for @@ -59,7 +61,7 @@ merge resolution. If the custom merge tool correctly indicates the success of a merge resolution with its exit code, then the configuration variable `mergetool.<tool>.trustExitCode` can be set to `true`. -Otherwise, 'git-mergetool' will prompt the user to indicate the +Otherwise, 'git mergetool' will prompt the user to indicate the success of the resolution after the custom tool has exited. -y:: @@ -72,13 +74,15 @@ success of the resolution after the custom tool has exited. This is the default behaviour; the option is provided to override any configuration settings. -Author ------- -Written by Theodore Y Ts'o <tytso@mit.edu> +TEMPORARY FILES +--------------- +`git mergetool` creates `*.orig` backup files while resolving merges. +These are safe to remove once a file has been merged and its +`git mergetool` session has completed. -Documentation --------------- -Documentation by Theodore Y Ts'o. +Setting the `mergetool.keepBackup` configuration variable to `false` +causes `git mergetool` to automatically remove the backup as files +are successfully merged. GIT --- diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 8bcc11443d..65e167a5c5 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -8,6 +8,7 @@ git-mktag - Creates a tag object SYNOPSIS -------- +[verse] 'git mktag' < signature_file DESCRIPTION @@ -32,15 +33,6 @@ exists, is separated by a blank line from the header. The message part may contain a signature that git itself doesn't care about, but that can be verified with gpg. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 81e3326772..5c6ebdfad9 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -8,6 +8,7 @@ git-mktree - Build a tree-object from ls-tree formatted text SYNOPSIS -------- +[verse] 'git mktree' [-z] [--missing] [--batch] DESCRIPTION @@ -34,14 +35,6 @@ OPTIONS optional. Note - if the '-z' option is used, lines are terminated with NUL. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index bdcb58526e..b8db373964 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -8,6 +8,7 @@ git-mv - Move or rename a file, a directory, or a symlink SYNOPSIS -------- +[verse] 'git mv' <options>... <args>... DESCRIPTION @@ -39,17 +40,6 @@ OPTIONS --dry-run:: Do nothing; only show what would happen - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -Rewritten by Ryan Anderson <ryan@michonline.com> -Move functionality added by Josef Weidendorfer <Josef.Weidendorfer@gmx.de> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 7ca8a7b48c..ad1d1468c9 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION ----------- Finds symbolic names suitable for human digestion for revisions given in any -format parsable by 'git-rev-parse'. +format parsable by 'git rev-parse'. OPTIONS @@ -55,7 +55,7 @@ wrote you about that fantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a. Of course, you look into the commit, but that only tells you what happened, but not the context. -Enter 'git-name-rev': +Enter 'git name-rev': ------------ % git name-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a @@ -70,15 +70,6 @@ Another nice thing you can do is: % git log | git name-rev --stdin ------------ - -Author ------- -Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> - -Documentation --------------- -Documentation by Johannes Schindelin. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 94cceb1319..e8319eac69 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -3,57 +3,383 @@ git-notes(1) NAME ---- -git-notes - Add/inspect commit notes +git-notes - Add or inspect object notes SYNOPSIS -------- [verse] -'git-notes' (edit [-F <file> | -m <msg>] | show) [commit] +'git notes' [list [<object>]] +'git notes' add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' copy [-f] ( --stdin | <from-object> <to-object> ) +'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [<object>] +'git notes' show [<object>] +'git notes' merge [-v | -q] [-s <strategy> ] <notes_ref> +'git notes' merge --commit [-v | -q] +'git notes' merge --abort [-v | -q] +'git notes' remove [--ignore-missing] [--stdin] [<object>...] +'git notes' prune [-n | -v] +'git notes' get-ref + DESCRIPTION ----------- -This command allows you to add notes to commit messages, without -changing the commit. To discern these notes from the message stored -in the commit object, the notes are indented like the message, after -an unindented line saying "Notes:". +Adds, removes, or reads notes attached to objects, without touching +the objects themselves. + +By default, notes are saved to and read from `refs/notes/commits`, but +this default can be overridden. See the OPTIONS, CONFIGURATION, and +ENVIRONMENT sections below. If this ref does not exist, it will be +quietly created when it is first needed to store a note. + +A typical use of notes is to supplement a commit message without +changing the commit itself. Notes can be shown by 'git log' along with +the original commit message. To distinguish these notes from the +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`). + +To change which notes are shown by 'git log', see the +"notes.displayRef" configuration in linkgit:git-log[1]. -To disable commit notes, you have to set the config variable -core.notesRef to the empty string. Alternatively, you can set it -to a different ref, something like "refs/notes/bugzilla". This setting -can be overridden by the environment variable "GIT_NOTES_REF". +See the "notes.rewrite.<command>" configuration for a way to carry +notes across commands that rewrite commits. SUBCOMMANDS ----------- +list:: + List the notes object for a given object. If no object is + given, show a list of all note objects and the objects they + annotate (in the format "<note object> <annotated object>"). + This is the default subcommand if no subcommand is given. + +add:: + Add notes for a given object (defaults to HEAD). Abort if the + object already has notes (use `-f` to overwrite existing notes). + However, if you're using `add` interactively (using an editor + to supply the notes contents), then - instead of aborting - + the existing notes will be opened in the editor (like the `edit` + subcommand). + +copy:: + Copy the notes for the first object onto the second object. + Abort if the second object already has notes, or if the first + object has none (use -f to overwrite existing notes to the + second object). This subcommand is equivalent to: + `git notes add [-f] -C $(git notes list <from-object>) <to-object>` ++ +In `\--stdin` mode, take lines in the format ++ +---------- +<from-object> SP <to-object> [ SP <rest> ] LF +---------- ++ +on standard input, and copy the notes from each <from-object> to its +corresponding <to-object>. (The optional `<rest>` is ignored so that +the command can read the input given to the `post-rewrite` hook.) + +append:: + Append to the notes of an existing object (defaults to HEAD). + Creates a new notes object if needed. + edit:: - Edit the notes for a given commit (defaults to HEAD). + Edit the notes for a given object (defaults to HEAD). show:: - Show the notes for a given commit (defaults to HEAD). + Show the notes for a given object (defaults to HEAD). +merge:: + Merge the given notes ref into the current notes ref. + This will try to merge the changes made by the given + notes ref (called "remote") since the merge-base (if + any) into the current notes ref (called "local"). ++ +If conflicts arise and a strategy for automatically resolving +conflicting notes (see the -s/--strategy option) is not given, +the "manual" resolver is used. This resolver checks out the +conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`), +and instructs the user to manually resolve the conflicts there. +When done, the user can either finalize the merge with +'git notes merge --commit', or abort the merge with +'git notes merge --abort'. + +remove:: + Remove the notes for given objects (defaults to HEAD). When + giving zero or one object from the command line, this is + equivalent to specifying an empty note message to + the `edit` subcommand. + +prune:: + Remove all notes for non-existing/unreachable objects. + +get-ref:: + Print the current notes ref. This provides an easy way to + retrieve the current notes ref (e.g. from scripts). OPTIONS ------- +-f:: +--force:: + When adding notes to an object that already has notes, + overwrite the existing notes (instead of aborting). + -m <msg>:: +--message=<msg>:: Use the given note message (instead of prompting). - If multiple `-m` (or `-F`) options are given, their - values are concatenated as separate paragraphs. + If multiple `-m` options are given, their values + are concatenated as separate paragraphs. + Lines starting with `#` and empty lines other than a + single line between paragraphs will be stripped out. -F <file>:: +--file=<file>:: Take the note message from the given file. Use '-' to read the note message from the standard input. - If multiple `-F` (or `-m`) options are given, their - values are concatenated as separate paragraphs. + Lines starting with `#` and empty lines other than a + single line between paragraphs will be stripped out. + +-C <object>:: +--reuse-message=<object>:: + Take the given blob object (for example, another note) as the + note message. (Use `git notes copy <object>` instead to + copy notes between objects.) + +-c <object>:: +--reedit-message=<object>:: + Like '-C', but with '-c' the editor is invoked, so that + the user can further edit the note message. + +--ref <ref>:: + Manipulate the notes tree in <ref>. This overrides + 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref + is taken to be in `refs/notes/` if it is not qualified. + +--ignore-missing:: + Do not consider it an error to request removing notes from an + object that does not have notes attached to it. + +--stdin:: + Also read the object names to remove notes from from the standard + input (there is no reason you cannot combine this with object + names from the command line). + +-n:: +--dry-run:: + Do not remove anything; just report the object names whose notes + would be removed. + +-s <strategy>:: +--strategy=<strategy>:: + When merging notes, resolve notes conflicts using the given + strategy. The following strategies are recognized: "manual" + (default), "ours", "theirs", "union" and "cat_sort_uniq". + See the "NOTES MERGE STRATEGIES" section below for more + information on each notes merge strategy. + +--commit:: + Finalize an in-progress 'git notes merge'. Use this option + when you have resolved the conflicts that 'git notes merge' + stored in .git/NOTES_MERGE_WORKTREE. This amends the partial + merge commit created by 'git notes merge' (stored in + .git/NOTES_MERGE_PARTIAL) by adding the notes in + .git/NOTES_MERGE_WORKTREE. The notes ref stored in the + .git/NOTES_MERGE_REF symref is updated to the resulting commit. + +--abort:: + Abort/reset a in-progress 'git notes merge', i.e. a notes merge + with conflicts. This simply removes all files related to the + notes merge. + +-q:: +--quiet:: + When merging notes, operate quietly. + +-v:: +--verbose:: + When merging notes, be more verbose. + When pruning notes, report all object names whose notes are + removed. + + +DISCUSSION +---------- + +Commit notes are blobs containing extra information about an object +(usually information to supplement a commit's message). These blobs +are taken from notes refs. A notes ref is usually a branch which +contains "files" whose paths are the object names for the objects +they describe, with some directory separators included for performance +reasons footnote:[Permitted pathnames have the form +'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory +names of two hexadecimal digits each followed by a filename with the +rest of the object ID.]. + +Every notes change creates a new commit at the specified notes ref. +You can therefore inspect the history of the notes by invoking, e.g., +`git log -p notes/commits`. Currently the commit message only records +which operation triggered the update, and the commit authorship is +determined according to the usual rules (see linkgit:git-commit[1]). +These details may change in the future. + +It is also permitted for a notes ref to point directly to a tree +object, in which case the history of the notes can be read with +`git log -p -g <refname>`. + + +NOTES MERGE STRATEGIES +---------------------- + +The default notes merge strategy is "manual", which checks out +conflicting notes in a special work tree for resolving notes conflicts +(`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the +conflicts in that work tree. +When done, the user can either finalize the merge with +'git notes merge --commit', or abort the merge with +'git notes merge --abort'. + +"ours" automatically resolves conflicting notes in favor of the local +version (i.e. the current notes ref). + +"theirs" automatically resolves notes conflicts in favor of the remote +version (i.e. the given notes ref being merged into the current notes +ref). + +"union" automatically resolves notes conflicts by concatenating the +local and remote versions. + +"cat_sort_uniq" is similar to "union", but in addition to concatenating +the local and remote versions, this strategy also sorts the resulting +lines, and removes duplicate lines from the result. This is equivalent +to applying the "cat | sort | uniq" shell pipeline to the local and +remote versions. This strategy is useful if the notes follow a line-based +format where one wants to avoid duplicated lines in the merge result. +Note that if either the local or remote version contain duplicate lines +prior to the merge, these will also be removed by this notes merge +strategy. + + +EXAMPLES +-------- + +You can use notes to add annotations with information that was not +available at the time a commit was written. + +------------ +$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 +$ git show -s 72a144e +[...] + Signed-off-by: Junio C Hamano <gitster@pobox.com> + +Notes: + Tested-by: Johannes Sixt <j6t@kdbg.org> +------------ + +In principle, a note is a regular Git blob, and any kind of +(non-)format is accepted. You can binary-safely create notes from +arbitrary files using 'git hash-object': + +------------ +$ cc *.c +$ blob=$(git hash-object -w a.out) +$ git notes --ref=built add -C "$blob" HEAD +------------ + +(You cannot simply use `git notes --ref=built add -F a.out HEAD` +because that is not binary-safe.) +Of course, it doesn't make much sense to display non-text-format notes +with 'git log', so if you use such notes, you'll probably need to write +some special-purpose tools to do something useful with them. + + +CONFIGURATION +------------- + +core.notesRef:: + Notes ref to read and manipulate instead of + `refs/notes/commits`. Must be an unabbreviated ref name. + This setting can be overridden through the environment and + command line. + +notes.displayRef:: + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages with the 'git log' family of commands. + This setting can be overridden on the command line or by the + 'GIT_NOTES_DISPLAY_REF' environment variable. + See linkgit:git-log[1]. + +notes.rewrite.<command>:: + When rewriting commits with <command> (currently `amend` or + `rebase`), if this variable is `false`, git will not copy + notes from the original to the rewritten commit. Defaults to + `true`. See also "`notes.rewriteRef`" below. ++ +This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' +environment variable. + +notes.rewriteMode:: + When copying notes during a rewrite, what to do if the target + commit already has a note. Must be one of `overwrite`, + `concatenate`, and `ignore`. Defaults to `concatenate`. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` +environment variable. + +notes.rewriteRef:: + When copying notes during a rewrite, specifies the (fully + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times. ++ +Does not have a default value; you must configure this variable to +enable note rewriting. ++ +Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. + + +ENVIRONMENT +----------- + +'GIT_NOTES_REF':: + Which ref to manipulate notes from, instead of `refs/notes/commits`. + This overrides the `core.notesRef` setting. + +'GIT_NOTES_DISPLAY_REF':: + Colon-delimited list of refs or globs indicating which refs, + in addition to the default from `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages. + This overrides the `notes.displayRef` setting. ++ +A warning will be issued for refs that do not exist, but a glob that +does not match any refs is silently ignored. + +'GIT_NOTES_REWRITE_MODE':: + When copying notes during a rewrite, what to do if the target + commit already has a note. + Must be one of `overwrite`, `concatenate`, and `ignore`. + This overrides the `core.rewriteMode` setting. + +'GIT_NOTES_REWRITE_REF':: + When rewriting commits, which notes to copy from the original + to the rewritten commit. Must be a colon-delimited list of + refs or globs. ++ +If not set in the environment, the list of notes to copy depends +on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. Author ------ -Written by Johannes Schindelin <johannes.schindelin@gmx.de> +Written by Johannes Schindelin <johannes.schindelin@gmx.de> and +Johan Herland <johan@herland.net> Documentation ------------- -Documentation by Johannes Schindelin +Documentation by Johannes Schindelin and Johan Herland GIT --- diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index f54d433d36..20c8551d6a 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -11,8 +11,8 @@ SYNOPSIS [verse] 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied] [--no-reuse-delta] [--delta-base-offset] [--non-empty] - [--local] [--incremental] [--window=N] [--depth=N] - [--revs [--unpacked | --all]*] [--stdout | base-name] + [--local] [--incremental] [--window=<n>] [--depth=<n>] + [--revs [--unpacked | --all]] [--stdout | base-name] [--keep-true-parents] < object-list @@ -21,27 +21,28 @@ DESCRIPTION Reads list of objects from the standard input, and writes a packed archive with specified base-name, or to the standard output. -A packed archive is an efficient way to transfer set of objects -between two repositories, and also is an archival format which -is efficient to access. The packed archive format (.pack) is -designed to be self contained so that it can be unpacked without -any further information, but for fast, random access to the objects -in the pack, a pack index file (.idx) will be generated. +A packed archive is an efficient way to transfer a set of objects +between two repositories as well as an access efficient archival +format. In a packed archive, an object is either stored as a +compressed whole or as a difference from some other object. +The latter is often called a delta. -Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or +The packed archive format (.pack) is designed to be self-contained +so that it can be unpacked without any further information. Therefore, +each object that a delta depends upon must be present within the pack. + +A pack index file (.idx) is generated for fast, random access to the +objects in the pack. Placing both the index file (.idx) and the packed +archive (.pack) in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) -enables git to read from such an archive. +enables git to read from the pack archive. -The 'git-unpack-objects' command can read the packed archive and +The 'git unpack-objects' command can read the packed archive and expand the objects contained in the pack into "one-file one-object" format; this is typically done by the smart-pull commands when a pack is created on-the-fly for efficient network transport by their peers. -In a packed archive, an object is either stored as a compressed -whole, or as a difference from some other object. The latter is -often called a delta. - OPTIONS ------- @@ -61,7 +62,7 @@ base-name:: --revs:: Read the revision arguments from the standard input, instead of individual object names. The revision arguments are processed - the same way as 'git-rev-list' with the `--objects` flag + the same way as 'git rev-list' with the `--objects` flag uses its `commit` arguments to build the list of objects it outputs. The objects on the resulting list are packed. @@ -73,7 +74,7 @@ base-name:: --all:: This implies `--revs`. In addition to the list of revision arguments read from the standard input, pretend - as if all refs under `$GIT_DIR/refs` are specified to be + as if all refs under `refs/` are specified to be included. --include-tag:: @@ -81,8 +82,8 @@ base-name:: reference was included in the resulting packfile. This can be useful to send new tags to native git clients. ---window=[N]:: ---depth=[N]:: +--window=<n>:: +--depth=<n>:: These two options affect how the objects contained in the pack are stored using delta compression. The objects are first internally sorted by type, size and @@ -94,10 +95,10 @@ base-name:: times to get to the necessary object. The default value for --window is 10 and --depth is 50. ---window-memory=[N]:: +--window-memory=<n>:: This option provides an additional limit on top of `--window`; the window size will dynamically scale down so as to not take - up more than N bytes in memory. This is useful in + up more than '<n>' bytes in memory. This is useful in repositories with a mix of large and small objects to not run out of memory with a large window, but still be able to take advantage of the large window for the smaller objects. The @@ -106,25 +107,25 @@ base-name:: default. --max-pack-size=<n>:: - Maximum size of each output packfile, expressed in MiB. + Maximum size of each output pack file. The size can be suffixed with + "k", "m", or "g". The minimum size allowed is limited to 1 MiB. If specified, multiple packfiles may be created. The default is unlimited, unless the config variable `pack.packSizeLimit` is set. --honor-pack-keep:: This flag causes an object already in a local pack that - has a .keep file to be ignored, even if it appears in the - standard input. + has a .keep file to be ignored, even if it would have + otherwise been packed. --incremental:: - This flag causes an object already in a pack ignored - even if it appears in the standard input. + This flag causes an object already in a pack to be ignored + even if it would have otherwise been packed. --local:: - This flag is similar to `--incremental`; instead of - ignoring all packed objects, it only ignores objects - that are packed and/or not in the local object store - (i.e. borrowed from an alternate). + This flag causes an object that is borrowed from an alternate + object store to be ignored even if it would have otherwise been + packed. --non-empty:: Only create a packed archive if it would contain at @@ -170,7 +171,7 @@ base-name:: wholesale enforcement of a different compression level on the packed data is desired. ---compression=[N]:: +--compression=<n>:: Specifies compression level for newly-compressed data in the generated pack. If not specified, pack compression level is determined first by pack.compression, then by core.compression, @@ -178,16 +179,31 @@ base-name:: Add --no-reuse-object if you want to force a uniform compression level on all data no matter the source. +--thin:: + Create a "thin" pack by omitting the common objects between a + sender and a receiver in order to reduce network transfer. This + option only makes sense in conjunction with --stdout. ++ +Note: A thin pack violates the packed archive format by omitting +required objects and is thus unusable by git without making it +self-contained. Use `git index-pack --fix-thin` +(see linkgit:git-index-pack[1]) to restore the self-contained property. + --delta-base-offset:: - A packed archive can express base object of a delta as - either 20-byte object name or as an offset in the - stream, but older version of git does not understand the - latter. By default, 'git-pack-objects' only uses the + A packed archive can express the base object of a delta as + either a 20-byte object name or as an offset in the + stream, but ancient versions of git don't understand the + latter. By default, 'git pack-objects' only uses the former format for better compatibility. This option allows the command to use the latter format for compactness. Depending on the average delta chain length, this option typically shrinks the resulting packfile by 3-5 per-cent. ++ +Note: Porcelain commands such as `git gc` (see linkgit:git-gc[1]), +`git repack` (see linkgit:git-repack[1]) pass this option by default +in modern git when they put objects in your repository into pack files. +So does `git bundle` (see linkgit:git-bundle[1]) when it creates a bundle. --threads=<n>:: Specifies the number of threads to spawn when searching for best @@ -208,15 +224,6 @@ base-name:: With this option, parents that are hidden by grafts are packed nevertheless. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation -------------- -Documentation by Junio C Hamano - SEE ALSO -------- linkgit:git-rev-list[1] diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index 5f9435e59b..f2869da572 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -8,6 +8,7 @@ git-pack-redundant - Find redundant pack files SYNOPSIS -------- +[verse] 'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > DESCRIPTION @@ -16,7 +17,7 @@ This program computes which packs in your repository are redundant. The output is suitable for piping to `xargs rm` if you are in the root of the repository. -'git-pack-redundant' accepts a list of objects on standard input. Any objects +'git pack-redundant' accepts a list of objects on standard input. Any objects given will be ignored when checking which packs are required. This makes the following command useful when wanting to remove packs which contain unreachable objects. @@ -38,14 +39,6 @@ OPTIONS --verbose:: Outputs some statistics to stderr. Has a small performance penalty. -Author ------- -Written by Lukas Sandström <lukass@etek.chalmers.se> - -Documentation --------------- -Documentation by Lukas Sandström <lukass@etek.chalmers.se> - SEE ALSO -------- linkgit:git-pack-objects[1] diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 1ee99c208c..a3c6677bfa 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -7,6 +7,7 @@ git-pack-refs - Pack heads and tags for efficient repository access SYNOPSIS -------- +[verse] 'git pack-refs' [--all] [--no-prune] DESCRIPTION @@ -56,11 +57,6 @@ 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. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt index 39d9daa7e0..a45ea1ece8 100644 --- a/Documentation/git-parse-remote.txt +++ b/Documentation/git-parse-remote.txt @@ -8,6 +8,7 @@ git-parse-remote - Routines to help parsing remote repository access parameters SYNOPSIS -------- +[verse] '. "$(git --exec-path)/git-parse-remote"' DESCRIPTION @@ -17,14 +18,6 @@ routines to parse files under $GIT_DIR/remotes/ and $GIT_DIR/branches/ and configuration variables that are related to fetching, pulling and pushing. -Author ------- -Written by Junio C Hamano. - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 253fc0fc25..90268f02e7 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -7,6 +7,7 @@ git-patch-id - Compute unique ID for a patch SYNOPSIS -------- +[verse] 'git patch-id' < <patch> DESCRIPTION @@ -18,7 +19,7 @@ ID" are almost guaranteed to be the same thing. IOW, you can use this thing to look for likely duplicate commits. -When dealing with 'git-diff-tree' output, it takes advantage of +When dealing with 'git diff-tree' output, it takes advantage of the fact that the patch is prefixed with the object name of the commit, and outputs two 40-byte hexadecimal strings. The first string is the patch ID, and the second string is the commit ID. @@ -29,14 +30,6 @@ OPTIONS <patch>:: The diff to create the ID of. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index 8282a5e82b..87ea3fb054 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -8,11 +8,12 @@ git-peek-remote - List the references in a remote repository SYNOPSIS -------- +[verse] 'git peek-remote' [--upload-pack=<git-upload-pack>] [<host>:]<directory> DESCRIPTION ----------- -This command is deprecated; use 'git-ls-remote' instead. +This command is deprecated; use 'git ls-remote' instead. OPTIONS ------- @@ -37,14 +38,6 @@ OPTIONS The repository to sync from. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index abfc6b6ead..80dc022ede 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -8,6 +8,7 @@ git-prune-packed - Remove extra objects that are already in pack files SYNOPSIS -------- +[verse] 'git prune-packed' [-n|--dry-run] [-q|--quiet] @@ -36,14 +37,6 @@ OPTIONS --quiet:: Squelch the progress indicator. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Ryan Anderson <ryan@michonline.com> - SEE ALSO -------- linkgit:git-pack-objects[1] diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index da6055d4b8..80d01b0571 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -8,21 +8,22 @@ git-prune - Prune all unreachable objects from the object database SYNOPSIS -------- -'git-prune' [-n] [-v] [--expire <expire>] [--] [<head>...] +[verse] +'git prune' [-n] [-v] [--expire <expire>] [--] [<head>...] DESCRIPTION ----------- -NOTE: In most cases, users should run 'git-gc', which calls -'git-prune'. See the section "NOTES", below. +NOTE: In most cases, users should run 'git gc', which calls +'git prune'. See the section "NOTES", below. -This runs 'git-fsck --unreachable' using all the refs -available in `$GIT_DIR/refs`, optionally with additional set of +This runs 'git fsck --unreachable' using all the refs +available in `refs/`, optionally with additional set of objects specified on the command line, and prunes all unpacked objects unreachable from any of these head objects from the object database. In addition, it prunes the unpacked objects that are also found in packs by -running 'git-prune-packed'. +running 'git prune-packed'. Note that unreachable, packed objects will remain. If this is not desired, see linkgit:git-repack[1]. @@ -31,10 +32,12 @@ OPTIONS ------- -n:: +--dry-run:: Do not remove anything; just report what it would remove. -v:: +--verbose:: Report all removed objects. \--:: @@ -62,12 +65,12 @@ $ git prune $(cd ../another && $(git rev-parse --all)) Notes ----- -In most cases, users will not need to call 'git-prune' directly, but -should instead call 'git-gc', which handles pruning along with +In most cases, users will not need to call 'git prune' directly, but +should instead call 'git gc', which handles pruning along with many other housekeeping tasks. For a description of which objects are considered for pruning, see -'git-fsck''s --unreachable option. +'git fsck''s --unreachable option. SEE ALSO -------- @@ -76,14 +79,6 @@ linkgit:git-fsck[1], linkgit:git-gc[1], linkgit:git-reflog[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index b93201158f..e1da468766 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -8,25 +8,92 @@ git-pull - Fetch from and merge with another repository or a local branch SYNOPSIS -------- -'git pull' <options> <repository> <refspec>... +[verse] +'git pull' [options] [<repository> [<refspec>...]] DESCRIPTION ----------- -Runs 'git-fetch' with the given parameters, and calls 'git-merge' -to merge the retrieved head(s) into the current branch. -With `--rebase`, calls 'git-rebase' instead of 'git-merge'. -Note that you can use `.` (current directory) as the -<repository> to pull from the local repository -- this is useful -when merging local branches into the current branch. +Incorporates changes from a remote repository into the current +branch. In its default mode, `git pull` is shorthand for +`git fetch` followed by `git merge FETCH_HEAD`. -Also note that options meant for 'git-pull' itself and underlying -'git-merge' must be given before the options meant for 'git-fetch'. +More precisely, 'git pull' runs 'git fetch' with the given +parameters and calls 'git merge' to merge the retrieved branch +heads into the current branch. +With `--rebase`, it runs 'git rebase' instead of 'git merge'. + +<repository> should be the name of a remote repository as +passed to linkgit:git-fetch[1]. <refspec> can name an +arbitrary remote ref (for example, the name of a tag) or even +a collection of refs with corresponding remote-tracking branches +(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}), +but usually it is the name of a branch in the remote repository. + +Default values for <repository> and <branch> are read from the +"remote" and "merge" configuration for the current branch +as set by linkgit:git-branch[1] `--track`. + +Assume the following history exists and the current branch is +"`master`": + +------------ + A---B---C master on origin + / + D---E---F---G master +------------ + +Then "`git pull`" will fetch and replay the changes from the remote +`master` branch since it diverged from the local `master` (i.e., `E`) +until its current commit (`C`) on top of `master` and record the +result in a new commit along with the names of the two parent commits +and a log message from the user describing the changes. + +------------ + A---B---C remotes/origin/master + / \ + D---E---F---G---H master +------------ + +See linkgit:git-merge[1] for details, including how conflicts +are presented and handled. + +In git 1.7.0 or later, to cancel a conflicting merge, use +`git reset --merge`. *Warning*: In older versions of git, running 'git pull' +with uncommitted changes is discouraged: while possible, it leaves you +in a state that may be hard to back out of in the case of a conflict. + +If any of the remote changes overlap with local uncommitted changes, +the merge will be automatically cancelled and the work tree untouched. +It is generally best to get any local changes in working order before +pulling or stash them away with linkgit:git-stash[1]. OPTIONS ------- +Options meant for 'git pull' itself and the underlying 'git merge' +must be given before the options meant for 'git fetch'. + +-q:: +--quiet:: + This is passed to both underlying git-fetch to squelch reporting of + during transfer, and underlying git-merge to squelch output during + merging. + +-v:: +--verbose:: + Pass --verbose to git-fetch and git-merge. + +--[no-]recurse-submodules[=yes|on-demand|no]:: + This option controls if new commits of all populated submodules should + be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]). + That might be necessary to get the data needed for merging submodule + commits, a feature git learned in 1.7.3. Notice that the result of a + merge will not be checked out in the submodule, "git submodule update" + has to be called afterwards to bring the work tree up to date with the + merge result. + Options related to merging ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -35,12 +102,15 @@ include::merge-options.txt[] :git-pull: 1 --rebase:: - Instead of a merge, perform a rebase after fetching. If - there is a remote ref for the upstream branch, and this branch - was rebased since last fetched, the rebase uses that information - to avoid rebasing non-local changes. To make this the default - for branch `<name>`, set configuration `branch.<name>.rebase` - to `true`. + Rebase the current branch on top of the upstream branch after + fetching. If there is a remote-tracking branch corresponding to + the upstream branch and the upstream branch was rebased since last + fetched, the rebase uses that information to avoid rebasing + non-local changes. ++ +See `branch.<name>.rebase` and `branch.autosetuprebase` in +linkgit:git-config[1] if you want to make `git pull` always use +`{litdd}rebase` instead of merging. + [NOTE] This is a potentially _dangerous_ mode of operation. @@ -77,7 +147,7 @@ and if there is not any such variable, the value on `URL: ` line in `$GIT_DIR/remotes/<origin>` file is used. In order to determine what remote branches to fetch (and -optionally store in the tracking branches) when the command is +optionally store in the remote-tracking branches) when the command is run without any refspec parameters on the command line, values of the configuration variable `remote.<origin>.fetch` are consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>` @@ -90,9 +160,9 @@ refs/heads/*:refs/remotes/origin/* ------------ A globbing refspec must have a non-empty RHS (i.e. must store -what were fetched in tracking branches), and its LHS and RHS +what were fetched in remote-tracking branches), and its LHS and RHS must end with `/*`. The above specifies that all remote -branches are tracked using tracking branches in +branches are tracked using remote-tracking branches in `refs/remotes/origin/` hierarchy under the same name. The rule to determine which remote branch to merge after @@ -148,25 +218,22 @@ $ git merge origin/next If you tried a pull which resulted in a complex conflicts and -would want to start over, you can recover with 'git-reset'. +would want to start over, you can recover with 'git reset'. +BUGS +---- +Using --recurse-submodules can only fetch new commits in already checked +out submodules right now. When e.g. upstream added a new submodule in the +just fetched commits of the superproject the submodule itself can not be +fetched, making it impossible to check out that submodule later without +having to do a fetch again. This is expected to be fixed in a future git +version. + SEE ALSO -------- linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -and Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Jon Loeliger, -David Greaves, -Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index e3eb1e8f19..aede48877f 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -10,8 +10,8 @@ SYNOPSIS -------- [verse] 'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [-v | --verbose] - [<repository> <refspec>...] + [--repo=<repository>] [-f | --force] [-v | --verbose] [-u | --set-upstream] + [<repository> [<refspec>...]] DESCRIPTION ----------- @@ -41,7 +41,7 @@ OPTIONS[[OPTIONS]] + The <src> is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as `master~4` or -`HEAD` (see linkgit:git-rev-parse[1]). +`HEAD` (see linkgit:gitrevisions[7]). + The <dst> tells which ref on the remote side is updated with this push. Arbitrary expressions cannot be used here, an actual ref must @@ -69,11 +69,11 @@ nor in any Push line of the corresponding remotes file---see below). --all:: Instead of naming each ref to push, specifies that all - refs under `$GIT_DIR/refs/heads/` be pushed. + refs under `refs/heads/` be pushed. --mirror:: Instead of naming each ref to push, specifies that all - refs under `$GIT_DIR/refs/` (which includes but is not + refs under `refs/` (which includes but is not limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`) be mirrored to the remote repository. Newly created local refs will be pushed to the remote end, locally updated refs @@ -96,7 +96,7 @@ nor in any Push line of the corresponding remotes file---see below). the same as prefixing all refs with a colon. --tags:: - All refs under `$GIT_DIR/refs/tags` are pushed, in + All refs under `refs/tags` are pushed, in addition to refspecs explicitly listed on the command line. @@ -116,7 +116,7 @@ nor in any Push line of the corresponding remotes file---see below). --repo=<repository>:: This option is only relevant if no <repository> argument is - passed in the invocation. In this case, 'git-push' derives the + passed in the invocation. In this case, 'git push' derives the remote name from the current branch: If it tracks a remote branch, then that remote repository is pushed to. Otherwise, the name "origin" is used. For this latter case, this option @@ -130,22 +130,43 @@ git push --repo=public #2 + is that #1 always pushes to "public" whereas #2 pushes to "public" only if the current branch does not track a remote branch. This is -useful if you write an alias or script around 'git-push'. +useful if you write an alias or script around 'git push'. + +-u:: +--set-upstream:: + For every branch that is up to date or successfully pushed, add + upstream (tracking) reference, used by argument-less + linkgit:git-pull[1] and other commands. For more information, + see 'branch.<name>.merge' in linkgit:git-config[1]. --thin:: --no-thin:: - These options are passed to 'git-send-pack'. Thin - transfer spends extra cycles to minimize the number of - objects to be sent and meant to be used on slower connection. + These options are passed to linkgit:git-send-pack[1]. A thin transfer + significantly reduces the amount of sent data when the sender and + receiver share many of the same objects in common. The default is + \--thin. + +-q:: +--quiet:: + Suppress all output, including the listing of updated refs, + unless an error occurs. Progress is not reported to the standard + error stream. -v:: --verbose:: Run verbosely. --q:: ---quiet:: - Suppress all output, including the listing of updated refs, - unless an error occurs. +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if the + standard error stream is not directed to a terminal. + +--recurse-submodules=check:: + Check whether all submodule commits used by the revisions to be + pushed are available on a remote tracking branch. Otherwise the + push will be aborted and the command will exit with non-zero status. + include::urls-remotes.txt[] @@ -169,27 +190,45 @@ If --porcelain is used, then each line of the output is of the form: <flag> \t <from>:<to> \t <summary> (<reason>) ------------------------------- +The status of up-to-date refs is shown only if --porcelain or --verbose +option is used. + flag:: - A single character indicating the status of the ref. This is - blank for a successfully pushed ref, `!` for a ref that was - rejected or failed to push, and '=' for a ref that was up to - date and did not need pushing (note that the status of up to - date refs is shown only when `git push` is running verbosely). + A single character indicating the status of the ref: +(space);; for a successfully pushed fast-forward; +`{plus}`;; for a successful forced update; +`-`;; for a successfully deleted ref; +`*`;; for a successfully pushed new ref; +`!`;; for a ref that was rejected or failed to push; and +`=`;; for a ref that was up to date and did not need pushing. summary:: For a successfully pushed ref, the summary shows the old and new values of the ref in a form suitable for using as an argument to `git log` (this is `<old>..<new>` in most cases, and - `<old>...<new>` for forced non-fast-forward updates). For a - failed update, more details are given for the failure. - The string `rejected` indicates that git did not try to send the - ref at all (typically because it is not a fast-forward). The - string `remote rejected` indicates that the remote end refused - the update; this rejection is typically caused by a hook on the - remote side. The string `remote failure` indicates that the - remote end did not report the successful update of the ref - (perhaps because of a temporary error on the remote side, a - break in the network connection, or other transient error). + `<old>\...<new>` for forced non-fast-forward updates). ++ +For a failed update, more details are given: ++ +-- +rejected:: + Git did not try to send the ref at all, typically because it + is not a fast-forward and you did not force the update. + +remote rejected:: + The remote end refused the update. Usually caused by a hook + on the remote side, or because the remote repository has one + of the following safety options in effect: + `receive.denyCurrentBranch` (for pushes to the checked out + branch), `receive.denyNonFastForwards` (for forced + non-fast-forward updates), `receive.denyDeletes` or + `receive.denyDeleteCurrent`. See linkgit:git-config[1]. + +remote failure:: + The remote end did not report the successful update of the ref, + perhaps because of a temporary error on the remote side, a + break in the network connection, or other transient error. +-- from:: The name of the local ref being pushed, minus its @@ -294,12 +333,12 @@ a case where you do mean to lose history. Examples -------- -git push:: +`git push`:: Works like `git push <remote>`, where <remote> is the current branch's remote (or `origin`, if no remote is configured for the current branch). -git push origin:: +`git push origin`:: Without additional configuration, works like `git push origin :`. + @@ -311,45 +350,45 @@ use `git config remote.origin.push HEAD`. Any valid <refspec> (like the ones in the examples below) can be configured as the default for `git push origin`. -git push origin ::: +`git push origin :`:: Push "matching" branches to `origin`. See <refspec> in the <<OPTIONS,OPTIONS>> section above for a description of "matching" branches. -git push origin master:: +`git push origin master`:: Find a ref that matches `master` in the source repository (most likely, it would find `refs/heads/master`), and update the same ref (e.g. `refs/heads/master`) in `origin` repository with it. If `master` did not exist remotely, it would be created. -git push origin HEAD:: +`git push origin HEAD`:: A handy way to push the current branch to the same name on the remote. -git push origin master:satellite/master dev:satellite/dev:: +`git push origin master:satellite/master dev:satellite/dev`:: Use the source ref that matches `master` (e.g. `refs/heads/master`) to update the ref that matches `satellite/master` (most probably `refs/remotes/satellite/master`) in the `origin` repository, then do the same for `dev` and `satellite/dev`. -git push origin HEAD:master:: +`git push origin HEAD:master`:: Push the current branch to the remote ref matching `master` in the `origin` repository. This form is convenient to push the current branch without thinking about its local name. -git push origin master:refs/heads/experimental:: +`git push origin master:refs/heads/experimental`:: Create the branch `experimental` in the `origin` repository by copying the current `master` branch. This form is only needed to create a new branch or tag in the remote repository when the local name and the remote name are different; otherwise, the ref name on its own will work. -git push origin :experimental:: +`git push origin :experimental`:: Find a ref that matches `experimental` in the `origin` repository (e.g. `refs/heads/experimental`), and delete it. -git push origin {plus}dev:master:: +`git push origin {plus}dev:master`:: Update the origin repository's master branch with the dev branch, allowing non-fast-forward updates. *This can leave unreferenced commits dangling in the origin repository.* Consider the @@ -373,16 +412,6 @@ Commits A and B would no longer belong to a branch with a symbolic name, and so would be unreachable. As such, these commits would be removed by a `git gc` command on the origin repository. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C -by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index 579e8d2f3b..7f112f3dcd 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -49,14 +49,6 @@ The default for the patch directory is patches or the value of the $QUILT_PATCHES environment variable. -Author ------- -Written by Eric Biederman <ebiederm@lnxi.com> - -Documentation --------------- -Documentation by Eric Biederman <ebiederm@lnxi.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index d6faa14149..5375549820 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,10 +8,11 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- +[verse] 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--index-output=<file>] [--no-sparse-checkout] - <tree-ish1> [<tree-ish2> [<tree-ish3>]] + (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -25,8 +26,8 @@ fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m` flag. When used with `-m`, the `-u` flag causes it to also update the files in the work tree with the result of the merge. -Trivial merges are done by 'git-read-tree' itself. Only conflicting paths -will be in unmerged state when 'git-read-tree' returns. +Trivial merges are done by 'git read-tree' itself. Only conflicting paths +will be in unmerged state when 'git read-tree' returns. OPTIONS ------- @@ -46,40 +47,45 @@ OPTIONS -i:: Usually a merge requires the index file as well as the - files in the working tree are up to date with the + files in the working tree to be up to date with the current head commit, in order not to lose local changes. This flag disables the check with the working tree and is meant to be used when creating a merge of trees that are not directly related to the current working tree status into a temporary index file. +-n:: +--dry-run:: + Check if the command would error out, without updating the index + nor the files in the working tree for real. + -v:: Show the progress of checking files out. --trivial:: - Restrict three-way merge by 'git-read-tree' to happen + Restrict three-way merge by 'git read-tree' to happen only if there is no file-level merging required, instead of resolving merge for trivial cases and leaving conflicting files unresolved in the index. --aggressive:: - Usually a three-way merge by 'git-read-tree' resolves + Usually a three-way merge by 'git read-tree' resolves the merge for really trivial cases and leaves other - cases unresolved in the index, so that Porcelains can + cases unresolved in the index, so that porcelains can implement different merge policies. This flag makes the - command to resolve a few more cases internally: + command resolve a few more cases internally: + * when one side removes a path and the other side leaves the path unmodified. The resolution is to remove that path. * when both sides remove a path. The resolution is to remove that path. -* when both sides adds a path identically. The resolution +* when both sides add a path identically. The resolution is to add that path. --prefix=<prefix>/:: Keep the current index contents, and read the contents - of named tree-ish under directory at `<prefix>`. The + of the named tree-ish under the directory at `<prefix>`. The original index file cannot have anything at the path - `<prefix>` itself, and have nothing in `<prefix>/` + `<prefix>` itself, nor anything in the `<prefix>/` directory. Note that the `<prefix>/` value must end with a slash. @@ -114,13 +120,17 @@ OPTIONS Disable sparse checkout support even if `core.sparseCheckout` is true. +--empty:: + Instead of reading tree object(s) into the index, just empty + it. + <tree-ish#>:: The id of the tree object(s) to be read/merged. Merging ------- -If `-m` is specified, 'git-read-tree' can perform 3 kinds of +If `-m` is specified, 'git read-tree' can perform 3 kinds of merge, a single tree merge if only 1 tree is given, a fast-forward merge with 2 trees, or a 3-way merge if 3 trees are provided. @@ -128,18 +138,18 @@ provided. Single Tree Merge ~~~~~~~~~~~~~~~~~ -If only 1 tree is specified, 'git-read-tree' operates as if the user did not +If only 1 tree is specified, 'git read-tree' operates as if the user did not specify `-m`, except that if the original index has an entry for a -given pathname, and the contents of the path matches with the tree +given pathname, and the contents of the path match with the tree being read, the stat info from the index is used. (In other words, the index's stat()s take precedence over the merged tree's). That means that if you do a `git read-tree -m <newtree>` followed by a -`git checkout-index -f -u -a`, the 'git-checkout-index' only checks out +`git checkout-index -f -u -a`, the 'git checkout-index' only checks out the stuff that really changed. -This is used to avoid unnecessary false hits when 'git-diff-files' is -run after 'git-read-tree'. +This is used to avoid unnecessary false hits when 'git diff-files' is +run after 'git read-tree'. Two Tree Merge @@ -150,44 +160,46 @@ is the head commit of the current repository, and $M is the head of a foreign tree, which is simply ahead of $H (i.e. we are in a fast-forward situation). -When two trees are specified, the user is telling 'git-read-tree' +When two trees are specified, the user is telling 'git read-tree' the following: 1. The current index and work tree is derived from $H, but - the user may have local changes in them since $H; + the user may have local changes in them since $H. 2. The user wants to fast-forward to $M. In this case, the `git read-tree -m $H $M` command makes sure that no local change is lost as the result of this "merge". -Here are the "carry forward" rules: +Here are the "carry forward" rules, where "I" denotes the index, +"clean" means that index and work tree coincide, and "exists"/"nothing" +refer to the presence of a path in the specified commit: - I (index) H M Result + I H M Result ------------------------------------------------------- - 0 nothing nothing nothing (does not happen) - 1 nothing nothing exists use M - 2 nothing exists nothing remove path from index - 3 nothing exists exists, use M if "initial checkout" + 0 nothing nothing nothing (does not happen) + 1 nothing nothing exists use M + 2 nothing exists nothing remove path from index + 3 nothing exists exists, use M if "initial checkout", H == M keep index otherwise - exists fail + exists, fail H != M clean I==H I==M ------------------ - 4 yes N/A N/A nothing nothing keep index - 5 no N/A N/A nothing nothing keep index + 4 yes N/A N/A nothing nothing keep index + 5 no N/A N/A nothing nothing keep index - 6 yes N/A yes nothing exists keep index - 7 no N/A yes nothing exists keep index - 8 yes N/A no nothing exists fail - 9 no N/A no nothing exists fail + 6 yes N/A yes nothing exists keep index + 7 no N/A yes nothing exists keep index + 8 yes N/A no nothing exists fail + 9 no N/A no nothing exists fail 10 yes yes N/A exists nothing remove path from index 11 no yes N/A exists nothing fail 12 yes no N/A exists nothing fail 13 no no N/A exists nothing fail - clean (H=M) + clean (H==M) ------ 14 yes exists exists keep index 15 no exists exists keep index @@ -202,26 +214,26 @@ Here are the "carry forward" rules: 21 no yes no exists exists fail In all "keep index" cases, the index entry stays as in the -original index file. If the entry were not up to date, -'git-read-tree' keeps the copy in the work tree intact when +original index file. If the entry is not up to date, +'git read-tree' keeps the copy in the work tree intact when operating under the -u flag. -When this form of 'git-read-tree' returns successfully, you can -see what "local changes" you made are carried forward by running +When this form of 'git read-tree' returns successfully, you can +see which of the "local changes" that you made were carried forward by running `git diff-index --cached $M`. Note that this does not -necessarily match `git diff-index --cached $H` would have +necessarily match what `git diff-index --cached $H` would have produced before such a two tree merge. This is because of cases 18 and 19 --- if you already had the changes in $M (e.g. maybe you picked it up via e-mail in a patch form), `git diff-index --cached $H` would have told you about the change before this merge, but it would not show in `git diff-index --cached $M` -output after two-tree merge. +output after the two-tree merge. -Case #3 is slightly tricky and needs explanation. The result from this +Case 3 is slightly tricky and needs explanation. The result from this rule logically should be to remove the path if the user staged the removal of the path and then switching to a new branch. That however will prevent the initial checkout from happening, so the rule is modified to use M (new -tree) only when the contents of the index is empty. Otherwise the removal +tree) only when the content of the index is empty. Otherwise the removal of the path is kept as long as $H and $M are the same. 3-Way Merge @@ -229,7 +241,7 @@ of the path is kept as long as $H and $M are the same. Each "index" entry has two bits worth of "stage" state. stage 0 is the normal one, and is the only one you'd see in any kind of normal use. -However, when you do 'git-read-tree' with three trees, the "stage" +However, when you do 'git read-tree' with three trees, the "stage" starts out at 1. This means that you can do @@ -245,7 +257,7 @@ branch into the current branch, we use the common ancestor tree as <tree1>, the current branch head as <tree2>, and the other branch head as <tree3>. -Furthermore, 'git-read-tree' has special-case logic that says: if you see +Furthermore, 'git read-tree' has special-case logic that says: if you see a file that matches in all respects in the following states, it "collapses" back to "stage0": @@ -261,7 +273,7 @@ a file that matches in all respects in the following states, it - stage 1 and stage 3 are the same and stage 2 is different take stage 2 (we did something while they did nothing) -The 'git-write-tree' command refuses to write a nonsensical tree, and it +The 'git write-tree' command refuses to write a nonsensical tree, and it will complain about unmerged entries if it sees a single entry that is not stage 0. @@ -277,7 +289,7 @@ start a 3-way merge with an index file that is already populated. Here is an outline of how the algorithm works: - if a file exists in identical format in all three trees, it will - automatically collapse to "merged" state by 'git-read-tree'. + automatically collapse to "merged" state by 'git read-tree'. - a file that has _any_ difference what-so-ever in the three trees will stay as separate entries in the index. It's up to "porcelain @@ -301,8 +313,8 @@ populated. Here is an outline of how the algorithm works: matching "stage1" entry if it exists too. .. all the normal trivial rules .. -You would normally use 'git-merge-index' with supplied -'git-merge-one-file' to do this last step. The script updates +You would normally use 'git merge-index' with supplied +'git merge-one-file' to do this last step. The script updates the files in the working tree as it merges each path and at the end of a successful merge. @@ -324,7 +336,7 @@ $ JC=`git rev-parse --verify "HEAD^0"` $ git checkout-index -f -u -a $JC ---------------- -You do random edits, without running 'git-update-index'. And then +You do random edits, without running 'git update-index'. And then you notice that the tip of your "upstream" tree has advanced since you pulled from him: @@ -350,14 +362,14 @@ your work-in-progress changes, and your work tree would be updated to the result of the merge. However, if you have local changes in the working tree that -would be overwritten by this merge, 'git-read-tree' will refuse +would be overwritten by this merge, 'git read-tree' will refuse to run to prevent your changes from being lost. In other words, there is no need to worry about what exists only in the working tree. When you have local changes in a part of the project that is not involved in the merge, your changes do not interfere with the merge, and are kept intact. When they -*do* interfere, the merge does not even start ('git-read-tree' +*do* interfere, the merge does not even start ('git read-tree' complains loudly and fails without modifying anything). In such a case, you can simply continue doing what you were in the middle of doing, and when your working tree is ready (i.e. you @@ -367,45 +379,45 @@ have finished your work-in-progress), attempt the merge again. Sparse checkout --------------- -"Sparse checkout" allows to sparsely populate working directory. -It uses skip-worktree bit (see linkgit:git-update-index[1]) to tell -Git whether a file on working directory is worth looking at. +"Sparse checkout" allows populating the working directory sparsely. +It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell +Git whether a file in the working directory is worth looking at. -"git read-tree" and other merge-based commands ("git merge", "git -checkout"...) can help maintaining skip-worktree bitmap and working +'git read-tree' and other merge-based commands ('git merge', 'git +checkout'...) can help maintaining the skip-worktree bitmap and working directory update. `$GIT_DIR/info/sparse-checkout` is used to -define the skip-worktree reference bitmap. When "git read-tree" needs -to update working directory, it will reset skip-worktree bit in index +define the skip-worktree reference bitmap. When 'git read-tree' needs +to update the working directory, it resets the skip-worktree bit in the index based on this file, which uses the same syntax as .gitignore files. -If an entry matches a pattern in this file, skip-worktree will be -set on that entry. Otherwise, skip-worktree will be unset. +If an entry matches a pattern in this file, skip-worktree will not be +set on that entry. Otherwise, skip-worktree will be set. Then it compares the new skip-worktree value with the previous one. If -skip-worktree turns from unset to set, it will add the corresponding -file back. If it turns from set to unset, that file will be removed. +skip-worktree turns from set to unset, it will add the corresponding +file back. If it turns from unset to set, that file will be removed. While `$GIT_DIR/info/sparse-checkout` is usually used to specify what -files are in. You can also specify what files are _not_ in, using -negate patterns. For example, to remove file "unwanted": +files are in, you can also specify what files are _not_ in, using +negate patterns. For example, to remove the file `unwanted`: ---------------- -* +/* !unwanted ---------------- -Another tricky thing is fully repopulating working directory when you +Another tricky thing is fully repopulating the working directory when you no longer want sparse checkout. You cannot just disable "sparse -checkout" because skip-worktree are still in the index and you working -directory is still sparsely populated. You should re-populate working +checkout" because skip-worktree bits are still in the index and your working +directory is still sparsely populated. You should re-populate the working directory with the `$GIT_DIR/info/sparse-checkout` file content as follows: ---------------- -* +/* ---------------- -Then you can disable sparse checkout. Sparse checkout support in "git -read-tree" and similar commands is disabled by default. You need to +Then you can disable sparse checkout. Sparse checkout support in 'git +read-tree' and similar commands is disabled by default. You need to turn `core.sparseCheckout` on in order to have sparse checkout support. @@ -415,15 +427,6 @@ SEE ALSO linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; linkgit:gitignore[5] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index ca5e1e8653..504945c691 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -9,18 +9,23 @@ SYNOPSIS -------- [verse] 'git rebase' [-i | --interactive] [options] [--onto <newbase>] - <upstream> [<branch>] + [<upstream>] [<branch>] 'git rebase' [-i | --interactive] [options] --onto <newbase> --root [<branch>] - 'git rebase' --continue | --skip | --abort DESCRIPTION ----------- -If <branch> is specified, 'git-rebase' will perform an automatic +If <branch> is specified, 'git rebase' will perform an automatic `git checkout <branch>` before doing anything else. Otherwise it remains on the current branch. +If <upstream> is not specified, the upstream configured in +branch.<name>.remote and branch.<name>.merge options will be used; see +linkgit:git-config[1] for details. If you are currently not on any +branch or if the current branch does not have a configured upstream, +the rebase will abort. + All changes made by commits in the current branch but that are not in <upstream> are saved to a temporary area. This is the same set of commits that would be shown by `git log <upstream>..HEAD` (or @@ -40,7 +45,7 @@ with a different commit message or timestamp will be skipped). It is possible that a merge failure will prevent this process from being completely automatic. You will have to resolve any such merge failure and run `git rebase --continue`. Another option is to bypass the commit -that caused the merge failure with `git rebase --skip`. To restore the +that caused the merge failure with `git rebase --skip`. To check out the original <branch> and remove the .git/rebase-apply working files, use the command `git rebase --abort` instead. @@ -66,8 +71,9 @@ would be: D---E---F---G master ------------ -The latter form is just a short-hand of `git checkout topic` -followed by `git rebase master`. +*NOTE:* The latter form is just a short-hand of `git checkout topic` +followed by `git rebase master`. When rebase exits `topic` will +remain the checked-out branch. If the upstream branch already contains a change you have made (e.g., because you mailed a patch which was applied upstream), then that commit @@ -170,8 +176,8 @@ This is useful if F and G were flawed in some way, or should not be part of topicA. Note that the argument to --onto and the <upstream> parameter can be any valid commit-ish. -In case of conflict, 'git-rebase' will stop at the first problematic commit -and leave conflict markers in the tree. You can use 'git-diff' to locate +In case of conflict, 'git rebase' will stop at the first problematic commit +and leave conflict markers in the tree. You can use 'git diff' to locate the markers (<<<<<<) and make edits to resolve the conflict. For each file you edit, you need to tell git that the conflict has been resolved, typically this would be done with @@ -187,7 +193,7 @@ desired resolution, you can continue the rebasing process with git rebase --continue -Alternatively, you can undo the 'git-rebase' with +Alternatively, you can undo the 'git rebase' with git rebase --abort @@ -199,6 +205,9 @@ rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. +rebase.autosquash:: + If set to true enable '--autosquash' option by default. + OPTIONS ------- <newbase>:: @@ -206,10 +215,15 @@ OPTIONS --onto option is not specified, the starting point is <upstream>. May be any valid commit, and not just an existing branch name. ++ +As a special case, you may use "A\...B" as a shortcut for the +merge base of A and B if there is exactly one merge base. You can +leave out at most one of A and B, in which case it defaults to HEAD. <upstream>:: Upstream branch to compare against. May be any valid commit, - not just an existing branch name. + not just an existing branch name. Defaults to the configured + upstream for the current branch. <branch>:: Working branch; defaults to HEAD. @@ -218,7 +232,11 @@ OPTIONS Restart the rebasing process after having resolved a merge conflict. --abort:: - Restore the original branch and abort the rebase operation. + Abort the rebase operation and reset HEAD to the original + branch. If <branch> was provided when the rebase operation was + started, then HEAD will be reset to <branch>. Otherwise HEAD + will be reset to where it was when the rebase operation was + started. --skip:: Restart the rebasing process by skipping the current patch. @@ -238,14 +256,21 @@ other words, the sides are swapped. -s <strategy>:: --strategy=<strategy>:: Use the given merge strategy. - If there is no `-s` option 'git-merge-recursive' is used + If there is no `-s` option 'git merge-recursive' is used instead. This implies --merge. + -Because 'git-rebase' replays each commit from the working branch +Because 'git rebase' replays each commit from the working branch on top of the <upstream> branch using the given strategy, using the 'ours' strategy simply discards all patches from the <branch>, which makes little sense. +-X <strategy-option>:: +--strategy-option=<strategy-option>:: + Pass the <strategy-option> through to the merge strategy. + This implies `\--merge` and, if no strategy has been + specified, `-s recursive`. Note the reversal of 'ours' and + 'theirs' as noted in above for the `-m` option. + -q:: --quiet:: Be quiet. Implies --no-stat. @@ -265,6 +290,10 @@ which makes little sense. --no-verify:: This option bypasses the pre-rebase hook. See also linkgit:githooks[5]. +--verify:: + Allows the pre-rebase hook to run, which is the default. This option can + be used to override --no-verify. See also linkgit:githooks[5]. + -C<n>:: Ensure at least <n> lines of surrounding context match before and after each change. When fewer lines of surrounding @@ -274,20 +303,28 @@ which makes little sense. -f:: --force-rebase:: Force the rebase even if the current branch is a descendant - of the commit you are rebasing onto. Normally the command will + of the commit you are rebasing onto. Normally non-interactive rebase will exit with the message "Current branch is up to date" in such a situation. + Incompatible with the --interactive option. ++ +You may find this (or --no-ff with an interactive rebase) helpful after +reverting a topic branch merge, as this option recreates the topic branch with +fresh commits so it can be remerged successfully without needing to "revert +the reversion" (see the +link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). --ignore-whitespace:: --whitespace=<option>:: - These flag are passed to the 'git-apply' program + These flag are passed to the 'git apply' program (see linkgit:git-apply[1]) that applies the patch. Incompatible with the --interactive option. --committer-date-is-author-date:: --ignore-date:: - These flags are passed to 'git-am' to easily change the dates + These flags are passed to 'git am' to easily change the dates of the rebased commits (see linkgit:git-am[1]). + Incompatible with the --interactive option. -i:: --interactive:: @@ -298,6 +335,11 @@ which makes little sense. -p:: --preserve-merges:: Instead of ignoring merges, try to recreate them. ++ +This uses the `--interactive` machinery internally, but combining it +with the `--interactive` option explicitly is generally not a good +idea unless you know what you are doing (see BUGS below). + --root:: Rebase all commits reachable from <branch>, instead of @@ -308,12 +350,39 @@ which makes little sense. root commits will be rewritten to have <newbase> as parent instead. +--autosquash:: +--no-autosquash:: + When the commit log message begins with "squash! ..." (or + "fixup! ..."), and there is a commit whose title begins with + the same ..., automatically modify the todo list of rebase -i + so that the commit marked for squashing comes right after the + commit to be modified, and change the action of the moved + commit from `pick` to `squash` (or `fixup`). ++ +This option is only valid when the '--interactive' option is used. ++ +If the '--autosquash' option is enabled by default using the +configuration variable `rebase.autosquash`, this option can be +used to override and disable this setting. + +--no-ff:: + With --interactive, cherry-pick all rebased commits instead of + fast-forwarding over the unchanged ones. This ensures that the + entire history of the rebased branch is composed of new commits. ++ +Without --interactive, this is a synonym for --force-rebase. ++ +You may find this helpful after reverting a topic branch merge, as this option +recreates the topic branch with fresh commits so it can be remerged +successfully without needing to "revert the reversion" (see the +link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). + include::merge-strategies.txt[] NOTES ----- -You should understand the implications of using 'git-rebase' on a +You should understand the implications of using 'git rebase' on a repository that you share. See also RECOVERING FROM UPSTREAM REBASE below. @@ -369,12 +438,12 @@ pick fa1afe1 The oneline of the next commit ... ------------------------------------------- -The oneline descriptions are purely for your pleasure; 'git-rebase' will +The oneline descriptions are purely for your pleasure; 'git rebase' will not look at them but at the commit names ("deadbee" and "fa1afe1" in this example), so do not delete or edit the names. By replacing the command "pick" with the command "edit", you can tell -'git-rebase' to stop after applying that commit, so that you can edit +'git rebase' to stop after applying that commit, so that you can edit the files and/or the commit message, amend the commit, and continue rebasing. @@ -382,17 +451,20 @@ If you just want to edit the commit message for a commit, replace the command "pick" with the command "reword". If you want to fold two or more commits into one, replace the command -"pick" with "squash" for the second and subsequent commit. If the -commits had different authors, it will attribute the squashed commit to -the author of the first commit. - -'git-rebase' will stop when "pick" has been replaced with "edit" or +"pick" for the second and subsequent commits with "squash" or "fixup". +If the commits had different authors, the folded commit will be +attributed to the author of the first commit. The suggested commit +message for the folded commit is the concatenation of the commit +messages of the first commit and of those with the "squash" command, +but omits the commit messages of commits with the "fixup" command. + +'git rebase' will stop when "pick" has been replaced with "edit" or when a command fails due to merge errors. When you are done editing and/or resolving conflicts you can continue with `git rebase --continue`. For example, if you want to reorder the last 5 commits, such that what was HEAD~4 becomes the new HEAD. To achieve that, you would call -'git-rebase' like this: +'git rebase' like this: ---------------------- $ git rebase -i HEAD~5 @@ -417,12 +489,36 @@ sure that the current HEAD is "B", and call $ git rebase -i -p --onto Q O ----------------------------- +Reordering and editing commits usually creates untested intermediate +steps. You may want to check that your history editing did not break +anything by running a test, or at least recompiling at intermediate +points in history by using the "exec" command (shortcut "x"). You may +do so by creating a todo list like this one: + +------------------------------------------- +pick deadbee Implement feature XXX +fixup f1a5c00 Fix to feature XXX +exec make +pick c0ffeee The oneline of the next commit +edit deadbab The oneline of the commit after +exec cd subdir; make test +... +------------------------------------------- + +The interactive rebase will stop when a command fails (i.e. exits with +non-0 status) to give you an opportunity to fix the problem. You can +continue with `git rebase --continue`. + +The "exec" command launches the command in a shell (the one specified +in `$SHELL`, or the default shell if `$SHELL` is not set), so you can +use shell features (like "cd", ">", ";" ...). The command is run from +the root of the working tree. SPLITTING COMMITS ----------------- In interactive mode, you can mark commits with the action "edit". However, -this does not necessarily mean that 'git-rebase' expects the result of this +this does not necessarily mean that 'git rebase' expects the result of this edit to be exactly one commit. Indeed, you can undo the commit, or you can add other commits. This can be used to split a commit into two: @@ -438,7 +534,7 @@ add other commits. This can be used to split a commit into two: - Now add the changes to the index that you want to have in the first commit. You can use `git add` (possibly interactively) or - 'git-gui' (or both) to do that. + 'git gui' (or both) to do that. - Commit the now-current index with whatever commit message is appropriate now. @@ -449,7 +545,7 @@ add other commits. This can be used to split a commit into two: If you are not absolutely sure that the intermediate revisions are consistent (they compile, pass the testsuite, etc.) you should use -'git-stash' to stash away the not-yet-committed changes +'git stash' to stash away the not-yet-committed changes after each commit, test, and amend the commit if fixes are necessary. @@ -512,8 +608,8 @@ Easy case: The changes are literally the same.:: Hard case: The changes are not the same.:: This happens if the 'subsystem' rebase had conflicts, or used - `\--interactive` to omit, edit, or squash commits; or if the - upstream used one of `commit \--amend`, `reset`, or + `\--interactive` to omit, edit, squash, or fixup commits; or + if the upstream used one of `commit \--amend`, `reset`, or `filter-branch`. @@ -524,7 +620,7 @@ Only works if the changes (patch IDs based on the diff contents) on 'subsystem' are literally the same before and after the rebase 'subsystem' did. -In that case, the fix is easy because 'git-rebase' knows to skip +In that case, the fix is easy because 'git rebase' knows to skip changes that are already present in the new upstream. So if you say (assuming you're on 'topic') ------------ @@ -551,12 +647,12 @@ NOTE: While an "easy case recovery" sometimes appears to be successful example, a commit that was removed via `git rebase \--interactive` will be **resurrected**! -The idea is to manually tell 'git-rebase' "where the old 'subsystem' +The idea is to manually tell 'git rebase' "where the old 'subsystem' ended and your 'topic' began", that is, what the old merge-base between them was. You will have to find a way to name the last commit of the old 'subsystem', for example: -* With the 'subsystem' reflog: after 'git-fetch', the old tip of +* With the 'subsystem' reflog: after 'git fetch', the old tip of 'subsystem' is at `subsystem@\{1}`. Subsequent fetches will increase the number. (See linkgit:git-reflog[1].) @@ -573,15 +669,27 @@ The ripple effect of a "hard case" recovery is especially bad: 'everyone' downstream from 'topic' will now have to perform a "hard case" recovery too! +BUGS +---- +The todo list presented by `--preserve-merges --interactive` does not +represent the topology of the revision graph. Editing commits and +rewording their commit messages should work fine, but attempts to +reorder commits tend to produce counterintuitive results. -Authors ------- -Written by Junio C Hamano <gitster@pobox.com> and -Johannes E. Schindelin <johannes.schindelin@gmx.de> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +For example, an attempt to rearrange +------------ +1 --- 2 --- 3 --- 4 --- 5 +------------ +to +------------ +1 --- 2 --- 4 --- 3 --- 5 +------------ +by moving the "pick 4" line will result in the following history: +------------ + 3 + / +1 --- 2 --- 4 --- 5 +------------ GIT --- diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index cb5f405280..b1f7dc643a 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -8,15 +8,16 @@ git-receive-pack - Receive what is pushed into the repository SYNOPSIS -------- -'git receive-pack' <directory> +[verse] +'git-receive-pack' <directory> DESCRIPTION ----------- -Invoked by 'git-send-pack' and updates the repository with the +Invoked by 'git send-pack' and updates the repository with the information fed from the remote end. This command is usually not invoked directly by the end user. -The UI for the protocol is on the 'git-send-pack' side, and the +The UI for the protocol is on the 'git send-pack' side, and the program pair is meant to be used to push updates to remote repository. For pull operations, see linkgit:git-fetch-pack[1]. @@ -149,16 +150,7 @@ if the repository is packed and is served via a dumb transport. SEE ALSO -------- -linkgit:git-send-pack[1] - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano. +linkgit:git-send-pack[1], linkgit:gitnamespaces[7] GIT --- diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 7f7a5445c7..976dc14937 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -8,6 +8,7 @@ git-reflog - Manage reflog information SYNOPSIS -------- +[verse] 'git reflog' <subcommand> <options> DESCRIPTION @@ -18,9 +19,7 @@ depending on the subcommand: [verse] 'git reflog expire' [--dry-run] [--stale-fix] [--verbose] [--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>... -+ 'git reflog delete' ref@\{specifier\}... -+ 'git reflog' ['show'] [log-options] [<ref>] Reflog is a mechanism to record when the tip of branches are @@ -42,7 +41,7 @@ see linkgit:git-log[1]. The reflog is useful in various git commands, to specify the old value of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be two moves ago", `master@\{one.week.ago\}` means "where master used to -point to one week ago", and so on. See linkgit:git-rev-parse[1] for +point to one week ago", and so on. See linkgit:gitrevisions[7] for more details. To delete single entries from the reflog, use the subcommand "delete" @@ -60,7 +59,7 @@ OPTIONS refs. + This computation involves traversing all the reachable objects, i.e. it -has the same cost as 'git-prune'. Fortunately, once this is run, we +has the same cost as 'git prune'. Fortunately, once this is run, we should not have to ever worry about missing objects, because the current prune and pack-objects know about reflogs and protect objects referred by them. @@ -92,14 +91,6 @@ them. --verbose:: Print extra information on screen. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index 25ff8f9dcb..3b33c99510 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -7,7 +7,8 @@ git-relink - Hardlink common objects in local repositories SYNOPSIS -------- -'git relink' [--safe] <dir> [<dir>]\* <master_dir> +[verse] +'git relink' [--safe] <dir>... <master_dir> DESCRIPTION ----------- @@ -24,14 +25,6 @@ OPTIONS <dir>:: Directories containing a .git/objects/ subdirectory. -Author ------- -Written by Ryan Anderson <ryan@michonline.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt new file mode 100644 index 0000000000..8a8e1d775d --- /dev/null +++ b/Documentation/git-remote-ext.txt @@ -0,0 +1,126 @@ +git-remote-ext(1) +================= + +NAME +---- +git-remote-ext - Bridge smart transport to external command. + +SYNOPSIS +-------- +[verse] +git remote add <nick> "ext::<command>[ <arguments>...]" + +DESCRIPTION +----------- +This remote helper uses the specified '<command>' to connect +to a remote git server. + +Data written to stdin of the specified '<command>' is assumed +to be sent to a git:// server, git-upload-pack, git-receive-pack +or git-upload-archive (depending on situation), and data read +from stdout of <command> is assumed to be received from +the same service. + +Command and arguments are separated by an unescaped space. + +The following sequences have a special meaning: + +'% ':: + Literal space in command or argument. + +'%%':: + Literal percent sign. + +'%s':: + Replaced with name (receive-pack, upload-pack, or + upload-archive) of the service git wants to invoke. + +'%S':: + Replaced with long name (git-receive-pack, + git-upload-pack, or git-upload-archive) of the service + git wants to invoke. + +'%G' (must be the first characters in an argument):: + This argument will not be passed to '<command>'. Instead, it + will cause the helper to start by sending git:// service requests to + the remote side with the service field set to an appropriate value and + the repository field set to rest of the argument. Default is not to send + such a request. ++ +This is useful if remote side is git:// server accessed over +some tunnel. + +'%V' (must be first characters in argument):: + This argument will not be passed to '<command>'. Instead it sets + the vhost field in the git:// service request (to rest of the argument). + Default is not to send vhost in such request (if sent). + +ENVIRONMENT VARIABLES: +---------------------- + +GIT_TRANSLOOP_DEBUG:: + If set, prints debugging information about various reads/writes. + +ENVIRONMENT VARIABLES PASSED TO COMMAND: +---------------------------------------- + +GIT_EXT_SERVICE:: + Set to long name (git-upload-pack, etc...) of service helper needs + to invoke. + +GIT_EXT_SERVICE_NOPREFIX:: + Set to long name (upload-pack, etc...) of service helper needs + to invoke. + + +EXAMPLES: +--------- +This remote helper is transparently used by git when +you use commands such as "git fetch <URL>", "git clone <URL>", +, "git push <URL>" or "git remote add <nick> <URL>", where <URL> +begins with `ext::`. Examples: + +"ext::ssh -i /home/foo/.ssh/somekey user@host.example %S 'foo/repo'":: + Like host.example:foo/repo, but use /home/foo/.ssh/somekey as + keypair and user as user on remote side. This avoids needing to + edit .ssh/config. + +"ext::socat -t3600 - ABSTRACT-CONNECT:/git-server %G/somerepo":: + Represents repository with path /somerepo accessable over + git protocol at abstract namespace address /git-server. + +"ext::git-server-alias foo %G/repo":: + Represents a repository with path /repo accessed using the + helper program "git-server-alias foo". The path to the + repository and type of request are not passed on the command + line but as part of the protocol stream, as usual with git:// + protocol. + +"ext::git-server-alias foo %G/repo %Vfoo":: + Represents a repository with path /repo accessed using the + helper program "git-server-alias foo". The hostname for the + remote server passed in the protocol stream will be "foo" + (this allows multiple virtual git servers to share a + link-level address). + +"ext::git-server-alias foo %G/repo% with% spaces %Vfoo":: + Represents a repository with path '/repo with spaces' accessed + using the helper program "git-server-alias foo". The hostname for + the remote server passed in the protocol stream will be "foo" + (this allows multiple virtual git servers to share a + link-level address). + +"ext::git-ssl foo.example /bar":: + Represents a repository accessed using the helper program + "git-ssl foo.example /bar". The type of request can be + determined by the helper using environment variables (see + above). + +Documentation +-------------- +Documentation by Ilari Liusvaara, Jonathan Nieder and the git list +<git@vger.kernel.org> + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt new file mode 100644 index 0000000000..f095d57d09 --- /dev/null +++ b/Documentation/git-remote-fd.txt @@ -0,0 +1,59 @@ +git-remote-fd(1) +================ + +NAME +---- +git-remote-fd - Reflect smart transport stream back to caller + +SYNOPSIS +-------- +"fd::<infd>[,<outfd>][/<anything>]" (as URL) + +DESCRIPTION +----------- +This helper uses specified file descriptors to connect to a remote git server. +This is not meant for end users but for programs and scripts calling git +fetch, push or archive. + +If only <infd> is given, it is assumed to be a bidirectional socket connected +to remote git server (git-upload-pack, git-receive-pack or +git-upload-achive). If both <infd> and <outfd> are given, they are assumed +to be pipes connected to a remote git server (<infd> being the inbound pipe +and <outfd> being the outbound pipe. + +It is assumed that any handshaking procedures have already been completed +(such as sending service request for git://) before this helper is started. + +<anything> can be any string. It is ignored. It is meant for providing +information to user in the URL in case that URL is displayed in some +context. + +ENVIRONMENT VARIABLES +--------------------- +GIT_TRANSLOOP_DEBUG:: + If set, prints debugging information about various reads/writes. + +EXAMPLES +-------- +`git fetch fd::17 master`:: + Fetch master, using file descriptor #17 to communicate with + git-upload-pack. + +`git fetch fd::17/foo master`:: + Same as above. + +`git push fd::7,8 master (as URL)`:: + Push master, using file descriptor #7 to read data from + git-receive-pack and file descriptor #8 to write data to + same service. + +`git push fd::7,8/bar master`:: + Same as above. + +Documentation +-------------- +Documentation by Ilari Liusvaara and the git list <git@vger.kernel.org> + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 4685a898f1..674797cd83 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -3,20 +3,192 @@ git-remote-helpers(1) NAME ---- -git-remote-helpers - Helper programs for interoperation with remote git +git-remote-helpers - Helper programs to interact with remote repositories SYNOPSIS -------- -'git remote-<transport>' <remote> +[verse] +'git remote-<transport>' <repository> [<URL>] DESCRIPTION ----------- -These programs are normally not used directly by end users, but are -invoked by various git programs that interact with remote repositories -when the repository they would operate on will be accessed using -transport code not linked into the main git binary. Various particular -helper programs will behave as documented here. +Remote helper programs are normally not used directly by end users, +but they are invoked by git when it needs to interact with remote +repositories git does not support natively. A given helper will +implement a subset of the capabilities documented here. When git +needs to interact with a repository using a remote helper, it spawns +the helper as an independent process, sends commands to the helper's +standard input, and expects results from the helper's standard +output. Because a remote helper runs as an independent process from +git, there is no need to re-link git to add a new helper, nor any +need to link the helper with the implementation of git. + +Every helper must support the "capabilities" command, which git +uses to determine what other commands the helper will accept. Those +other commands can be used to discover and update remote refs, +transport objects between the object database and the remote repository, +and update the local object store. + +Git comes with a "curl" family of remote helpers, that handle various +transport protocols, such as 'git-remote-http', 'git-remote-https', +'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities +'fetch', 'option', and 'push'. + +INPUT FORMAT +------------ + +Git sends the remote helper a list of commands on standard input, one +per line. The first command is always the 'capabilities' command, in +response to which the remote helper must print a list of the +capabilities it supports (see below) followed by a blank line. The +response to the capabilities command determines what commands Git uses +in the remainder of the command stream. + +The command stream is terminated by a blank line. In some cases +(indicated in the documentation of the relevant commands), this blank +line is followed by a payload in some other protocol (e.g., the pack +protocol), while in others it indicates the end of input. + +Capabilities +~~~~~~~~~~~~ + +Each remote helper is expected to support only a subset of commands. +The operations a helper supports are declared to git in the response +to the `capabilities` command (see COMMANDS, below). + +'option':: + For specifying settings like `verbosity` (how much output to + write to stderr) and `depth` (how much history is wanted in the + case of a shallow clone) that affect how other commands are + carried out. + +'connect':: + For fetching and pushing using git's native packfile protocol + that requires a bidirectional, full-duplex connection. + +'push':: + For listing remote refs and pushing specified objects from the + local object store to remote refs. + +'fetch':: + For listing remote refs and fetching the associated history to + the local object store. + +'import':: + For listing remote refs and fetching the associated history as + a fast-import stream. + +'refspec' <refspec>:: + This modifies the 'import' capability, allowing the produced + fast-import stream to modify refs in a private namespace + instead of writing to refs/heads or refs/remotes directly. + It is recommended that all importers providing the 'import' + capability use this. ++ +A helper advertising the capability +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}` +is saying that, when it is asked to `import refs/heads/topic`, the +stream it outputs will update the `refs/svn/origin/branches/topic` +ref. ++ +This capability can be advertised multiple times. The first +applicable refspec takes precedence. The left-hand of refspecs +advertised with this capability must cover all refs reported by +the list command. If no 'refspec' capability is advertised, +there is an implied `refspec {asterisk}:{asterisk}`. + +Capabilities for Pushing +~~~~~~~~~~~~~~~~~~~~~~~~ +'connect':: + Can attempt to connect to 'git receive-pack' (for pushing), + 'git upload-pack', etc for communication using the + packfile protocol. ++ +Supported commands: 'connect'. + +'push':: + Can discover remote refs and push local commits and the + history leading up to them to new or existing remote refs. ++ +Supported commands: 'list for-push', 'push'. + +If a helper advertises both 'connect' and 'push', git will use +'connect' if possible and fall back to 'push' if the helper requests +so when connecting (see the 'connect' command under COMMANDS). + +Capabilities for Fetching +~~~~~~~~~~~~~~~~~~~~~~~~~ +'connect':: + Can try to connect to 'git upload-pack' (for fetching), + 'git receive-pack', etc for communication using the + packfile protocol. ++ +Supported commands: 'connect'. + +'fetch':: + Can discover remote refs and transfer objects reachable from + them to the local object store. ++ +Supported commands: 'list', 'fetch'. + +'import':: + Can discover remote refs and output objects reachable from + them as a stream in fast-import format. ++ +Supported commands: 'list', 'import'. + +If a helper advertises 'connect', git will use it if possible and +fall back to another capability if the helper requests so when +connecting (see the 'connect' command under COMMANDS). +When choosing between 'fetch' and 'import', git prefers 'fetch'. +Other frontends may have some other order of preference. + +'refspec' <refspec>:: + This modifies the 'import' capability. ++ +A helper advertising +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}` +in its capabilities is saying that, when it handles +`import refs/heads/topic`, the stream it outputs will update the +`refs/svn/origin/branches/topic` ref. ++ +This capability can be advertised multiple times. The first +applicable refspec takes precedence. The left-hand of refspecs +advertised with this capability must cover all refs reported by +the list command. If no 'refspec' capability is advertised, +there is an implied `refspec {asterisk}:{asterisk}`. + +INVOCATION +---------- + +Remote helper programs are invoked with one or (optionally) two +arguments. The first argument specifies a remote repository as in git; +it is either the name of a configured remote or a URL. The second +argument specifies a URL; it is usually of the form +'<transport>://<address>', but any arbitrary string is possible. +The 'GIT_DIR' environment variable is set up for the remote helper +and can be used to determine where to store additional data or from +which directory to invoke auxiliary git commands. + +When git encounters a URL of the form '<transport>://<address>', where +'<transport>' is a protocol that it cannot handle natively, it +automatically invokes 'git remote-<transport>' with the full URL as +the second argument. If such a URL is encountered directly on the +command line, the first argument is the same as the second, and if it +is encountered in a configured remote, the first argument is the name +of that remote. + +A URL of the form '<transport>::<address>' explicitly instructs git to +invoke 'git remote-<transport>' with '<address>' as the second +argument. If such a URL is encountered directly on the command line, +the first argument is '<address>', and if it is encountered in a +configured remote, the first argument is the name of that remote. + +Additionally, when a configured remote has 'remote.<name>.vcs' set to +'<transport>', git explicitly invokes 'git remote-<transport>' with +'<name>' as the first argument. If set, the second argument is +'remote.<name>.url'; otherwise, the second argument is omitted. COMMANDS -------- @@ -25,8 +197,8 @@ Commands are given by the caller on the helper's standard input, one per line. 'capabilities':: Lists the capabilities of the helper, one per line, ending - with a blank line. Each capability may be preceeded with '*'. - This marks them mandatory for git version using the remote + with a blank line. Each capability may be preceded with '*', + which marks them mandatory for git version using the remote helper to understand (unknown mandatory capability is fatal error). @@ -35,27 +207,27 @@ Commands are given by the caller on the helper's standard input, one per line. [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for a symref, or "?" to indicate that the helper could not get the value of the ref. A space-separated list of attributes follows - the name; unrecognized attributes are ignored. After the - complete list, outputs a blank line. + the name; unrecognized attributes are ignored. The list ends + with a blank line. + If 'push' is supported this may be called as 'list for-push' to obtain the current refs prior to sending one or more 'push' commands to the helper. 'option' <name> <value>:: - Set the transport helper option <name> to <value>. Outputs a + Sets the transport helper option <name> to <value>. Outputs a single line containing one of 'ok' (option successfully set), 'unsupported' (option not recognized) or 'error <msg>' - (option <name> is supported but <value> is not correct + (option <name> is supported but <value> is not valid for it). Options should be set before other commands, - and may how those commands behave. + and may influence the behavior of those commands. + Supported if the helper has the "option" capability. 'fetch' <sha1> <name>:: Fetches the given object, writing the necessary objects to the database. Fetch commands are sent in a batch, one - per line, and the batch is terminated with a blank line. + per line, terminated with a blank line. Outputs a single blank line when all fetch commands in the same batch are complete. Only objects which were reported in the ref list with a sha1 may be fetched this way. @@ -67,9 +239,24 @@ suitably updated. Supported if the helper has the "fetch" capability. 'push' +<src>:<dst>:: - Pushes the given <src> commit or branch locally to the + Pushes the given local <src> commit or branch to the remote branch described by <dst>. A batch sequence of - one or more push commands is terminated with a blank line. + one or more 'push' commands is terminated with a blank line + (if there is only one reference to push, a single 'push' command + is followed by a blank line). For example, the following would + be two batches of 'push', the first asking the remote-helper + to push the local ref 'master' to the remote ref 'master' and + the local 'HEAD' to the remote 'branch', and the second + asking to push ref 'foo' to ref 'bar' (forced update requested + by the '+'). ++ +------------ +push refs/heads/master:refs/heads/master +push HEAD:refs/heads/branch +\n +push +refs/heads/foo:refs/heads/bar +\n +------------ + Zero or more protocol options may be entered after the last 'push' command, before the batch's terminating blank line. @@ -91,6 +278,14 @@ Supported if the helper has the "push" capability. by applying the refspecs from the "refspec" capability to the name of the ref. + +Especially useful for interoperability with a foreign versioning +system. ++ +Just like 'push', a batch sequence of one or more 'import' is +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. 'connect' <service>:: @@ -115,34 +310,6 @@ completing a valid response for the current command. Additional commands may be supported, as may be determined from capabilities reported by the helper. -CAPABILITIES ------------- - -'fetch':: - This helper supports the 'fetch' command. - -'option':: - This helper supports the option command. - -'push':: - This helper supports the 'push' command. - -'import':: - This helper supports the 'import' command. - -'refspec' 'spec':: - When using the import command, expect the source ref to have - been written to the destination ref. The earliest applicable - refspec takes precedence. For example - "refs/heads/*:refs/svn/origin/branches/*" means that, after an - "import refs/heads/name", the script has written to - refs/svn/origin/branches/name. If this capability is used at - all, it must cover all refs reported by the list command; if - it is not used, it is effectively "*:*" - -'connect':: - This helper supports the 'connect' command. - REF LIST ATTRIBUTES ------------------- @@ -157,20 +324,20 @@ REF LIST ATTRIBUTES OPTIONS ------- -'option verbosity' <N>:: - Change the level of messages displayed by the helper. - When N is 0 the end-user has asked the process to be - quiet, and the helper should produce only error output. - N of 1 is the default level of verbosity, higher values - of N correspond to the number of -v flags passed on the +'option verbosity' <n>:: + Changes the verbosity of messages displayed by the helper. + A value of 0 for <n> means that processes operate + quietly, and the helper produces only error output. + 1 is the default level of verbosity, and higher values + of <n> correspond to the number of -v flags passed on the command line. 'option progress' \{'true'|'false'\}:: - Enable (or disable) progress messages displayed by the + Enables (or disables) progress messages displayed by the transport helper during a command. 'option depth' <depth>:: - Deepen the history of a shallow repository. + Deepens the history of a shallow repository. 'option followtags' \{'true'|'false'\}:: If enabled the helper should automatically fetch annotated @@ -186,14 +353,16 @@ OPTIONS helpers this only applies to the 'push', if supported. 'option servpath <c-style-quoted-path>':: - Set service path (--upload-pack, --receive-pack etc.) for - next connect. Remote helper MAY support this option. Remote - helper MUST NOT rely on this option being set before + Sets service path (--upload-pack, --receive-pack etc.) for + next connect. Remote helper may support this option, but + must not rely on this option being set before connect request occurs. -Documentation -------------- -Documentation by Daniel Barkalow and Ilari Liusvaara +SEE ALSO +-------- +linkgit:git-remote[1] + +linkgit:git-remote-testgit[1] GIT --- diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt new file mode 100644 index 0000000000..2a67d456a3 --- /dev/null +++ b/Documentation/git-remote-testgit.txt @@ -0,0 +1,30 @@ +git-remote-testgit(1) +===================== + +NAME +---- +git-remote-testgit - Example remote-helper + + +SYNOPSIS +-------- +[verse] +git clone testgit::<source-repo> [<destination>] + +DESCRIPTION +----------- + +This command is a simple remote-helper, that is used both as a +testcase for the remote-helper functionality, and as an example to +show remote-helper authors one possible implementation. + +The best way to learn more is to read the comments and source code in +'git-remote-testgit.py'. + +SEE ALSO +-------- +linkgit:git-remote-helpers[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 35d32f7de4..5a8c5061f3 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,16 +10,17 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url> +'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 set-head' <name> (-a | -d | <branch>) +'git remote set-branches' <name> [--add] <branch>... 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> 'git remote set-url --delete' [--push] <name> <url> 'git remote' [-v | --verbose] 'show' [-n] <name> 'git remote prune' [-n | --dry-run] <name> -'git remote' [-v | --verbose] 'update' [-p | --prune] [group | remote]... +'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...] DESCRIPTION ----------- @@ -51,24 +52,33 @@ update remote-tracking branches <name>/<branch>. With `-f` option, `git fetch <name>` is run immediately after the remote information is set up. + +With `--tags` option, `git fetch <name>` imports every tag from the +remote repository. ++ +With `--no-tags` option, `git fetch <name>` does not import tags from +the remote repository. ++ With `-t <branch>` option, instead of the default glob refspec for the remote to track all branches under -`$GIT_DIR/remotes/<name>/`, a refspec to track only `<branch>` +the `refs/remotes/<name>/` namespace, a refspec to track only `<branch>` is created. You can give more than one `-t <branch>` to track multiple branches without grabbing all branches. + -With `-m <master>` option, `$GIT_DIR/remotes/<name>/HEAD` is set +With `-m <master>` option, a symbolic-ref `refs/remotes/<name>/HEAD` is set up to point at remote's `<master>` branch. See also the set-head command. + -In mirror mode, enabled with `\--mirror`, the refs will not be stored -in the 'refs/remotes/' namespace, but in 'refs/heads/'. This option -only makes sense in bare repositories. If a remote uses mirror -mode, furthermore, `git push` will always behave as if `\--mirror` -was passed. +When a fetch mirror is created with `\--mirror=fetch`, the refs will not +be stored in the 'refs/remotes/' namespace, but rather everything in +'refs/' on the remote will be directly mirrored into 'refs/' in the +local repository. This option only makes sense in bare repositories, +because a fetch would overwrite any local commits. ++ +When a push mirror is created with `\--mirror=push`, then `git push` +will always behave as if `\--mirror` was passed. 'rename':: -Rename the remote named <old> to <new>. All remote tracking branches and +Rename the remote named <old> to <new>. All remote-tracking branches and configuration settings for the remote are updated. + In case <old> and <new> are the same, and <old> is a file under @@ -77,33 +87,46 @@ the configuration file format. 'rm':: -Remove the remote named <name>. All remote tracking branches and +Remove the remote named <name>. All remote-tracking branches and configuration settings for the remote are removed. 'set-head':: -Sets or deletes the default branch (`$GIT_DIR/remotes/<name>/HEAD`) for +Sets or deletes the default branch (i.e. the target of the +symbolic-ref `refs/remotes/<name>/HEAD`) for the named remote. Having a default branch for a remote is not required, but allows the name of the remote to be specified in lieu of a specific branch. For example, if the default branch for `origin` is set to `master`, then `origin` may be specified wherever you would normally specify `origin/master`. + -With `-d`, `$GIT_DIR/remotes/<name>/HEAD` is deleted. +With `-d`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted. + -With `-a`, the remote is queried to determine its `HEAD`, then -`$GIT_DIR/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote +With `-a`, the remote is queried to determine its `HEAD`, then the +symbolic-ref `refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote `HEAD` is pointed at `next`, "`git remote set-head origin -a`" will set -`$GIT_DIR/refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will +the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will only work if `refs/remotes/origin/next` already exists; if not it must be fetched first. + -Use `<branch>` to set `$GIT_DIR/remotes/<name>/HEAD` explicitly. e.g., "git -remote set-head origin master" will set `$GIT_DIR/refs/remotes/origin/HEAD` to +Use `<branch>` to set the symbolic-ref `refs/remotes/<name>/HEAD` explicitly. e.g., "git +remote set-head origin master" will set the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/master`. This will only work if `refs/remotes/origin/master` already exists; if not it must be fetched first. + +'set-branches':: + +Changes the list of branches tracked by the named remote. +This can be used to track a subset of the available remote branches +after the initial setup for a remote. ++ +The named branches will be interpreted as if specified with the +`-t` option on the 'git remote add' command line. ++ +With `--add`, instead of replacing the list of currently tracked +branches, adds to that list. + 'set-url':: Changes URL remote points to. Sets first URL remote points to matching @@ -127,7 +150,7 @@ With `-n` option, the remote heads are not queried first with 'prune':: -Deletes all stale tracking branches under <name>. +Deletes all stale remote-tracking branches under <name>. These stale branches have already been removed from the remote repository referenced by <name>, but are still locally available in "remotes/<name>". @@ -178,7 +201,7 @@ $ git checkout -b nfs linux-nfs/master ... ------------ -* Imitate 'git-clone' but track only selected branches +* Imitate 'git clone' but track only selected branches + ------------ $ mkdir project.git @@ -195,16 +218,6 @@ linkgit:git-fetch[1] linkgit:git-branch[1] linkgit:git-config[1] -Author ------- -Written by Junio Hamano - - -Documentation --------------- -Documentation by J. Bruce Fields and the git-list <git@vger.kernel.org>. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index c9257a10c9..40af321153 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -8,7 +8,8 @@ git-repack - Pack unpacked objects in a repository SYNOPSIS -------- -'git repack' [-a] [-A] [-d] [-f] [-l] [-n] [-q] [--window=N] [--depth=N] +[verse] +'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>] DESCRIPTION ----------- @@ -49,35 +50,39 @@ other objects in that pack they already have locally. deleted by way of being left in the old pack and then removed. Instead, the loose unreachable objects will be pruned according to normal expiry rules - with the next 'git-gc' invocation. See linkgit:git-gc[1]. + with the next 'git gc' invocation. See linkgit:git-gc[1]. -d:: After packing, if the newly created packs make some existing packs redundant, remove the redundant packs. - Also run 'git-prune-packed' to remove redundant + Also run 'git prune-packed' to remove redundant loose object files. -l:: - Pass the `--local` option to 'git-pack-objects'. See + Pass the `--local` option to 'git pack-objects'. See linkgit:git-pack-objects[1]. -f:: + Pass the `--no-reuse-delta` option to `git-pack-objects`, see + linkgit:git-pack-objects[1]. + +-F:: Pass the `--no-reuse-object` option to `git-pack-objects`, see linkgit:git-pack-objects[1]. -q:: - Pass the `-q` option to 'git-pack-objects'. See + Pass the `-q` option to 'git pack-objects'. See linkgit:git-pack-objects[1]. -n:: Do not update the server information with - 'git-update-server-info'. This option skips + 'git update-server-info'. This option skips updating local catalog files needed to publish this repository (or a direct copy of it) over HTTP or FTP. See linkgit:git-update-server-info[1]. ---window=[N]:: ---depth=[N]:: +--window=<n>:: +--depth=<n>:: These two options affect how the objects contained in the pack are stored using delta compression. The objects are first internally sorted by type, size and optionally names and compared against the @@ -87,10 +92,10 @@ other objects in that pack they already have locally. to be applied that many times to get to the necessary object. The default value for --window is 10 and --depth is 50. ---window-memory=[N]:: +--window-memory=<n>:: This option provides an additional limit on top of `--window`; the window size will dynamically scale down so as to not take - up more than N bytes in memory. This is useful in + up more than '<n>' bytes in memory. This is useful in repositories with a mix of large and small objects to not run out of memory with a large window, but still be able to take advantage of the large window for the smaller objects. The @@ -99,32 +104,25 @@ other objects in that pack they already have locally. default. --max-pack-size=<n>:: - Maximum size of each output packfile, expressed in MiB. + Maximum size of each output pack file. The size can be suffixed with + "k", "m", or "g". The minimum size allowed is limited to 1 MiB. If specified, multiple packfiles may be created. - The default is unlimited. + The default is unlimited, unless the config variable + `pack.packSizeLimit` is set. Configuration ------------- -When configuration variable `repack.UseDeltaBaseOffset` is set -for the repository, the command passes `--delta-base-offset` -option to 'git-pack-objects'; this typically results in slightly -smaller packs, but the generated packs are incompatible with -versions of git older than (and including) v1.4.3; do not set -the variable in a repository that older version of git needs to -be able to read (this includes repositories from which packs can -be copied out over http or rsync, and people who obtained packs -that way can try to use older git with it). - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Ryan Anderson <ryan@michonline.com> +By default, the command passes `--delta-base-offset` option to +'git pack-objects'; this typically results in slightly smaller packs, +but the generated packs are incompatible with versions of Git older than +version 1.4.4. If you need to share your repository with such ancient Git +versions, either directly or via the dumb http or rsync protocol, then you +need to set the configuration variable `repack.UseDeltaBaseOffset` to +"false" and repack. Access from old Git versions over the native protocol +is unaffected by this option as the conversion is performed on the fly +as needed in that case. SEE ALSO -------- diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 65a0da508a..17df525275 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -65,7 +65,7 @@ OPTIONS BUGS ---- Comparing blobs or trees that have been replaced with those that -replace them will not work properly. And using 'git reset --hard' to +replace them will not work properly. And using `git reset --hard` to go back to a replaced commit will move the branch to the replacement commit instead of the replaced commit. @@ -80,17 +80,6 @@ linkgit:git-tag[1] linkgit:git-branch[1] linkgit:git[1] -Author ------- -Written by Christian Couder <chriscool@tuxfamily.org> and Junio C -Hamano <gitster@pobox.com>, based on 'git tag' by Kristian Hogsberg -<krh@redhat.com> and Carlos Rica <jasampler@gmail.com>. - -Documentation --------------- -Documentation by Christian Couder <chriscool@tuxfamily.org> and the -git-list <git@vger.kernel.org>, based on 'git tag' documentation. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index e5bdb5533e..9ec115b9e0 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -8,6 +8,7 @@ git-repo-config - Get and set repository or global options SYNOPSIS -------- +[verse] 'git repo-config' ... @@ -16,3 +17,7 @@ DESCRIPTION This is a synonym for linkgit:git-config[1]. Please refer to the documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 19335fddae..b99681ce85 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -7,7 +7,8 @@ git-request-pull - Generates a summary of pending changes SYNOPSIS -------- -'git request-pull' <start> <url> [<end>] +[verse] +'git request-pull' [-p] <start> <url> [<end>] DESCRIPTION ----------- @@ -17,6 +18,9 @@ the given URL in the generated summary. OPTIONS ------- +-p:: + Show patch text + <start>:: Commit to start at. @@ -26,14 +30,6 @@ OPTIONS <end>:: Commit to end at; defaults to HEAD. -Author ------- -Written by Ryan Anderson <ryan@michonline.com> and Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 7dd515b8cc..a6253ba617 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -7,7 +7,8 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- -'git rerere' ['clear'|'diff'|'status'|'gc'] +[verse] +'git rerere' ['clear'|'forget' <pathspec>|'diff'|'status'|'gc'] DESCRIPTION ----------- @@ -30,16 +31,21 @@ enable this command. COMMANDS -------- -Normally, 'git-rerere' is run without arguments or user-intervention. +Normally, 'git rerere' is run without arguments or user-intervention. However, it has several commands that allow it to interact with its working state. 'clear':: This resets the metadata used by rerere if a merge resolution is to be -aborted. Calling 'git-am [--skip|--abort]' or 'git-rebase [--skip|--abort]' +aborted. Calling 'git am [--skip|--abort]' or 'git rebase [--skip|--abort]' will automatically invoke this command. +'forget' <pathspec>:: + +This resets the conflict resolutions which rerere has recorded for the current +conflict in <pathspec>. + 'diff':: This displays diffs for the current state of the resolution. It is @@ -142,32 +148,32 @@ finally ready and merged into the master branch. This merge would require you to resolve the conflict, introduced by the commits marked with `*`. However, this conflict is often the same conflict you resolved when you created the test merge you -blew away. 'git-rerere' helps you resolve this final +blew away. 'git rerere' helps you resolve this final conflicted merge using the information from your earlier hand resolve. -Running the 'git-rerere' command immediately after a conflicted +Running the 'git rerere' command immediately after a conflicted automerge records the conflicted working tree files, with the usual conflict markers `<<<<<<<`, `=======`, and `>>>>>>>` in them. Later, after you are done resolving the conflicts, -running 'git-rerere' again will record the resolved state of these +running 'git rerere' again will record the resolved state of these files. Suppose you did this when you created the test merge of master into the topic branch. Next time, after seeing the same conflicted automerge, -running 'git-rerere' will perform a three-way merge between the +running 'git rerere' will perform a three-way merge between the earlier conflicted automerge, the earlier manual resolution, and the current conflicted automerge. If this three-way merge resolves cleanly, the result is written out to your working tree file, so you do not have to manually -resolve it. Note that 'git-rerere' leaves the index file alone, +resolve it. Note that 'git rerere' leaves the index file alone, so you still need to do the final sanity checks with `git diff` -(or `git diff -c`) and 'git-add' when you are satisfied. +(or `git diff -c`) and 'git add' when you are satisfied. -As a convenience measure, 'git-merge' automatically invokes -'git-rerere' upon exiting with a failed automerge and 'git-rerere' +As a convenience measure, 'git merge' automatically invokes +'git rerere' upon exiting with a failed automerge and 'git rerere' records the hand resolve when it is a new conflict, or reuses the earlier hand -resolve when it is not. 'git-commit' also invokes 'git-rerere' +resolve when it is not. 'git commit' also invokes 'git rerere' when committing a merge result. What this means is that you do not have to do anything special yourself (besides enabling the rerere.enabled config variable). @@ -177,8 +183,8 @@ resolution is recorded, and it will be reused when you do the actual merge later with the updated master and topic branch, as long as the recorded resolution is still applicable. -The information 'git-rerere' records is also used when running -'git-rebase'. After blowing away the test merge and continuing +The information 'git rerere' records is also used when running +'git rebase'. After blowing away the test merge and continuing development on the topic branch: ------------ @@ -197,14 +203,9 @@ you could run `git rebase master topic`, to bring yourself up-to-date before your topic is ready to be sent upstream. This would result in falling back to a three-way merge, and it would conflict the same way as the test merge you resolved earlier. -'git-rerere' will be run by 'git-rebase' to help you resolve this +'git rerere' will be run by 'git rebase' to help you resolve this conflict. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index c7aa444317..b2832fc7eb 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,158 +8,119 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git reset' [--mixed | --soft | --hard | --merge] [-q] [<commit>] 'git reset' [-q] [<commit>] [--] <paths>... -'git reset' --patch [<commit>] [--] [<paths>...] +'git reset' [--patch|-p] [<commit>] [--] [<paths>...] +'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- -Sets the current head to the specified commit and optionally resets the -index and working tree to match. - -This command is useful if you notice some small error in a recent -commit (or set of commits) and want to redo that part without showing -the undo in the history. - -If you want to undo a commit other than the latest on a branch, -linkgit:git-revert[1] is your friend. - -The second and third forms with 'paths' and/or --patch are used to -revert selected paths in the index from a given commit, without moving -HEAD. - +In the first and second form, copy entries from <commit> to the index. +In the third form, set the current branch head (HEAD) to <commit>, optionally +modifying index and working tree to match. The <commit> defaults to HEAD +in all forms. + +'git reset' [-q] [<commit>] [--] <paths>...:: + This form resets the index entries for all <paths> to their + state at <commit>. (It does not affect the working tree, nor + the current branch.) ++ +This means that `git reset <paths>` is the opposite of `git add +<paths>`. ++ +After running `git reset <paths>` to update the index entry, you can +use linkgit:git-checkout[1] to check the contents out of the index to +the working tree. +Alternatively, using linkgit:git-checkout[1] and specifying a commit, you +can copy the contents of a path out of a commit to the index and to the +working tree in one go. + +'git reset' --patch|-p [<commit>] [--] [<paths>...]:: + Interactively select hunks in the difference between the index + and <commit> (defaults to HEAD). The chosen hunks are applied + in reverse to the index. ++ +This means that `git reset -p` is the opposite of `git add -p`, 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>]:: + 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: ++ +-- +--soft:: + Does not touch the index file nor the working tree at all (but + resets the head to <commit>, just like all modes do). This leaves + all your changed files "Changes to be committed", as 'git status' + would put it. -OPTIONS -------- --mixed:: Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated. This is the default action. ---soft:: - Does not touch the index file nor the working tree at all, but - requires them to be in a good order. This leaves all your changed - files "Changes to be committed", as 'git-status' would - put it. - --hard:: - Matches the working tree and index to that of the tree being - switched to. Any changes to tracked files in the working tree - since <commit> are lost. + Resets the index and working tree. Any changes to tracked files in the + working tree since <commit> are discarded. --merge:: - Resets the index to match the tree recorded by the named commit, - and updates the files that are different between the named commit - and the current commit in the working tree. - --p:: ---patch:: - Interactively select hunks in the difference between the index - and <commit> (defaults to HEAD). The chosen hunks are applied - in reverse to the index. + Resets the index and updates the files in the working tree that are + different between <commit> and HEAD, but keeps those which are + different between the index and working tree (i.e. which have changes + which have not been added). + If a file that is different between <commit> and the index has unstaged + changes, reset is aborted. + -This means that `git reset -p` is the opposite of `git add -p` (see -linkgit:git-add[1]). - --q:: ---quiet:: - Be quiet, only report errors. - -<commit>:: - Commit to make the current HEAD. If not given defaults to HEAD. - -DISCUSSION ----------- - -The tables below show what happens when running: - ----------- -git reset --option target ----------- - -to reset the HEAD to another commit (`target`) with the different -reset options depending on the state of the files. - -In these tables, A, B, C and D are some different states of a -file. For example, the first line of the first table means that if a -file is in state A in the working tree, in state B in the index, in -state C in HEAD and in state D in the target, then "git reset --soft -target" will put the file in state A in the working tree, in state B -in the index and in state D in HEAD. - - working index HEAD target working index HEAD - ---------------------------------------------------- - A B C D --soft A B D - --mixed A D D - --hard D D D - --merge (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - A B C C --soft A B C - --mixed A C C - --hard C C C - --merge (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - B B C D --soft B B D - --mixed B D D - --hard D D D - --merge D D D - - working index HEAD target working index HEAD - ---------------------------------------------------- - B B C C --soft B B C - --mixed B C C - --hard C C C - --merge C C C +In other words, --merge does something like a 'git read-tree -u -m <commit>', +but carries forward unmerged index entries. - working index HEAD target working index HEAD - ---------------------------------------------------- - B C C D --soft B C D - --mixed B D D - --hard D D D - --merge (disallowed) +--keep:: + Resets index entries and updates files in the working tree that are + different between <commit> and HEAD. + If a file that is different between <commit> and HEAD has local changes, + reset is aborted. +-- - working index HEAD target working index HEAD - ---------------------------------------------------- - B C C C --soft B C C - --mixed B C C - --hard C C C - --merge B C C - -"reset --merge" is meant to be used when resetting out of a conflicted -merge. Any mergy operation guarantees that the work tree file that is -involved in the merge does not have local change wrt the index before -it starts, and that it writes the result out to the work tree. So if -we see some difference between the index and the target and also -between the index and the work tree, then it means that we are not -resetting out from a state that a mergy operation left after failing -with a conflict. That is why we disallow --merge option in this case. +If you want to undo a commit other than the latest on a branch, +linkgit:git-revert[1] is your friend. -The following tables show what happens when there are unmerged -entries: - working index HEAD target working index HEAD - ---------------------------------------------------- - X U A B --soft (disallowed) - --mixed X B B - --hard B B B - --merge B B B +OPTIONS +------- - working index HEAD target working index HEAD - ---------------------------------------------------- - X U A A --soft (disallowed) - --mixed X A A - --hard A A A - --merge A A A +-q:: +--quiet:: + Be quiet, only report errors. -X means any state and U means an unmerged index. -Examples +EXAMPLES -------- +Undo add:: ++ +------------ +$ edit <1> +$ git add frotz.c filfre.c +$ mailx <2> +$ git reset <3> +$ git pull git://info.example.com/ nitfol <4> +------------ ++ +<1> You are happily working on something, and find the changes +in these files are in good order. You do not want to see them +when you run "git diff", because you plan to work on other files +and changes with these files are distracting. +<2> Somebody asks you to pull, and the changes sounds worthy of merging. +<3> However, you already dirtied the index (i.e. your index does +not match the HEAD commit). But you know the pull you are going +to make does not affect frotz.c nor filfre.c, so you revert the +index changes for these two files. Your changes in working tree +remain there. +<4> Then you can pull and merge, leaving frotz.c and filfre.c +changes still in the working tree. + Undo a commit and redo:: + ------------ @@ -179,19 +140,6 @@ edit the message further, you can give -C option instead. + See also the --amend option to linkgit:git-commit[1]. -Undo commits permanently:: -+ ------------- -$ git commit ... -$ git reset --hard HEAD~3 <1> ------------- -+ -<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad -and you do not want to ever see them again. Do *not* do this if -you have already given these commits to somebody else. (See the -"RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for -the implications of doing so.) - Undo a commit, making it a topic branch:: + ------------ @@ -207,28 +155,18 @@ current HEAD. <2> Rewind the master branch to get rid of those three commits. <3> Switch to "topic/wip" branch and keep working. -Undo add:: +Undo commits permanently:: + ------------ -$ edit <1> -$ git add frotz.c filfre.c -$ mailx <2> -$ git reset <3> -$ git pull git://info.example.com/ nitfol <4> +$ git commit ... +$ git reset --hard HEAD~3 <1> ------------ + -<1> You are happily working on something, and find the changes -in these files are in good order. You do not want to see them -when you run "git diff", because you plan to work on other files -and changes with these files are distracting. -<2> Somebody asks you to pull, and the changes sounds worthy of merging. -<3> However, you already dirtied the index (i.e. your index does -not match the HEAD commit). But you know the pull you are going -to make does not affect frotz.c nor filfre.c, so you revert the -index changes for these two files. Your changes in working tree -remain there. -<4> Then you can pull and merge, leaving frotz.c and filfre.c -changes still in the working tree. +<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +and you do not want to ever see them again. Do *not* do this if +you have already given these commits to somebody else. (See the +"RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for +the implications of doing so.) Undo a merge or pull:: + @@ -258,7 +196,7 @@ tip of the current branch in ORIG_HEAD, so resetting hard to it brings your index file and the working tree back to that state, and resets the tip of the branch to that commit. -Undo a merge or pull inside a dirty work tree:: +Undo a merge or pull inside a dirty working tree:: + ------------ $ git pull <1> @@ -325,13 +263,140 @@ $ git add frotz.c <3> <2> This commits all other changes in the index. <3> Adds the file to the index again. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds <torvalds@osdl.org> +Keep changes in working tree while discarding some previous commits:: ++ +Suppose you are working on something and you commit it, and then you +continue working a bit more, but now you think that what you have in +your working tree should be in another branch that has nothing to do +with what you committed previously. You can start a new branch and +reset it while keeping the changes in your working tree. ++ +------------ +$ git tag start +$ git checkout -b branch1 +$ edit +$ git commit ... <1> +$ edit +$ git checkout -b branch2 <2> +$ git reset --keep start <3> +------------ ++ +<1> This commits your first edits in branch1. +<2> In the ideal world, you could have realized that the earlier + commit did not belong to the new topic when you created and switched + to branch2 (i.e. "git checkout -b branch2 start"), but nobody is + perfect. +<3> But you can use "reset --keep" to remove the unwanted commit after + you switched to "branch2". + + +DISCUSSION +---------- + +The tables below show what happens when running: + +---------- +git reset --option target +---------- + +to reset the HEAD to another commit (`target`) with the different +reset options depending on the state of the files. + +In these tables, A, B, C and D are some different states of a +file. For example, the first line of the first table means that if a +file is in state A in the working tree, in state B in the index, in +state C in HEAD and in state D in the target, then "git reset --soft +target" will leave the file in the working tree in state A and in the +index in state B. It resets (i.e. moves) the HEAD (i.e. the tip of +the current branch, if you are on one) to "target" (which has the file +in state D). + + working index HEAD target working index HEAD + ---------------------------------------------------- + A B C D --soft A B D + --mixed A D D + --hard D D D + --merge (disallowed) + --keep (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + A B C C --soft A B C + --mixed A C C + --hard C C C + --merge (disallowed) + --keep A C C + + working index HEAD target working index HEAD + ---------------------------------------------------- + B B C D --soft B B D + --mixed B D D + --hard D D D + --merge D D D + --keep (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + B B C C --soft B B C + --mixed B C C + --hard C C C + --merge C C C + --keep B C C + + working index HEAD target working index HEAD + ---------------------------------------------------- + B C C D --soft B C D + --mixed B D D + --hard D D D + --merge (disallowed) + --keep (disallowed) -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + working index HEAD target working index HEAD + ---------------------------------------------------- + B C C C --soft B C C + --mixed B C C + --hard C C C + --merge B C C + --keep B C C + +"reset --merge" is meant to be used when resetting out of a conflicted +merge. Any mergy operation guarantees that the working tree file that is +involved in the merge does not have local change wrt the index before +it starts, and that it writes the result out to the working tree. So if +we see some difference between the index and the target and also +between the index and the working tree, then it means that we are not +resetting out from a state that a mergy operation left after failing +with a conflict. That is why we disallow --merge option in this case. + +"reset --keep" is meant to be used when removing some of the last +commits in the current branch while keeping changes in the working +tree. If there could be conflicts between the changes in the commit we +want to remove and the changes in the working tree we want to keep, +the reset is disallowed. That's why it is disallowed if there are both +changes between the working tree and HEAD, and between HEAD and the +target. To be safe, it is also disallowed when there are unmerged +entries. + +The following tables show what happens when there are unmerged +entries: + + working index HEAD target working index HEAD + ---------------------------------------------------- + X U A B --soft (disallowed) + --mixed X B B + --hard B B B + --merge B B B + --keep (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + X U A A --soft (disallowed) + --mixed X A A + --hard A A A + --merge A A A + --keep (disallowed) + +X means any state and U means an unmerged index. GIT --- diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 3341d1b62f..38fafcaa6b 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -9,34 +9,43 @@ git-rev-list - Lists commit objects in reverse chronological order SYNOPSIS -------- [verse] -'git-rev-list' [ \--max-count=number ] - [ \--skip=number ] - [ \--max-age=timestamp ] - [ \--min-age=timestamp ] +'git rev-list' [ \--max-count=<number> ] + [ \--skip=<number> ] + [ \--max-age=<timestamp> ] + [ \--min-age=<timestamp> ] [ \--sparse ] [ \--merges ] [ \--no-merges ] + [ \--min-parents=<number> ] + [ \--no-min-parents ] + [ \--max-parents=<number> ] + [ \--no-max-parents ] [ \--first-parent ] [ \--remove-empty ] [ \--full-history ] [ \--not ] [ \--all ] - [ \--branches ] - [ \--tags ] - [ \--remotes ] + [ \--branches[=<pattern>] ] + [ \--tags[=<pattern>] ] + [ \--remotes[=<pattern>] ] + [ \--glob=<glob-pattern> ] + [ \--ignore-missing ] [ \--stdin ] [ \--quiet ] [ \--topo-order ] [ \--parents ] [ \--timestamp ] [ \--left-right ] + [ \--left-only ] + [ \--right-only ] + [ \--cherry-mark ] [ \--cherry-pick ] [ \--encoding[=<encoding>] ] [ \--(author|committer|grep)=<pattern> ] [ \--regexp-ignore-case | -i ] [ \--extended-regexp | -E ] [ \--fixed-strings | -F ] - [ \--date={local|relative|default|iso|rfc|short} ] + [ \--date=(local|relative|default|iso|rfc|short) ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] [ \--bisect ] @@ -93,8 +102,8 @@ between the two operands. The following two commands are equivalent: 'rev-list' is a very essential git command, since it provides the ability to build and traverse commit ancestry graphs. For this reason, it has a lot of different options that enables it to be -used by commands as different as 'git-bisect' and -'git-repack'. +used by commands as different as 'git bisect' and +'git repack'. OPTIONS ------- @@ -104,16 +113,6 @@ include::rev-list-options.txt[] include::pretty-formats.txt[] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano, Jonas Fonseca -and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 82045a2522..8023dc086d 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -8,6 +8,7 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- +[verse] 'git rev-parse' [ --option ] <args>... DESCRIPTION @@ -15,16 +16,16 @@ DESCRIPTION Many git porcelainish commands take mixture of flags (i.e. parameters that begin with a dash '-') and parameters -meant for the underlying 'git-rev-list' command they use internally +meant for the underlying 'git rev-list' command they use internally and flags and parameters for the other commands they use -downstream of 'git-rev-list'. This command is used to +downstream of 'git rev-list'. This command is used to distinguish between them. OPTIONS ------- --parseopt:: - Use 'git-rev-parse' in option parsing mode (see PARSEOPT section below). + Use 'git rev-parse' in option parsing mode (see PARSEOPT section below). --keep-dashdash:: Only meaningful in `--parseopt` mode. Tells the option parser to echo @@ -33,20 +34,20 @@ OPTIONS --stop-at-non-option:: Only meaningful in `--parseopt` mode. Lets the option parser stop at the first non-option argument. This can be used to parse sub-commands - that take options themself. + that take options themselves. --sq-quote:: - Use 'git-rev-parse' in shell quoting mode (see SQ-QUOTE + Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE section below). In contrast to the `--sq` option below, this mode does only quoting. Nothing else is done to command input. --revs-only:: Do not output flags and parameters not meant for - 'git-rev-list' command. + 'git rev-list' command. --no-revs:: Do not output flags and parameters meant for - 'git-rev-list' command. + 'git rev-list' command. --flags:: Do not output non-flag parameters. @@ -74,7 +75,7 @@ OPTIONS properly quoted for consumption by shell. Useful when you expect your parameter to contain whitespaces and newlines (e.g. when using pickaxe `-S` with - 'git-diff-\*'). In contrast to the `--sq-quote` option, + 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, the command input is still interpreted as usual. --not:: @@ -95,22 +96,35 @@ OPTIONS unfortunately named tag "master"), and show them as full refnames (e.g. "refs/heads/master"). ---abbrev-ref[={strict|loose}]:: +--abbrev-ref[=(strict|loose)]:: A non-ambiguous short name of the objects name. The option core.warnAmbiguousRefs is used to select the strict abbreviation mode. --all:: - Show all refs found in `$GIT_DIR/refs`. - ---branches:: - Show branch refs found in `$GIT_DIR/refs/heads`. + Show all refs found in `refs/`. + +--branches[=pattern]:: +--tags[=pattern]:: +--remotes[=pattern]:: + Show all branches, tags, or remote-tracking branches, + respectively (i.e., refs found in `refs/heads`, + `refs/tags`, or `refs/remotes`, respectively). ++ +If a `pattern` is given, only refs matching the given shell glob are +shown. If the pattern does not contain a globbing character (`?`, +`{asterisk}`, or `[`), it is turned into a prefix match by +appending `/{asterisk}`. ---tags:: - Show tag refs found in `$GIT_DIR/refs/tags`. +--glob=pattern:: + Show all refs matching the shell glob pattern `pattern`. If + the pattern does not start with `refs/`, this is automatically + prepended. If the pattern does not contain a globbing + character (`?`, `{asterisk}`, or `[`), it is turned into a prefix + match by appending `/{asterisk}`. ---remotes:: - Show tag refs found in `$GIT_DIR/refs/remotes`. +--show-toplevel:: + Show the absolute path of the top-level directory. --show-prefix:: When the command is invoked from a subdirectory, show the @@ -123,7 +137,12 @@ OPTIONS directory (typically a sequence of "../", or an empty string). --git-dir:: - Show `$GIT_DIR` if defined else show the path to the .git directory. + Show `$GIT_DIR` if defined. Otherwise show the path to + the .git directory, relative to the current directory. ++ +If `$GIT_DIR` is not defined and the current directory +is not detected to lie in a git repository or work tree +print a message to stderr and exit with nonzero status. --is-inside-git-dir:: When the current working directory is below the repository @@ -136,6 +155,12 @@ OPTIONS --is-bare-repository:: When the repository is bare print "true", otherwise "false". +--local-env-vars:: + List the GIT_* environment variables that are local to the + repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). + Only the names of the variables are listed, not their value, + even if they are set. + --short:: --short=number:: Instead of outputting the full SHA1 values of object names try to @@ -145,223 +170,42 @@ OPTIONS --since=datestring:: --after=datestring:: Parse the date string, and output the corresponding - --max-age= parameter for 'git-rev-list'. + --max-age= parameter for 'git rev-list'. --until=datestring:: --before=datestring:: Parse the date string, and output the corresponding - --min-age= parameter for 'git-rev-list'. + --min-age= parameter for 'git rev-list'. <args>...:: Flags and parameters to be parsed. +--resolve-git-dir <path>:: + Check if <path> is a valid git-dir or a git-file pointing to a valid + git-dir. If <path> is a valid git-dir the resolved path to git-dir will + be printed. -SPECIFYING REVISIONS --------------------- - -A revision parameter typically, but not necessarily, names a -commit object. They use what is called an 'extended SHA1' -syntax. Here are various ways to spell object names. The -ones listed near the end of this list are to name trees and -blobs contained in a commit. - -* The full SHA1 object name (40-byte hexadecimal string), or - a substring of such that is unique within the repository. - E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both - name the same commit object if there are no other object in - your repository whose object name starts with dae86e. - -* An output from 'git-describe'; i.e. a closest tag, optionally - followed by a dash and a number of commits, followed by a dash, a - `g`, and an abbreviated object name. - -* A symbolic ref name. E.g. 'master' typically means the commit - object referenced by $GIT_DIR/refs/heads/master. If you - happen to have both heads/master and tags/master, you can - explicitly say 'heads/master' to tell git which one you mean. - When ambiguous, a `<name>` is disambiguated by taking the - first match in the following rules: - - . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`); - - . otherwise, `$GIT_DIR/refs/<name>` if exists; - - . otherwise, `$GIT_DIR/refs/tags/<name>` if exists; - - . otherwise, `$GIT_DIR/refs/heads/<name>` if exists; - - . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists; - - . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists. -+ -HEAD names the commit your changes in the working tree is based on. -FETCH_HEAD records the branch you fetched from a remote repository -with your last 'git-fetch' invocation. -ORIG_HEAD is created by commands that moves your HEAD in a drastic -way, to record the position of the HEAD before their operation, so that -you can change the tip of the branch back to the state before you ran -them easily. -MERGE_HEAD records the commit(s) you are merging into your branch -when you run 'git-merge'. - -* A ref followed by the suffix '@' with a date specification - enclosed in a brace - pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 - second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value - of the ref at a prior point in time. This suffix may only be - used immediately following a ref name and the ref must have an - existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state - of your *local* ref at a given time; e.g., what was in your local - `master` branch last week. If you want to look at commits made during - certain times, see `--since` and `--until`. - -* A ref followed by the suffix '@' with an ordinal specification - enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify - the n-th prior value of that ref. For example 'master@\{1\}' - is the immediate prior value of 'master' while 'master@\{5\}' - is the 5th prior value of 'master'. This suffix may only be used - immediately following a ref name and the ref must have an existing - log ($GIT_DIR/logs/<ref>). - -* You can use the '@' construct with an empty ref part to get at a - reflog of the current branch. For example, if you are on the - branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'. - -* The special construct '@\{-<n>\}' means the <n>th branch checked out - before the current one. - -* A suffix '{caret}' to a revision parameter means the first parent of - that commit object. '{caret}<n>' means the <n>th parent (i.e. - 'rev{caret}' - is equivalent to 'rev{caret}1'). As a special rule, - 'rev{caret}0' means the commit itself and is used when 'rev' is the - object name of a tag object that refers to a commit object. - -* A suffix '{tilde}<n>' to a revision parameter means the commit - object that is the <n>th generation grand-parent of the named - commit object, following only the first parent. I.e. rev~3 is - equivalent to rev{caret}{caret}{caret} which is equivalent to - rev{caret}1{caret}1{caret}1. See below for a illustration of - the usage of this form. - -* A suffix '{caret}' followed by an object type name enclosed in - brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object - could be a tag, and dereference the tag recursively until an - object of that type is found or the object cannot be - dereferenced anymore (in which case, barf). `rev{caret}0` - introduced earlier is a short-hand for `rev{caret}\{commit\}`. - -* A suffix '{caret}' followed by an empty brace pair - (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag, - and dereference the tag recursively until a non-tag object is - found. - -* A colon, followed by a slash, followed by a text: this names - a commit whose commit message starts with the specified text. - This name returns the youngest matching commit which is - reachable from any ref. If the commit message starts with a - '!', you have to repeat that; the special sequence ':/!', - followed by something else than '!' is reserved for now. - -* A suffix ':' followed by a path; this names the blob or tree - at the given path in the tree-ish object named by the part - before the colon. - -* A colon, optionally followed by a stage number (0 to 3) and a - colon, followed by a path; this names a blob object in the - index at the given path. Missing stage number (and the colon - that follows it) names a stage 0 entry. During a merge, stage - 1 is the common ancestor, stage 2 is the target branch's version - (typically the current branch), and stage 3 is the version from - the branch being merged. - -Here is an illustration, by Jon Loeliger. Both commit nodes B -and C are parents of commit node A. Parent commits are ordered -left-to-right. - -........................................ -G H I J - \ / \ / - D E F - \ | / \ - \ | / | - \|/ | - B C - \ / - \ / - A -........................................ - - A = = A^0 - B = A^ = A^1 = A~1 - C = A^2 = A^2 - D = A^^ = A^1^1 = A~2 - E = B^2 = A^^2 - F = B^3 = A^^3 - G = A^^^ = A^1^1^1 = A~3 - H = D^2 = B^^2 = A^^^2 = A~2^2 - I = F^ = B^3^ = A^^3^ - J = F^2 = B^3^2 = A^^3^2 - - -SPECIFYING RANGES ------------------ - -History traversing commands such as 'git-log' operate on a set -of commits, not just a single commit. To these commands, -specifying a single revision with the notation described in the -previous section means the set of commits reachable from that -commit, following the commit ancestry chain. - -To exclude commits reachable from a commit, a prefix `{caret}` -notation is used. E.g. `{caret}r1 r2` means commits reachable -from `r2` but exclude the ones reachable from `r1`. - -This set operation appears so often that there is a shorthand -for it. When you have two commits `r1` and `r2` (named according -to the syntax explained in SPECIFYING REVISIONS above), you can ask -for commits that are reachable from r2 excluding those that are reachable -from r1 by `{caret}r1 r2` and it can be written as `r1..r2`. - -A similar notation `r1\...r2` is called symmetric difference -of `r1` and `r2` and is defined as -`r1 r2 --not $(git merge-base --all r1 r2)`. -It is the set of commits that are reachable from either one of -`r1` or `r2` but not from both. - -Two other shorthands for naming a set that is formed by a commit -and its parent commits exist. The `r1{caret}@` notation means all -parents of `r1`. `r1{caret}!` includes commit `r1` but excludes -all of its parents. - -Here are a handful of examples: - - D G H D - D F G H I J D F - ^G D H D - ^D B E I J F B - B...C G H D E B C - ^D B C E I J F B C - C^@ I J F - F^! D G H D F +include::revisions.txt[] PARSEOPT -------- -In `--parseopt` mode, 'git-rev-parse' helps massaging options to bring to shell +In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell scripts the same facilities C builtins have. It works as an option normalizer (e.g. splits single switches aggregate values), a bit like `getopt(1)` does. It takes on the standard input the specification of the options to parse and -understand, and echoes on the standard output a line suitable for `sh(1)` `eval` +understand, and echoes on the standard output a string suitable for `sh(1)` `eval` to replace the arguments with normalized ones. In case of error, it outputs usage on the standard error stream, and exits with code 129. +Note: Make sure you quote the result when passing it to `eval`. See +below for an example. + Input Format ~~~~~~~~~~~~ -'git-rev-parse --parseopt' input format is fully text based. It has two parts, +'git rev-parse --parseopt' input format is fully text based. It has two parts, separated by a line that contains only `--`. The lines before the separator (should be more than one) are used for the usage. The lines after the separator describe the options. @@ -414,19 +258,19 @@ bar= some cool option --bar with an argument An option group Header C? option C with an optional argument" -eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?` +eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" ------------ SQ-QUOTE -------- -In `--sq-quote` mode, 'git-rev-parse' echoes on the standard output a +In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a single line suitable for `sh(1)` `eval`. This line is made by normalizing the arguments following `--sq-quote`. Nothing other than quoting the arguments is done. If you want command input to still be interpreted as usual by -'git-rev-parse' before the output is shell quoted, see the `--sq` +'git rev-parse' before the output is shell quoted, see the `--sq` option. Example @@ -469,16 +313,6 @@ $ git rev-parse --default master --verify $REV + but if $REV is empty, the commit object name from master will be printed. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> . -Junio C Hamano <gitster@pobox.com> and Pierre Habouzit <madcoder@debian.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 5e1175800a..f3519413e7 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -3,37 +3,45 @@ git-revert(1) NAME ---- -git-revert - Revert an existing commit +git-revert - Revert some existing commits SYNOPSIS -------- -'git revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit> +[verse] +'git revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit>... +'git revert' --reset +'git revert' --continue DESCRIPTION ----------- -Given one existing commit, revert the change the patch introduces, and record a -new commit that records it. This requires your working tree to be clean (no -modifications from the HEAD commit). -Note: 'git revert' is used to record a new commit to reverse the -effect of an earlier commit (often a faulty one). If you want to +Given one or more existing commits, revert the changes that the +related patches introduce, and record some new commits that record +them. This requires your working tree to be clean (no modifications +from the HEAD commit). + +Note: 'git revert' is used to record some new commits to reverse the +effect of some earlier commits (often only a faulty one). If you want to throw away all uncommitted changes in your working directory, you should see linkgit:git-reset[1], particularly the '--hard' option. If you want to extract specific files as they were in another commit, you -should see linkgit:git-checkout[1], specifically the 'git checkout -<commit> -- <filename>' syntax. Take care with these alternatives as +should see linkgit:git-checkout[1], specifically the `git checkout +<commit> \-- <filename>` syntax. Take care with these alternatives as both will discard uncommitted changes in your working directory. OPTIONS ------- -<commit>:: - Commit to revert. +<commit>...:: + Commits to revert. For a more complete list of ways to spell commit names, see - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + linkgit:gitrevisions[7]. + Sets of commits can also be given but no traversal is done by + default, see linkgit:git-rev-list[1] and its '--no-walk' + option. -e:: --edit:: - With this option, 'git-revert' will let you edit the commit + With this option, 'git revert' will let you edit the commit message prior to committing the revert. This is the default if you run the command from a terminal. @@ -54,16 +62,16 @@ See the link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for more details. --no-edit:: - With this option, 'git-revert' will not start the commit + With this option, 'git revert' will not start the commit message editor. -n:: --no-commit:: - Usually the command automatically creates a commit with - a commit log message stating which commit was - reverted. This flag applies the change necessary - to revert the named commit to your working tree - and the index, but does not make the commit. In addition, + Usually the command automatically creates some commits with + commit log messages stating which commits were + reverted. This flag applies the changes necessary + to revert the named commits to your working tree + and the index, but does not make the commits. In addition, when this option is used, your index does not have to match the HEAD commit. The revert is done against the beginning state of your index. @@ -75,14 +83,38 @@ effect to your index in a row. --signoff:: Add Signed-off-by line at the end of the commit message. +--strategy=<strategy>:: + Use the given merge strategy. Should only be used once. + See the MERGE STRATEGIES section in linkgit:git-merge[1] + for details. + +-X<option>:: +--strategy-option=<option>:: + Pass the merge strategy-specific option through to the + merge strategy. See linkgit:git-merge[1] for details. + +SEQUENCER SUBCOMMANDS +--------------------- +include::sequencer.txt[] + +EXAMPLES +-------- +`git revert HEAD~3`:: + + Revert the changes specified by the fourth last commit in HEAD + and create a new commit with the reverted changes. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> +`git revert -n master{tilde}5..master{tilde}2`:: -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + Revert the changes done by commits from the fifth last commit + in master (included) to the third last commit in master + (included), but do not create any commit with the reverted + changes. The revert only modifies the working tree and the + index. + +SEE ALSO +-------- +linkgit:git-cherry-pick[1] GIT --- diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index c21d19e573..665ad4ddab 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -7,6 +7,7 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- +[verse] 'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... DESCRIPTION @@ -78,7 +79,8 @@ a file that you have not told git about does not remove that file. File globbing matches across directory boundaries. Thus, given two directories `d` and `d2`, there is a difference between -using `git rm \'d\*\'` and `git rm \'d/\*\'`, as the former will +using `git rm {apostrophe}d{asterisk}{apostrophe}` and +`git rm {apostrophe}d/{asterisk}{apostrophe}`, as the former will also remove all of directory `d2`. REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM @@ -88,8 +90,8 @@ the paths that have disappeared from the filesystem. However, depending on the use case, there are several ways that can be done. -Using "git commit -a" -~~~~~~~~~~~~~~~~~~~~~ +Using ``git commit -a'' +~~~~~~~~~~~~~~~~~~~~~~~ If you intend that your next commit should record all modifications of tracked files in the working tree and record all removals of files that have been removed from the working tree with `rm` @@ -97,8 +99,8 @@ files that have been removed from the working tree with `rm` automatically notice and record all removals. You can also have a similar effect without committing by using `git add -u`. -Using "git add -A" -~~~~~~~~~~~~~~~~~~ +Using ``git add -A'' +~~~~~~~~~~~~~~~~~~~~ When accepting a new code drop for a vendor branch, you probably want to record both the removal of paths and additions of new paths as well as modifications of existing paths. @@ -110,8 +112,8 @@ tree using this command: git ls-files -z | xargs -0 rm -f ---------------- -and then "untar" the new code in the working tree. Alternately -you could "rsync" the changes into the working tree. +and then untar the new code in the working tree. Alternately +you could 'rsync' the changes into the working tree. After that, the easiest way to record all removals, additions, and modifications in the working tree is: @@ -135,15 +137,15 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached EXAMPLES -------- -git rm Documentation/\\*.txt:: - Removes all `\*.txt` files from the index that are under the +`git rm Documentation/\*.txt`:: + Removes all `*.txt` files from the index that are under the `Documentation` directory and any of its subdirectories. + -Note that the asterisk `\*` is quoted from the shell in this +Note that the asterisk `*` is quoted from the shell in this example; this lets git, and not the shell, expand the pathnames of files and subdirectories under the `Documentation/` directory. -git rm -f git-*.sh:: +`git rm -f git-*.sh`:: Because this example lets the shell expand the asterisk (i.e. you are listing the files explicitly), it does not remove `subdir/git-foo.sh`. @@ -152,14 +154,6 @@ SEE ALSO -------- linkgit:git-add[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index ced35b2f53..327233c85b 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -8,6 +8,7 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- +[verse] 'git send-email' [options] <file|directory|rev-list options>... @@ -82,11 +83,26 @@ See the CONFIGURATION section for 'sendemail.multiedit'. set, as returned by "git var -l". --in-reply-to=<identifier>:: - Specify the contents of the first In-Reply-To header. - Subsequent emails will refer to the previous email - instead of this if --chain-reply-to is set. - Only necessary if --compose is also set. If --compose - is not set, this will be prompted for. + Make the first mail (or all the mails with `--no-thread`) appear as a + reply to the given Message-Id, which avoids breaking threads to + provide a new patch series. + The second and subsequent emails will be sent as replies according to + the `--[no]-chain-reply-to` setting. ++ +So for example when `--thread` and `--no-chain-reply-to` are specified, the +second and subsequent patches will be replies to the first one like in the +illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`: ++ + [PATCH 0/2] Here is what I did... + [PATCH 1/2] Clean up and tests + [PATCH 2/2] Implementation + [PATCH v2 0/3] Here is a reroll + [PATCH v2 1/3] Clean up + [PATCH v2 2/3] New tests + [PATCH v2 3/3] Implementation ++ +Only necessary if --compose is also set. If --compose +is not set, this will be prompted for. --subject=<string>:: Specify the initial subject of the email thread. @@ -97,10 +113,19 @@ See the CONFIGURATION section for 'sendemail.multiedit'. Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the project involved. Default is the value of the 'sendemail.to' configuration value; if that is unspecified, - this will be prompted for. + and --to-cmd is not specified, this will be prompted for. + The --to option must be repeated for each user you want on the to list. +--8bit-encoding=<encoding>:: + When encountering a non-ASCII message or subject that does not + declare its encoding, add headers/quoting to indicate it is + encoded in <encoding>. Default is the value of the + 'sendemail.assume8bitEncoding'; if that is unspecified, this + will be prompted for if any non-ASCII files are encountered. ++ +Note that no attempts whatsoever are made to validate the encoding. + Sending ~~~~~~~ @@ -119,6 +144,13 @@ Sending value reverts to plain SMTP. Default is the value of 'sendemail.smtpencryption'. +--smtp-domain=<FQDN>:: + Specifies the Fully Qualified Domain Name (FQDN) used in the + HELO/EHLO command to the SMTP server. Some servers require the + FQDN to match your IP address. If not set, git send-email attempts + to determine your FQDN automatically. Default is the value of + 'sendemail.smtpdomain'. + --smtp-pass[=<password>]:: Password for SMTP-AUTH. The argument is optional: If no argument is specified, then the empty string is used as @@ -149,6 +181,15 @@ user is prompted for a password while the input is masked for privacy. are also accepted. The port can also be set with the 'sendemail.smtpserverport' configuration variable. +--smtp-server-option=<option>:: + If set, specifies the outgoing SMTP server option to use. + Default value can be specified by the 'sendemail.smtpserveroption' + configuration option. ++ +The --smtp-server-option option must be repeated for each option you want +to pass to the server. Likewise, different lines in the configuration files +must be used for each option. + --smtp-ssl:: Legacy alias for '--smtp-encryption ssl'. @@ -161,6 +202,12 @@ user is prompted for a password while the input is masked for privacy. Automating ~~~~~~~~~~ +--to-cmd=<command>:: + Specify a command to execute once per patch file which + should generate patch file specific "To:" entries. + Output of this command must be single email address per line. + Default is the value of 'sendemail.tocmd' configuration value. + --cc-cmd=<command>:: Specify a command to execute once per patch file which should generate patch file specific "Cc:" entries. @@ -276,6 +323,9 @@ have been specified, in which case default to 'compose'. Default is the value of 'sendemail.validate'; if this is not set, default to '--validate'. +--force:: + Send emails even if safety checks would prevent it. + CONFIGURATION ------------- @@ -299,19 +349,32 @@ sendemail.confirm:: one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm' in the previous section for the meaning of these values. +EXAMPLE +------- +Use gmail as the smtp server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To use 'git send-email' to send your patches through the GMail SMTP server, +edit ~/.gitconfig to specify your account settings: -Author ------- -Written by Ryan Anderson <ryan@michonline.com> + [sendemail] + smtpencryption = tls + smtpserver = smtp.gmail.com + smtpuser = yourname@gmail.com + smtpserverport = 587 -git-send-email is originally based upon -send_lots_of_email.pl by Greg Kroah-Hartman. +Once your commits are ready to be sent to the mailing list, run the +following commands: + $ git format-patch --cover-letter -M origin/master -o outgoing/ + $ edit outgoing/0000-* + $ git send-email outgoing/* -Documentation --------------- -Documentation by Ryan Anderson +Note: the following perl modules are required + Net::SMTP::SSL, MIME::Base64 and Authen::SASL +SEE ALSO +-------- +linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5) GIT --- diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 5a04c6eaf7..bd3eaa69bf 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -8,11 +8,12 @@ git-send-pack - Push objects over git protocol to another repository SYNOPSIS -------- +[verse] 'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] DESCRIPTION ----------- -Usually you would want to use 'git-push', which is a +Usually you would want to use 'git push', which is a higher-level wrapper of this command, instead. See linkgit:git-push[1]. Invokes 'git-receive-pack' on a possibly remote repository, and @@ -48,8 +49,8 @@ OPTIONS Run verbosely. --thin:: - Spend extra cycles to minimize the number of objects to be sent. - Use it on slower connection. + Send a "thin" pack, which records objects in deltified form based + on objects not included in the pack to reduce network traffic. <host>:: A remote host to house the repository. When this @@ -86,7 +87,7 @@ and the destination side (after the colon). The ref to be pushed is determined by finding a match that matches the source side, and where it is pushed is determined by using the destination side. The rules used to match a ref are the same -rules used by 'git-rev-parse' to resolve a symbolic ref +rules used by 'git rev-parse' to resolve a symbolic ref name. See linkgit:git-rev-parse[1]. - It is an error if <src> does not match exactly one of the @@ -114,15 +115,6 @@ With '--force', the fast-forward check is disabled for all refs. Optionally, a <ref> parameter can be prefixed with a plus '+' sign to disable the fast-forward check only on that ref. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt new file mode 100644 index 0000000000..5c3ec327bb --- /dev/null +++ b/Documentation/git-sh-i18n--envsubst.txt @@ -0,0 +1,36 @@ +git-sh-i18n{litdd}envsubst(1) +============================= + +NAME +---- +git-sh-i18n--envsubst - Git's own envsubst(1) for i18n fallbacks + +SYNOPSIS +-------- +[verse] +eval_gettext () { + printf "%s" "$1" | ( + export PATH $('git sh-i18n{litdd}envsubst' --variables "$1"); + 'git sh-i18n{litdd}envsubst' "$1" + ) +} + +DESCRIPTION +----------- + +This is not a command the end user would want to run. Ever. +This documentation is meant for people who are studying the +plumbing scripts and/or are writing new ones. + +'git sh-i18n{litdd}envsubst' is Git's stripped-down copy of the GNU +`envsubst(1)` program that comes with the GNU gettext package. It's +used internally by linkgit:git-sh-i18n[1] to interpolate the variables +passed to the the `eval_gettext` function. + +No promises are made about the interface, or that this +program won't disappear without warning in the next version +of Git. Don't use it. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-sh-i18n.txt b/Documentation/git-sh-i18n.txt new file mode 100644 index 0000000000..60cf49cb2a --- /dev/null +++ b/Documentation/git-sh-i18n.txt @@ -0,0 +1,43 @@ +git-sh-i18n(1) +============== + +NAME +---- +git-sh-i18n - Git's i18n setup code for shell scripts + +SYNOPSIS +-------- +[verse] +'. "$(git --exec-path)/git-sh-i18n"' + +DESCRIPTION +----------- + +This is not a command the end user would want to run. Ever. +This documentation is meant for people who are studying the +Porcelain-ish scripts and/or are writing new ones. + +The 'git sh-i18n scriptlet is designed to be sourced (using +`.`) by Git's porcelain programs implemented in shell +script. It provides wrappers for the GNU `gettext` and +`eval_gettext` functions accessible through the `gettext.sh` +script, and provides pass-through fallbacks on systems +without GNU gettext. + +FUNCTIONS +--------- + +gettext:: + Currently a dummy fall-through function implemented as a wrapper + around `printf(1)`. Will be replaced by a real gettext + implementation in a later version. + +eval_gettext:: + Currently a dummy fall-through function implemented as a wrapper + around `printf(1)` with variables expanded by the + linkgit:git-sh-i18n{litdd}envsubst[1] helper. Will be replaced by a + real gettext implementation in a later version. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 18f14b5be8..a2f346ca71 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -7,6 +7,7 @@ git-sh-setup - Common git shell script setup code SYNOPSIS -------- +[verse] '. "$(git --exec-path)/git-sh-setup"' DESCRIPTION @@ -16,7 +17,7 @@ This is not a command the end user would want to run. Ever. This documentation is meant for people who are studying the Porcelain-ish scripts and/or are writing new ones. -The 'git-sh-setup' scriptlet is designed to be sourced (using +The 'git sh-setup' scriptlet is designed to be sourced (using `.`) by other shell scripts to set up some variables pointing at the normal git directories and a few helper shell functions. @@ -58,23 +59,19 @@ cd_to_toplevel:: runs chdir to the toplevel of the working tree. require_work_tree:: - checks if the repository is a bare repository, and dies - if so. Used by scripts that require working tree - (e.g. `checkout`). + checks if the current directory is within the working tree + of the repository, and otherwise dies. + +require_work_tree_exists:: + checks if the working tree associated with the repository + exists, and otherwise dies. Often done before calling + cd_to_toplevel, which is impossible to do if there is no + working tree. get_author_ident_from_commit:: outputs code for use with eval to set the GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 0f3ad811cf..9b9250600f 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -3,32 +3,31 @@ git-shell(1) NAME ---- -git-shell - Restricted login shell for GIT-only SSH access +git-shell - Restricted login shell for Git-only SSH access SYNOPSIS -------- -'$(git --exec-path)/git-shell' -c <command> <argument> +[verse] +'git shell' [-c <command> <argument>] DESCRIPTION ----------- -This is meant to be used as a login shell for SSH accounts you want -to restrict to GIT pull/push access only. It permits execution only -of server-side GIT commands implementing the pull/push functionality. -The commands can be executed only by the '-c' option; the shell is not -interactive. - -Currently, only four commands are permitted to be called, 'git-receive-pack' -'git-upload-pack' and 'git-upload-archive' with a single required argument, or -'cvs server' (to invoke 'git-cvsserver'). - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Petr Baudis and the git-list <git@vger.kernel.org>. + +A login shell for SSH accounts to provide restricted Git access. When +'-c' is given, the program executes <command> non-interactively; +<command> can be one of 'git receive-pack', 'git upload-pack', 'git +upload-archive', 'cvs server', or a command in COMMAND_DIR. The shell +is started in interactive mode when no arguments are given; in this +case, COMMAND_DIR must exist, and any of the executables in it can be +invoked. + +'cvs server' is a special command which executes git-cvsserver. + +COMMAND_DIR is the path "$HOME/git-shell-commands". The user must have +read and execute permissions to the directory in order to execute the +programs in it. The programs are executed with a cwd of $HOME, and +<argument> is parsed as a command-line string. GIT --- diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 42463a955d..ff3755b4c7 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -3,22 +3,27 @@ git-shortlog(1) NAME ---- -git-shortlog - Summarize 'git-log' output +git-shortlog - Summarize 'git log' output SYNOPSIS -------- [verse] git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] -git shortlog [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<committish>...] +'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] <commit>... DESCRIPTION ----------- -Summarizes 'git-log' output in a format suitable for inclusion +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. Additionally, "[PATCH]" will be stripped from the commit description. +If no revisions are passed on the command line and either standard input +is not a terminal or there is no current branch, 'git shortlog' will +output a summary of the log read from standard input, without +reference to the current repository. + OPTIONS ------- @@ -39,6 +44,14 @@ OPTIONS --email:: Show the email address of each author. +--format[=<format>]:: + Instead of the commit subject, use some other information to + describe each commit. '<format>' can be any string accepted + by the `--format` option of 'git log', such as '{asterisk} [%h] %s'. + (See the "PRETTY FORMATS" section of linkgit:git-log[1].) + + Each pretty-printed commit will be rewrapped before it is shown. + -w[<width>[,<indent1>[,<indent2>]]]:: Linewrap the output by wrapping each line at `width`. The first line of each entry is indented by `indent1` spaces, and the second @@ -55,15 +68,6 @@ spelled differently. include::mailmap.txt[] - -Author ------- -Written by Jeff Garzik <jgarzik@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 734336119c..a8e77b5350 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -9,19 +9,18 @@ SYNOPSIS -------- [verse] 'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order] - [--current] [--color | --no-color] [--sparse] + [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] - [<rev> | <glob>]... - + [(<rev> | <glob>)...] 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION ----------- Shows the commit ancestry graph starting from the commits named -with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads -and/or $GIT_DIR/refs/tags) semi-visually. +with <rev>s or <globs>s (or all refs under refs/heads +and/or refs/tags) semi-visually. It cannot show more than 29 branches and commits at a time. @@ -32,13 +31,13 @@ no <rev> nor <glob> is given on the command line. OPTIONS ------- <rev>:: - Arbitrary extended SHA1 expression (see linkgit:git-rev-parse[1]) + Arbitrary extended SHA1 expression (see linkgit:gitrevisions[7]) that typically names a branch head or a tag. <glob>:: A glob pattern that matches branch or tag names under - $GIT_DIR/refs. For example, if you have many topic - branches under $GIT_DIR/refs/heads/topic, giving + refs/. For example, if you have many topic + branches under refs/heads/topic, giving `topic/*` would show all of them. -r:: @@ -117,13 +116,15 @@ OPTIONS When no explicit <ref> parameter is given, it defaults to the current branch (or `HEAD` if it is detached). ---color:: +--color[=<when>]:: Color the status sign (one of these: `*` `!` `+` `-`) of each commit corresponding to the branch it's in. + The value must be always (the default), never, or auto. --no-color:: Turn off colored output, even when the configuration file gives the default to color output. + Same as `--color=never`. Note that --more, --list, --independent and --merge-base options are mutually exclusive. @@ -166,17 +167,17 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master], -whose commit message is "Add \'git show-branch\'". The "fixes" -branch adds one commit "Introduce "reset type" flag to "git reset"". -The "mhf" branch adds many other commits. The current branch -is "master". +whose commit message is "Add {apostrophe}git show-branch{apostrophe}". +The "fixes" branch adds one commit "Introduce "reset type" flag to +"git reset"". The "mhf" branch adds many other commits. +The current branch is "master". EXAMPLE ------- If you keep your primary branches immediately under -`$GIT_DIR/refs/heads`, and topic branches in subdirectories of +`refs/heads`, and topic branches in subdirectories of it, having the following in the configuration file may help: ------------ @@ -198,17 +199,6 @@ shows 10 reflog entries going back from the tip as of 1 hour ago. Without `--list`, the output also shows how these tips are topologically related with each other. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by Junio C Hamano. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index e3285aacfd..2dcbbb2454 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -8,27 +8,19 @@ git-show-index - Show packed archive index SYNOPSIS -------- +[verse] 'git show-index' < idx-file DESCRIPTION ----------- Reads given idx file for packed git archive created with -'git-pack-objects' command, and dumps its contents. +'git pack-objects' command, and dumps its contents. The information it outputs is subset of what you can get from -'git-verify-pack -v'; this command only shows the packfile +'git verify-pack -v'; this command only shows the packfile offset and SHA1 of each object. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 70f400b266..3c45895299 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference] [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] - [--heads] [--] <pattern>... + [--heads] [--] [<pattern>...] 'git show-ref' --exclude-existing[=<pattern>] < ref-list DESCRIPTION @@ -72,9 +72,9 @@ OPTIONS --exclude-existing[=<pattern>]:: - Make 'git-show-ref' act as a filter that reads refs from stdin of the - form "^(?:<anything>\s)?<refname>(?:\^\{\})?$" and performs the - following actions on each: + Make 'git show-ref' act as a filter that reads refs from stdin of the + form "^(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$" + and performs the following actions on each: (1) strip "^{}" at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; @@ -84,7 +84,11 @@ OPTIONS <pattern>...:: - Show references matching one or more patterns. + Show references matching one or more patterns. Patterns are matched from + the end of the full name, and only complete parts are matched, e.g. + 'master' matches 'refs/heads/master', 'refs/remotes/origin/master', + 'refs/tags/jedi/master' but not 'refs/heads/mymaster' nor + 'refs/remotes/master/jedi'. OUTPUT ------ @@ -135,7 +139,7 @@ When using the '--verify' flag, the command requires an exact path: will only match the exact branch called "master". -If nothing matches, 'git-show-ref' will return an error code of 1, +If nothing matches, 'git show-ref' will return an error code of 1, and in the case of verification, it will show an error message. For scripting, you can ask it to be quiet with the "--quiet" flag, which @@ -163,14 +167,15 @@ flag, so you can do to get a listing of all tags together with what they dereference. +FILES +----- +`.git/refs/*`, `.git/packed-refs` + SEE ALSO -------- -linkgit:git-ls-remote[1] - -AUTHORS -------- -Written by Linus Torvalds <torvalds@osdl.org>. -Man page by Jonas Fonseca <fonseca@diku.dk>. +linkgit:git-ls-remote[1], +linkgit:git-update-ref[1], +linkgit:gitrepository-layout[5] GIT --- diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 48b612e2ae..1e38819e67 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -8,6 +8,7 @@ git-show - Show various types of objects SYNOPSIS -------- +[verse] 'git show' [options] <object>... DESCRIPTION @@ -16,16 +17,16 @@ Shows one or more objects (blobs, trees, tags and commits). For commits it shows the log message and textual diff. It also presents the merge commit in a special format as produced by -'git-diff-tree --cc'. +'git diff-tree --cc'. For tags, it shows the tag message and the referenced objects. -For trees, it shows the names (equivalent to 'git-ls-tree' +For trees, it shows the names (equivalent to 'git ls-tree' with \--name-only). For plain blobs, it shows the plain contents. -The command takes options applicable to the 'git-diff-tree' command to +The command takes options applicable to the 'git diff-tree' command to control how the changes the commit introduces are shown. This manual page describes only the most frequently used options. @@ -36,7 +37,7 @@ OPTIONS <object>...:: The names of objects to show. For a more complete list of ways to spell object names, see - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. include::pretty-options.txt[] @@ -47,19 +48,23 @@ include::pretty-formats.txt[] EXAMPLES -------- -git show v1.0.0:: +`git show v1.0.0`:: Shows the tag `v1.0.0`, along with the object the tags points at. -git show v1.0.0^\{tree\}:: +`git show v1.0.0^\{tree\}`:: Shows the tree pointed to by the tag `v1.0.0`. -git show next~10:Documentation/README:: +`git show -s --format=%s v1.0.0^\{commit\}`:: + Shows the subject of the commit pointed to by the + tag `v1.0.0`. + +`git show next~10:Documentation/README`:: Shows the contents of the file `Documentation/README` as they were current in the 10th last commit of the branch `next`. -git show master:Makefile master:t/Makefile:: +`git show master:Makefile master:t/Makefile`:: Concatenates the contents of said Makefiles in the head of the branch `master`. @@ -68,17 +73,6 @@ Discussion include::i18n.txt[] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com>. Significantly enhanced by -Johannes Schindelin <Johannes.Schindelin@gmx.de>. - - -Documentation -------------- -Documentation by David Greaves, Petr Baudis and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt index 7f251a5865..ba3fe0d7f5 100644 --- a/Documentation/git-stage.txt +++ b/Documentation/git-stage.txt @@ -17,3 +17,7 @@ DESCRIPTION This is a synonym for linkgit:git-add[1]. Please refer to the documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 3f14b727b8..43af38aa4b 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -13,14 +13,15 @@ SYNOPSIS 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] [<message>]] +'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] + [-u|--include-untracked] [-a|--all] [<message>]] 'git stash' clear 'git stash' create DESCRIPTION ----------- -Use 'git stash' when you want to record the current state of the +Use `git stash` when you want to record the current state of the working directory and the index, but want to go back to a clean working directory. The command saves your local modifications away and reverts the working directory to match the `HEAD` commit. @@ -33,7 +34,7 @@ A stash is by default listed as "WIP on 'branchname' ...", but you can give a more descriptive message on the command line when you create one. -The latest stash you created is stored in `$GIT_DIR/refs/stash`; older +The latest stash you created is stored in `refs/stash`; older stashes are found in the reflog of this reference and can be named using the usual reflog syntax (e.g. `stash@\{0}` is the most recently created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}` @@ -42,7 +43,7 @@ is also possible). OPTIONS ------- -save [--patch] [--[no-]keep-index] [-q|--quiet] [<message>]:: +save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: Save your local modifications to a new 'stash', and run `git reset --hard` to revert them. The <message> part is optional and gives @@ -54,12 +55,18 @@ save [--patch] [--[no-]keep-index] [-q|--quiet] [<message>]:: If the `--keep-index` option is used, all changes already added to the index are left intact. + -With `--patch`, you can interactively select hunks from in the diff +If the `--include-untracked` option is used, all untracked files are also +stashed and then cleaned up with `git clean`, leaving the working directory +in a very clean state. If the `--all` option is used instead then the +ignored files are stashed and cleaned in addition to the untracked files. ++ +With `--patch`, you can interactively select hunks from the diff between HEAD and the working tree to be stashed. The stash entry is constructed such that its index state is the same as the index state of your repository, and its worktree contains only the changes you selected interactively. The selected changes are then rolled back -from your worktree. +from your worktree. See the ``Interactive Mode'' section of +linkgit:git-add[1] to learn how to operate the `\--patch` mode. + The `--patch` option implies `--keep-index`. You can use `--no-keep-index` to override this. @@ -77,7 +84,7 @@ stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation stash@{1}: On master: 9cc0589... Add git-stash ---------------------------------------------------------------- + -The command takes options applicable to the 'git-log' +The command takes options applicable to the 'git log' command to control what is shown and how. See linkgit:git-log[1]. show [<stash>]:: @@ -85,7 +92,7 @@ show [<stash>]:: Show the changes recorded in the stash as a diff between the stashed state and its original parent. When no `<stash>` is given, shows the latest one. By default, the command shows the diffstat, but - it will accept any format known to 'git-diff' (e.g., `git stash show + it will accept any format known to 'git diff' (e.g., `git stash show -p stash@\{1}` to view the second most recent stash in patch form). pop [--index] [-q|--quiet] [<stash>]:: @@ -104,18 +111,22 @@ tree's changes, but also the index's ones. However, this can fail, when you have conflicts (which are stored in the index, where you therefore can no longer apply the changes as they were originally). + -When no `<stash>` is given, `stash@\{0}` is assumed. +When no `<stash>` is given, `stash@\{0}` is assumed, otherwise `<stash>` must +be a reference of the form `stash@\{<revision>}`. apply [--index] [-q|--quiet] [<stash>]:: - Like `pop`, but do not remove the state from the stash list. + Like `pop`, but do not remove the state from the stash list. Unlike `pop`, + `<stash>` may be any commit that looks like a commit created by + `stash save` or `stash create`. branch <branchname> [<stash>]:: Creates and checks out a new branch named `<branchname>` starting from the commit at which the `<stash>` was originally created, applies the - changes recorded in `<stash>` to the new working tree and index, then - drops the `<stash>` if that completes successfully. When no `<stash>` + changes recorded in `<stash>` to the new working tree and index. + If that succeeds, and `<stash>` is a reference of the form + `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>` is given, applies the latest one. + This is useful if the branch on which you ran `git stash save` has @@ -132,7 +143,9 @@ clear:: drop [-q|--quiet] [<stash>]:: Remove a single stashed state from the stash list. When no `<stash>` - is given, it removes the latest one. i.e. `stash@\{0}` + is given, it removes the latest one. i.e. `stash@\{0}`, otherwise + `<stash>` must a valid stash log reference of the form + `stash@\{<revision>}`. create:: @@ -201,7 +214,7 @@ $ git reset --soft HEAD^ # ... continue hacking ... ---------------------------------------------------------------- + -You can use 'git-stash' to simplify the above, like this: +You can use 'git stash' to simplify the above, like this: + ---------------------------------------------------------------- # ... hack hack hack ... @@ -251,10 +264,6 @@ linkgit:git-commit[1], linkgit:git-reflog[1], linkgit:git-reset[1] -AUTHOR ------- -Written by Nanako Shiraishi <nanako3@bluebottle.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index b3dfa42cc0..3d51717bbe 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -8,6 +8,7 @@ git-status - Show the working tree status SYNOPSIS -------- +[verse] 'git status' [<options>...] [--] [<pathspec>...] DESCRIPTION @@ -17,7 +18,7 @@ current HEAD commit, paths that have differences between the working tree and the index file, and paths in the working tree that are not tracked by git (and are not ignored by linkgit:gitignore[5]). The first are what you _would_ commit by running `git commit`; the second and -third are what you _could_ commit by running 'git-add' before running +third are what you _could_ commit by running 'git add' before running `git commit`. OPTIONS @@ -27,27 +28,50 @@ OPTIONS --short:: Give the output in the short-format. +-b:: +--branch:: + Show the branch and tracking info even in short-format. + --porcelain:: - Give the output in a stable, easy-to-parse format for scripts. - Currently this is identical to --short output, but is guaranteed - not to change in the future, making it safe for scripts. + Give the output in an easy-to-parse format for scripts. + This is similar to the short output, but will remain stable + across git versions and regardless of user configuration. See + below for details. -u[<mode>]:: --untracked-files[=<mode>]:: - Show untracked files (Default: 'all'). + Show untracked files. ++ +The mode parameter is optional (defaults to 'all'), and is used to +specify the handling of untracked files; when -u is not used, the +default is 'normal', i.e. show untracked files and directories. + -The mode parameter is optional, and is used to specify -the handling of untracked files. The possible options are: +The possible options are: + --- - 'no' - Show no untracked files - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. --- + -See linkgit:git-config[1] for configuration variable -used to change the default for when the option is not -specified. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. + +--ignore-submodules[=<when>]:: + Ignore changes to submodules when looking for changes. <when> can be + either "none", "untracked", "dirty" or "all", which is the default. + Using "none" will consider the submodule modified when it either contains + untracked or modified files or its HEAD differs from the commit recorded + in the superproject and can be used to override any settings of the + 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When + "untracked" is used submodules are not considered dirty when they only + contain untracked content (but they are still scanned for modified + content). Using "dirty" ignores all changes to the work tree of submodules, + only changes to the commits stored in the superproject are shown (this was + the behavior before 1.7.0). Using "all" hides all changes to submodules + (and suppresses the output of submodule summaries when the config option + `status.submodulesummary` is set). + +--ignored:: + Show ignored files as well. -z:: Terminate entries with NUL, instead of LF. This implies @@ -59,34 +83,55 @@ OUTPUT The output from this command is designed to be used as a commit template comment, and all the output lines are prefixed with '#'. The default, long format, is designed to be human readable, -verbose and descriptive. They are subject to change in any time. +verbose and descriptive. Its contents and format are subject to change +at any time. The paths mentioned in the output, unlike many other git commands, are made relative to the current directory if you are working in a subdirectory (this is on purpose, to help cutting and pasting). See the status.relativePaths config option below. -In short-format, the status of each path is shown as +Short Format +~~~~~~~~~~~~ + +In the short-format, the status of each path is shown as XY PATH1 -> PATH2 -where `PATH1` is the path in the `HEAD`, and ` -> PATH2` part is +where `PATH1` is the path in the `HEAD`, and the ` \-> PATH2` part is shown only when `PATH1` corresponds to a different path in the -index/worktree (i.e. renamed). - -For unmerged entries, `X` shows the status of stage #2 (i.e. ours) and `Y` -shows the status of stage #3 (i.e. theirs). - -For entries that do not have conflicts, `X` shows the status of the index, -and `Y` shows the status of the work tree. For untracked paths, `XY` are -`??`. +index/worktree (i.e. the file is renamed). The 'XY' is a two-letter +status code. + +The fields (including the `\->`) are separated from each other by a +single space. If a filename contains whitespace or other nonprintable +characters, that field will be quoted in the manner of a C string +literal: surrounded by ASCII double quote (34) characters, and with +interior special characters backslash-escaped. + +For paths with merge conflicts, `X` and 'Y' show the modification +states of each side of the merge. For paths that do not have merge +conflicts, `X` shows the status of the index, and `Y` shows the status +of the work tree. For untracked paths, `XY` are `??`. Other status +codes can be interpreted as follows: + +* ' ' = unmodified +* 'M' = modified +* 'A' = added +* 'D' = deleted +* 'R' = renamed +* 'C' = copied +* 'U' = updated but unmerged + +Ignored files are not listed, unless `--ignored` option is in effect, +in which case `XY` are `!!`. X Y Meaning ------------------------------------------------- [MD] not updated M [ MD] updated in index A [ MD] added to index - D [ MD] deleted from index + D [ M] deleted from index R [ MD] renamed in index C [ MD] copied in index [MARC] index and work tree matches @@ -102,8 +147,37 @@ and `Y` shows the status of the work tree. For untracked paths, `XY` are U U unmerged, both modified ------------------------------------------------- ? ? untracked + ! ! ignored ------------------------------------------------- +If -b is used the short-format status is preceded by a line + +## branchname tracking info + +Porcelain Format +~~~~~~~~~~~~~~~~ + +The porcelain format is similar to the short format, but is guaranteed +not to change in a backwards-incompatible way between git versions or +based on user configuration. This makes it ideal for parsing by scripts. +The description of the short format above also describes the porcelain +format, with a few exceptions: + +1. The user's color.status configuration is not respected; color will + always be off. + +2. The user's status.relativePaths configuration is not respected; paths + shown will always be relative to the repository root. + +There is also an alternate -z format recommended for machine parsing. In +that format, the status field is the same, but some other things +change. First, the '\->' is omitted from rename entries and the field +order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL +(ASCII 0) follows each filename, replacing space as a field separator +and the terminating newline (but a space still separates the status +field from the first filename). Third, filenames containing special +characters are not specially formatted; no quoting or +backslash-escaping is performed. Fourth, there is no branch line. CONFIGURATION ------------- @@ -126,14 +200,6 @@ SEE ALSO -------- linkgit:gitignore[5] -Author ------- -Written by Junio C Hamano <gitster@pobox.com>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 7508c0e42d..b78f031cd4 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -8,6 +8,7 @@ git-stripspace - Filter out empty lines SYNOPSIS -------- +[verse] 'git stripspace' [-s | --strip-comments] < <stream> DESCRIPTION @@ -23,14 +24,6 @@ OPTIONS <stream>:: Byte stream to act on. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 4ef70c42eb..6ec3fef079 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,13 +9,14 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b branch] +'git submodule' [--quiet] add [-b branch] [-f|--force] [--reference <repository>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...] -'git submodule' [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...] +'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] + [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> 'git submodule' [--quiet] sync [--] [<path>...] @@ -78,7 +79,9 @@ to exist in the superproject. If <path> is not given, the <repository> is the URL of the new submodule's origin repository. This may be either an absolute URL, or (if it begins with ./ or ../), the location relative to the superproject's origin -repository. +repository. If the superproject doesn't have an origin configured +the superproject is its own authoritative upstream and the current +working directory is used instead. + <path> is the relative location for the cloned submodule to exist in the superproject. If <path> does not exist, then the @@ -99,60 +102,77 @@ locate the submodule using the relative URL in .gitmodules. status:: Show the status of the submodules. This will print the SHA-1 of the currently checked out commit for each submodule, along with the - submodule path and the output of 'git-describe' for the + submodule path and the output of 'git describe' for the SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not - initialized and `+` if the currently checked out submodule commit + initialized, `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing - repository. This command is the default command for 'git-submodule'. + 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 +If `--recursive` is specified, this command will recurse into nested submodules, and show their status as well. ++ +If you are only interested in changes of the currently initialized +submodules with respect to the commit recorded in the index or the HEAD, +linkgit:git-status[1] and linkgit:git-diff[1] will provide that information +too (and can also report changes to a submodule's work tree). init:: Initialize the submodules, i.e. register each submodule name and url found in .gitmodules into .git/config. + It will also copy the value of `submodule.$name.update` into + .git/config. The key used in .git/config is `submodule.$name.url`. This command does not alter existing information in .git/config. You can then customize the submodule clone URLs in .git/config - for your local setup and proceed to 'git submodule update'; - you can also just use 'git submodule update --init' without + for your local setup and proceed to `git submodule update`; + you can also just use `git submodule update --init` without the explicit 'init' step if you do not intend to customize any submodule locations. update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. - This will make the submodules HEAD be detached unless '--rebase' or - '--merge' is specified or the key `submodule.$name.update` is set to - `rebase` or `merge`. + This will make the submodules HEAD be detached unless `--rebase` or + `--merge` is specified or the key `submodule.$name.update` is set to + `rebase`, `merge` or `none`. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the -submodule with the --init option. +submodule with the `--init` option. + -If '--recursive' is specified, this command will recurse into the +If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. ++ +If the configuration key `submodule.$name.update` is set to `none` the +submodule with name `$name` will not be updated by default. This can be +overriden by adding `--checkout` to the command. summary:: Show commit summary between the given commit (defaults to HEAD) and working tree/index. For a submodule in question, a series of commits in the submodule between the given super project commit and the - index or working tree (switched by --cached) are shown. If the option - --files is given, show the series of commits in the submodule between + index or working tree (switched by `--cached`) are shown. If the option + `--files` is given, show the series of commits in the submodule between the index of the super project and the working tree of the submodule - (this option doesn't allow to use the --cached option or to provide an + (this option doesn't allow to use the `--cached` option or to provide an explicit commit). ++ +Using the `--submodule=log` option with linkgit:git-diff[1] will provide that +information too. foreach:: Evaluates an arbitrary shell command in each checked out submodule. - The command has access to the variables $name, $path and $sha1: + The command has access to the variables $name, $path, $sha1 and + $toplevel: $name is the name of the relevant submodule section in .gitmodules, $path is the name of the submodule directory relative to the - superproject, and $sha1 is the commit as recorded in the superproject. + superproject, $sha1 is the commit as recorded in the superproject, + and $toplevel is the absolute path to the top-level of the superproject. Any submodules defined in the superproject but not checked out are - ignored by this command. Unless given --quiet, foreach prints the name + ignored by this command. Unless given `--quiet`, foreach prints the name of each submodule before evaluating the command. - If --recursive is given, submodules are traversed recursively (i.e. + If `--recursive` is given, submodules are traversed recursively (i.e. the given shell command is evaluated in nested submodules as well). A non-zero return from the command in any submodule causes the processing to terminate. This can be overridden by adding '|| :' @@ -164,12 +184,14 @@ commit for each submodule. sync:: Synchronizes submodules' remote URL configuration setting - to the value specified in .gitmodules. This is useful when + to the value specified in .gitmodules. It will only affect those + submodules which already have an url entry in .git/config (that is the + case when they are initialized or freshly added). This is useful when submodule URLs change upstream and you need to update your local repositories accordingly. + "git submodule sync" synchronizes all submodules while -"git submodule sync -- A" synchronizes submodule "A" only. +"git submodule sync \-- A" synchronizes submodule "A" only. OPTIONS ------- @@ -181,6 +203,13 @@ OPTIONS --branch:: Branch of repository to add as submodule. +-f:: +--force:: + 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. + --cached:: This option is only valid for status and summary commands. These commands typically use the commit found in the submodule HEAD, but @@ -218,18 +247,23 @@ OPTIONS This option is only valid for the update command. Rebase the current branch onto the commit recorded in the superproject. If this option is given, the submodule's HEAD will not - be detached. If a a merge failure prevents this process, you will have + be detached. If a merge failure prevents this process, you will have to resolve these failures with linkgit:git-rebase[1]. If the key `submodule.$name.update` is set to `rebase`, this option is implicit. +--init:: + This option is only valid for the update command. + Initialize all submodules for which "git submodule init" has not been + called so far before updating. + --reference <repository>:: This option is only valid for add and update commands. These commands sometimes need to clone a remote repository. In this case, this option will be passed to the linkgit:git-clone[1] command. + *NOTE*: Do *not* use this option unless you have read the note -for linkgit:git-clone[1]'s --reference and --shared options carefully. +for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. --recursive:: This option is only valid for foreach, update and status commands. @@ -250,11 +284,6 @@ This file should be formatted in the same way as `$GIT_DIR/config`. The key to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] for details. - -AUTHOR ------- -Written by Lars Hjemli <hjemli@gmail.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 4cdca0d874..34ee785064 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -7,6 +7,7 @@ git-svn - Bidirectional operation between a Subversion repository and git SYNOPSIS -------- +[verse] 'git svn' <command> [options] [arguments] DESCRIPTION @@ -56,13 +57,17 @@ COMMANDS as well, they take precedence. --no-metadata;; Set the 'noMetadata' option in the [svn-remote] config. + This option is not recommended, please read the 'svn.noMetadata' + section of this manpage before using this option. --use-svm-props;; Set the 'useSvmProps' option in the [svn-remote] config. --use-svnsync-props;; Set the 'useSvnsyncProps' option in the [svn-remote] config. --rewrite-root=<URL>;; Set the 'rewriteRoot' option in the [svn-remote] config. ---username=<USER>;; +--rewrite-uuid=<UUID>;; + Set the 'rewriteUUID' option in the [svn-remote] config. +--username=<user>;; For transports that SVN handles authentication for (http, https, and plain svn), specify the username. For other transports (eg svn+ssh://), you must include the username in @@ -141,17 +146,6 @@ Skip "branches" and "tags" of first level directories;; ------------------------------------------------------------------------ -- ---use-log-author;; - When retrieving svn commits into git (as part of fetch, rebase, or - dcommit operations), look for the first From: or Signed-off-by: line - in the log message and use that as the author string. ---add-author-from;; - When committing to svn from git (as part of commit or dcommit - operations), if the existing log message doesn't already have a - From: or Signed-off-by: line, append a From: line based on the - git commit's author string. If you use this, then --use-log-author - will retrieve a valid author string for all commits. - 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; @@ -163,6 +157,17 @@ Skip "branches" and "tags" of first level directories;; affecting the working tree; and the 'rebase' command will be able to update the working tree with the latest changes. +--preserve-empty-dirs;; + Create a placeholder file in the local Git repository for each + empty directory fetched from Subversion. This includes directories + that become empty by removing all entries in the Subversion + repository (but not the directory itself). The placeholder files + are also tracked and removed when no longer necessary. + +--placeholder-filename=<filename>;; + Set the name of placeholder files created by --preserve-empty-dirs. + Default: ".gitignore" + 'rebase':: This fetches revisions from the SVN parent of the current HEAD and rebases the current (uncommitted to SVN) work against it. @@ -213,6 +218,30 @@ config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) Using this option for any other purpose (don't ask) is very strongly discouraged. +--mergeinfo=<mergeinfo>;; + Add the given merge information during the dcommit + (e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can + store this information (as a property), and svn clients starting from + version 1.5 can make use of it. To specify merge information from multiple + branches, use a single space character between the branches + (`--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"`) ++ +[verse] +config key: svn.pushmergeinfo ++ +This option will cause git-svn to attempt to automatically populate the +svn:mergeinfo property in the SVN repository when possible. Currently, this can +only be done when dcommitting non-fast-forward merges where all parents but the +first have already been pushed into SVN. + +--interactive;; + Ask the user to confirm that a patch set should actually be sent to SVN. + For each patch, one may answer "yes" (accept this patch), "no" (discard this + patch), "all" (accept all patches), or "quit". + + + 'git svn dcommit' returns immediately if answer if "no" or "quit", without + commiting anything to SVN. + 'branch':: Create a branch in the SVN repository. @@ -239,6 +268,19 @@ discouraged. where <name> is the name of the SVN repository as specified by the -R option to 'init' (or "svn" by default). +--username;; + Specify the SVN username to perform the commit as. This option overrides + the 'username' configuration property. + +--commit-url;; + Use the specified URL to connect to the destination Subversion + repository. This is useful in cases where the source SVN + repository is read-only. This option overrides configuration + property 'commiturl'. ++ + git config --get-all svn-remote.<name>.commiturl ++ + 'tag':: Create a tag in the SVN repository. This is a shorthand for 'branch -t'. @@ -284,7 +326,7 @@ Any other arguments are passed directly to 'git log' Show what revision and author last modified each line of a file. The output of this mode is format-compatible with the output of `svn blame' by default. Like the SVN blame command, - local uncommitted changes in the working copy are ignored; + local uncommitted changes in the working tree are ignored; the version of the file in the HEAD revision is annotated. Unknown arguments are passed directly to 'git blame'. + @@ -326,6 +368,8 @@ Any other arguments are passed directly to 'git log' Empty directories are automatically recreated when using "git svn clone" and "git svn rebase", so "mkdirs" is intended for use after commands like "git checkout" or "git reset". + (See the svn-remote.<name>.automkdirs config file option for + more information.) 'commit-diff':: Commits the diff of two tree-ish arguments from the @@ -421,13 +465,13 @@ git rebase --onto remotes/git-svn A^ master OPTIONS ------- ---shared[={false|true|umask|group|all|world|everybody}]:: +--shared[=(false|true|umask|group|all|world|everybody)]:: --template=<template_directory>:: Only used with the 'init' command. These are passed directly to 'git init'. --r <ARG>:: ---revision <ARG>:: +-r <arg>:: +--revision <arg>:: Used with the 'fetch' command. + This allows revision ranges for partial/cauterized history @@ -548,6 +592,17 @@ repository that will be fetched from. For 'branch' and 'tag', display the urls that will be used for copying when creating the branch or tag. +--use-log-author:: + When retrieving svn commits into git (as part of 'fetch', 'rebase', or + 'dcommit' operations), look for the first `From:` or `Signed-off-by:` line + in the log message and use that as the author string. +--add-author-from:: + When committing to svn from git (as part of 'commit-diff', 'set-tree' or 'dcommit' + operations), if the existing log message doesn't already have a + `From:` or `Signed-off-by:` line, append a `From:` line based on the + git commit's author string. If you use this, then `--use-log-author` + will retrieve a valid author string for all commits. + ADVANCED OPTIONS ---------------- @@ -582,13 +637,22 @@ svn.noMetadata:: svn-remote.<name>.noMetadata:: This gets rid of the 'git-svn-id:' lines at the end of every commit. + -If you lose your .git/svn/git-svn/.rev_db file, 'git svn' will not -be able to rebuild it and you won't be able to fetch again, -either. This is fine for one-shot imports. +This option can only be used for one-shot imports as 'git svn' +will not be able to fetch again without metadata. Additionally, +if you lose your .git/svn/**/.rev_map.* files, 'git svn' will not +be able to rebuild them. + The 'git svn log' command will not work on repositories using this, either. Using this conflicts with the 'useSvmProps' option for (hopefully) obvious reasons. ++ +This option is NOT recommended as it makes it difficult to track down +old references to SVN revision numbers in existing documentation, bug +reports and archives. If you plan to eventually migrate from SVN to git +and are certain about dropping SVN history, consider +linkgit:git-filter-branch[1] instead. filter-branch also allows +reformatting of metadata for ease-of-reading and rewriting authorship +info for non-"svn.authorsFile" users. svn.useSvmProps:: svn-remote.<name>.useSvmProps:: @@ -616,6 +680,22 @@ svn-remote.<name>.rewriteRoot:: the repository with a public http:// or svn:// URL in the metadata so users of it will see the public URL. +svn-remote.<name>.rewriteUUID:: + Similar to the useSvmProps option; this is for users who need + to remap the UUID manually. This may be useful in situations + where the original UUID is not available via either useSvmProps + or useSvnsyncProps. + +svn-remote.<name>.pushurl:: + + Similar to git's 'remote.<name>.pushurl', this key is designed + to be used in cases where 'url' points to an SVN repository + via a read-only transport, to provide an alternate read/write + transport. It is assumed that both keys point to the same + repository. Unlike 'commiturl', 'pushurl' is a base path. If + either 'commiturl' or 'pushurl' could be used, 'commiturl' + takes precedence. + svn.brokenSymlinkWorkaround:: This disables potentially expensive checks to workaround broken symlinks checked into SVN by broken clients. Set this @@ -625,13 +705,28 @@ svn.brokenSymlinkWorkaround:: revision fetched. If unset, 'git svn' assumes this option to be "true". -Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps +svn.pathnameencoding:: + This instructs git svn to recode pathnames to a given encoding. + It can be used by windows users and by those who work in non-utf8 + locales to avoid corrupted file names with non-ASCII characters. + Valid encodings are the ones supported by Perl's Encode module. + +svn-remote.<name>.automkdirs:: + Normally, the "git svn clone" and "git svn rebase" commands + attempt to recreate empty directories that are in the + Subversion repository. If this option is set to "false", then + empty directories will only be created if the "git svn mkdirs" + command is run explicitly. If unset, 'git svn' assumes this + option to be "true". + +Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps options all affect the metadata generated and used by 'git svn'; they *must* be set in the configuration file before any history is imported and these settings should never be changed once they are set. -Additionally, only one of these four options can be used per-svn-remote -section because they affect the 'git-svn-id:' metadata line. +Additionally, only one of these options can be used per svn-remote +section because they affect the 'git-svn-id:' metadata line, except +for rewriteRoot and rewriteUUID which can be used together. BASIC EXAMPLES @@ -690,8 +785,11 @@ have each person clone that repository with 'git clone': cd project git init git remote add origin server:/pub/project - git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' + git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*' git fetch +# Prevent fetch/pull from remote git server in the future, +# we only want to use git svn for future updates + git config --remove-section remote.origin # Create a local branch from one of the branches just fetched git checkout -b master FETCH_HEAD # Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server) @@ -715,10 +813,9 @@ use `git svn rebase` to update your work branch instead of `git pull` or when committing into SVN, which can lead to merge commits reversing previous commits in SVN. -DESIGN PHILOSOPHY ------------------ -Merge tracking in Subversion is lacking and doing branched development -with Subversion can be cumbersome as a result. While 'git svn' can track +MERGE TRACKING +-------------- +While 'git svn' can track copy history (including branches and tags) for repositories adopting a standard layout, it cannot yet represent merge history that happened inside git back upstream to SVN users. Therefore it is advised that @@ -728,16 +825,15 @@ compatibility with SVN (see the CAVEATS section below). CAVEATS ------- -For the sake of simplicity and interoperating with a less-capable system -(SVN), it is recommended that all 'git svn' users clone, fetch and dcommit +For the sake of simplicity and interoperating with Subversion, +it is recommended that all 'git svn' users clone, fetch and dcommit directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push' operations between git repositories and branches. The recommended method of exchanging code between git branches and users is 'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository. Running 'git merge' or 'git pull' is NOT recommended on a branch you -plan to 'dcommit' from. Subversion does not represent merges in any -reasonable or useful fashion; so users using Subversion cannot see any +plan to 'dcommit' from because Subversion users cannot see any merges you've made. Furthermore, if you merge or pull from a git branch that is a mirror of an SVN branch, 'dcommit' may commit to the wrong branch. @@ -787,7 +883,7 @@ Renamed and copied directories are not detected by git and hence not tracked when committing to SVN. I do not plan on adding support for this as it's quite difficult and time-consuming to get working for all the possible corner cases (git doesn't do it, either). Committing -renamed and copied files are fully supported if they're similar enough +renamed and copied files is fully supported if they're similar enough for git to detect them. CONFIGURATION @@ -816,14 +912,26 @@ independent path component (surrounded by '/' or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'. +It is also possible to fetch a subset of branches or tags by using a +comma-separated list of names within braces. For example: + +------------------------------------------------------------------------ +[svn-remote "huge-project"] + url = http://server.org/svn + fetch = trunk/src:refs/remotes/trunk + branches = branches/{red,green}/src:refs/remotes/branches/* + tags = tags/{1.0,2.0}/src:refs/remotes/tags/* +------------------------------------------------------------------------ + +Note that git-svn keeps track of the highest revision in which a branch +or tag has appeared. If the subset of branches or tags is changed after +fetching, then .git/svn/.metadata must be manually edited to remove (or +reset) branches-maxRev and/or tags-maxRev as appropriate. + SEE ALSO -------- linkgit:git-rebase[1] -Author ------- -Written by Eric Wong <normalperson@yhbt.net>. - -Documentation -------------- -Written by Eric Wong <normalperson@yhbt.net>. +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 6392538807..75b1ae5061 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -7,6 +7,7 @@ git-symbolic-ref - Read and modify symbolic refs SYNOPSIS -------- +[verse] 'git symbolic-ref' [-q] [-m <reason>] <name> [<ref>] DESCRIPTION @@ -49,14 +50,10 @@ cumbersome. On some platforms, `ln -sf` does not even work as advertised (horrors). Therefore symbolic links are now deprecated and symbolic refs are used by default. -'git-symbolic-ref' will exit with status 0 if the contents of the +'git symbolic-ref' will exit with status 0 if the contents of the symbolic ref were printed correctly, with status 1 if the requested name is not a symbolic ref, or 128 if another error occurs. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 299b04f726..c83cb13de6 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -12,27 +12,28 @@ SYNOPSIS 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... -'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>] +'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION ----------- -Adds a tag reference in `.git/refs/tags/`. +Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +to delete, list or verify tags. -Unless `-f` is given, the tag must not yet exist in +Unless `-f` is given, the tag to be created must not yet exist in the `.git/refs/tags/` directory. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command -creates a 'tag' object, and requires the tag message. Unless +creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. -Otherwise just the SHA1 object name of the commit object is -written (i.e. a lightweight tag). +Otherwise just a tag reference for the SHA1 object name of the commit object is +created (i.e. a lightweight tag). A GnuPG signed tag object will be created when `-s` or `-u <key-id>` is used. When `-u <key-id>` is not used, the @@ -42,12 +43,15 @@ GnuPG key for signing. OPTIONS ------- -a:: +--annotate:: Make an unsigned, annotated tag object -s:: +--sign:: Make a GPG-signed tag, using the default e-mail address's key -u <key-id>:: +--local-user=<key-id>:: Make a GPG-signed tag, using the given key -f:: @@ -55,9 +59,11 @@ OPTIONS Replace an existing tag with the given name (instead of failing) -d:: +--delete:: Delete existing tags with the given names. -v:: +--verify:: Verify the gpg signature of the given tag names. -n<num>:: @@ -68,13 +74,18 @@ OPTIONS If the tag is not annotated, the commit message is displayed instead. -l <pattern>:: - List tags with names that match the given pattern (or all if no pattern is given). - Typing "git tag" without arguments, also lists all tags. +--list <pattern>:: + List tags with names that match the given pattern (or all if no + pattern is given). Running "git tag" without arguments also + lists all tags. The pattern is a shell wildcard (i.e., matched + using fnmatch(3)). Multiple patterns may be given; if any of + them matches, the tag is shown. --contains <commit>:: Only list tags which contain the specified commit. -m <msg>:: +--message=<msg>:: Use the given tag message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. @@ -82,6 +93,7 @@ OPTIONS is given. -F <file>:: +--file=<file>:: Take the tag message from the given file. Use '-' to read the message from the standard input. Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` @@ -95,7 +107,7 @@ OPTIONS CONFIGURATION ------------- -By default, 'git-tag' in sign-with-default mode (-s) will use your +By default, 'git tag' in sign-with-default mode (-s) will use your committer identity (of the form "Your Name <your@email.address>") to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows: @@ -131,12 +143,12 @@ and be done with it. . The insane thing. You really want to call the new version "X" too, 'even though' -others have already seen the old one. So just use 'git-tag -f' +others have already seen the old one. So just use 'git tag -f' again, as if you hadn't already published the old one. However, Git does *not* (and it should not) change tags behind users back. So if somebody already got the old tag, doing a -'git-pull' on your tree shouldn't just make them overwrite the old +'git pull' on your tree shouldn't just make them overwrite the old one. If somebody got a release tag from you, you cannot just change @@ -164,20 +176,19 @@ You can test which tag you have by doing which should return 0123456789abcdef.. if you have the new version. -Sorry for inconvenience. +Sorry for the inconvenience. ------------ Does this seem a bit complicated? It *should* be. There is no -way that it would be correct to just "fix" it behind peoples -backs. People need to know that their tags might have been -changed. +way that it would be correct to just "fix" it automatically. +People need to know that their tags might have been changed. On Automatic following ~~~~~~~~~~~~~~~~~~~~~~ If you are following somebody else's tree, you are most likely -using tracking branches (`refs/heads/origin` in traditional +using remote-tracking branches (`refs/heads/origin` in traditional layout, or `refs/remotes/origin/master` in the separate-remote layout). You usually want the tags from the other end. @@ -188,9 +199,10 @@ the toplevel but not limited to them. Mere mortals when pulling from each other do not necessarily want to automatically get private anchor point tags from the other person. -You would notice "please pull" messages on the mailing list says -repo URL and branch name alone. This is designed to be easily -cut&pasted to a 'git-fetch' command line: +Often, "please pull" messages on the mailing list just provide +two pieces of information: a repo URL and a branch name; this +is designed to be easily cut&pasted at the end of a 'git fetch' +command line: ------------ Linus, please pull from @@ -206,14 +218,14 @@ becomes: $ git pull git://git..../proj.git master ------------ -In such a case, you do not want to automatically follow other's -tags. +In such a case, you do not want to automatically follow the other +person's tags. -One important aspect of git is it is distributed, and being -distributed largely means there is no inherent "upstream" or +One important aspect of git is its distributed nature, which +largely means there is no inherent "upstream" or "downstream" in the system. On the face of it, the above example might seem to indicate that the tag namespace is owned -by upper echelon of people and tags only flow downwards, but +by the upper echelon of people and that tags only flow downwards, but that is not the case. It only shows that the usage pattern determines who are interested in whose tags. @@ -231,8 +243,8 @@ this case. It may well be that among networking people, they may want to exchange the tags internal to their group, but in that workflow -they are most likely tracking with each other's progress by -having tracking branches. Again, the heuristic to automatically +they are most likely tracking each other's progress by +having remote-tracking branches. Again, the heuristic to automatically follow such tags is a good thing. @@ -241,35 +253,26 @@ On Backdating Tags If you have imported some changes from another VCS and would like to add tags for major releases of your work, it is useful to be able -to specify the date to embed inside of the tag object. The data in +to specify the date to embed inside of the tag object; such data in the tag object affects, for example, the ordering of tags in the gitweb interface. To set the date used in future tag objects, set the environment -variable GIT_COMMITTER_DATE to one or more of the date and time. The -date and time can be specified in a number of ways; the most common -is "YYYY-MM-DD HH:MM". +variable GIT_COMMITTER_DATE (see the later discussion of possible +values; the most common form is "YYYY-MM-DD HH:MM"). -An example follows. +For example: ------------ $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 ------------ +include::date-formats.txt[] SEE ALSO -------- linkgit:git-check-ref-format[1]. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, -Junio C Hamano <gitster@pobox.com> and Chris Wright <chrisw@osdl.org>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index a5d9558dd1..346e7a2079 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -8,23 +8,24 @@ git-tar-tree - Create a tar archive of the files in the named tree object SYNOPSIS -------- +[verse] 'git tar-tree' [--remote=<repo>] <tree-ish> [ <base> ] DESCRIPTION ----------- -THIS COMMAND IS DEPRECATED. Use 'git-archive' with `--format=tar` +THIS COMMAND IS DEPRECATED. Use 'git archive' with `--format=tar` option instead (and move the <base> argument to `--prefix=base/`). Creates a tar archive containing the tree structure for the named tree. When <base> is specified it is added as a leading path to the files in the generated tar archive. -'git-tar-tree' behaves differently when given a tree ID versus when given +'git tar-tree' behaves differently when given a tree ID versus when given a commit ID or tag ID. In the first case the current time is used as modification time of each file in the archive. In the latter case the commit time as recorded in the referenced commit object is used instead. Additionally the commit ID is stored in a global extended pax header. -It can be extracted using 'git-get-tar-commit-id'. +It can be extracted using 'git get-tar-commit-id'. OPTIONS ------- @@ -52,38 +53,30 @@ tar.umask:: EXAMPLES -------- -git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -):: +`git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)`:: Create a tar archive that contains the contents of the latest commit on the current branch, and extracts it in `/var/tmp/junk` directory. -git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz:: +`git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a tarball for v1.4.0 release. -git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz:: +`git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a tarball for v1.4.0 release, but without a global extended pax header. -git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar:: +`git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar`:: Get a tarball v1.4.0 from example.com. -git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar:: +`git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar`:: Put everything in the current head's Documentation/ directory into 'git-1.4.0-docs.tar', with the prefix 'git-docs/'. -Author ------- -Written by Rene Scharfe. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt index 995db9fead..e9f148a00d 100644 --- a/Documentation/git-unpack-file.txt +++ b/Documentation/git-unpack-file.txt @@ -9,6 +9,7 @@ git-unpack-file - Creates a temporary file with a blob's contents SYNOPSIS -------- +[verse] 'git unpack-file' <blob> DESCRIPTION @@ -22,14 +23,6 @@ OPTIONS <blob>:: Must be a blob id -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index 36d1038056..ff23494e70 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -8,6 +8,7 @@ git-unpack-objects - Unpack objects from a packed archive SYNOPSIS -------- +[verse] 'git unpack-objects' [-n] [-q] [-r] [--strict] <pack-file @@ -43,15 +44,6 @@ OPTIONS --strict:: Don't write objects with broken content or links. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation -------------- -Documentation by Junio C Hamano - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 8d88018eed..a3081f4e23 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git update-index' [--add] [--remove | --force-remove] [--replace] [--refresh] [-q] [--unmerged] [--ignore-missing] - [--cacheinfo <mode> <object> <file>]\* + [(--cacheinfo <mode> <object> <file>)...] [--chmod=(+|-)x] [--assume-unchanged | --no-assume-unchanged] [--skip-worktree | --no-skip-worktree] @@ -21,7 +21,7 @@ SYNOPSIS [--info-only] [--index-info] [-z] [--stdin] [--verbose] - [--] [<file>]\* + [--] [<file>...] DESCRIPTION ----------- @@ -32,7 +32,7 @@ cleared. See also linkgit:git-add[1] for a more user-friendly way to do some of the most common operations on the index. -The way 'git-update-index' handles files it is told about can be modified +The way 'git update-index' handles files it is told about can be modified using the various options: OPTIONS @@ -54,7 +54,7 @@ OPTIONS -q:: Quiet. If --refresh finds that the index needs an update, the default behavior is to error out. This option makes - 'git-update-index' continue anyway. + 'git update-index' continue anyway. --ignore-submodules:: Do not try to update submodules. This option is only respected @@ -62,7 +62,7 @@ OPTIONS --unmerged:: If --refresh finds unmerged changes in the index, the default - behavior is to error out. This option makes 'git-update-index' + behavior is to error out. This option makes 'git update-index' continue anyway. --ignore-missing:: @@ -93,8 +93,6 @@ OPTIONS This option can be also used as a coarse file-level mechanism to ignore uncommitted changes in tracked files (akin to what `.gitignore` does for untracked files). -You should remember that an explicit 'git add' operation will -still cause the file to be refreshed from the working tree. Git will fail (gracefully) in case it needs to modify this file in the index e.g. when merging in a commit; thus, in case the assumed-untracked file is changed upstream, @@ -113,7 +111,7 @@ you will need to handle the situation manually. -g:: --again:: - Runs 'git-update-index' itself on the paths whose index + Runs 'git update-index' itself on the paths whose index entries are different from those from the `HEAD` commit. --unresolve:: @@ -131,7 +129,7 @@ you will need to handle the situation manually. --replace:: By default, when a file `path` exists in the index, - 'git-update-index' refuses an attempt to add `path/file`. + 'git update-index' refuses an attempt to add `path/file`. Similarly if a file `path/file` exists, a file `path` cannot be added. With --replace flag, existing entries that conflict with the entry being added are @@ -146,8 +144,8 @@ you will need to handle the situation manually. Report what is being added and removed from index. -z:: - Only meaningful with `--stdin`; paths are separated with - NUL character instead of LF. + Only meaningful with `--stdin` or `--index-info`; paths are + separated with NUL character instead of LF. \--:: Do not interpret any more arguments as options. @@ -167,7 +165,7 @@ up-to-date for mode/content changes. But what it *does* do is to can refresh the index for a file that hasn't been changed but where the stat entry is out of date. -For example, you'd want to do this after doing a 'git-read-tree', to link +For example, you'd want to do this after doing a 'git read-tree', to link up the stat index details with the proper files. Using --cacheinfo or --info-only @@ -208,13 +206,13 @@ back on 3-way merge. . mode SP type SP sha1 TAB path + -The second format is to stuff 'git-ls-tree' output +The second format is to stuff 'git ls-tree' output into the index file. . mode SP sha1 SP stage TAB path + This format is to put higher order stages into the -index file and matches 'git-ls-files --stage' output. +index file and matches 'git ls-files --stage' output. To place a higher stage entry to the index, the path should first be removed by feeding a mode=0 entry for the path, and @@ -266,13 +264,15 @@ tree files, you have to explicitly tell git about it by dropping "assume unchanged" bit, either before or after you modify them. In order to set "assume unchanged" bit, use `--assume-unchanged` -option. To unset, use `--no-assume-unchanged`. +option. To unset, use `--no-assume-unchanged`. To see which files +have the "assume unchanged" bit set, use `git ls-files -v` +(see linkgit:git-ls-files[1]). The command looks at `core.ignorestat` configuration variable. When this is true, paths updated with `git update-index paths...` and paths updated with other git commands that update both index and -working tree (e.g. 'git-apply --index', 'git-checkout-index -u', -and 'git-read-tree -u') are automatically marked as "assume +working tree (e.g. 'git apply --index', 'git checkout-index -u', +and 'git read-tree -u') are automatically marked as "assume unchanged". Note that "assume unchanged" bit is *not* set if `git update-index --refresh` finds the working tree file matches the index (use `git update-index --really-refresh` if you want @@ -346,7 +346,7 @@ unreliable, this should be set to 'false' (see linkgit:git-config[1]). This causes the command to ignore differences in file modes recorded in the index and the file mode on the filesystem if they differ only on executable bit. On such an unfortunate filesystem, you may -need to use 'git-update-index --chmod='. +need to use 'git update-index --chmod='. Quite similarly, if `core.symlinks` configuration variable is set to 'false' (see linkgit:git-config[1]), symbolic links are checked out @@ -365,16 +365,8 @@ ctime for marking files processed) (see linkgit:git-config[1]). SEE ALSO -------- linkgit:git-config[1], -linkgit:git-add[1] - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +linkgit:git-add[1], +linkgit:git-ls-files[1] GIT --- diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 9639f705af..d377a35243 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -7,6 +7,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- +[verse] 'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>]) DESCRIPTION @@ -60,8 +61,9 @@ still contains <oldvalue>. Logging Updates --------------- -If config parameter "core.logAllRefUpdates" is true or the file -"$GIT_DIR/logs/<ref>" exists then `git update-ref` will append +If config parameter "core.logAllRefUpdates" is true and the ref is one under +"refs/heads/", "refs/remotes/", "refs/notes/", or the symbolic ref HEAD; or +the file "$GIT_DIR/logs/<ref>" exists then `git update-ref` will append a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating the log name) describing the change in ref value. Log lines are formatted as: @@ -84,10 +86,6 @@ An update will fail (without changing <ref>) if the current user is unable to create a new log file, append to the existing log file or does not have committer information available. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 035cc3018f..bd0e36492f 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -8,6 +8,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers SYNOPSIS -------- +[verse] 'git update-server-info' [--force] DESCRIPTION @@ -38,15 +39,6 @@ what they are for: * info/refs - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt index bbd7617587..4d52d3833a 100644 --- a/Documentation/git-upload-archive.txt +++ b/Documentation/git-upload-archive.txt @@ -8,15 +8,16 @@ git-upload-archive - Send archive back to git-archive SYNOPSIS -------- +[verse] 'git upload-archive' <directory> DESCRIPTION ----------- -Invoked by 'git-archive --remote' and sends a generated archive to the +Invoked by 'git archive --remote' and sends a generated archive to the other end over the git protocol. This command is usually not invoked directly by the end user. The UI -for the protocol is on the 'git-archive' side, and the program pair +for the protocol is on the 'git archive' side, and the program pair is meant to be used to get an archive from a remote repository. OPTIONS @@ -24,14 +25,6 @@ OPTIONS <directory>:: The repository to get a tar archive from. -Author ------- -Written by Franck Bui-Huu. - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index b8e49dce4a..71f16083d6 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -8,17 +8,18 @@ git-upload-pack - Send objects packed back to git-fetch-pack SYNOPSIS -------- -'git upload-pack' [--strict] [--timeout=<n>] <directory> +[verse] +'git-upload-pack' [--strict] [--timeout=<n>] <directory> DESCRIPTION ----------- -Invoked by 'git-fetch-pack', learns what +Invoked by 'git fetch-pack', learns what objects the other side is missing, and sends them after packing. This command is usually not invoked directly by the end user. -The UI for the protocol is on the 'git-fetch-pack' side, and the +The UI for the protocol is on the 'git fetch-pack' side, and the program pair is meant to be used to pull updates from a remote -repository. For push operations, see 'git-send-pack'. +repository. For push operations, see 'git send-pack'. OPTIONS @@ -33,13 +34,9 @@ OPTIONS <directory>:: The repository to sync from. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano. +SEE ALSO +-------- +linkgit:gitnamespaces[7] GIT --- diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index ef6aa81872..5317cc2474 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -8,7 +8,8 @@ git-var - Show a git logical variable SYNOPSIS -------- -'git var' [ -l | <variable> ] +[verse] +'git var' ( -l | <variable> ) DESCRIPTION ----------- @@ -20,7 +21,7 @@ OPTIONS Cause the logical variables to be listed. In addition, all the variables of the git configuration file .git/config are listed as well. (However, the configuration variables listing functionality - is deprecated in favor of 'git config -l'.) + is deprecated in favor of `git config -l`.) EXAMPLE -------- @@ -65,14 +66,6 @@ linkgit:git-commit-tree[1] linkgit:git-tag[1] linkgit:git-config[1] -Author ------- -Written by Eric Biederman <ebiederm@xmission.com> - -Documentation --------------- -Documentation by Eric Biederman and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 97f7f9165e..cd230769fd 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -8,13 +8,14 @@ git-verify-pack - Validate packed git archive files SYNOPSIS -------- -'git verify-pack' [-v|--verbose] [--] <pack>.idx ... +[verse] +'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... DESCRIPTION ----------- Reads given idx file for packed git archive created with the -'git-pack-objects' command and verifies idx file and the +'git pack-objects' command and verifies idx file and the corresponding pack file. OPTIONS @@ -47,14 +48,6 @@ for objects that are not deltified in the pack, and for objects that are deltified. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index 84e70a0234..5ff76e892a 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -7,25 +7,22 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- +[verse] 'git verify-tag' <tag>... DESCRIPTION ----------- -Validates the gpg signature created by 'git-tag'. +Validates the gpg signature created by 'git tag'. OPTIONS ------- +-v:: +--verbose:: + Print the contents of the tag object before validating it. + <tag>...:: SHA1 identifiers of git tag objects. -Author ------- -Written by Jan Harkes <jaharkes@cs.cmu.edu> and Eric W. Biederman <ebiederm@xmission.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 278cf73527..c2bc87bc61 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -1,5 +1,5 @@ -git-web--browse(1) -================== +git-web{litdd}browse(1) +======================= NAME ---- @@ -7,7 +7,8 @@ git-web--browse - git helper script to launch a web browser SYNOPSIS -------- -'git web--browse' [OPTIONS] URL/FILE ... +[verse] +'git web{litdd}browse' [OPTIONS] URL/FILE ... DESCRIPTION ----------- @@ -20,8 +21,14 @@ The following browsers (or commands) are currently supported: * firefox (this is the default under X Window when not using KDE) * iceweasel +* seamonkey +* iceape +* chromium (also supported as chromium-browser) +* google-chrome (also supported as chrome) * konqueror (this is the default under KDE, see 'Note about konqueror' below) +* opera * w3m (this is the default outside graphical environments) +* elinks * links * lynx * dillo @@ -32,19 +39,19 @@ Custom commands may also be specified. OPTIONS ------- --b BROWSER:: ---browser=BROWSER:: - Use the specified BROWSER. It must be in the list of supported +-b <browser>:: +--browser=<browser>:: + Use the specified browser. It must be in the list of supported browsers. --t BROWSER:: ---tool=BROWSER:: +-t <browser>:: +--tool=<browser>:: Same as above. --c CONF.VAR:: ---config=CONF.VAR:: +-c <conf.var>:: +--config=<conf.var>:: CONF.VAR is looked up in the git config files. If it's set, - then its value specify the browser that should be used. + then its value specifies the browser that should be used. CONFIGURATION VARIABLES ----------------------- @@ -62,7 +69,7 @@ browser.<tool>.path You can explicitly provide a full path to your preferred browser by setting the configuration variable 'browser.<tool>.path'. For example, you can configure the absolute path to firefox by setting -'browser.firefox.path'. Otherwise, 'git-web--browse' assumes the tool +'browser.firefox.path'. Otherwise, 'git web{litdd}browse' assumes the tool is available in PATH. browser.<tool>.cmd @@ -71,7 +78,7 @@ browser.<tool>.cmd When the browser, specified by options or configuration variables, is not among the supported ones, then the corresponding 'browser.<tool>.cmd' configuration variable will be looked up. If this -variable exists then 'git-web--browse' will treat the specified tool +variable exists then 'git web{litdd}browse' will treat the specified tool as a custom command and will use a shell eval to run the command with the URLs passed as arguments. @@ -110,16 +117,6 @@ $ git config --global web.browser firefox as they are probably more user specific than repository specific. See linkgit:git-config[1] for more information about this. -Author ------- -Written by Christian Couder <chriscool@tuxfamily.org> and the git-list -<git@vger.kernel.org>, based on 'git-mergetool' by Theodore Y. Ts'o. - -Documentation -------------- -Documentation by Christian Couder <chriscool@tuxfamily.org> and the -git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index cadfbd9040..76c7f7eec5 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -8,13 +8,14 @@ git-whatchanged - Show logs with difference each commit introduces SYNOPSIS -------- +[verse] 'git whatchanged' <option>... DESCRIPTION ----------- Shows commit logs and diff output each commit introduces. The -command internally invokes 'git-rev-list' piped to -'git-diff-tree', and takes command line options for both of +command internally invokes 'git rev-list' piped to +'git diff-tree', and takes command line options for both of these commands. This manual page describes only the most frequently used options. @@ -52,28 +53,17 @@ include::pretty-formats.txt[] Examples -------- -git whatchanged -p v2.6.12.. include/scsi drivers/scsi:: +`git whatchanged -p v2.6.12.. include/scsi drivers/scsi`:: Show as patches the commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -git whatchanged --since="2 weeks ago" \-- gitk:: +`git whatchanged --since="2 weeks ago" \-- gitk`:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named 'gitk' - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index c8899d528a..f22041a9dc 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -8,6 +8,7 @@ git-write-tree - Create a tree object from the current index SYNOPSIS -------- +[verse] 'git write-tree' [--missing-ok] [--prefix=<prefix>/] DESCRIPTION @@ -17,17 +18,17 @@ tree object is printed to standard output. The index must be in a fully merged state. -Conceptually, 'git-write-tree' sync()s the current index contents +Conceptually, 'git write-tree' sync()s the current index contents into a set of tree files. In order to have that match what is actually in your directory right -now, you need to have done a 'git-update-index' phase before you did the -'git-write-tree'. +now, you need to have done a 'git update-index' phase before you did the +'git write-tree'. OPTIONS ------- --missing-ok:: - Normally 'git-write-tree' ensures that the objects referenced by the + Normally 'git write-tree' ensures that the objects referenced by the directory exist in the object database. This option disables this check. @@ -36,15 +37,6 @@ OPTIONS `<prefix>`. This can be used to write the tree object for a subproject that is in the named subdirectory. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index 352c23019f..5e80cfd71a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -9,10 +9,11 @@ git - the stupid content tracker SYNOPSIS -------- [verse] -'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path] - [-p|--paginate|--no-pager] [--no-replace-objects] - [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] - [--help] COMMAND [ARGS] +'git' [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] + [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] + [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] + [-c <name>=<value>] + [--help] <command> [<args>] DESCRIPTION ----------- @@ -27,7 +28,7 @@ also want to read linkgit:gitcvs-migration[7]. See the link:user-manual.html[Git User's Manual] for a more in-depth introduction. -The COMMAND is either a name of a Git command (see below) or an alias +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]). Formatted and hyperlinked version of the latest git @@ -43,146 +44,229 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.6.6/git.html[documentation for release 1.6.6] +* link:v1.7.7.1/git.html[documentation for release 1.7.7.1] * release notes for - link:RelNotes-1.6.6.txt[1.6.6]. + link:RelNotes/1.7.7.1.txt[1.7.7.1], + link:RelNotes/1.7.7.txt[1.7.7]. -* link:v1.6.5.7/git.html[documentation for release 1.6.5.7] +* link:v1.7.6.4/git.html[documentation for release 1.7.6.4] * release notes for - link:RelNotes-1.6.5.7.txt[1.6.5.7], - link:RelNotes-1.6.5.6.txt[1.6.5.6], - link:RelNotes-1.6.5.5.txt[1.6.5.5], - link:RelNotes-1.6.5.4.txt[1.6.5.4], - link:RelNotes-1.6.5.3.txt[1.6.5.3], - link:RelNotes-1.6.5.2.txt[1.6.5.2], - link:RelNotes-1.6.5.1.txt[1.6.5.1], - link:RelNotes-1.6.5.txt[1.6.5]. + link:RelNotes/1.7.6.4.txt[1.7.6.4], + link:RelNotes/1.7.6.3.txt[1.7.6.3], + link:RelNotes/1.7.6.2.txt[1.7.6.2], + link:RelNotes/1.7.6.1.txt[1.7.6.1], + link:RelNotes/1.7.6.txt[1.7.6]. -* link:v1.6.4.4/git.html[documentation for release 1.6.4.4] +* link:v1.7.5.4/git.html[documentation for release 1.7.5.4] * release notes for - link:RelNotes-1.6.4.4.txt[1.6.4.4], - link:RelNotes-1.6.4.3.txt[1.6.4.3], - link:RelNotes-1.6.4.2.txt[1.6.4.2], - link:RelNotes-1.6.4.1.txt[1.6.4.1], - link:RelNotes-1.6.4.txt[1.6.4]. + link:RelNotes/1.7.5.4.txt[1.7.5.4], + link:RelNotes/1.7.5.3.txt[1.7.5.3], + link:RelNotes/1.7.5.2.txt[1.7.5.2], + link:RelNotes/1.7.5.1.txt[1.7.5.1], + link:RelNotes/1.7.5.txt[1.7.5]. + +* link:v1.7.4.5/git.html[documentation for release 1.7.4.5] + +* release notes for + link:RelNotes/1.7.4.5.txt[1.7.4.5], + link:RelNotes/1.7.4.4.txt[1.7.4.4], + link:RelNotes/1.7.4.3.txt[1.7.4.3], + link:RelNotes/1.7.4.2.txt[1.7.4.2], + link:RelNotes/1.7.4.1.txt[1.7.4.1], + link:RelNotes/1.7.4.txt[1.7.4]. + +* link:v1.7.3.5/git.html[documentation for release 1.7.3.5] + +* release notes for + link:RelNotes/1.7.3.5.txt[1.7.3.5], + link:RelNotes/1.7.3.4.txt[1.7.3.4], + link:RelNotes/1.7.3.3.txt[1.7.3.3], + link:RelNotes/1.7.3.2.txt[1.7.3.2], + link:RelNotes/1.7.3.1.txt[1.7.3.1], + link:RelNotes/1.7.3.txt[1.7.3]. + +* link:v1.7.2.5/git.html[documentation for release 1.7.2.5] + +* release notes for + link:RelNotes/1.7.2.5.txt[1.7.2.5], + link:RelNotes/1.7.2.4.txt[1.7.2.4], + link:RelNotes/1.7.2.3.txt[1.7.2.3], + link:RelNotes/1.7.2.2.txt[1.7.2.2], + link:RelNotes/1.7.2.1.txt[1.7.2.1], + link:RelNotes/1.7.2.txt[1.7.2]. + +* link:v1.7.1.4/git.html[documentation for release 1.7.1.4] + +* release notes for + link:RelNotes/1.7.1.4.txt[1.7.1.4], + link:RelNotes/1.7.1.3.txt[1.7.1.3], + link:RelNotes/1.7.1.2.txt[1.7.1.2], + link:RelNotes/1.7.1.1.txt[1.7.1.1], + link:RelNotes/1.7.1.txt[1.7.1]. + +* link:v1.7.0.9/git.html[documentation for release 1.7.0.9] + +* release notes for + link:RelNotes/1.7.0.9.txt[1.7.0.9], + link:RelNotes/1.7.0.8.txt[1.7.0.8], + link:RelNotes/1.7.0.7.txt[1.7.0.7], + link:RelNotes/1.7.0.6.txt[1.7.0.6], + link:RelNotes/1.7.0.5.txt[1.7.0.5], + link:RelNotes/1.7.0.4.txt[1.7.0.4], + link:RelNotes/1.7.0.3.txt[1.7.0.3], + link:RelNotes/1.7.0.2.txt[1.7.0.2], + link:RelNotes/1.7.0.1.txt[1.7.0.1], + link:RelNotes/1.7.0.txt[1.7.0]. + +* link:v1.6.6.3/git.html[documentation for release 1.6.6.3] + +* release notes for + link:RelNotes/1.6.6.3.txt[1.6.6.3], + link:RelNotes/1.6.6.2.txt[1.6.6.2], + link:RelNotes/1.6.6.1.txt[1.6.6.1], + link:RelNotes/1.6.6.txt[1.6.6]. + +* link:v1.6.5.9/git.html[documentation for release 1.6.5.9] + +* release notes for + link:RelNotes/1.6.5.9.txt[1.6.5.9], + link:RelNotes/1.6.5.8.txt[1.6.5.8], + link:RelNotes/1.6.5.7.txt[1.6.5.7], + link:RelNotes/1.6.5.6.txt[1.6.5.6], + link:RelNotes/1.6.5.5.txt[1.6.5.5], + link:RelNotes/1.6.5.4.txt[1.6.5.4], + link:RelNotes/1.6.5.3.txt[1.6.5.3], + link:RelNotes/1.6.5.2.txt[1.6.5.2], + link:RelNotes/1.6.5.1.txt[1.6.5.1], + link:RelNotes/1.6.5.txt[1.6.5]. + +* link:v1.6.4.5/git.html[documentation for release 1.6.4.5] + +* release notes for + link:RelNotes/1.6.4.5.txt[1.6.4.5], + link:RelNotes/1.6.4.4.txt[1.6.4.4], + link:RelNotes/1.6.4.3.txt[1.6.4.3], + link:RelNotes/1.6.4.2.txt[1.6.4.2], + link:RelNotes/1.6.4.1.txt[1.6.4.1], + link:RelNotes/1.6.4.txt[1.6.4]. * link:v1.6.3.4/git.html[documentation for release 1.6.3.4] * release notes for - link:RelNotes-1.6.3.4.txt[1.6.3.4], - link:RelNotes-1.6.3.3.txt[1.6.3.3], - link:RelNotes-1.6.3.2.txt[1.6.3.2], - link:RelNotes-1.6.3.1.txt[1.6.3.1], - link:RelNotes-1.6.3.txt[1.6.3]. + link:RelNotes/1.6.3.4.txt[1.6.3.4], + link:RelNotes/1.6.3.3.txt[1.6.3.3], + link:RelNotes/1.6.3.2.txt[1.6.3.2], + link:RelNotes/1.6.3.1.txt[1.6.3.1], + link:RelNotes/1.6.3.txt[1.6.3]. * release notes for - link:RelNotes-1.6.2.5.txt[1.6.2.5], - link:RelNotes-1.6.2.4.txt[1.6.2.4], - link:RelNotes-1.6.2.3.txt[1.6.2.3], - link:RelNotes-1.6.2.2.txt[1.6.2.2], - link:RelNotes-1.6.2.1.txt[1.6.2.1], - link:RelNotes-1.6.2.txt[1.6.2]. + link:RelNotes/1.6.2.5.txt[1.6.2.5], + link:RelNotes/1.6.2.4.txt[1.6.2.4], + link:RelNotes/1.6.2.3.txt[1.6.2.3], + link:RelNotes/1.6.2.2.txt[1.6.2.2], + link:RelNotes/1.6.2.1.txt[1.6.2.1], + link:RelNotes/1.6.2.txt[1.6.2]. * link:v1.6.1.3/git.html[documentation for release 1.6.1.3] * release notes for - link:RelNotes-1.6.1.3.txt[1.6.1.3], - link:RelNotes-1.6.1.2.txt[1.6.1.2], - link:RelNotes-1.6.1.1.txt[1.6.1.1], - link:RelNotes-1.6.1.txt[1.6.1]. + link:RelNotes/1.6.1.3.txt[1.6.1.3], + link:RelNotes/1.6.1.2.txt[1.6.1.2], + link:RelNotes/1.6.1.1.txt[1.6.1.1], + link:RelNotes/1.6.1.txt[1.6.1]. * link:v1.6.0.6/git.html[documentation for release 1.6.0.6] * release notes for - link:RelNotes-1.6.0.6.txt[1.6.0.6], - link:RelNotes-1.6.0.5.txt[1.6.0.5], - link:RelNotes-1.6.0.4.txt[1.6.0.4], - link:RelNotes-1.6.0.3.txt[1.6.0.3], - link:RelNotes-1.6.0.2.txt[1.6.0.2], - link:RelNotes-1.6.0.1.txt[1.6.0.1], - link:RelNotes-1.6.0.txt[1.6.0]. + link:RelNotes/1.6.0.6.txt[1.6.0.6], + link:RelNotes/1.6.0.5.txt[1.6.0.5], + link:RelNotes/1.6.0.4.txt[1.6.0.4], + link:RelNotes/1.6.0.3.txt[1.6.0.3], + link:RelNotes/1.6.0.2.txt[1.6.0.2], + link:RelNotes/1.6.0.1.txt[1.6.0.1], + link:RelNotes/1.6.0.txt[1.6.0]. * link:v1.5.6.6/git.html[documentation for release 1.5.6.6] * release notes for - link:RelNotes-1.5.6.6.txt[1.5.6.6], - link:RelNotes-1.5.6.5.txt[1.5.6.5], - link:RelNotes-1.5.6.4.txt[1.5.6.4], - link:RelNotes-1.5.6.3.txt[1.5.6.3], - link:RelNotes-1.5.6.2.txt[1.5.6.2], - link:RelNotes-1.5.6.1.txt[1.5.6.1], - link:RelNotes-1.5.6.txt[1.5.6]. + link:RelNotes/1.5.6.6.txt[1.5.6.6], + link:RelNotes/1.5.6.5.txt[1.5.6.5], + link:RelNotes/1.5.6.4.txt[1.5.6.4], + link:RelNotes/1.5.6.3.txt[1.5.6.3], + link:RelNotes/1.5.6.2.txt[1.5.6.2], + link:RelNotes/1.5.6.1.txt[1.5.6.1], + link:RelNotes/1.5.6.txt[1.5.6]. * link:v1.5.5.6/git.html[documentation for release 1.5.5.6] * release notes for - link:RelNotes-1.5.5.6.txt[1.5.5.6], - link:RelNotes-1.5.5.5.txt[1.5.5.5], - link:RelNotes-1.5.5.4.txt[1.5.5.4], - link:RelNotes-1.5.5.3.txt[1.5.5.3], - link:RelNotes-1.5.5.2.txt[1.5.5.2], - link:RelNotes-1.5.5.1.txt[1.5.5.1], - link:RelNotes-1.5.5.txt[1.5.5]. + link:RelNotes/1.5.5.6.txt[1.5.5.6], + link:RelNotes/1.5.5.5.txt[1.5.5.5], + link:RelNotes/1.5.5.4.txt[1.5.5.4], + link:RelNotes/1.5.5.3.txt[1.5.5.3], + link:RelNotes/1.5.5.2.txt[1.5.5.2], + link:RelNotes/1.5.5.1.txt[1.5.5.1], + link:RelNotes/1.5.5.txt[1.5.5]. * link:v1.5.4.7/git.html[documentation for release 1.5.4.7] * release notes for - link:RelNotes-1.5.4.7.txt[1.5.4.7], - link:RelNotes-1.5.4.6.txt[1.5.4.6], - link:RelNotes-1.5.4.5.txt[1.5.4.5], - link:RelNotes-1.5.4.4.txt[1.5.4.4], - link:RelNotes-1.5.4.3.txt[1.5.4.3], - link:RelNotes-1.5.4.2.txt[1.5.4.2], - link:RelNotes-1.5.4.1.txt[1.5.4.1], - link:RelNotes-1.5.4.txt[1.5.4]. + link:RelNotes/1.5.4.7.txt[1.5.4.7], + link:RelNotes/1.5.4.6.txt[1.5.4.6], + link:RelNotes/1.5.4.5.txt[1.5.4.5], + link:RelNotes/1.5.4.4.txt[1.5.4.4], + link:RelNotes/1.5.4.3.txt[1.5.4.3], + link:RelNotes/1.5.4.2.txt[1.5.4.2], + link:RelNotes/1.5.4.1.txt[1.5.4.1], + link:RelNotes/1.5.4.txt[1.5.4]. * link:v1.5.3.8/git.html[documentation for release 1.5.3.8] * release notes for - link:RelNotes-1.5.3.8.txt[1.5.3.8], - link:RelNotes-1.5.3.7.txt[1.5.3.7], - link:RelNotes-1.5.3.6.txt[1.5.3.6], - link:RelNotes-1.5.3.5.txt[1.5.3.5], - link:RelNotes-1.5.3.4.txt[1.5.3.4], - link:RelNotes-1.5.3.3.txt[1.5.3.3], - link:RelNotes-1.5.3.2.txt[1.5.3.2], - link:RelNotes-1.5.3.1.txt[1.5.3.1], - link:RelNotes-1.5.3.txt[1.5.3]. + link:RelNotes/1.5.3.8.txt[1.5.3.8], + link:RelNotes/1.5.3.7.txt[1.5.3.7], + link:RelNotes/1.5.3.6.txt[1.5.3.6], + link:RelNotes/1.5.3.5.txt[1.5.3.5], + link:RelNotes/1.5.3.4.txt[1.5.3.4], + link:RelNotes/1.5.3.3.txt[1.5.3.3], + link:RelNotes/1.5.3.2.txt[1.5.3.2], + link:RelNotes/1.5.3.1.txt[1.5.3.1], + link:RelNotes/1.5.3.txt[1.5.3]. * link:v1.5.2.5/git.html[documentation for release 1.5.2.5] * release notes for - link:RelNotes-1.5.2.5.txt[1.5.2.5], - link:RelNotes-1.5.2.4.txt[1.5.2.4], - link:RelNotes-1.5.2.3.txt[1.5.2.3], - link:RelNotes-1.5.2.2.txt[1.5.2.2], - link:RelNotes-1.5.2.1.txt[1.5.2.1], - link:RelNotes-1.5.2.txt[1.5.2]. + link:RelNotes/1.5.2.5.txt[1.5.2.5], + link:RelNotes/1.5.2.4.txt[1.5.2.4], + link:RelNotes/1.5.2.3.txt[1.5.2.3], + link:RelNotes/1.5.2.2.txt[1.5.2.2], + link:RelNotes/1.5.2.1.txt[1.5.2.1], + link:RelNotes/1.5.2.txt[1.5.2]. * link:v1.5.1.6/git.html[documentation for release 1.5.1.6] * release notes for - link:RelNotes-1.5.1.6.txt[1.5.1.6], - link:RelNotes-1.5.1.5.txt[1.5.1.5], - link:RelNotes-1.5.1.4.txt[1.5.1.4], - link:RelNotes-1.5.1.3.txt[1.5.1.3], - link:RelNotes-1.5.1.2.txt[1.5.1.2], - link:RelNotes-1.5.1.1.txt[1.5.1.1], - link:RelNotes-1.5.1.txt[1.5.1]. + link:RelNotes/1.5.1.6.txt[1.5.1.6], + link:RelNotes/1.5.1.5.txt[1.5.1.5], + link:RelNotes/1.5.1.4.txt[1.5.1.4], + link:RelNotes/1.5.1.3.txt[1.5.1.3], + link:RelNotes/1.5.1.2.txt[1.5.1.2], + link:RelNotes/1.5.1.1.txt[1.5.1.1], + link:RelNotes/1.5.1.txt[1.5.1]. * link:v1.5.0.7/git.html[documentation for release 1.5.0.7] * release notes for - link:RelNotes-1.5.0.7.txt[1.5.0.7], - link:RelNotes-1.5.0.6.txt[1.5.0.6], - link:RelNotes-1.5.0.5.txt[1.5.0.5], - link:RelNotes-1.5.0.3.txt[1.5.0.3], - link:RelNotes-1.5.0.2.txt[1.5.0.2], - link:RelNotes-1.5.0.1.txt[1.5.0.1], - link:RelNotes-1.5.0.txt[1.5.0]. + link:RelNotes/1.5.0.7.txt[1.5.0.7], + link:RelNotes/1.5.0.6.txt[1.5.0.6], + link:RelNotes/1.5.0.5.txt[1.5.0.5], + link:RelNotes/1.5.0.3.txt[1.5.0.3], + link:RelNotes/1.5.0.2.txt[1.5.0.2], + link:RelNotes/1.5.0.1.txt[1.5.0.1], + link:RelNotes/1.5.0.txt[1.5.0]. * documentation for release link:v1.4.4.4/git.html[1.4.4.4], link:v1.3.3/git.html[1.3.3], @@ -209,19 +293,36 @@ displayed. See linkgit:git-help[1] for more information, because `git --help ...` is converted internally into `git help ...`. ---exec-path:: +-c <name>=<value>:: + Pass a configuration parameter to the command. The value + given will override values from configuration files. + The <name> is expected in the same format as listed by + 'git config' (subkeys separated by dots). + +--exec-path[=<path>]:: Path to wherever your core git programs are installed. This can also be controlled by setting the GIT_EXEC_PATH environment variable. If no path is given, 'git' will print the current setting and then exit. --html-path:: - Print the path to wherever your git HTML documentation is installed - and exit. + Print the path, without trailing slash, where git's HTML + documentation is installed and exit. + +--man-path:: + Print the manpath (see `man(1)`) for the man pages for + this version of git and exit. + +--info-path:: + Print the path where the Info files documenting this + version of git are installed and exit. -p:: --paginate:: - Pipe all output into 'less' (or if set, $PAGER). + Pipe all output into 'less' (or if set, $PAGER) if standard + output is a terminal. This overrides the `pager.<cmd>` + configuration options (see the "Configuration Mechanism" section + below). --no-pager:: Do not pipe git output into a pager. @@ -232,17 +333,17 @@ help ...`. path or relative path to current working directory. --work-tree=<path>:: - Set the path to the working tree. The value will not be - used in combination with repositories found automatically in - a .git directory (i.e. $GIT_DIR is not set). + Set the path to the working tree. It can be an absolute path + or a path relative to the current working directory. This can also be controlled by setting the GIT_WORK_TREE environment variable and the core.worktree configuration - variable. It can be an absolute path or relative path to - the directory specified by --git-dir or GIT_DIR. - Note: If --git-dir or GIT_DIR are specified but none of - --work-tree, GIT_WORK_TREE and core.worktree is specified, - the current working directory is regarded as the top directory - of your working tree. + variable (see core.worktree in linkgit:git-config[1] for a + more detailed discussion). + +--namespace=<path>:: + Set the git namespace. See linkgit:gitnamespaces[7] for more + details. Equivalent to setting the `GIT_NAMESPACE` environment + variable. --bare:: Treat the repository as a bare repository. If GIT_DIR @@ -393,7 +494,8 @@ people. Here is an example: ------------ Various commands read from the configuration file and adjust -their operation accordingly. +their operation accordingly. See linkgit:git-config[1] for a +list. Identifier Terminology @@ -436,19 +538,18 @@ Any git command accepting any <object> can also use the following symbolic notation: HEAD:: - indicates the head of the current branch (i.e. the - contents of `$GIT_DIR/HEAD`). + indicates the head of the current branch. <tag>:: a valid tag 'name' - (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). + (i.e. a `refs/tags/<tag>` reference). <head>:: a valid head 'name' - (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). + (i.e. a `refs/heads/<head>` reference). For a more complete list of ways to spell object names, see -"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. +"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. File/Directory Structure @@ -507,6 +608,10 @@ git so take care if using Cogito etc. This can also be controlled by the '--work-tree' command line option and the core.worktree configuration variable. +'GIT_NAMESPACE':: + Set the git namespace; see linkgit:gitnamespaces[7] for details. + The '--namespace' command-line option also sets this value. + 'GIT_CEILING_DIRECTORIES':: This should be a colon-separated list of absolute paths. If set, it is a list of directories that git should not chdir @@ -515,6 +620,16 @@ git so take care if using Cogito etc. a GIT_DIR set on the command line or in the environment. (Useful for excluding slow-loading network directories.) +'GIT_DISCOVERY_ACROSS_FILESYSTEM':: + When run in a directory that does not have ".git" repository + directory, git tries to find such a directory in the parent + directories to find the top of the working tree, but by default it + does not cross filesystem boundaries. This environment variable + can be set to true to tell git not to stop at filesystem + boundaries. Like 'GIT_CEILING_DIRECTORIES', this will not affect + an explicit repository directory set via 'GIT_DIR' or on the + command line. + git Commits ~~~~~~~~~~~ 'GIT_AUTHOR_NAME':: @@ -548,7 +663,6 @@ where: contents of <old|new>, <old|new>-hex:: are the 40-hexdigit SHA1 hashes, <old|new>-mode:: are the octal representation of the file modes. - + The file parameters can point at the user's working file (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` @@ -573,8 +687,8 @@ other linkgit:git-config[1]. 'GIT_SSH':: - If this environment variable is set then 'git-fetch' - and 'git-push' will use this command instead + If this environment variable is set then 'git fetch' + and 'git push' will use this command instead of 'ssh' when they need to connect to a remote system. The '$GIT_SSH' command will be given exactly two arguments: the 'username@host' (or just 'host') from the URL and the @@ -588,10 +702,17 @@ Usually it is easier to configure any desired options through your personal `.ssh/config` file. Please consult your ssh documentation for further details. +'GIT_ASKPASS':: + If this environment variable is set, then git commands which need to + acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) + will call this program with a suitable prompt as command line argument + and read the password from its STDOUT. See also the 'core.askpass' + option in linkgit:git-config[1]. + 'GIT_FLUSH':: If this environment variable is set to "1", then commands such - as 'git-blame' (in incremental mode), 'git-rev-list', 'git-log', - and 'git-whatchanged' will force a flush of the output stream + as 'git blame' (in incremental mode), 'git rev-list', 'git log', + and 'git whatchanged' will force a flush of the output stream after each commit-oriented record have been flushed. If this variable is set to "0", the output of these commands will be done using completely buffered I/O. If this environment variable is @@ -667,16 +788,19 @@ unmerged version of a file when a merge is in progress. Authors ------- -* git's founding father is Linus Torvalds <torvalds@osdl.org>. -* The current git nurse is Junio C Hamano <gitster@pobox.com>. -* The git potty was written by Andreas Ericsson <ae@op5.se>. -* General upbringing is handled by the git-list <git@vger.kernel.org>. - -Documentation +Git was started by Linus Torvalds, and is currently maintained by Junio +C Hamano. Numerous contributions have come from the git mailing list +<git@vger.kernel.org>. For a more complete list of contributors, see +http://git-scm.com/about. If you have a clone of git.git itself, the +output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you +the authors for specific parts of the project. + +Reporting Bugs -------------- -The documentation for git suite was started by David Greaves -<david@dgreaves.com>, and later enhanced greatly by the -contributors on the git-list <git@vger.kernel.org>. + +Report bugs to the Git mailing list <git@vger.kernel.org> where the +development and maintenance is primarily done. You do not have to be +subscribed to the list to send a message there. SEE ALSO -------- diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 5a45e51890..25e46aeb7a 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -62,17 +62,24 @@ consults `$GIT_DIR/info/attributes` file (which has the highest precedence), `.gitattributes` file in the same directory as the path in question, and its parent directories up to the toplevel of the work tree (the further the directory that contains `.gitattributes` -is from the path in question, the lower its precedence). +is from the path in question, the lower its precedence). Finally +global and system-wide files are considered (they have the lowest +precedence). If you wish to affect only a single repository (i.e., to assign -attributes to files that are particular to one user's workflow), then +attributes to files that are particular to +one user's workflow for that repository), then attributes should be placed in the `$GIT_DIR/info/attributes` file. Attributes which should be version-controlled and distributed to other repositories (i.e., attributes of interest to all users) should go into -`.gitattributes` files. +`.gitattributes` files. Attributes that should affect all repositories +for a single user should be placed in a file specified by the +`core.attributesfile` configuration option (see linkgit:git-config[1]). +Attributes for all users on a system should be placed in the +`$(prefix)/etc/gitattributes` file. Sometimes you would need to override an setting of an attribute -for a path to `unspecified` state. This can be done by listing +for a path to `Unspecified` state. This can be done by listing the name of the attribute prefixed with an exclamation point `!`. @@ -88,57 +95,158 @@ Checking-out and checking-in These attributes affect how the contents stored in the repository are copied to the working tree files when commands -such as 'git-checkout' and 'git-merge' run. They also affect how +such as 'git checkout' and 'git merge' run. They also affect how git stores the contents you prepare in the working tree in the -repository upon 'git-add' and 'git-commit'. +repository upon 'git add' and 'git commit'. -`crlf` +`text` ^^^^^^ -This attribute controls the line-ending convention. +This attribute enables and controls end-of-line normalization. When a +text file is normalized, its line endings are converted to LF in the +repository. To control what line ending style is used in the working +directory, use the `eol` attribute for a single file and the +`core.eol` configuration variable for all text files. Set:: - Setting the `crlf` attribute on a path is meant to mark - the path as a "text" file. 'core.autocrlf' conversion - takes place without guessing the content type by - inspection. + Setting the `text` attribute on a path enables end-of-line + normalization and marks the path as a text file. End-of-line + conversion takes place without guessing the content type. Unset:: - Unsetting the `crlf` attribute on a path tells git not to + Unsetting the `text` attribute on a path tells git not to attempt any end-of-line conversion upon checkin or checkout. +Set to string value "auto":: + + When `text` is set to "auto", the path is marked for automatic + end-of-line normalization. If git decides that the content is + text, its line endings are normalized to LF on checkin. + Unspecified:: - Unspecified `crlf` attribute tells git to apply the - `core.autocrlf` conversion when the file content looks - like text. + If the `text` attribute is unspecified, git uses the + `core.autocrlf` configuration variable to determine if the + file should be converted. -Set to string value "input":: +Any other value causes git to act as if `text` has been left +unspecified. - This is similar to setting the attribute to `true`, but - also forces git to act as if `core.autocrlf` is set to - `input` for the path. +`eol` +^^^^^ -Any other value set to `crlf` attribute is ignored and git acts -as if the attribute is left unspecified. +This attribute sets a specific line-ending style to be used in the +working directory. It enables end-of-line normalization without any +content checks, effectively setting the `text` attribute. +Set to string value "crlf":: -The `core.autocrlf` conversion -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + This setting forces git to normalize line endings for this + file on checkin and convert them to CRLF when the file is + checked out. + +Set to string value "lf":: + + This setting forces git to normalize line endings to LF on + checkin and prevents conversion to CRLF when the file is + checked out. + +Backwards compatibility with `crlf` attribute +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For backwards compatibility, the `crlf` attribute is interpreted as +follows: + +------------------------ +crlf text +-crlf -text +crlf=input eol=lf +------------------------ + +End-of-line conversion +^^^^^^^^^^^^^^^^^^^^^^ + +While git normally leaves file contents alone, it can be configured to +normalize line endings to LF in the repository and, optionally, to +convert them to CRLF when files are checked out. + +Here is an example that will make git normalize .txt, .vcproj and .sh +files, ensure that .vcproj files have CRLF and .sh files have LF in +the working directory, and prevent .jpg files from being normalized +regardless of their content. + +------------------------ +*.txt text +*.vcproj eol=crlf +*.sh eol=lf +*.jpg -text +------------------------ + +Other source code management systems normalize all text files in their +repositories, and there are two ways to enable similar automatic +normalization in git. + +If you simply want to have CRLF line endings in your working directory +regardless of the repository you are working with, you can set the +config variable "core.autocrlf" without changing any attributes. + +------------------------ +[core] + autocrlf = true +------------------------ + +This does not force normalization of all text files, but does ensure +that text files that you introduce to the repository have their line +endings normalized to LF when they are added, and that files that are +already normalized in the repository stay normalized. + +If you want to interoperate with a source code management system that +enforces end-of-line normalization, or you simply want all text files +in your repository to be normalized, you should instead set the `text` +attribute to "auto" for _all_ files. + +------------------------ +* text=auto +------------------------ + +This ensures that all files that git considers to be text will have +normalized (LF) line endings in the repository. The `core.eol` +configuration variable controls which line endings git will use for +normalized files in your working directory; the default is to use the +native line ending for your platform, or CRLF if `core.autocrlf` is +set. + +NOTE: When `text=auto` normalization is enabled in an existing +repository, any text files containing CRLFs should be normalized. If +they are not they will be normalized the next time someone tries to +change them, causing unfortunate misattribution. From a clean working +directory: + +------------------------------------------------- +$ echo "* text=auto" >>.gitattributes +$ rm .git/index # Remove the index to force git to +$ git reset # re-scan the working directory +$ git status # Show files that will be normalized +$ git add -u +$ git add .gitattributes +$ git commit -m "Introduce end-of-line normalization" +------------------------------------------------- + +If any files that should not be normalized show up in 'git status', +unset their `text` attribute before running 'git add -u'. -If the configuration variable `core.autocrlf` is false, no -conversion is done. +------------------------ +manual.pdf -text +------------------------ -When `core.autocrlf` is true, it means that the platform wants -CRLF line endings for files in the working tree, and you want to -convert them back to the normal LF line endings when checking -in to the repository. +Conversely, text files that git does not detect can have normalization +enabled manually. -When `core.autocrlf` is set to "input", line endings are -converted to LF upon checkin, but there is no conversion done -upon checkout. +------------------------ +weirdchars.txt text +------------------------ If `core.safecrlf` is set to "true" or "warn", git verifies if the conversion is reversible for the current setting of @@ -148,16 +256,16 @@ an irreversible conversion. The safety triggers to prevent such a conversion done to the files in the work tree, but there are a few exceptions. Even though... -- 'git-add' itself does not touch the files in the work tree, the +- 'git add' itself does not touch the files in the work tree, the next checkout would, so the safety triggers; -- 'git-apply' to update a text file with a patch does touch the files +- 'git apply' to update a text file with a patch does touch the files in the work tree, but the operation is about text files and CRLF conversion is about fixing the line ending inconsistencies, so the safety does not trigger; -- 'git-diff' itself does not touch the files in the work tree, it is - often run to inspect the changes you intend to next 'git-add'. To +- 'git diff' itself does not touch the files in the work tree, it is + often run to inspect the changes you intend to next 'git add'. To catch potential problems early, safety triggers. @@ -216,6 +324,27 @@ command is "cat"). smudge = cat ------------------------ +For best results, `clean` should not alter its output further if it is +run twice ("clean->clean" should be equivalent to "clean"), and +multiple `smudge` commands should not alter `clean`'s output +("smudge->smudge->clean" should be equivalent to "clean"). See the +section on merging below. + +The "indent" filter is well-behaved in this regard: it will not modify +input that is already correctly indented. In this case, the lack of a +smudge filter means that the clean filter _must_ accept its own output +without modifying it. + +Sequence "%f" on the filter command line is replaced with the name of +the file the filter is working on. A filter might use this in keyword +substitution. For example: + +------------------------ +[filter "p4"] + clean = git-p4-filter --clean %f + smudge = git-p4-filter --smudge %f +------------------------ + Interaction between checkin/checkout attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -223,11 +352,34 @@ Interaction between checkin/checkout attributes In the check-in codepath, the worktree file is first converted with `filter` driver (if specified and corresponding driver defined), then the result is processed with `ident` (if -specified), and then finally with `crlf` (again, if specified +specified), and then finally with `text` (again, if specified and applicable). In the check-out codepath, the blob content is first converted -with `crlf`, and then `ident` and fed to `filter`. +with `text`, and then `ident` and fed to `filter`. + + +Merging branches with differing checkin/checkout attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you have added attributes to a file that cause the canonical +repository format for that file to change, such as adding a +clean/smudge filter or text/eol/ident attributes, merging anything +where the attribute is not in place would normally cause merge +conflicts. + +To prevent these unnecessary merge conflicts, git can be told to run a +virtual check-out and check-in of all three stages of a file when +resolving a three-way merge by setting the `merge.renormalize` +configuration variable. This prevents changes caused by check-in +conversion from causing spurious merge conflicts when a converted file +is merged with an unconverted file. + +As long as a "smudge->clean" results in the same output as a "clean" +even on files that are already smudged, this strategy will +automatically resolve all filter-related conflicts. Filters that do +not act in this way may cause additional merge conflicts that must be +resolved manually. Generating diff text @@ -340,6 +492,10 @@ patterns are available: - `cpp` suitable for source code in the C and C++ languages. +- `csharp` suitable for source code in the C# language. + +- `fortran` suitable for source code in the Fortran language. + - `html` suitable for HTML/XHTML documents. - `java` suitable for source code in the Java language. @@ -348,6 +504,8 @@ patterns are available: - `pascal` suitable for source code in the Pascal/Delphi language. +- `perl` suitable for source code in the Perl language. + - `php` suitable for source code in the PHP language. - `python` suitable for source code in the Python language. @@ -360,7 +518,7 @@ patterns are available: Customizing word diff ^^^^^^^^^^^^^^^^^^^^^ -You can customize the rules that `git diff --color-words` uses to +You can customize the rules that `git diff --word-diff` uses to split words in a line, by specifying an appropriate regular expression in the "diff.*.wordRegex" configuration variable. For example, in TeX a backslash followed by a sequence of letters forms a command, but @@ -414,6 +572,90 @@ because it quickly conveys the changes you have made), you should generate it separately and send it as a comment _in addition to_ the usual binary diff that you might send. +Because text conversion can be slow, especially when doing a +large number of them with `git log -p`, git provides a mechanism +to cache the output and use it in future diffs. To enable +caching, set the "cachetextconv" variable in your diff driver's +config. For example: + +------------------------ +[diff "jpg"] + textconv = exif + cachetextconv = true +------------------------ + +This will cache the result of running "exif" on each blob +indefinitely. If you change the textconv config variable for a +diff driver, git will automatically invalidate the cache entries +and re-run the textconv filter. If you want to invalidate the +cache manually (e.g., because your version of "exif" was updated +and now produces better output), you can remove the cache +manually with `git update-ref -d refs/notes/textconv/jpg` (where +"jpg" is the name of the diff driver, as in the example above). + +Choosing textconv versus external diff +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to show differences between binary or specially-formatted +blobs in your repository, you can choose to use either an external diff +command, or to use textconv to convert them to a diff-able text format. +Which method you choose depends on your exact situation. + +The advantage of using an external diff command is flexibility. You are +not bound to find line-oriented changes, nor is it necessary for the +output to resemble unified diff. You are free to locate and report +changes in the most appropriate way for your data format. + +A textconv, by comparison, is much more limiting. You provide a +transformation of the data into a line-oriented text format, and git +uses its regular diff tools to generate the output. There are several +advantages to choosing this method: + +1. Ease of use. It is often much simpler to write a binary to text + transformation than it is to perform your own diff. In many cases, + existing programs can be used as textconv filters (e.g., exif, + odt2txt). + +2. Git diff features. By performing only the transformation step + yourself, you can still utilize many of git's diff features, + including colorization, word-diff, and combined diffs for merges. + +3. Caching. Textconv caching can speed up repeated diffs, such as those + you might trigger by running `git log -p`. + + +Marking files as binary +^^^^^^^^^^^^^^^^^^^^^^^ + +Git usually guesses correctly whether a blob contains text or binary +data by examining the beginning of the contents. However, sometimes you +may want to override its decision, either because a blob contains binary +data later in the file, or because the content, while technically +composed of text characters, is opaque to a human reader. For example, +many postscript files contain only ascii characters, but produce noisy +and meaningless diffs. + +The simplest way to mark a file as binary is to unset the diff +attribute in the `.gitattributes` file: + +------------------------ +*.ps -diff +------------------------ + +This will cause git to generate `Binary files differ` (or a binary +patch, if binary patches are enabled) instead of a regular diff. + +However, one may also want to specify other diff driver attributes. For +example, you might want to use `textconv` to convert postscript files to +an ascii representation for human viewing, but otherwise treat them as +binary files. You cannot specify both `-diff` and `diff=ps` attributes. +The solution is to use the `diff.*.binary` config option: + +------------------------ +[diff "ps"] + textconv = ps2ascii + binary = true +------------------------ Performing a three-way merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -421,7 +663,7 @@ Performing a three-way merge `merge` ^^^^^^^ -The attribute `merge` affects how three versions of a file is +The attribute `merge` affects how three versions of a file are merged when a file-level merge is necessary during `git merge`, and other commands such as `git revert` and `git cherry-pick`. @@ -435,15 +677,15 @@ Unset:: Take the version from the current branch as the tentative merge result, and declare that the merge has - conflicts. This is suitable for binary files that does + conflicts. This is suitable for binary files that do not have a well-defined merge semantics. Unspecified:: By default, this uses the same built-in 3-way merge - driver as is the case the `merge` attribute is set. - However, `merge.default` configuration variable can name - different merge driver to be used for paths to which the + driver as is the case when the `merge` attribute is set. + However, the `merge.default` configuration variable can name + different merge driver to be used with paths for which the `merge` attribute is unspecified. String:: @@ -511,7 +753,8 @@ command to run to merge ancestor's version (`%O`), current version (`%A`) and the other branches' version (`%B`). These three tokens are replaced with the names of temporary files that hold the contents of these versions when the command line is -built. +built. Additionally, %L will be replaced with the conflict marker +size (see below). The merge driver is expected to leave the result of the merge in the file named with `%A` by overwriting it, and exit with zero @@ -525,6 +768,23 @@ When left unspecified, the driver itself is used for both internal merge and the final merge. +`conflict-marker-size` +^^^^^^^^^^^^^^^^^^^^^^ + +This attribute controls the length of conflict markers left in +the work tree file during a conflicted merge. Only setting to +the value to a positive integer has any meaningful effect. + +For example, this line in `.gitattributes` can be used to tell the merge +machinery to leave much longer (instead of the usual 7-character-long) +conflict markers when merging the file `Documentation/git-merge.txt` +results in a conflict. + +------------------------ +Documentation/git-merge.txt conflict-marker-size=32 +------------------------ + + Checking whitespace errors ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -539,6 +799,8 @@ control per path. Set:: Notice all types of potential whitespace errors known to git. + The tab width is taken from the value of the `core.whitespace` + configuration variable. Unset:: @@ -546,13 +808,13 @@ Unset:: Unspecified:: - Use the value of `core.whitespace` configuration variable to + Use the value of the `core.whitespace` configuration variable to decide what to notice as error. String:: Specify a comma separate list of common whitespace problems to - notice in the same format as `core.whitespace` configuration + notice in the same format as the `core.whitespace` configuration variable. @@ -606,38 +868,41 @@ If this attribute is not set or has an invalid value, the value of the (See linkgit:git-config[1]). -USING ATTRIBUTE MACROS +USING MACRO ATTRIBUTES ---------------------- You do not want any end-of-line conversions applied to, nor textual diffs produced for, any binary file you track. You would need to specify e.g. ------------ -*.jpg -crlf -diff +*.jpg -text -diff ------------ but that may become cumbersome, when you have many attributes. Using -attribute macros, you can specify groups of attributes set or unset at -the same time. The system knows a built-in attribute macro, `binary`: +macro attributes, you can define an attribute that, when set, also +sets or unsets a number of other attributes at the same time. The +system knows a built-in macro attribute, `binary`: ------------ *.jpg binary ------------ -which is equivalent to the above. Note that the attribute macros can only -be "Set" (see the above example that sets "binary" macro as if it were an -ordinary attribute --- setting it in turn unsets "crlf" and "diff"). +Setting the "binary" attribute also unsets the "text" and "diff" +attributes as above. Note that macro attributes can only be "Set", +though setting one might have the effect of setting or unsetting other +attributes or even returning other attributes to the "Unspecified" +state. -DEFINING ATTRIBUTE MACROS +DEFINING MACRO ATTRIBUTES ------------------------- -Custom attribute macros can be defined only in the `.gitattributes` file -at the toplevel (i.e. not in any subdirectory). The built-in attribute -macro "binary" is equivalent to: +Custom macro attributes can be defined only in the `.gitattributes` +file at the toplevel (i.e. not in any subdirectory). The built-in +macro attribute "binary" is equivalent to: ------------ -[attr]binary -diff -crlf +[attr]binary -diff -text ------------ @@ -690,6 +955,9 @@ frotz unspecified ---------------------------------------------------------------- +SEE ALSO +-------- +linkgit:git-check-attr[1]. GIT --- diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 6928724a05..f734f97b8e 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -169,10 +169,6 @@ See also http://marc.info/?l=git&m=116563135620359 and http://marc.info/?l=git&m=119150393620273 for further information. -Documentation -------------- -Documentation by Pierre Habouzit and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f762dca440..c27d086f68 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -27,6 +27,14 @@ interfaces on top of it called "porcelain". You may not want to use the plumbing directly very often, but it can be good to know what the plumbing does for when the porcelain isn't flushing. +Back when this document was originally written, many porcelain +commands were shell scripts. For simplicity, it still uses them as +examples to illustrate how plumbing is fit together to form the +porcelain commands. The source tree includes some of these scripts in +contrib/examples/ for reference. Although these are not implemented as +shell scripts anymore, the description of what the plumbing layer +commands do is still valid. + [NOTE] Deeper technical details are often marked as Notes, which you can skip on your first reading. @@ -44,7 +52,7 @@ to import into git. For our first example, we're going to start a totally new repository from scratch, with no pre-existing files, and we'll call it 'git-tutorial'. To start up, create a subdirectory for it, change into that -subdirectory, and initialize the git infrastructure with 'git-init': +subdirectory, and initialize the git infrastructure with 'git init': ------------------------------------------------ $ mkdir git-tutorial @@ -102,7 +110,7 @@ An 'object' is identified by its 160-bit SHA1 hash, aka 'object name', and a reference to an object is always the 40-byte hex representation of that SHA1 name. The files in the `refs` subdirectory are expected to contain these hex references -(usually with a final `\'\n\'` at the end), and you should thus +(usually with a final `\n` at the end), and you should thus expect to see a number of 41-byte files containing these references in these `refs` subdirectories when you actually start populating your tree. @@ -139,7 +147,7 @@ but to actually check in your hard work, you will have to go through two steps: - commit that index file as an object. The first step is trivial: when you want to tell git about any changes -to your working tree, you use the 'git-update-index' program. That +to your working tree, you use the 'git update-index' program. That program normally just takes a list of filenames you want to update, but to avoid trivial mistakes, it refuses to add new entries to the index (or remove existing ones) unless you explicitly tell it that you're @@ -173,14 +181,14 @@ and see two files: which correspond with the objects with names of `557db...` and `f24c7...` respectively. -If you want to, you can use 'git-cat-file' to look at those objects, but +If you want to, you can use 'git cat-file' to look at those objects, but you'll have to use the object name, not the filename of the object: ---------------- $ git cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238 ---------------- -where the `-t` tells 'git-cat-file' to tell you what the "type" of the +where the `-t` tells 'git cat-file' to tell you what the "type" of the object is. git will tell you that you have a "blob" object (i.e., just a regular file), and you can see the contents with @@ -205,7 +213,7 @@ hexadecimal digits in most places. Anyway, as we mentioned previously, you normally never actually take a look at the objects themselves, and typing long 40-character hex names is not something you'd normally want to do. The above digression -was just to show that 'git-update-index' did something magical, and +was just to show that 'git update-index' did something magical, and actually saved away the contents of your files into the git object database. @@ -228,7 +236,7 @@ $ echo "It's a new day for git" >>hello and you can now, since you told git about the previous state of `hello`, ask git what has changed in the tree compared to your old index, using the -'git-diff-files' command: +'git diff-files' command: ------------ $ git diff-files @@ -239,7 +247,7 @@ version of a 'diff', but that internal version really just tells you that it has noticed that "hello" has been modified, and that the old object contents it had have been replaced with something else. -To make it readable, we can tell 'git-diff-files' to output the +To make it readable, we can tell 'git diff-files' to output the differences as a patch, using the `-p` flag: ------------ @@ -255,7 +263,7 @@ index 557db03..263414f 100644 i.e. the diff of the change we caused by adding another line to `hello`. -In other words, 'git-diff-files' always shows us the difference between +In other words, 'git diff-files' always shows us the difference between what is recorded in the index, and what is currently in the working tree. That's very useful. @@ -283,7 +291,7 @@ that in two phases: creating a 'tree' object, and committing that 'tree' object as a 'commit' object together with an explanation of what the tree was all about, along with information of how we came to that state. -Creating a tree object is trivial, and is done with 'git-write-tree'. +Creating a tree object is trivial, and is done with 'git write-tree'. There are no options or other input: `git write-tree` will take the current index state, and write an object that describes that whole index. In other words, we're now tying together all the different @@ -302,28 +310,28 @@ and this will just output the name of the resulting tree, in this case ---------------- which is another incomprehensible object name. Again, if you want to, -you can use `git cat-file -t 8988d\...` to see that this time the object +you can use `git cat-file -t 8988d...` to see that this time the object is not a "blob" object, but a "tree" object (you can also use `git cat-file` to actually output the raw object contents, but you'll see mainly a binary mess, so that's less interesting). -However -- normally you'd never use 'git-write-tree' on its own, because +However -- normally you'd never use 'git write-tree' on its own, because normally you always commit a tree into a commit object using the -'git-commit-tree' command. In fact, it's easier to not actually use -'git-write-tree' on its own at all, but to just pass its result in as an -argument to 'git-commit-tree'. +'git commit-tree' command. In fact, it's easier to not actually use +'git write-tree' on its own at all, but to just pass its result in as an +argument to 'git commit-tree'. -'git-commit-tree' normally takes several arguments -- it wants to know +'git commit-tree' normally takes several arguments -- it wants to know what the 'parent' of a commit was, but since this is the first commit ever in this new repository, and it has no parents, we only need to pass in -the object name of the tree. However, 'git-commit-tree' also wants to get a +the object name of the tree. However, 'git commit-tree' also wants to get a commit message on its standard input, and it will write out the resulting object name for the commit to its standard output. And this is where we create the `.git/refs/heads/master` file which is pointed at by `HEAD`. This file is supposed to contain the reference to the top-of-tree of the master branch, and since -that's exactly what 'git-commit-tree' spits out, we can do this +that's exactly what 'git commit-tree' spits out, we can do this all with a sequence of simple shell commands: ------------------------------------------------ @@ -345,11 +353,11 @@ instead, and it would have done the above magic scripting for you. Making a change --------------- -Remember how we did the 'git-update-index' on file `hello` and then we +Remember how we did the 'git update-index' on file `hello` and then we changed `hello` afterward, and could compare the new state of `hello` with the state we saved in the index file? -Further, remember how I said that 'git-write-tree' writes the contents +Further, remember how I said that 'git write-tree' writes the contents of the *index* file to the tree, and thus what we just committed was in fact the *original* contents of the file `hello`, not the new ones. We did that on purpose, to show the difference between the index state, and the @@ -360,12 +368,12 @@ As before, if we do `git diff-files -p` in our git-tutorial project, we'll still see the same difference we saw last time: the index file hasn't changed by the act of committing anything. However, now that we have committed something, we can also learn to use a new command: -'git-diff-index'. +'git diff-index'. -Unlike 'git-diff-files', which showed the difference between the index -file and the working tree, 'git-diff-index' shows the differences +Unlike 'git diff-files', which showed the difference between the index +file and the working tree, 'git diff-index' shows the differences between a committed *tree* and either the index file or the working -tree. In other words, 'git-diff-index' wants a tree to be diffed +tree. In other words, 'git diff-index' wants a tree to be diffed against, and before we did the commit, we couldn't do that, because we didn't have anything to diff against. @@ -375,7 +383,7 @@ But now we can do $ git diff-index -p HEAD ---------------- -(where `-p` has the same meaning as it did in 'git-diff-files'), and it +(where `-p` has the same meaning as it did in 'git diff-files'), and it will show us the same difference, but for a totally different reason. Now we're comparing the working tree not against the index file, but against the tree we just wrote. It just so happens that those two @@ -390,7 +398,7 @@ $ git diff HEAD which ends up doing the above for you. -In other words, 'git-diff-index' normally compares a tree against the +In other words, 'git diff-index' normally compares a tree against the working tree, but when given the `\--cached` flag, it is told to instead compare against just the index cache contents, and ignore the current working tree state entirely. Since we just wrote the index @@ -399,7 +407,7 @@ an empty set of differences, and that's exactly what it does. [NOTE] ================ -'git-diff-index' really always uses the index for its +'git diff-index' really always uses the index for its comparisons, and saying that it compares a tree against the working tree is thus not strictly accurate. In particular, the list of files to compare (the "meta-data") *always* comes from the index file, @@ -428,11 +436,11 @@ $ git update-index hello (note how we didn't need the `\--add` flag this time, since git knew about the file already). -Note what happens to the different 'git-diff-\*' versions here. After -we've updated `hello` in the index, `git diff-files -p` now shows no +Note what happens to the different 'git diff-{asterisk}' versions here. +After we've updated `hello` in the index, `git diff-files -p` now shows no differences, but `git diff-index -p HEAD` still *does* show that the current state is different from the state we committed. In fact, now -'git-diff-index' shows the same difference whether we use the `--cached` +'git diff-index' shows the same difference whether we use the `--cached` flag or not, since now the index is coherent with the working tree. Now, since we've updated `hello` in the index, we can commit the new @@ -460,7 +468,7 @@ You've now made your first real git commit. And if you're interested in looking at what `git commit` really does, feel free to investigate: it's a few very simple shell scripts to generate the helpful (?) commit message headers, and a few one-liners that actually do the -commit itself ('git-commit'). +commit itself ('git commit'). Inspecting Changes @@ -468,9 +476,9 @@ Inspecting Changes While creating changes is useful, it's even more useful if you can tell later what changed. The most useful command for this is another of the -'diff' family, namely 'git-diff-tree'. +'diff' family, namely 'git diff-tree'. -'git-diff-tree' can be given two arbitrary trees, and it will tell you the +'git diff-tree' can be given two arbitrary trees, and it will tell you the differences between them. Perhaps even more commonly, though, you can give it just a single commit object, and it will figure out the parent of that commit itself, and show the difference directly. Thus, to get @@ -486,7 +494,7 @@ and it will show what the last commit (in `HEAD`) actually changed. [NOTE] ============ Here is an ASCII art by Jon Loeliger that illustrates how -various diff-\* commands compare things. +various 'diff-{asterisk}' commands compare things. diff-tree +----+ @@ -518,15 +526,15 @@ various diff-\* commands compare things. +-----------+ ============ -More interestingly, you can also give 'git-diff-tree' the `--pretty` flag, +More interestingly, you can also give 'git diff-tree' the `--pretty` flag, which tells it to also show the commit message and author and date of the commit, and you can tell it to show a whole series of diffs. Alternatively, you can tell it to be "silent", and not show the diffs at all, but just show the actual commit message. -In fact, together with the 'git-rev-list' program (which generates a -list of revisions), 'git-diff-tree' ends up being a veritable fount of -changes. A trivial (but very useful) script called 'git-whatchanged' is +In fact, together with the 'git rev-list' program (which generates a +list of revisions), 'git diff-tree' ends up being a veritable fount of +changes. A trivial (but very useful) script called 'git whatchanged' is included with git which does exactly this, and shows a log of recent activities. @@ -553,14 +561,14 @@ When using the above two commands, the initial commit will be shown. If this is a problem because it is huge, you can hide it by setting the log.showroot configuration variable to false. Having this, you can still show it for each command just adding the `\--root` option, -which is a flag for 'git-diff-tree' accepted by both commands. +which is a flag for 'git diff-tree' accepted by both commands. With that, you should now be having some inkling of what git does, and can explore on your own. [NOTE] Most likely, you are not directly using the core -git Plumbing commands, but using Porcelain such as 'git-add', `git-rm' +git Plumbing commands, but using Porcelain such as 'git add', `git-rm' and `git-commit'. @@ -595,7 +603,7 @@ pointer to the state you want to tag, but also a small tag name and message, along with optionally a PGP signature that says that yes, you really did that tag. You create these annotated tags with either the `-a` or -`-s` flag to 'git-tag': +`-s` flag to 'git tag': ---------------- $ git tag -s <tagname> @@ -642,7 +650,7 @@ and it will be gone. There's no external repository, and there's no history outside the project you created. - if you want to move or duplicate a git repository, you can do so. There - is 'git-clone' command, but if all you want to do is just to + is 'git clone' command, but if all you want to do is just to create a copy of your repository (with all the full history that went along with it), you can do so with a regular `cp -a git-tutorial new-git-tutorial`. @@ -666,7 +674,7 @@ When copying a remote repository, you'll want to at a minimum update the index cache when you do this, and especially with other peoples' repositories you often want to make sure that the index cache is in some known state (you don't know *what* they've done and not yet checked in), -so usually you'll precede the 'git-update-index' with a +so usually you'll precede the 'git update-index' with a ---------------- $ git read-tree --reset HEAD @@ -674,7 +682,7 @@ $ git update-index --refresh ---------------- which will force a total index re-build from the tree pointed to by `HEAD`. -It resets the index contents to `HEAD`, and then the 'git-update-index' +It resets the index contents to `HEAD`, and then the 'git update-index' makes sure to match up all index entries with the checked-out files. If the original repository had uncommitted changes in its working tree, `git update-index --refresh` notices them and @@ -689,8 +697,8 @@ $ git reset and in fact a lot of the common git command combinations can be scripted with the `git xyz` interfaces. You can learn things by just looking at what the various git scripts do. For example, `git reset` used to be -the above two lines implemented in 'git-reset', but some things like -'git-status' and 'git-commit' are slightly more complex scripts around +the above two lines implemented in 'git reset', but some things like +'git status' and 'git commit' are slightly more complex scripts around the basic git commands. Many (most?) public remote repositories will not contain any of @@ -729,7 +737,7 @@ where the `-u` flag means that you want the checkout to keep the index up-to-date (so that you don't have to refresh it afterward), and the `-a` flag means "check out all files" (if you have a stale copy or an older version of a checked out tree you may also need to add the `-f` -flag first, to tell 'git-checkout-index' to *force* overwriting of any old +flag first, to tell 'git checkout-index' to *force* overwriting of any old files). Again, this can all be simplified with @@ -776,7 +784,7 @@ to it. ================================================ If you make the decision to start your new branch at some other point in the history than the current `HEAD`, you can do so by -just telling 'git-checkout' what the base of the checkout would be. +just telling 'git checkout' what the base of the checkout would be. In other words, if you have an earlier tag or branch, you'd just do ------------ @@ -819,7 +827,7 @@ $ git branch <branchname> [startingpoint] which will simply _create_ the branch, but will not do anything further. You can then later -- once you decide that you want to actually develop -on that branch -- switch to that branch with a regular 'git-checkout' +on that branch -- switch to that branch with a regular 'git checkout' with the branchname as the argument. @@ -881,7 +889,7 @@ source. Anyway, let's exit 'gitk' (`^Q` or the File menu), and decide that we want to merge the work we did on the `mybranch` branch into the `master` branch (which is currently our `HEAD` too). To do that, there's a nice -script called 'git-merge', which wants to know which branches you want +script called 'git merge', which wants to know which branches you want to resolve and what the merge is all about: ------------ @@ -925,7 +933,7 @@ $ git commit -i hello which will very loudly warn you that you're now committing a merge (which is correct, so never mind), and you can write a small merge -message about your adventures in 'git-merge'-land. +message about your adventures in 'git merge'-land. After you're done, start up `gitk \--all` to see graphically what the history looks like. Notice that `mybranch` still exists, and you can @@ -950,11 +958,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 +(notice the asterisk `{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. -All of them have non blank characters in the first column (`*` +All of them have non blank characters in the first column (`{asterisk}` 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 work" commit has the plus `+` character in the second column, @@ -963,25 +971,25 @@ commits from the master branch. The string inside brackets before the commit log message is a short name you can use to name the commit. In the above example, 'master' and 'mybranch' are branch heads. 'master^' is the first parent of 'master' -branch head. Please see linkgit:git-rev-parse[1] if you want to +branch head. Please see linkgit:gitrevisions[7] if you want to see more complex cases. [NOTE] -Without the '--more=1' option, 'git-show-branch' would not output the +Without the '--more=1' option, 'git show-branch' would not output the '[master^]' commit, as '[mybranch]' commit is a common ancestor of both 'master' and 'mybranch' tips. Please see linkgit:git-show-branch[1] for details. [NOTE] If there were more commits on the 'master' branch after the merge, the -merge commit itself would not be shown by 'git-show-branch' by +merge commit itself would not be shown by 'git show-branch' by default. You would need to provide '--sparse' option to make the merge commit visible in this case. Now, let's pretend you are the one who did all the work in `mybranch`, and the fruit of your hard work has finally been merged to the `master` branch. Let's go back to `mybranch`, and run -'git-merge' to get the "upstream changes" back to your branch. +'git merge' to get the "upstream changes" back to your branch. ------------ $ git checkout mybranch @@ -1023,12 +1031,12 @@ Merging external work It's usually much more common that you merge with somebody else than merging with your own branches, so it's worth pointing out that git makes that very easy too, and in fact, it's not that different from -doing a 'git-merge'. In fact, a remote merge ends up being nothing +doing a 'git merge'. In fact, a remote merge ends up being nothing more than "fetch the work from a remote repository into a temporary tag" -followed by a 'git-merge'. +followed by a 'git merge'. Fetching from a remote repository is done by, unsurprisingly, -'git-fetch': +'git fetch': ---------------- $ git fetch <remote-repository> @@ -1084,7 +1092,7 @@ Downloader from http and https URL first obtains the topmost commit object name from the remote site by looking at the specified refname under `repo.git/refs/` directory, and then tries to obtain the -commit object by downloading from `repo.git/objects/xx/xxx\...` +commit object by downloading from `repo.git/objects/xx/xxx...` using the object name of that commit object. Then it reads the commit object to find out its parent commits and the associate tree object; it repeats this process until it gets all the @@ -1095,7 +1103,7 @@ The 'commit walkers' are sometimes also called 'dumb transports', because they do not require any git aware smart server like git Native transport does. Any stock HTTP server that does not even support directory index would suffice. But -you must prepare your repository with 'git-update-server-info' +you must prepare your repository with 'git update-server-info' to help dumb transport downloaders. Once you fetch from the remote repository, you `merge` that @@ -1115,7 +1123,7 @@ argument. [NOTE] You could do without using any branches at all, by keeping as many local repositories as you would like to have -branches, and merging between them with 'git-pull', just like +branches, and merging between them with 'git pull', just like you merge between branches. The advantage of this approach is that it lets you keep a set of files for each `branch` checked out and you may find it easier to switch back and forth if you @@ -1132,7 +1140,7 @@ like this: $ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/ ------------------------------------------------ -and use the "linus" keyword with 'git-pull' instead of the full URL. +and use the "linus" keyword with 'git pull' instead of the full URL. Examples. @@ -1168,7 +1176,7 @@ $ git show-branch --more=2 master mybranch +* [master^] Some fun. ------------ -Remember, before running 'git-merge', our `master` head was at +Remember, before running 'git merge', our `master` head was at "Some fun." commit, while our `mybranch` head was at "Some work." commit. @@ -1195,7 +1203,7 @@ Now we are ready to experiment with the merge by hand. `git merge` command, when merging two branches, uses 3-way merge algorithm. First, it finds the common ancestor between them. -The command it uses is 'git-merge-base': +The command it uses is 'git merge-base': ------------ $ mb=$(git merge-base HEAD mybranch) @@ -1219,7 +1227,7 @@ this: $ git read-tree -m -u $mb HEAD mybranch ------------ -This is the same 'git-read-tree' command we have already seen, +This is the same 'git read-tree' command we have already seen, but it takes three trees, unlike previous examples. This reads the contents of each tree into different 'stage' in the index file (the first tree goes to stage 1, the second to stage 2, @@ -1260,8 +1268,8 @@ $ git ls-files --unmerged The next step of merging is to merge these three versions of the file, using 3-way merge. This is done by giving -'git-merge-one-file' command as one of the arguments to -'git-merge-index' command: +'git merge-one-file' command as one of the arguments to +'git merge-index' command: ------------ $ git merge-index git-merge-one-file hello @@ -1270,7 +1278,7 @@ ERROR: Merge conflict in hello fatal: merge program failed ------------ -'git-merge-one-file' script is called with parameters to +'git merge-one-file' script is called with parameters to describe those three versions, and is responsible to leave the merge results in the working tree. It is a fairly straightforward shell script, and @@ -1289,9 +1297,9 @@ $ git ls-files --stage ------------ This is the state of the index file and the working file after -'git-merge' returns control back to you, leaving the conflicting +'git merge' returns control back to you, leaving the conflicting merge for you to resolve. Notice that the path `hello` is still -unmerged, and what you see with 'git-diff' at this point is +unmerged, and what you see with 'git diff' at this point is differences since stage 2 (i.e. your version). @@ -1328,8 +1336,8 @@ into it later. Obviously, this repository creation needs to be done only once. [NOTE] -'git-push' uses a pair of commands, -'git-send-pack' on your local machine, and 'git-receive-pack' +'git push' uses a pair of commands, +'git send-pack' on your local machine, and 'git-receive-pack' on the remote machine. The communication between the two over the network internally uses an SSH connection. @@ -1344,7 +1352,7 @@ $ mkdir my-git.git ------------ Then, make that directory into a git repository by running -'git-init', but this time, since its name is not the usual +'git init', but this time, since its name is not the usual `.git`, we do things slightly differently: ------------ @@ -1407,12 +1415,12 @@ $ git repack will do it for you. If you followed the tutorial examples, you would have accumulated about 17 objects in `.git/objects/??/` -directories by now. 'git-repack' tells you how many objects it +directories by now. 'git repack' tells you how many objects it packed, and stores the packed file in `.git/objects/pack` directory. [NOTE] -You will see two files, `pack-\*.pack` and `pack-\*.idx`, +You will see two files, `pack-{asterisk}.pack` and `pack-{asterisk}.idx`, in `.git/objects/pack` directory. They are closely related to each other, and if you ever copy them by hand to a different repository for whatever reason, you should make sure you copy @@ -1420,7 +1428,7 @@ them together. The former holds all the data from the objects in the pack, and the latter holds the index for random access. -If you are paranoid, running 'git-verify-pack' command would +If you are paranoid, running 'git verify-pack' command would detect if you have a corrupt pack, but do not worry too much. Our programs are always perfect ;-). @@ -1487,17 +1495,17 @@ If other people are pulling from your repository over dumb transport protocols (HTTP), you need to keep this repository 'dumb transport friendly'. After `git init`, `$GIT_DIR/hooks/post-update.sample` copied from the standard templates -would contain a call to 'git-update-server-info' +would contain a call to 'git update-server-info' but you need to manually enable the hook with `mv post-update.sample post-update`. This makes sure -'git-update-server-info' keeps the necessary files up-to-date. +'git update-server-info' keeps the necessary files up-to-date. 3. Push into the public repository from your primary repository. -4. 'git-repack' the public repository. This establishes a big +4. 'git repack' the public repository. This establishes a big pack that contains the initial set of objects as the - baseline, and possibly 'git-prune' if the transport + baseline, and possibly 'git prune' if the transport used for pulling from your repository supports packed repositories. @@ -1511,14 +1519,14 @@ You can repack this private repository whenever you feel like. 6. Push your changes to the public repository, and announce it to the public. -7. Every once in a while, 'git-repack' the public repository. +7. Every once in a while, 'git repack' the public repository. Go back to step 5. and continue working. A recommended work cycle for a "subsystem maintainer" who works on that project and has an own "public repository" goes like this: -1. Prepare your work repository, by 'git-clone' the public +1. Prepare your work repository, by 'git clone' the public repository of the "project lead". The URL used for the initial cloning is stored in the remote.origin.url configuration variable. @@ -1533,7 +1541,7 @@ on that project and has an own "public repository" goes like this: point at the repository you are borrowing from. 4. Push into the public repository from your primary - repository. Run 'git-repack', and possibly 'git-prune' if the + repository. Run 'git repack', and possibly 'git prune' if the transport used for pulling from your repository supports packed repositories. @@ -1550,7 +1558,7 @@ like. "project lead" and possibly your "sub-subsystem maintainers" to pull from it. -7. Every once in a while, 'git-repack' the public repository. +7. Every once in a while, 'git repack' the public repository. Go back to step 5. and continue working. @@ -1558,7 +1566,7 @@ A recommended work cycle for an "individual developer" who does not have a "public" repository is somewhat different. It goes like this: -1. Prepare your work repository, by 'git-clone' the public +1. Prepare your work repository, by 'git clone' the public repository of the "project lead" (or a "subsystem maintainer", if you work on a subsystem). The URL used for the initial cloning is stored in the remote.origin.url @@ -1656,8 +1664,8 @@ $ git reset --hard master~2 ------------ You can make sure `git show-branch` matches the state before -those two 'git-merge' you just did. Then, instead of running -two 'git-merge' commands in a row, you would merge these two +those two 'git merge' you just did. Then, instead of running +two 'git merge' commands in a row, you would merge these two branch heads (this is known as 'making an Octopus'): ------------ diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt index 0e49c1c037..aeb0cdc973 100644 --- a/Documentation/gitcvs-migration.txt +++ b/Documentation/gitcvs-migration.txt @@ -7,7 +7,8 @@ gitcvs-migration - git for CVS users SYNOPSIS -------- -git cvsimport * +[verse] +'git cvsimport' * DESCRIPTION ----------- @@ -47,25 +48,25 @@ them first before running git pull. [NOTE] ================================ The 'pull' command knows where to get updates from because of certain -configuration variables that were set by the first 'git-clone' +configuration variables that were set by the first 'git clone' command; see `git config -l` and the linkgit:git-config[1] man page for details. ================================ You can update the shared repository with your changes by first committing -your changes, and then using the 'git-push' command: +your changes, and then using the 'git push' command: ------------------------------------------------ $ git push origin master ------------------------------------------------ to "push" those commits to the shared repository. If someone else has -updated the repository more recently, 'git-push', like 'cvs commit', will +updated the repository more recently, 'git push', like 'cvs commit', will complain, in which case you must pull any changes before attempting the push again. -In the 'git-push' command above we specify the name of the remote branch -to update (`master`). If we leave that out, 'git-push' tries to update +In the 'git push' command above we specify the name of the remote branch +to update (`master`). If we leave that out, 'git push' tries to update any branches in the remote repository that have the same name as a branch in the local repository. So the last 'push' can be done with either of: diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index e8041bc08f..370624c171 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -3,16 +3,17 @@ gitdiffcore(7) NAME ---- -gitdiffcore - Tweaking diff output (June 2005) +gitdiffcore - Tweaking diff output SYNOPSIS -------- +[verse] 'git diff' * DESCRIPTION ----------- -The diff commands 'git-diff-index', 'git-diff-files', and 'git-diff-tree' +The diff commands 'git diff-index', 'git diff-files', and 'git diff-tree' can be told to manipulate differences they find in unconventional ways before showing 'diff' output. The manipulation is collectively called "diffcore transformation". This short note @@ -23,18 +24,18 @@ that is easier to understand than the conventional kind. The chain of operation ---------------------- -The 'git-diff-{asterisk}' family works by first comparing two sets of +The 'git diff-{asterisk}' family works by first comparing two sets of files: - - 'git-diff-index' compares contents of a "tree" object and the + - 'git diff-index' compares contents of a "tree" object and the working directory (when '\--cached' flag is not used) or a "tree" object and the index file (when '\--cached' flag is used); - - 'git-diff-files' compares contents of the index file and the + - 'git diff-files' compares contents of the index file and the working directory; - - 'git-diff-tree' compares contents of two "tree" objects; + - 'git diff-tree' compares contents of two "tree" objects; In all of these cases, the commands themselves first optionally limit the two sets of files by any pathspecs given on their command-lines, @@ -74,12 +75,12 @@ into another list. There are currently 5 such transformations: - diffcore-pickaxe - diffcore-order -These are applied in sequence. The set of filepairs 'git-diff-{asterisk}' +These are applied in sequence. The set of filepairs 'git diff-{asterisk}' commands find are used as the input to diffcore-break, and the output from diffcore-break is used as the input to the next transformation. The final result is then passed to the output routine and generates either diff-raw format (see Output -format sections of the manual for 'git-diff-{asterisk}' commands) or +format sections of the manual for 'git diff-{asterisk}' commands) or diff-patch format. @@ -87,7 +88,7 @@ diffcore-break: For Splitting Up "Complete Rewrites" ---------------------------------------------------- The second transformation in the chain is diffcore-break, and is -controlled by the -B option to the 'git-diff-{asterisk}' commands. This is +controlled by the -B option to the 'git diff-{asterisk}' commands. This is used to detect a filepair that represents "complete rewrite" and break such filepair into two filepairs that represent delete and create. E.g. If the input contained this filepair: @@ -123,7 +124,7 @@ diffcore-rename: For Detection Renames and Copies This transformation is used to detect renames and copies, and is controlled by the -M option (to detect renames) and the -C option -(to detect copies as well) to the 'git-diff-{asterisk}' commands. If the +(to detect copies as well) to the 'git diff-{asterisk}' commands. If the input contained these filepairs: ------------------------------------------------ @@ -168,11 +169,11 @@ number after the "-M" or "-C" option (e.g. "-M8" to tell it to use 8/10 = 80%). Note. When the "-C" option is used with `\--find-copies-harder` -option, 'git-diff-{asterisk}' commands feed unmodified filepairs to +option, 'git diff-{asterisk}' commands feed unmodified filepairs to diffcore mechanism as well as modified ones. This lets the copy detector consider unmodified files as copy source candidates at the expense of making it slower. Without `\--find-copies-harder`, -'git-diff-{asterisk}' commands can detect copies only if the file that was +'git diff-{asterisk}' commands can detect copies only if the file that was copied happened to have been modified in the same changeset. @@ -223,13 +224,13 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String This transformation is used to find filepairs that represent changes that touch a specified string, and is controlled by the --S option and the `\--pickaxe-all` option to the 'git-diff-{asterisk}' +-S option and the `\--pickaxe-all` option to the 'git diff-{asterisk}' commands. When diffcore-pickaxe is in use, it checks if there are -filepairs whose "original" side has the specified string and -whose "result" side does not. Such a filepair represents "the -string appeared in this changeset". It also checks for the +filepairs whose "result" side and whose "origin" side have +different number of specified string. Such a filepair represents +"the string appeared in this changeset". It also checks for the opposite case that loses the specified string. When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves @@ -246,7 +247,7 @@ diffcore-order: For Sorting the Output Based on Filenames This is used to reorder the filepairs according to the user's (or project's) taste, and is controlled by the -O option to the -'git-diff-{asterisk}' commands. +'git diff-{asterisk}' commands. This takes a text file each of whose lines is a shell glob pattern. Filepairs that match a glob pattern on an earlier line diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 29eeae77ca..28edefa202 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -15,7 +15,7 @@ DESCRIPTION Hooks are little scripts you can place in `$GIT_DIR/hooks` directory to trigger action at certain points. When -'git-init' is run, a handful of example hooks are copied into the +'git init' is run, a handful of example hooks are copied into the `hooks` directory of the new repository, but by default they are all disabled. To enable a hook, rename it by removing its `.sample` suffix. @@ -32,10 +32,10 @@ HOOKS applypatch-msg ~~~~~~~~~~~~~~ -This hook is invoked by 'git-am' script. It takes a single +This hook is invoked by 'git am' script. It takes a single parameter, the name of the file that holds the proposed commit log message. Exiting with non-zero status causes -'git-am' to abort before applying the patch. +'git am' to abort before applying the patch. The hook is allowed to edit the message file in place, and can be used to normalize the message into some project standard @@ -48,7 +48,7 @@ The default 'applypatch-msg' hook, when enabled, runs the pre-applypatch ~~~~~~~~~~~~~~ -This hook is invoked by 'git-am'. It takes no parameter, and is +This hook is invoked by 'git am'. It takes no parameter, and is invoked after the patch is applied, but before a commit is made. If it exits with non-zero status, then the working tree will not be @@ -63,33 +63,33 @@ The default 'pre-applypatch' hook, when enabled, runs the post-applypatch ~~~~~~~~~~~~~~~ -This hook is invoked by 'git-am'. It takes no parameter, +This hook is invoked by 'git am'. It takes no parameter, and is invoked after the patch is applied and a commit is made. This hook is meant primarily for notification, and cannot affect -the outcome of 'git-am'. +the outcome of 'git am'. pre-commit ~~~~~~~~~~ -This hook is invoked by 'git-commit', and can be bypassed +This hook is invoked by 'git commit', and can be bypassed with `\--no-verify` option. It takes no parameter, and is invoked before obtaining the proposed commit log message and making a commit. Exiting with non-zero status from this script -causes the 'git-commit' to abort. +causes the 'git commit' to abort. The default 'pre-commit' hook, when enabled, catches introduction of lines with trailing whitespaces and aborts the commit when such a line is found. -All the 'git-commit' hooks are invoked with the environment +All the 'git commit' hooks are invoked with the environment variable `GIT_EDITOR=:` if the command will not bring up an editor to modify the commit message. prepare-commit-msg ~~~~~~~~~~~~~~~~~~ -This hook is invoked by 'git-commit' right after preparing the +This hook is invoked by 'git commit' right after preparing the default log message, and before the editor is started. It takes one to three parameters. The first is the name of the file @@ -101,7 +101,7 @@ commit is a merge or a `.git/MERGE_MSG` file exists); `squash` (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by a commit SHA1 (if a `-c`, `-C` or `\--amend` option was given). -If the exit status is non-zero, 'git-commit' will abort. +If the exit status is non-zero, 'git commit' will abort. The purpose of the hook is to edit the message file in place, and it is not suppressed by the `\--no-verify` option. A non-zero exit @@ -114,10 +114,10 @@ out the `Conflicts:` part of a merge's commit message. commit-msg ~~~~~~~~~~ -This hook is invoked by 'git-commit', and can be bypassed +This hook is invoked by 'git commit', and can be bypassed with `\--no-verify` option. It takes a single parameter, the name of the file that holds the proposed commit log message. -Exiting with non-zero status causes the 'git-commit' to +Exiting with non-zero status causes the 'git commit' to abort. The hook is allowed to edit the message file in place, and can @@ -131,30 +131,30 @@ The default 'commit-msg' hook, when enabled, detects duplicate post-commit ~~~~~~~~~~~ -This hook is invoked by 'git-commit'. It takes no +This hook is invoked by 'git commit'. It takes no parameter, and is invoked after a commit is made. This hook is meant primarily for notification, and cannot affect -the outcome of 'git-commit'. +the outcome of 'git commit'. pre-rebase ~~~~~~~~~~ -This hook is called by 'git-rebase' and can be used to prevent a branch +This hook is called by 'git rebase' and can be used to prevent a branch from getting rebased. post-checkout ~~~~~~~~~~~~~ -This hook is invoked when a 'git-checkout' is run after having updated the +This hook is invoked when a 'git checkout' is run after having updated the worktree. The hook is given three parameters: the ref of the previous HEAD, the ref of the new HEAD (which may or may not have changed), and a flag indicating whether the checkout was a branch checkout (changing branches, flag=1) or a file checkout (retrieving a file from the index, flag=0). -This hook cannot affect the outcome of 'git-checkout'. +This hook cannot affect the outcome of 'git checkout'. -It is also run after 'git-clone', unless the --no-checkout (-n) option is +It is also run after 'git clone', unless the --no-checkout (-n) option is used. The first parameter given to the hook is the null-ref, the second the ref of the new HEAD and the flag is always 1. @@ -165,10 +165,10 @@ properties. post-merge ~~~~~~~~~~ -This hook is invoked by 'git-merge', which happens when a 'git-pull' +This hook is invoked by 'git merge', which happens when a 'git pull' is done on a local repository. The hook takes a single parameter, a status flag specifying whether or not the merge being done was a squash merge. -This hook cannot affect the outcome of 'git-merge' and is not executed, +This hook cannot affect the outcome of 'git merge' and is not executed, if the merge failed due to conflicts. This hook can be used in conjunction with a corresponding pre-commit hook to @@ -181,7 +181,7 @@ pre-receive ~~~~~~~~~~~ This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git-push' is done on a local repository. +which happens when a 'git push' is done on a local repository. Just before starting to update refs on the remote repository, the pre-receive hook is invoked. Its exit status determines the success or failure of the update. @@ -202,7 +202,7 @@ updated. If the hook exits with zero, updating of individual refs can still be prevented by the <<update,'update'>> hook. Both standard output and standard error output are forwarded to -'git-send-pack' on the other end, so you can simply `echo` messages +'git send-pack' on the other end, so you can simply `echo` messages for the user. [[update]] @@ -210,7 +210,7 @@ update ~~~~~~ This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git-push' is done on a local repository. +which happens when a 'git push' is done on a local repository. Just before updating the ref on the remote repository, the update hook is invoked. Its exit status determines the success or failure of the ref update. @@ -241,7 +241,7 @@ implement access control which is finer grained than the one based on filesystem group. Both standard output and standard error output are forwarded to -'git-send-pack' on the other end, so you can simply `echo` messages +'git send-pack' on the other end, so you can simply `echo` messages for the user. The default 'update' hook, when enabled--and with @@ -253,7 +253,7 @@ post-receive ~~~~~~~~~~~~ This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git-push' is done on a local repository. +which happens when a 'git push' is done on a local repository. It executes on the remote repository once after all the refs have been updated. @@ -270,7 +270,7 @@ both old and new values of all the refs in addition to their names. Both standard output and standard error output are forwarded to -'git-send-pack' on the other end, so you can simply `echo` messages +'git send-pack' on the other end, so you can simply `echo` messages for the user. The default 'post-receive' hook is empty, but there is @@ -283,7 +283,7 @@ post-update ~~~~~~~~~~~ This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git-push' is done on a local repository. +which happens when a 'git push' is done on a local repository. It executes on the remote repository once after all the refs have been updated. @@ -301,22 +301,56 @@ updated values of the refs. You might consider it instead if you need them. When enabled, the default 'post-update' hook runs -'git-update-server-info' to keep the information used by dumb +'git update-server-info' to keep the information used by dumb transports (e.g., HTTP) up-to-date. If you are publishing a git repository that is accessible via HTTP, you should probably enable this hook. Both standard output and standard error output are forwarded to -'git-send-pack' on the other end, so you can simply `echo` messages +'git send-pack' on the other end, so you can simply `echo` messages for the user. pre-auto-gc ~~~~~~~~~~~ -This hook is invoked by 'git-gc --auto'. It takes no parameter, and -exiting with non-zero status from this script causes the 'git-gc --auto' +This hook is invoked by 'git gc --auto'. It takes no parameter, and +exiting with non-zero status from this script causes the 'git gc --auto' to abort. +post-rewrite +~~~~~~~~~~~~ + +This hook is invoked by commands that rewrite commits (`git commit +--amend`, 'git-rebase'; currently 'git-filter-branch' does 'not' call +it!). Its first argument denotes the command it was invoked by: +currently one of `amend` or `rebase`. Further command-dependent +arguments may be passed in the future. + +The hook receives a list of the rewritten commits on stdin, in the +format + + <old-sha1> SP <new-sha1> [ SP <extra-info> ] LF + +The 'extra-info' is again command-dependent. If it is empty, the +preceding SP is also omitted. Currently, no commands pass any +'extra-info'. + +The hook always runs after the automatic note copying (see +"notes.rewrite.<command>" in linkgit:git-config.txt) has happened, and +thus has access to these notes. + +The following command-specific comments apply: + +rebase:: + For the 'squash' and 'fixup' operation, all commits that were + squashed are listed as being rewritten to the squashed commit. + This means that there will be several lines sharing the same + 'new-sha1'. ++ +The commits are guaranteed to be listed in the order that they were +processed by rebase. + + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 7df3cef46f..2e7328b830 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -14,11 +14,8 @@ DESCRIPTION A `gitignore` file specifies intentionally untracked files that git should ignore. -Note that all the `gitignore` files really concern only files -that are not already tracked by git; -in order to ignore uncommitted changes in already tracked files, -please refer to the 'git update-index --assume-unchanged' -documentation. +Files already tracked by git are not affected; see the NOTES +below for details. Each line in a `gitignore` file specifies a pattern. When deciding whether to ignore a path, git normally checks @@ -56,13 +53,14 @@ the user's editor of choice) generally go into a file specified by `core.excludesfile` in the user's `~/.gitconfig`. The underlying git plumbing tools, such as -'git-ls-files' and 'git-read-tree', read +'git ls-files' and 'git read-tree', read `gitignore` patterns specified by command-line options, or from files specified by command-line options. Higher-level git -tools, such as 'git-status' and 'git-add', +tools, such as 'git status' and 'git add', use patterns from the sources specified above. -Patterns have the following format: +PATTERN FORMAT +-------------- - A blank line matches no files, so it can serve as a separator for readability. @@ -83,18 +81,35 @@ Patterns have the following format: - If the pattern does not contain a slash '/', git treats it as a shell glob pattern and checks for a match against the - pathname without leading directories. + pathname relative to the location of the `.gitignore` file + (relative to the toplevel of the work tree if not from a + `.gitignore` file). - Otherwise, git treats the pattern as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. - For example, "Documentation/\*.html" matches - "Documentation/git.html" but not - "Documentation/ppc/ppc.html". A leading slash matches the - beginning of the pathname; for example, "/*.c" matches - "cat-file.c" but not "mozilla-sha1/sha1.c". + For example, "Documentation/{asterisk}.html" matches + "Documentation/git.html" but not "Documentation/ppc/ppc.html" + or "tools/perf/Documentation/perf.html". -An example: + - A leading slash matches the beginning of the pathname. + For example, "/{asterisk}.c" matches "cat-file.c" but not + "mozilla-sha1/sha1.c". + +NOTES +----- + +The purpose of gitignore files is to ensure that certain files +not tracked by git remain untracked. + +To ignore uncommitted changes in a file that is already tracked, +use 'git update-index {litdd}assume-unchanged'. + +To stop tracking a file that is currently tracked, use +'git rm --cached'. + +EXAMPLES +-------- -------------------------------------------------------------- $ git status @@ -136,10 +151,10 @@ Another example: The second .gitignore prevents git from ignoring `arch/foo/kernel/vmlinux.lds.S`. -Documentation -------------- -Documentation by David Greaves, Junio C Hamano, Josh Triplett, -Frank Lichtenheld, and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-rm[1], linkgit:git-update-index[1], +linkgit:gitrepository-layout[5] GIT --- diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index cf465cb47e..a17a354936 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -7,6 +7,7 @@ gitk - The git repository browser SYNOPSIS -------- +[verse] 'gitk' [<option>...] [<revs>] [--] [<path>...] DESCRIPTION @@ -22,7 +23,7 @@ git repository. OPTIONS ------- To control which revisions to show, the command takes options applicable to -the 'git-rev-list' command (see linkgit:git-rev-list[1]). +the 'git rev-list' command (see linkgit:git-rev-list[1]). This manual page describes only the most frequently used options. @@ -69,7 +70,7 @@ frequently used options. the form "'<from>'..'<to>'" to show all revisions between '<from>' and back to '<to>'. Note, more advanced revision selection can be applied. For a more complete list of ways to spell object names, see - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + linkgit:gitrevisions[7]. <path>...:: @@ -113,15 +114,6 @@ SEE ALSO A minimal repository browser and git tool output highlighter written in C using Ncurses. -Author ------- -Written by Paul Mackerras <paulus@samba.org>. - -Documentation --------------- -Documentation by Junio C Hamano, Jonas Fonseca, and the git-list -<git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 5daf750d19..4040941e55 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -29,6 +29,9 @@ submodule.<name>.path:: submodule.<name>.url:: Defines an url from where the submodule repository can be cloned. + This may be either an absolute URL ready to be passed to + linkgit:git-clone[1] or (if it begins with ./ or ../) a location + relative to the superproject's origin repository. submodule.<name>.update:: Defines what to do when the submodule is updated by the superproject. @@ -41,6 +44,29 @@ submodule.<name>.update:: This config option is overridden if 'git submodule update' is given the '--merge' or '--rebase' options. +submodule.<name>.fetchRecurseSubmodules:: + This option can be used to control recursive fetching of this + submodule. If this option is also present in the submodules entry in + .git/config of the superproject, the setting there will override the + one found in .gitmodules. + Both settings can be overridden on the command line by using the + "--[no-]recurse-submodules" option to "git fetch" and "git pull". + +submodule.<name>.ignore:: + Defines under what circumstances "git status" and the diff family show + a submodule as modified. When set to "all", it will never be considered + modified, "dirty" will ignore all changes to the submodules work tree and + takes only differences between the HEAD of the submodule and the commit + recorded in the superproject into account. "untracked" will additionally + let submodules with modified tracked files in their work tree show up. + Using "none" (the default when this option is not set) also shows + submodules that have untracked files in their work tree as changed. + If this option is also present in the submodules entry in .git/config of + the superproject, the setting there will override the one found in + .gitmodules. + Both settings can be overridden on the command line by using the + "--ignore-submodule" option. + EXAMPLES -------- @@ -64,10 +90,6 @@ SEE ALSO -------- linkgit:git-submodule[1] linkgit:git-config[1] -DOCUMENTATION -------------- -Documentation by Lars Hjemli <hjemli@gmail.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.txt new file mode 100644 index 0000000000..c6713cf5d7 --- /dev/null +++ b/Documentation/gitnamespaces.txt @@ -0,0 +1,82 @@ +gitnamespaces(7) +================ + +NAME +---- +gitnamespaces - Git namespaces + +SYNOPSIS +-------- +[verse] +GIT_NAMESPACE=<namespace> 'git upload-pack' +GIT_NAMESPACE=<namespace> 'git receive-pack' + + +DESCRIPTION +----------- + +Git supports dividing the refs of a single repository into multiple +namespaces, each of which has its own branches, tags, and HEAD. Git can +expose each namespace as an independent repository to pull from and push +to, while sharing the object store, and exposing all the refs to +operations such as linkgit:git-gc[1]. + +Storing multiple repositories as namespaces of a single repository +avoids storing duplicate copies of the same objects, such as when +storing multiple branches of the same source. The alternates mechanism +provides similar support for avoiding duplicates, but alternates do not +prevent duplication between new objects added to the repositories +without ongoing maintenance, while namespaces do. + +To specify a namespace, set the `GIT_NAMESPACE` environment variable to +the namespace. For each ref namespace, git stores the corresponding +refs in a directory under `refs/namespaces/`. For example, +`GIT_NAMESPACE=foo` will store refs under `refs/namespaces/foo/`. You +can also specify namespaces via the `--namespace` option to +linkgit:git[1]. + +Note that namespaces which include a `/` will expand to a hierarchy of +namespaces; for example, `GIT_NAMESPACE=foo/bar` will store refs under +`refs/namespaces/foo/refs/namespaces/bar/`. This makes paths in +`GIT_NAMESPACE` behave hierarchically, so that cloning with +`GIT_NAMESPACE=foo/bar` produces the same result as cloning with +`GIT_NAMESPACE=foo` and cloning from that repo with `GIT_NAMESPACE=bar`. It +also avoids ambiguity with strange namespace paths such as `foo/refs/heads/`, +which could otherwise generate directory/file conflicts within the `refs` +directory. + +linkgit:git-upload-pack[1] and linkgit:git-receive-pack[1] rewrite the +names of refs as specified by `GIT_NAMESPACE`. git-upload-pack and +git-receive-pack will ignore all references outside the specified +namespace. + +The smart HTTP server, linkgit:git-http-backend[1], will pass +GIT_NAMESPACE through to the backend programs; see +linkgit:git-http-backend[1] for sample configuration to expose +repository namespaces as repositories. + +For a simple local test, you can use linkgit:git-remote-ext[1]: + +---------- +git clone ext::'git --namespace=foo %s /tmp/prefixed.git' +---------- + +SECURITY +-------- + +Anyone with access to any namespace within a repository can potentially +access objects from any other namespace stored in the same repository. +You can't directly say "give me object ABCD" if you don't have a ref to +it, but you can do some other sneaky things like: + +. Claiming to push ABCD, at which point the server will optimize out the + need for you to actually send it. Now you have a ref to ABCD and can + fetch it (claiming not to have it, of course). + +. Requesting other refs, claiming that you have ABCD, at which point the + server may generate deltas against ABCD. + +None of this causes a problem if you only host public repositories, or +if everyone who may read one namespace may also read everything in every +other namespace (for instance, if everyone in an organization has read +permission to every repository). diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 1befca98d4..5c891f1169 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -16,39 +16,32 @@ You may find these things in your git repository (`.git` directory for a repository associated with your working tree, or `<project>.git` directory for a public 'bare' repository. It is also possible to have a working tree where `.git` is a plain -ascii file containing `gitdir: <path>`, i.e. the path to the +ASCII file containing `gitdir: <path>`, i.e. the path to the real git repository). objects:: Object store associated with this repository. Usually an object store is self sufficient (i.e. all the objects that are referred to by an object found in it are also - found in it), but there are couple of ways to violate - it. + found in it), but there are a few ways to violate it. + -. You could populate the repository by running a commit walker -without `-a` option. Depending on which options are given, you -could have only commit objects without associated blobs and -trees this way, for example. A repository with this kind of -incomplete object store is not suitable to be published to the -outside world but sometimes useful for private repository. -. You also could have an incomplete but locally usable repository -by cloning shallowly. See linkgit:git-clone[1]. -. You can be using `objects/info/alternates` mechanism, or -`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow' +. You could have an incomplete but locally usable repository +by creating a shallow clone. See linkgit:git-clone[1]. +. You could be using the `objects/info/alternates` or +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow' objects from other object stores. A repository with this kind of incomplete object store is not suitable to be published for use with dumb transports but otherwise is OK as long as -`objects/info/alternates` points at the right object stores -it borrows from. +`objects/info/alternates` points at the object stores it +borrows from. objects/[0-9a-f][0-9a-f]:: - Traditionally, each object is stored in its own file. - They are split into 256 subdirectories using the first - two letters from its object name to keep the number of - directory entries `objects` directory itself needs to - hold. Objects found here are often called 'unpacked' - (or 'loose') objects. + A newly created object is stored in its own file. + The objects are splayed over 256 subdirectories using + the first two characters of the sha1 object name to + keep the number of directory entries in `objects` + itself to a manageable number. Objects found + here are often called 'unpacked' (or 'loose') objects. objects/pack:: Packs (files that store many object in compressed form, @@ -64,7 +57,7 @@ objects/info/packs:: are available in this object store. Whenever a pack is added or removed, `git update-server-info` should be run to keep this file up-to-date if the repository is - published for dumb transports. 'git-repack' does this + published for dumb transports. 'git repack' does this by default. objects/info/alternates:: @@ -85,7 +78,7 @@ objects/info/http-alternates:: refs:: References are stored in subdirectories of this - directory. The 'git-prune' command knows to keep + directory. The 'git prune' command knows to preserve objects reachable from refs found in this directory and its subdirectories. @@ -119,21 +112,22 @@ HEAD:: + HEAD can also record a specific commit directly, instead of being a symref to point at the current branch. Such a state -is often called 'detached HEAD', and almost all commands work -identically as normal. See linkgit:git-checkout[1] for -details. +is often called 'detached HEAD.' See linkgit:git-checkout[1] +for details. branches:: A slightly deprecated way to store shorthands to be used - to specify URL to 'git-fetch', 'git-pull' and 'git-push' - commands is to store a file in `branches/<name>` and - give 'name' to these commands in place of 'repository' - argument. + to specify a URL to 'git fetch', 'git pull' and 'git push'. + A file can be stored as `branches/<name>` and then + 'name' can be given to these commands in place of + 'repository' argument. See the REMOTES section in + linkgit:git-fetch[1] for details. This mechanism is legacy + and not likely to be found in modern repositories. hooks:: Hooks are customization scripts used by various git commands. A handful of sample hooks are installed when - 'git-init' is run, but all of them are disabled by + 'git init' is run, but all of them are disabled by default. To enable, the `.sample` suffix has to be removed from the filename by renaming. Read linkgit:githooks[5] for more details about @@ -151,10 +145,10 @@ info/refs:: This file helps dumb transports discover what refs are available in this repository. If the repository is published for dumb transports, this file should be - regenerated by 'git-update-server-info' every time a tag + regenerated by 'git update-server-info' every time a tag or branch is created or modified. This is normally done from the `hooks/update` hook, which is run by the - 'git-receive-pack' command when you 'git-push' into the + 'git-receive-pack' command when you 'git push' into the repository. info/grafts:: @@ -168,14 +162,16 @@ info/grafts:: info/exclude:: This file, by convention among Porcelains, stores the exclude pattern list. `.gitignore` is the per-directory - ignore file. 'git-status', 'git-add', 'git-rm' and - 'git-clean' look at it but the core git commands do not look + ignore file. 'git status', 'git add', 'git rm' and + 'git clean' look at it but the core git commands do not look at it. See also: linkgit:gitignore[5]. remotes:: - Stores shorthands to be used to give URL and default - refnames to interact with remote repository to - 'git-fetch', 'git-pull' and 'git-push' commands. + Stores shorthands for URL and default refnames for use + when interacting with remote repositories via 'git fetch', + 'git pull' and 'git push' commands. See the REMOTES section + in linkgit:git-fetch[1] for details. This mechanism is legacy + and not likely to be found in modern repositories. logs:: Records of changes made to refs are stored in this diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt new file mode 100644 index 0000000000..fc4789f98e --- /dev/null +++ b/Documentation/gitrevisions.txt @@ -0,0 +1,35 @@ +gitrevisions(7) +================ + +NAME +---- +gitrevisions - specifying revisions and ranges for git + +SYNOPSIS +-------- +gitrevisions + + +DESCRIPTION +----------- + +Many Git commands take revision parameters as arguments. Depending on +the command, they denote a specific commit or, for commands which +walk the revision graph (such as linkgit:git-log[1]), all commits which can +be reached from that commit. In the latter case one can also specify a +range of revisions explicitly. + +In addition, some Git commands (such as linkgit:git-show[1]) also take +revision parameters which denote other objects than commits, e.g. blobs +("files") or trees ("directories of files"). + +include::revisions.txt[] + + +SEE ALSO +-------- +linkgit:git-rev-parse[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index dc8fc3a18a..f1e4422acc 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -7,6 +7,7 @@ gittutorial-2 - A tutorial introduction to git: part two SYNOPSIS -------- +[verse] git * DESCRIPTION @@ -260,7 +261,7 @@ index a042389..513feba 100644 +hello world, again ------------------------------------------------ -So 'git-diff' is comparing against something other than the head. +So 'git diff' is comparing against something other than the head. The thing that it's comparing against is actually the index file, which is stored in .git/index in a binary format, but whose contents we can examine with ls-files: @@ -275,9 +276,9 @@ hello world! hello world, again ------------------------------------------------ -So what our 'git-add' did was store a new blob and then put +So what our 'git add' did was store a new blob and then put a reference to it in the index file. If we modify the file again, -we'll see that the new modifications are reflected in the 'git-diff' +we'll see that the new modifications are reflected in the 'git diff' output: ------------------------------------------------ @@ -292,7 +293,7 @@ index 513feba..ba3da7b 100644 +again? ------------------------------------------------ -With the right arguments, 'git-diff' can also show us the difference +With the right arguments, 'git diff' can also show us the difference between the working directory and the last commit, or between the index and the last commit: @@ -316,7 +317,7 @@ index a042389..513feba 100644 +hello world, again ------------------------------------------------ -At any time, we can create a new commit using 'git-commit' (without +At any time, we can create a new commit using 'git commit' (without the "-a" option), and verify that the state committed only includes the changes stored in the index file, not the additional change that is still only in our working tree: @@ -334,11 +335,11 @@ index 513feba..ba3da7b 100644 +again? ------------------------------------------------ -So by default 'git-commit' uses the index to create the commit, not +So by default 'git commit' uses the index to create the commit, not the working tree; the "-a" option to commit tells it to first update the index with all changes in the working tree. -Finally, it's worth looking at the effect of 'git-add' on the index +Finally, it's worth looking at the effect of 'git add' on the index file: ------------------------------------------------ @@ -346,7 +347,7 @@ $ echo "goodbye, world" >closing.txt $ git add closing.txt ------------------------------------------------ -The effect of the 'git-add' was to add one entry to the index file: +The effect of the 'git add' was to add one entry to the index file: ------------------------------------------------ $ git ls-files --stage @@ -373,7 +374,7 @@ $ git status # # new file: closing.txt # -# Changed but not updated: +# Changes not staged for commit: # (use "git add <file>..." to update what will be committed) # # modified: file.txt diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index cf0689cfeb..dee050567e 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -7,6 +7,7 @@ gittutorial - A tutorial introduction to git (for version 1.5.1 or newer) SYNOPSIS -------- +[verse] git * DESCRIPTION @@ -67,7 +68,7 @@ You've now initialized the working directory--you may notice a new directory created, named ".git". Next, tell git to take a snapshot of the contents of all files under the -current directory (note the '.'), with 'git-add': +current directory (note the '.'), with 'git add': ------------------------------------------------ $ git add . @@ -75,7 +76,7 @@ $ git add . This snapshot is now stored in a temporary staging area which git calls the "index". You can permanently store the contents of the index in the -repository with 'git-commit': +repository with 'git commit': ------------------------------------------------ $ git commit @@ -94,15 +95,15 @@ $ git add file1 file2 file3 ------------------------------------------------ You are now ready to commit. You can see what is about to be committed -using 'git-diff' with the --cached option: +using 'git diff' with the --cached option: ------------------------------------------------ $ git diff --cached ------------------------------------------------ -(Without --cached, 'git-diff' will show you any changes that +(Without --cached, 'git diff' will show you any changes that you've made but not yet added to the index.) You can also get a brief -summary of the situation with 'git-status': +summary of the situation with 'git status': ------------------------------------------------ $ git status @@ -126,7 +127,7 @@ $ git commit This will again prompt you for a message describing the change, and then record a new version of the project. -Alternatively, instead of running 'git-add' beforehand, you can use +Alternatively, instead of running 'git add' beforehand, you can use ------------------------------------------------ $ git commit -a @@ -147,7 +148,7 @@ Git tracks content not files Many revision control systems provide an `add` command that tells the system to start tracking changes to a new file. Git's `add` command -does something simpler and more powerful: 'git-add' is used both for new +does something simpler and more powerful: 'git add' is used both for new and newly modified files, and in both cases it takes a snapshot of the given files and stages that content in the index, ready for inclusion in the next commit. @@ -376,7 +377,7 @@ alice$ git remote add bob /home/bob/myrepo ------------------------------------------------ With this, Alice can perform the first part of the "pull" operation -alone using the 'git-fetch' command without merging them with her own +alone using the 'git fetch' command without merging them with her own branch, using: ------------------------------------- @@ -384,8 +385,8 @@ alice$ git fetch bob ------------------------------------- Unlike the longhand form, when Alice fetches from Bob using a -remote repository shorthand set up with 'git-remote', what was -fetched is stored in a remote tracking branch, in this case +remote repository shorthand set up with 'git remote', what was +fetched is stored in a remote-tracking branch, in this case `bob/master`. So after this: ------------------------------------- @@ -402,8 +403,8 @@ could merge the changes into her master branch: alice$ git merge bob/master ------------------------------------- -This `merge` can also be done by 'pulling from her own remote -tracking branch', like this: +This `merge` can also be done by 'pulling from her own remote-tracking +branch', like this: ------------------------------------- alice$ git pull . remotes/bob/master @@ -428,7 +429,7 @@ bob$ git config --get remote.origin.url /home/alice/project ------------------------------------- -(The complete configuration created by 'git-clone' is visible using +(The complete configuration created by 'git clone' is visible using `git config -l`, and the linkgit:git-config[1] man page explains the meaning of each option.) @@ -458,7 +459,7 @@ Exploring history ----------------- Git history is represented as a series of interrelated commits. We -have already seen that the 'git-log' command can list those commits. +have already seen that the 'git log' command can list those commits. Note that first line of each git log entry also gives a name for the commit: @@ -471,7 +472,7 @@ Date: Tue May 16 17:18:22 2006 -0700 merge-base: Clarify the comments on post processing. ------------------------------------- -We can give this name to 'git-show' to see the details about this +We can give this name to 'git show' to see the details about this commit. ------------------------------------- @@ -529,13 +530,13 @@ $ git reset --hard HEAD^ # reset your current branch and working Be careful with that last command: in addition to losing any changes in the working directory, it will also remove all later commits from this branch. If this branch is the only branch containing those -commits, they will be lost. Also, don't use 'git-reset' on a +commits, they will be lost. Also, don't use 'git reset' on a publicly-visible branch that other developers pull from, as it will force needless merges on other developers to clean up the history. -If you need to undo changes that you have pushed, use 'git-revert' +If you need to undo changes that you have pushed, use 'git revert' instead. -The 'git-grep' command can search for strings in any version of your +The 'git grep' command can search for strings in any version of your project, so ------------------------------------- @@ -544,7 +545,7 @@ $ git grep "hello" v2.5 searches for all occurrences of "hello" in v2.5. -If you leave out the commit name, 'git-grep' will search any of the +If you leave out the commit name, 'git grep' will search any of the files it manages in your current directory. So ------------------------------------- @@ -554,7 +555,7 @@ $ git grep "hello" is a quick way to search just the files that are tracked by git. Many git commands also take sets of commits, which can be specified -in a number of ways. Here are some examples with 'git-log': +in a number of ways. Here are some examples with 'git log': ------------------------------------- $ git log v2.5..v2.6 # commits between v2.5 and v2.6 @@ -564,7 +565,7 @@ $ git log v2.5.. Makefile # commits since v2.5 which modify # Makefile ------------------------------------- -You can also give 'git-log' a "range" of commits where the first is not +You can also give 'git log' a "range" of commits where the first is not necessarily an ancestor of the second; for example, if the tips of the branches "stable" and "master" diverged from a common commit some time ago, then @@ -583,9 +584,9 @@ $ git log master..stable will show the list of commits made on the stable branch but not the master branch. -The 'git-log' command has a weakness: it must present commits in a +The 'git log' command has a weakness: it must present commits in a list. When the history has lines of development that diverged and -then merged back together, the order in which 'git-log' presents +then merged back together, the order in which 'git log' presents those commits is meaningless. Most projects with multiple contributors (such as the Linux kernel, @@ -609,7 +610,7 @@ of the file: $ git diff v2.5:Makefile HEAD:Makefile.in ------------------------------------- -You can also use 'git-show' to see any such file: +You can also use 'git show' to see any such file: ------------------------------------- $ git show v2.5:Makefile diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt new file mode 100644 index 0000000000..7aba497b74 --- /dev/null +++ b/Documentation/gitweb.conf.txt @@ -0,0 +1,889 @@ +gitweb.conf(5) +============== + +NAME +---- +gitweb.conf - Gitweb (git web interface) configuration file + +SYNOPSIS +-------- +/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl + +DESCRIPTION +----------- + +The gitweb CGI script for viewing Git repositories over the web uses a +perl script fragment as its configuration file. You can set variables +using "`our $variable = value`"; text from a "#" character until the +end of a line is ignored. See *perlsyn*(1) for details. + +An example: + + # gitweb configuration file for http://git.example.org + # + our $projectroot = "/srv/git"; # FHS recommendation + our $site_name = 'Example.org >> Repos'; + + +The configuration file is used to override the default settings that +were built into gitweb at the time the 'gitweb.cgi' script was generated. + +While one could just alter the configuration settings in the gitweb +CGI itself, those changes would be lost upon upgrade. Configuration +settings might also be placed into a file in the same directory as the +CGI script with the default name 'gitweb_config.perl' -- allowing +one to have multiple gitweb instances with different configurations by +the use of symlinks. + +Note that some configuration can be controlled on per-repository rather than +gitweb-wide basis: see "Per-repository gitweb configuration" subsection on +linkgit:gitweb[1] manpage. + + +DISCUSSION +---------- +Gitweb reads configuration data from the following sources in the +following order: + + * built-in values (some set during build stage), + + * common system-wide configuration file (defaults to + '/etc/gitweb-common.conf'), + + * either per-instance configuration file (defaults to 'gitweb_config.perl' + in the same directory as the installed gitweb), or if it does not exists + then fallback system-wide configuration file (defaults to '/etc/gitweb.conf'). + +Values obtained in later configuration files override values obtained earlier +in the above sequence. + +Locations of the common system-wide configuration file, the fallback +system-wide configuration file and the per-instance configuration file +are defined at compile time using build-time Makefile configuration +variables, respectively `GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` +and `GITWEB_CONFIG`. + +You can also override locations of gitweb configuration files during +runtime by setting the following environment variables: +`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG` +to a non-empty value. + + +The syntax of the configuration files is that of Perl, since these files are +handled by sourcing them as fragments of Perl code (the language that +gitweb itself is written in). Variables are typically set using the +`our` qualifier (as in "`our $variable = <value>;`") to avoid syntax +errors if a new version of gitweb no longer uses a variable and therefore +stops declaring it. + +You can include other configuration file using read_config_file() +subroutine. For example, one might want to put gitweb configuration +related to access control for viewing repositories via Gitolite (one +of git repository management tools) in a separate file, e.g. in +'/etc/gitweb-gitolite.conf'. To include it, put + +-------------------------------------------------- +read_config_file("/etc/gitweb-gitolite.conf"); +-------------------------------------------------- + +somewhere in gitweb configuration file used, e.g. in per-installation +gitweb configuration file. Note that read_config_file() checks itself +that the file it reads exists, and does nothing if it is not found. +It also handles errors in included file. + + +The default configuration with no configuration file at all may work +perfectly well for some installations. Still, a configuration file is +useful for customizing or tweaking the behavior of gitweb in many ways, and +some optional features will not be present unless explicitly enabled using +the configurable `%features` variable (see also "Configuring gitweb +features" section below). + + +CONFIGURATION VARIABLES +----------------------- +Some configuration variables have their default values (embedded in the CGI +script) set during building gitweb -- if that is the case, this fact is put +in their description. See gitweb's 'INSTALL' file for instructions on building +and installing gitweb. + + +Location of repositories +~~~~~~~~~~~~~~~~~~~~~~~~ +The configuration variables described below control how gitweb finds +git repositories, and how repositories are displayed and accessed. + +See also "Repositories" and later subsections in linkgit:gitweb[1] manpage. + +$projectroot:: + Absolute filesystem path which will be prepended to project path; + the path to repository is `$projectroot/$project`. Set to + `$GITWEB_PROJECTROOT` during installation. This variable has to be + set correctly for gitweb to find repositories. ++ +For example, if `$projectroot` is set to "/srv/git" by putting the following +in gitweb config file: ++ +---------------------------------------------------------------------------- +our $projectroot = "/srv/git"; +---------------------------------------------------------------------------- ++ +then ++ +------------------------------------------------ +http://git.example.com/gitweb.cgi?p=foo/bar.git +------------------------------------------------ ++ +and its path_info based equivalent ++ +------------------------------------------------ +http://git.example.com/gitweb.cgi/foo/bar.git +------------------------------------------------ ++ +will map to the path '/srv/git/foo/bar.git' on the filesystem. + +$projects_list:: + Name of a plain text file listing projects, or a name of directory + to be scanned for projects. ++ +Project list files should list one project per line, with each line +having the following format ++ +----------------------------------------------------------------------------- +<URI-encoded filesystem path to repository> SP <URI-encoded repository owner> +----------------------------------------------------------------------------- ++ +The default value of this variable is determined by the `GITWEB_LIST` +makefile variable at installation time. If this variable is empty, gitweb +will fall back to scanning the `$projectroot` directory for repositories. + +$project_maxdepth:: + If `$projects_list` variable is unset, gitweb will recursively + scan filesystem for git repositories. The `$project_maxdepth` + is used to limit traversing depth, relative to `$projectroot` + (starting point); it means that directories which are further + from `$projectroot` than `$project_maxdepth` will be skipped. ++ +It is purely performance optimization, originally intended for MacOS X, +where recursive directory traversal is slow. Gitweb follows symbolic +links, but it detects cycles, ignoring any duplicate files and directories. ++ +The default value of this variable is determined by the build-time +configuration variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to +2007. + +$export_ok:: + Show repository only if this file exists (in repository). Only + effective if this variable evaluates to true. Can be set when + building gitweb by setting `GITWEB_EXPORT_OK`. This path is + relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok', + unless started with `--export-all`. By default this variable is + not set, which means that this feature is turned off. + +$export_auth_hook:: + Function used to determine which repositories should be shown. + This subroutine should take one parameter, the full path to + a project, and if it returns true, that project will be included + in the projects list and can be accessed through gitweb as long + as it fulfills the other requirements described by $export_ok, + $projects_list, and $projects_maxdepth. Example: ++ +---------------------------------------------------------------------------- +our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; }; +---------------------------------------------------------------------------- ++ +though the above might be done by using `$export_ok` instead ++ +---------------------------------------------------------------------------- +our $export_ok = "git-daemon-export-ok"; +---------------------------------------------------------------------------- ++ +If not set (default), it means that this feature is disabled. ++ +See also more involved example in "Controlling access to git repositories" +subsection on linkgit:gitweb[1] manpage. + +$strict_export:: + Only allow viewing of repositories also shown on the overview page. + This for example makes `$gitweb_export_ok` file decide if repository is + available and not only if it is shown. If `$gitweb_list` points to + file with list of project, only those repositories listed would be + available for gitweb. Can be set during building gitweb via + `GITWEB_STRICT_EXPORT`. By default this variable is not set, which + means that you can directly access those repositories that are hidden + from projects list page (e.g. the are not listed in the $projects_list + file). + + +Finding files +~~~~~~~~~~~~~ +The following configuration variables tell gitweb where to find files. +The values of these variables are paths on the filesystem. + +$GIT:: + Core git executable to use. By default set to `$GIT_BINDIR/git`, which + in turn is by default set to `$(bindir)/git`. If you use git installed + from a binary package, you should usually set this to "/usr/bin/git". + This can just be "git" if your web server has a sensible PATH; from + security point of view it is better to use absolute path to git binary. + If you have multiple git versions installed it can be used to choose + which one to use. Must be (correctly) set for gitweb to be able to + work. + +$mimetypes_file:: + File to use for (filename extension based) guessing of MIME types before + trying '/etc/mime.types'. *NOTE* that this path, if relative, is taken + as relative to the current git repository, not to CGI script. If unset, + only '/etc/mime.types' is used (if present on filesystem). If no mimetypes + file is found, mimetype guessing based on extension of file is disabled. + Unset by default. + +$highlight_bin:: + Path to the highlight executable to use (it must be the one from + http://www.andre-simon.de[] due to assumptions about parameters and output). + By default set to 'highlight'; set it to full path to highlight + executable if it is not installed on your web server's PATH. + Note that 'highlight' feature must be set for gitweb to actually + use syntax hightlighting. ++ +*NOTE*: if you want to add support for new file type (supported by +"highlight" but not used by gitweb), you need to modify `%highlight_ext` +or `%highlight_basename`, depending on whether you detect type of file +based on extension (for example "sh") or on its basename (for example +"Makefile"). The keys of these hashes are extension and basename, +respectively, and value for given key is name of syntax to be passed via +`--syntax <syntax>` to highlighter. ++ +For example if repositories you are hosting use "phtml" extension for +PHP files, and you want to have correct syntax-highlighting for those +files, you can add the following to gitweb configuration: ++ +--------------------------------------------------------- +our %highlight_ext; +$highlight_ext{'phtml'} = 'php'; +--------------------------------------------------------- + + +Links and their targets +~~~~~~~~~~~~~~~~~~~~~~~ +The configuration variables described below configure some of gitweb links: +their target and their look (text or image), and where to find page +prerequisites (stylesheet, favicon, images, scripts). Usually they are left +at their default values, with the possible exception of `@stylesheets` +variable. + +@stylesheets:: + List of URIs of stylesheets (relative to the base URI of a page). You + might specify more than one stylesheet, for example to use "gitweb.css" + as base with site specific modifications in a separate stylesheet + to make it easier to upgrade gitweb. For example, you can add + a `site` stylesheet by putting ++ +---------------------------------------------------------------------------- +push @stylesheets, "gitweb-site.css"; +---------------------------------------------------------------------------- ++ +in the gitweb config file. Those values that are relative paths are +relative to base URI of gitweb. ++ +This list should contain the URI of gitweb's standard stylesheet. The default +URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS` +makefile variable. Its default value is 'static/gitweb.css' +(or 'static/gitweb.min.css' if the `CSSMIN` variable is defined, +i.e. if CSS minifier is used during build). ++ +*Note*: there is also a legacy `$stylesheet` configuration variable, which was +used by older gitweb. If `$stylesheet` variable is defined, only CSS stylesheet +given by this variable is used by gitweb. + +$logo:: + Points to the location where you put 'git-logo.png' on your web + server, or to be more the generic URI of logo, 72x27 size). This image + is displayed in the top right corner of each gitweb page and used as + a logo for the Atom feed. Relative to the base URI of gitweb (as a path). + Can be adjusted when building gitweb using `GITWEB_LOGO` variable + By default set to 'static/git-logo.png'. + +$favicon:: + Points to the location where you put 'git-favicon.png' on your web + server, or to be more the generic URI of favicon, which will be served + as "image/png" type. Web browsers that support favicons (website icons) + may display them in the browser's URL bar and next to the site name in + bookmarks. Relative to the base URI of gitweb. Can be adjusted at + build time using `GITWEB_FAVICON` variable. + By default set to 'static/git-favicon.png'. + +$javascript:: + Points to the location where you put 'gitweb.js' on your web server, + or to be more generic the URI of JavaScript code used by gitweb. + Relative to the base URI of gitweb. Can be set at build time using + the `GITWEB_JS` build-time configuration variable. ++ +The default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if +the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used +at build time. *Note* that this single file is generated from multiple +individual JavaScript "modules". + +$home_link:: + Target of the home link on the top of all pages (the first part of view + "breadcrumbs"). By default it is set to the absolute URI of a current page + (to the value of `$my_uri` variable, or to "/" if `$my_uri` is undefined + or is an empty string). + +$home_link_str:: + Label for the "home link" at the top of all pages, leading to `$home_link` + (usually the main gitweb page, which contains the projects list). It is + used as the first component of gitweb's "breadcrumb trail": + `<home link> / <project> / <action>`. Can be set at build time using + the `GITWEB_HOME_LINK_STR` variable. By default it is set to "projects", + as this link leads to the list of projects. Other popular choice it to + set it to the name of site. + +$logo_url:: +$logo_label:: + URI and label (title) for the Git logo link (or your site logo, + if you chose to use different logo image). By default, these both + refer to git homepage, http://git-scm.com[]; in the past, they pointed + to git documentation at http://www.kernel.org[]. + + +Changing gitweb's look +~~~~~~~~~~~~~~~~~~~~~~ +You can adjust how pages generated by gitweb look using the variables described +below. You can change the site name, add common headers and footers for all +pages, and add a description of this gitweb installation on its main page +(which is the projects list page), etc. + +$site_name:: + Name of your site or organization, to appear in page titles. Set it + to something descriptive for clearer bookmarks etc. If this variable + is not set or is, then gitweb uses the value of the `SERVER_NAME` + CGI environment variable, setting site name to "$SERVER_NAME Git", + or "Untitled Git" if this variable is not set (e.g. if running gitweb + as standalone script). ++ +Can be set using the `GITWEB_SITENAME` at build time. Unset by default. + +$site_html_head_string:: + HTML snippet to be included in the <head> section of each page. + Can be set using `GITWEB_SITE_HTML_HEAD_STRING` at build time. + No default value. + +$site_header:: + Name of a file with HTML to be included at the top of each page. + Relative to the directory containing the 'gitweb.cgi' script. + Can be set using `GITWEB_SITE_HEADER` at build time. No default + value. + +$site_footer:: + Name of a file with HTML to be included at the bottom of each page. + Relative to the directory containing the 'gitweb.cgi' script. + Can be set using `GITWEB_SITE_FOOTER` at build time. No default + value. + +$home_text:: + Name of a HTML file which, if it exists, is included on the + gitweb projects overview page ("projects_list" view). Relative to + the directory containing the gitweb.cgi script. Default value + can be adjusted during build time using `GITWEB_HOMETEXT` variable. + By default set to 'indextext.html'. + +$projects_list_description_width:: + The width (in characters) of the "Description" column of the projects list. + Longer descriptions will be truncated (trying to cut at word boundary); + the full description is available in the 'title' attribute (usually shown on + mouseover). The default is 25, which might be too small if you + use long project descriptions. + +$default_projects_order:: + Default value of ordering of projects on projects list page, which + means the ordering used if you don't explicitly sort projects list + (if there is no "o" CGI query parameter in the URL). Valid values + are "none" (unsorted), "project" (projects are by project name, + i.e. path to repository relative to `$projectroot`), "descr" + (project description), "owner", and "age" (by date of most current + commit). ++ +Default value is "project". Unknown value means unsorted. + + +Changing gitweb's behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~ +These configuration variables control _internal_ gitweb behavior. + +$default_blob_plain_mimetype:: + Default mimetype for the blob_plain (raw) view, if mimetype checking + doesn't result in some other type; by default "text/plain". + Gitweb guesses mimetype of a file to display based on extension + of its filename, using `$mimetypes_file` (if set and file exists) + and '/etc/mime.types' files (see *mime.types*(5) manpage; only + filename extension rules are supported by gitweb). + +$default_text_plain_charset:: + Default charset for text files. If this is not set, the web server + configuration will be used. Unset by default. + +$fallback_encoding:: + Gitweb assumes this charset when a line contains non-UTF-8 characters. + The fallback decoding is used without error checking, so it can be even + "utf-8". The value must be a valid encoding; see the *Encoding::Supported*(3pm) + man page for a list. The default is "latin1", aka. "iso-8859-1". + +@diff_opts:: + Rename detection options for git-diff and git-diff-tree. The default is + (\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies, + or set it to () i.e. empty list if you don't want to have renames + detection. ++ +*Note* that rename and especially copy detection can be quite +CPU-intensive. Note also that non git tools can have problems with +patches generated with options mentioned above, especially when they +involve file copies (\'-C') or criss-cross renames (\'-B'). + + +Some optional features and policies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Most of features are configured via `%feature` hash; however some of extra +gitweb features can be turned on and configured using variables described +below. This list beside configuration variables that control how gitweb +looks does contain variables configuring administrative side of gitweb +(e.g. cross-site scripting prevention; admittedly this as side effect +affects how "summary" pages look like, or load limiting). + +@git_base_url_list:: + List of git base URLs. These URLs are used to generate URLs + describing from where to fetch a project, which are shown on + project summary page. The full fetch URL is "`$git_base_url/$project`", + for each element of this list. You can set up multiple base URLs + (for example one for `git://` protocol, and one for `http://` + protocol). ++ +Note that per repository configuration can be set in '$GIT_DIR/cloneurl' +file, or as values of multi-value `gitweb.url` configuration variable in +project config. Per-repository configuration takes precedence over value +composed from `@git_base_url_list` elements and project name. ++ +You can setup one single value (single entry/item in this list) at build +time by setting the `GITWEB_BASE_URL` built-time configuration variable. +By default it is set to (), i.e. an empty list. This means that gitweb +would not try to create project URL (to fetch) from project name. + +$projects_list_group_categories:: + Whether to enables the grouping of projects by category on the project + list page. The category of a project is determined by the + `$GIT_DIR/category` file or the `gitweb.category` variable in each + repository's configuration. Disabled by default (set to 0). + +$project_list_default_category:: + Default category for projects for which none is specified. If this is + set to the empty string, such projects will remain uncategorized and + listed at the top, above categorized projects. Used only if project + categories are enabled, which means if `$projects_list_group_categories` + is true. By default set to "" (empty string). + +$prevent_xss:: + If true, some gitweb features are disabled to prevent content in + repositories from launching cross-site scripting (XSS) attacks. Set this + to true if you don't trust the content of your repositories. + False by default (set to 0). + +$maxload:: + Used to set the maximum load that we will still respond to gitweb queries. + If the server load exceeds this value then gitweb will return + "503 Service Unavailable" error. The server load is taken to be 0 + if gitweb cannot determine its value. Currently it works only on Linux, + where it uses '/proc/loadavg'; the load there is the number of active + tasks on the system -- processes that are actually running -- averaged + over the last minute. ++ +Set `$maxload` to undefined value (`undef`) to turn this feature off. +The default value is 300. + +$per_request_config:: + If this is set to code reference, it will be run once for each request. + You can set parts of configuration that change per session this way. + For example, one might use the following code in a gitweb configuration + file ++ +-------------------------------------------------------------------------------- +our $per_request_config = sub { + $ENV{GL_USER} = $cgi->remote_user || "gitweb"; +}; +-------------------------------------------------------------------------------- ++ +If `$per_request_config` is not a code reference, it is interpreted as boolean +value. If it is true gitweb will process config files once per request, +and if it is false gitweb will process config files only once, each time it +is executed. True by default (set to 1). ++ +*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default +values before every request, so if you want to change them, be sure to set +this variable to true or a code reference effecting the desired changes. ++ +This variable matters only when using persistent web environments that +serve multiple requests using single gitweb instance, like mod_perl, +FastCGI or Plackup. + + +Other variables +~~~~~~~~~~~~~~~ +Usually you should not need to change (adjust) any of configuration +variables described below; they should be automatically set by gitweb to +correct value. + + +$version:: + Gitweb version, set automatically when creating gitweb.cgi from + gitweb.perl. You might want to modify it if you are running modified + gitweb, for example ++ +--------------------------------------------------- +our $version .= " with caching"; +--------------------------------------------------- ++ +if you run modified version of gitweb with caching support. This variable +is purely informational, used e.g. in the "generator" meta header in HTML +header. + +$my_url:: +$my_uri:: + Full URL and absolute URL of the gitweb script; + in earlier versions of gitweb you might have need to set those + variables, but now there should be no need to do it. See + `$per_request_config` if you need to set them still. + +$base_url:: + Base URL for relative URLs in pages generated by gitweb, + (e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs), + needed and used '<base href="$base_url">' only for URLs with nonempty + PATH_INFO. Usually gitweb sets its value correctly, + and there is no need to set this variable, e.g. to $my_uri or "/". + See `$per_request_config` if you need to override it anyway. + + +CONFIGURING GITWEB FEATURES +--------------------------- +Many gitweb features can be enabled (or disabled) and configured using the +`%feature` hash. Names of gitweb features are keys of this hash. + +Each `%feature` hash element is a hash reference and has the following +structure: +---------------------------------------------------------------------- +"<feature_name>" => { + "sub" => <feature-sub (subroutine)>, + "override" => <allow-override (boolean)>, + "default" => [ <options>... ] +}, +---------------------------------------------------------------------- +Some features cannot be overridden per project. For those +features the structure of appropriate `%feature` hash element has a simpler +form: +---------------------------------------------------------------------- +"<feature_name>" => { + "override" => 0, + "default" => [ <options>... ] +}, +---------------------------------------------------------------------- +As one can see it lacks the \'sub' element. + +The meaning of each part of feature configuration is described +below: + +default:: + List (array reference) of feature parameters (if there are any), + used also to toggle (enable or disable) given feature. ++ +Note that it is currently *always* an array reference, even if +feature doesn't accept any configuration parameters, and \'default' +is used only to turn it on or off. In such case you turn feature on +by setting this element to `[1]`, and torn it off by setting it to +`[0]`. See also the passage about the "blame" feature in the "Examples" +section. ++ +To disable features that accept parameters (are configurable), you +need to set this element to empty list i.e. `[]`. + +override:: + If this field has a true value then the given feature is + overriddable, which means that it can be configured + (or enabled/disabled) on a per-repository basis. ++ +Usually given "<feature>" is configurable via the `gitweb.<feature>` +config variable in the per-repository git configuration file. ++ +*Note* that no feature is overriddable by default. + +sub:: + Internal detail of implementation. What is important is that + if this field is not present then per-repository override for + given feature is not supported. ++ +You wouldn't need to ever change it in gitweb config file. + + +Features in `%feature` +~~~~~~~~~~~~~~~~~~~~~~ +The gitweb features that are configurable via `%feature` hash are listed +below. This should be a complete list, but ultimately the authoritative +and complete list is in gitweb.cgi source code, with features described +in the comments. + +blame:: + Enable the "blame" and "blame_incremental" blob views, showing for + each line the last commit that modified it; see linkgit:git-blame[1]. + This can be very CPU-intensive and is therefore disabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.blame` configuration variable (boolean). + +snapshot:: + Enable and configure the "snapshot" action, which allows user to + download a compressed archive of any tree or commit, as produced + by linkgit:git-archive[1] and possibly additionally compressed. + This can potentially generate high traffic if you have large project. ++ +The value of \'default' is a list of names of snapshot formats, +defined in `%known_snapshot_formats` hash, that you wish to offer. +Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz +compressed tar archive) and "zip"; please consult gitweb sources for +a definitive list. By default only "tgz" is offered. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.blame` configuration variable, which contains +a comma separated list of formats or "none" to disable snapshots. +Unknown values are ignored. + +grep:: + Enable grep search, which lists the files in currently selected + tree (directory) containing the given string; see linkgit:git-grep[1]. + This can be potentially CPU-intensive, of course. Enabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.grep` configuration variable (boolean). + +pickaxe:: + Enable the so called pickaxe search, which will list the commits + that introduced or removed a given string in a file. This can be + practical and quite faster alternative to "blame" action, but it is + still potentially CPU-intensive. Enabled by default. ++ +The pickaxe search is described in linkgit:git-log[1] (the +description of `-S<string>` option, which refers to pickaxe entry in +linkgit:gitdiffcore[7] for more details). ++ +This feature can be configured on a per-repository basis by setting +repository's `gitweb.pickaxe` configuration variable (boolean). + +show-sizes:: + Enable showing size of blobs (ordinary files) in a "tree" view, in a + separate column, similar to what `ls -l` does; see description of + `-l` option in linkgit:git-ls-tree[1] manpage. This costs a bit of + I/O. Enabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.showsizes` configuration variable (boolean). + +patches:: + Enable and configure "patches" view, which displays list of commits in email + (plain text) output format; see also linkgit:git-format-patch[1]. + The value is the maximum number of patches in a patchset generated + in "patches" view. Set the 'default' field to a list containing single + item of or to an empty list to disable patch view, or to a list + containing a single negative number to remove any limit. + Default value is 16. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.patches` configuration variable (integer). + +avatar:: + Avatar support. When this feature is enabled, views such as + "shortlog" or "commit" will display an avatar associated with + the email of each committer and author. ++ +Currently available providers are *"gravatar"* and *"picon"*. +Only one provider at a time can be selected ('default' is one element list). +If an unknown provider is specified, the feature is disabled. +*Note* that some providers might require extra Perl packages to be +installed; see 'gitweb/INSTALL' for more details. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.avatar` configuration variable. ++ +See also `%avatar_size` with pixel sizes for icons and avatars +("default" is used for one-line like "log" and "shortlog", "double" +is used for two-line like "commit", "commitdiff" or "tag"). If the +default font sizes or lineheights are changed (e.g. via adding extra +CSS stylesheet in `@stylesheets`), it may be appropriate to change +these values. + +highlight:: + Server-side syntax highlight support in "blob" view. It requires + `$highlight_bin` program to be available (see the description of + this variable in the "Configuration variables" section above), + and therefore is disabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.highlight` configuration variable (boolean). + +remote_heads:: + Enable displaying remote heads (remote-tracking branches) in the "heads" + list. In most cases the list of remote-tracking branches is an + unnecessary internal private detail, and this feature is therefore + disabled by default. linkgit:git-instaweb[1], which is usually used + to browse local repositories, enables and uses this feature. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.remote_heads` configuration variable (boolean). + + +The remaining features cannot be overridden on a per project basis. + +search:: + Enable text search, which will list the commits which match author, + committer or commit text to a given string; see the description of + `--author`, `--committer` and `--grep` options in linkgit:git-log[1] + manpage. Enabled by default. ++ +Project specific override is not supported. + +forks:: + If this feature is enabled, gitweb considers projects in + subdirectories of project root (basename) to be forks of existing + projects. For each project `$projname.git`, projects in the + `$projname/` directory and its subdirectories will not be + shown in the main projects list. Instead, a \'+' mark is shown + next to `$projname`, which links to a "forks" view that lists all + the forks (all projects in `$projname/` subdirectory). Additionally + a "forks" view for a project is linked from project summary page. ++ +If the project list is taken from a file (`$projects_list` points to a +file), forks are only recognized if they are listed after the main project +in that file. ++ +Project specific override is not supported. + +actions:: + Insert custom links to the action bar of all project pages. This + allows you to link to third-party scripts integrating into gitweb. ++ +The "default" value consists of a list of triplets in the form +`("<label>", "<link>", "<position>")` where "position" is the label +after which to insert the link, "link" is a format string where `%n` +expands to the project name, `%f` to the project path within the +filesystem (i.e. "$projectroot/$project"), `%h` to the current hash +(\'h' gitweb parameter) and `%b` to the current hash base +(\'hb' gitweb parameter); `%%` expands to \'%'. ++ +For example, at the time this page was written, the http://repo.or.cz[] +git hosting site set it to the following to enable graphical log +(using the third party tool *git-browser*): ++ +---------------------------------------------------------------------- +$feature{'actions'}{'default'} = + [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')]; +---------------------------------------------------------------------- ++ +This adds a link titled "graphiclog" after the "summary" link, leading to +`git-browser` script, passing `r=<project>` as a query parameter. ++ +Project specific override is not supported. + +timed:: + Enable displaying how much time and how many git commands it took to + generate and display each page in the page footer (at the bottom of + page). For example the footer might contain: "This page took 6.53325 + seconds and 13 git commands to generate." Disabled by default. ++ +Project specific override is not supported. + +javascript-timezone:: + Enable and configure the ability to change a common timezone for dates + in gitweb output via JavaScript. Dates in gitweb output include + authordate and committerdate in "commit", "commitdiff" and "log" + views, and taggerdate in "tag" view. Enabled by default. ++ +The value is a list of three values: a default timezone (for if the client +hasn't selected some other timezone and saved it in a cookie), a name of cookie +where to store selected timezone, and a CSS class used to mark up +dates for manipulation. If you want to turn this feature off, set "default" +to empty list: `[]`. ++ +Typical gitweb config files will only change starting (default) timezone, +and leave other elements at their default values: ++ +--------------------------------------------------------------------------- +$feature{'javascript-timezone'}{'default'}[0] = "utc"; +--------------------------------------------------------------------------- ++ +The example configuration presented here is guaranteed to be backwards +and forward compatible. ++ +Timezone values can be "local" (for local timezone that browser uses), "utc" +(what gitweb uses when JavaScript or this feature is disabled), or numerical +timezones in the form of "+/-HHMM", such as "+0200". ++ +Project specific override is not supported. + + +EXAMPLES +-------- + +To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and +"zip" snapshots), while allowing individual projects to turn them off, put +the following in your GITWEB_CONFIG file: + + $feature{'blame'}{'default'} = [1]; + $feature{'blame'}{'override'} = 1; + + $feature{'pickaxe'}{'default'} = [1]; + $feature{'pickaxe'}{'override'} = 1; + + $feature{'snapshot'}{'default'} = ['zip', 'tgz']; + $feature{'snapshot'}{'override'} = 1; + +If you allow overriding for the snapshot feature, you can specify which +snapshot formats are globally disabled. You can also add any command line +options you want (such as setting the compression level). For instance, you +can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by +adding the following lines to your gitweb configuration file: + + $known_snapshot_formats{'zip'}{'disabled'} = 1; + $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; + +ENVIRONMENT +----------- +The location of per-instance and system-wide configuration files can be +overridden using the following environment variables: + +GITWEB_CONFIG:: + Sets location of per-instance configuration file. +GITWEB_CONFIG_SYSTEM:: + Sets location of fallback system-wide configuration file. + This file is read only if per-instance one does not exist. +GITWEB_CONFIG_COMMON:: + Sets location of common system-wide configuration file. + + +FILES +----- +gitweb_config.perl:: + This is default name of per-instance configuration file. The + format of this file is described above. +/etc/gitweb.conf:: + This is default name of fallback system-wide configuration + file. This file is used only if per-instance configuration + variable is not found. +/etc/gitweb-common.conf:: + This is default name of common system-wide configuration + file. + + +SEE ALSO +-------- +linkgit:gitweb[1], linkgit:git-instaweb[1] + +'gitweb/README', 'gitweb/INSTALL' + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt new file mode 100644 index 0000000000..605a085326 --- /dev/null +++ b/Documentation/gitweb.txt @@ -0,0 +1,704 @@ +gitweb(1) +========= + +NAME +---- +gitweb - Git web interface (web frontend to Git repositories) + +SYNOPSIS +-------- +To get started with gitweb, run linkgit:git-instaweb[1] from a git repository. +This would configure and start your web server, and run web browser pointing to +gitweb. + + +DESCRIPTION +----------- +Gitweb provides a web interface to git repositories. It's features include: + +* Viewing multiple Git repositories with common root. +* Browsing every revision of the repository. +* Viewing the contents of files in the repository at any revision. +* Viewing the revision log of branches, history of files and directories, + see what was changed when, by who. +* Viewing the blame/annotation details of any file (if enabled). +* Generating RSS and Atom feeds of commits, for any branch. + The feeds are auto-discoverable in modern web browsers. +* Viewing everything that was changed in a revision, and step through + revisions one at a time, viewing the history of the repository. +* Finding commits which commit messages matches given search term. + +See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or +http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, +browsed using gitweb itself. + + +CONFIGURATION +------------- +Various aspects of gitweb's behavior can be controlled through the configuration +file 'gitweb_config.perl' or '/etc/gitweb.conf'. See the linkgit:gitweb.conf[5] +for details. + +Repositories +~~~~~~~~~~~~ +Gitweb can show information from one or more Git repositories. These +repositories have to be all on local filesystem, and have to share common +repository root, i.e. be all under a single parent repository (but see also +"Advanced web server setup" section, "Webserver configuration with multiple +projects' root" subsection). + +----------------------------------------------------------------------- +our $projectroot = '/path/to/parent/directory'; +----------------------------------------------------------------------- + +The default value for `$projectroot` is '/pub/git'. You can change it during +building gitweb via `GITWEB_PROJECTROOT` build configuration variable. + +By default all git repositories under `$projectroot` are visible and available +to gitweb. The list of projects is generated by default by scanning the +`$projectroot` directory for git repositories (for object databases to be +more exact; gitweb is not interested in a working area, and is best suited +to showing "bare" repositories). + +The name of repository in gitweb is path to it's `$GIT_DIR` (it's object +database) relative to `$projectroot`. Therefore the repository $repo can be +found at "$projectroot/$repo". + + +Projects list file format +~~~~~~~~~~~~~~~~~~~~~~~~~ +Instead of having gitweb find repositories by scanning filesystem +starting from $projectroot, you can provide a pre-generated list of +visible projects by setting `$projects_list` to point to a plain text +file with a list of projects (with some additional info). + +This file uses the following format: + +* One record (for project / repository) per line; does not support line +continuation (newline escaping). + +* Leading and trailing whitespace are ignored. + +* Whitespace separated fields; any run of whitespace can be used as field +separator (rules for Perl's "`split(" ", $line)`"). + +* Fields use modified URI encoding, defined in RFC 3986, section 2.1 +(Percent-Encoding), or rather "Query string encoding" (see +link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference +being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be +also percent-encoded). ++ +Reserved characters are: "%" (used for encoding), "{plus}" (can be used to +encode SPACE), all whitespace characters as defined in Perl, including SP, +TAB and LF, (used to separate fields in a record). + +* Currently recognized fields are: +<repository path>:: + path to repository GIT_DIR, relative to `$projectroot` +<repository owner>:: + displayed as repository owner, preferably full name, or email, + or both + +You can generate the projects list index file using the project_index action +(the 'TXT' link on projects list page) directly from gitweb; see also +"Generating projects list using gitweb" section below. + +Example contents: +----------------------------------------------------------------------- +foo.git Joe+R+Hacker+<joe@example.com> +foo/bar.git O+W+Ner+<owner@example.org> +----------------------------------------------------------------------- + + +By default this file controls only which projects are *visible* on projects +list page (note that entries that do not point to correctly recognized git +repositories won't be displayed by gitweb). Even if a project is not +visible on projects list page, you can view it nevertheless by hand-crafting +a gitweb URL. By setting `$strict_export` configuration variable (see +linkgit:gitweb.conf[5]) to true value you can allow viewing only of +repositories also shown on the overview page (i.e. only projects explicitly +listed in projects list file will be accessible). + + +Generating projects list using gitweb +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We assume that GITWEB_CONFIG has its default Makefile value, namely +'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file: +---------------------------------------------------------------------------- +read_config_file("gitweb_config.perl"); +$projects_list = $projectroot; +---------------------------------------------------------------------------- + +Then create the following script to get list of project in the format +suitable for GITWEB_LIST build configuration variable (or +`$projects_list` variable in gitweb config): + +---------------------------------------------------------------------------- +#!/bin/sh + +export GITWEB_CONFIG="gitweb_make_index.perl" +export GATEWAY_INTERFACE="CGI/1.1" +export HTTP_ACCEPT="*/*" +export REQUEST_METHOD="GET" +export QUERY_STRING="a=project_index" + +perl -- /var/www/cgi-bin/gitweb.cgi +---------------------------------------------------------------------------- + +Run this script and save its output to a file. This file could then be used +as projects list file, which means that you can set `$projects_list` to its +filename. + + +Controlling access to git repositories +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default all git repositories under `$projectroot` are visible and +available to gitweb. You can however configure how gitweb controls access +to repositories. + +* As described in "Projects list file format" section, you can control which +projects are *visible* by selectively including repositories in projects +list file, and setting `$projects_list` gitweb configuration variable to +point to it. With `$strict_export` set, projects list file can be used to +control which repositories are *available* as well. + +* You can configure gitweb to only list and allow viewing of the explicitly +exported repositories, via `$export_ok` variable in gitweb config file; see +linkgit:gitweb.conf[5] manpage. If it evaluates to true, gitweb shows +repositories only if this file named by `$export_ok` exists in its object +database (if directory has the magic file named `$export_ok`). ++ +For example linkgit:git-daemon[1] by default (unless `--export-all` option +is used) allows pulling only for those repositories that have +'git-daemon-export-ok' file. Adding ++ +-------------------------------------------------------------------------- +our $export_ok = "git-daemon-export-ok"; +-------------------------------------------------------------------------- ++ +makes gitweb show and allow access only to those repositories that can be +fetched from via `git://` protocol. + +* Finally, it is possible to specify an arbitrary perl subroutine that will +be called for each repository to determine if it can be exported. The +subroutine receives an absolute path to the project (repository) as its only +parameter (i.e. "$projectroot/$project"). ++ +For example, if you use mod_perl to run the script, and have dumb +HTTP protocol authentication configured for your repositories, you +can use the following hook to allow access only if the user is +authorized to read the files: ++ +-------------------------------------------------------------------------- +$export_auth_hook = sub { + use Apache2::SubRequest (); + use Apache2::Const -compile => qw(HTTP_OK); + my $path = "$_[0]/HEAD"; + my $r = Apache2::RequestUtil->request; + my $sub = $r->lookup_file($path); + return $sub->filename eq $path + && $sub->status == Apache2::Const::HTTP_OK; +}; +-------------------------------------------------------------------------- + + +Per-repository gitweb configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can configure individual repositories shown in gitweb by creating file +in the 'GIT_DIR' of git repository, or by setting some repo configuration +variable (in 'GIT_DIR/config', see linkgit:git-config[1]). + +You can use the following files in repository: + +README.html:: + A html file (HTML fragment) which is included on the gitweb project + "summary" page inside `<div>` block element. You can use it for longer + description of a project, to provide links (for example to project's + homepage), etc. This is recognized only if XSS prevention is off + (`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include + a README safely when XSS prevention is on may be worked out in the + future. + +description (or `gitweb.description`):: + Short (shortened to `$projects_list_description_width` in the projects + list page, which is 25 characters by default; see + linkgit:gitweb.conf[5]) single line description of a project (of a + repository). Plain text file; HTML will be escaped. By default set to ++ +------------------------------------------------------------------------------- +Unnamed repository; edit this file to name it for gitweb. +------------------------------------------------------------------------------- ++ +from the template during repository creation, usually installed in +'/usr/share/git-core/templates/'. You can use the `gitweb.description` repo +configuration variable, but the file takes precedence. + +category (or `gitweb.category`):: + Singe line category of a project, used to group projects if + `$projects_list_group_categories` is enabled. By default (file and + configuration variable absent), uncategorized projects are put in the + `$project_list_default_category` category. You can use the + `gitweb.category` repo configuration variable, but the file takes + precedence. ++ +The configuration variables `$projects_list_group_categories` and +`$project_list_default_category` are described in linkgit:gitweb.conf[5] + +cloneurl (or multiple-valued `gitweb.url`):: + File with repository URL (used for clone and fetch), one per line. + Displayed in the project summary page. You can use multiple-valued + `gitweb.url` repository configuration variable for that, but the file + takes precedence. ++ +This is per-repository enhancement / version of global prefix-based +`@git_base_url_list` gitweb configuration variable (see +linkgit:gitweb.conf[5]). + +gitweb.owner:: + You can use the `gitweb.owner` repository configuration variable to set + repository's owner. It is displayed in the project list and summary + page. ++ +If it's not set, filesystem directory's owner is used (via GECOS field, +i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset +(gitweb scans `$projectroot` for repositories); if `$projects_list` +points to file with list of repositories, then project owner defaults to +value from this file for given repository. + +various `gitweb.*` config variables (in config):: + Read description of `%feature` hash for detailed list, and descriptions. + See also "Configuring gitweb features" section in linkgit:gitweb.conf[5] + + +ACTIONS, AND URLS +----------------- +Gitweb can use path_info (component) based URLs, or it can pass all necessary +information via query parameters. The typical gitweb URLs are broken down in to +five components: + +----------------------------------------------------------------------- +.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments> +----------------------------------------------------------------------- + +repo:: + The repository the action will be performed on. ++ +All actions except for those that list all available projects, +in whatever form, require this parameter. + +action:: + The action that will be run. Defaults to 'projects_list' if repo + is not set, and to 'summary' otherwise. + +revision:: + Revision shown. Defaults to HEAD. + +path:: + The path within the <repository> that the action is performed on, + for those actions that require it. + +arguments:: + Any arguments that control the behaviour of the action. + +Some actions require or allow to specify two revisions, and sometimes even two +pathnames. In most general form such path_info (component) based gitweb URL +looks like this: + +----------------------------------------------------------------------- +.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments> +----------------------------------------------------------------------- + + +Each action is implemented as a subroutine, and must be present in %actions +hash. Some actions are disabled by default, and must be turned on via feature +mechanism. For example to enable 'blame' view add the following to gitweb +configuration file: + +----------------------------------------------------------------------- +$feature{'blame'}{'default'} = [1]; +----------------------------------------------------------------------- + + +Actions: +~~~~~~~~ +The standard actions are: + +project_list:: + Lists the available Git repositories. This is the default command if no + repository is specified in the URL. + +summary:: + Displays summary about given repository. This is the default command if + no action is specified in URL, and only repository is specified. + +heads:: +remotes:: + Lists all local or all remote-tracking branches in given repository. ++ +The latter is not available by default, unless configured. + +tags:: + List all tags (lightweight and annotated) in given repository. + +blob:: +tree:: + Shows the files and directories in a given repository path, at given + revision. This is default command if no action is specified in the URL, + and path is given. + +blob_plain:: + Returns the raw data for the file in given repository, at given path and + revision. Links to this action are marked 'raw'. + +blobdiff:: + Shows the difference between two revisions of the same file. + +blame:: +blame_incremental:: + Shows the blame (also called annotation) information for a file. On a + per line basis it shows the revision in which that line was last changed + and the user that committed the change. The incremental version (which + if configured is used automatically when JavaScript is enabled) uses + Ajax to incrementally add blame info to the contents of given file. ++ +This action is disabled by default for performance reasons. + +commit:: +commitdiff:: + Shows information about a specific commit in a repository. The 'commit' + view shows information about commit in more detail, the 'commitdiff' + action shows changeset for given commit. + +patch:: + Returns the commit in plain text mail format, suitable for applying with + linkgit:git-am[1]. + +tag:: + Display specific annotated tag (tag object). + +log:: +shortlog:: + Shows log information (commit message or just commit subject) for a + given branch (starting from given revision). ++ +The 'shortlog' view is more compact; it shows one commit per line. + +history:: + Shows history of the file or directory in a given repository path, + starting from given revision (defaults to HEAD, i.e. default branch). ++ +This view is similar to 'shortlog' view. + +rss:: +atom:: + Generates an RSS (or Atom) feed of changes to repository. + + +WEBSERVER CONFIGURATION +----------------------- +This section explains how to configure some common webservers to run gitweb. In +all cases, `/path/to/gitweb` in the examples is the directory you ran installed +gitweb in, and contains `gitweb_config.perl`. + +If you've configured a web server that isn't listed here for gitweb, please send +in the instructions so they can be included in a future release. + +Apache as CGI +~~~~~~~~~~~~~ +Apache must be configured to support CGI scripts in the directory in +which gitweb is installed. Let's assume that it is '/var/www/cgi-bin' +directory. + +----------------------------------------------------------------------- +ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" + +<Directory "/var/www/cgi-bin"> + Options Indexes FollowSymlinks ExecCGI + AllowOverride None + Order allow,deny + Allow from all +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/cgi-bin/gitweb.cgi + +Apache with mod_perl, via ModPerl::Registry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can use mod_perl with gitweb. You must install Apache::Registry +(for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable +this support. + +Assuming that gitweb is installed to '/var/www/perl', the following +Apache configuration (for mod_perl 2.x) is suitable. + +----------------------------------------------------------------------- +Alias /perl "/var/www/perl" + +<Directory "/var/www/perl"> + SetHandler perl-script + PerlResponseHandler ModPerl::Registry + PerlOptions +ParseHeaders + Options Indexes FollowSymlinks +ExecCGI + AllowOverride None + Order allow,deny + Allow from all +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/perl/gitweb.cgi + +Apache with FastCGI +~~~~~~~~~~~~~~~~~~~ +Gitweb works with Apache and FastCGI. First you need to rename, copy +or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is +installed in '/usr/share/gitweb' directory. The following Apache +configuration is suitable (UNTESTED!) + +----------------------------------------------------------------------- +FastCgiServer /usr/share/gitweb/gitweb.cgi +ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi + +Alias /gitweb/static /usr/share/gitweb/static +<Directory /usr/share/gitweb/static> + SetHandler default-handler +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/gitweb + + +ADVANCED WEB SERVER SETUP +------------------------- +All of those examples use request rewriting, and need `mod_rewrite` +(or equivalent; examples below are written for Apache). + +Single URL for gitweb and for fetching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you want to have one URL for both gitweb and your `http://` +repositories, you can configure Apache like this: + +----------------------------------------------------------------------- +<VirtualHost *:80> + ServerName git.example.org + DocumentRoot /pub/git + SetEnv GITWEB_CONFIG /etc/gitweb.conf + + # turning on mod rewrite + RewriteEngine on + + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi + + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ + /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] +</VirtualHost> +----------------------------------------------------------------------- + +The above configuration expects your public repositories to live under +'/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`, +both as cloneable GIT URL and as browseable gitweb interface. If you then +start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` +then you can even use the `git://` URL with exactly the same path. + +Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the +named file (i.e. in this example '/etc/gitweb.conf') as a configuration for +gitweb. You don't really need it in above example; it is required only if +your configuration file is in different place than built-in (during +compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'. See +linkgit:gitweb.conf[5] for details, especially information about precedence +rules. + +If you use the rewrite rules from the example you *might* also need +something like the following in your gitweb configuration file +('/etc/gitweb.conf' following example): +---------------------------------------------------------------------------- +@stylesheets = ("/some/absolute/path/gitweb.css"); +$my_uri = "/"; +$home_link = "/"; +$per_request_config = 1; +---------------------------------------------------------------------------- +Nowadays though gitweb should create HTML base tag when needed (to set base +URI for relative links), so it should work automatically. + + +Webserver configuration with multiple projects' root +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you want to use gitweb with several project roots you can edit your +Apache virtual host and gitweb configuration files in the following way. + +The virtual host configuration (in Apache configuration file) should look +like this: +-------------------------------------------------------------------------- +<VirtualHost *:80> + ServerName git.example.org + DocumentRoot /pub/git + SetEnv GITWEB_CONFIG /etc/gitweb.conf + + # turning on mod rewrite + RewriteEngine on + + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT] + + # look for a public_git folder in unix users' home + # http://git.example.org/~<user>/ + RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # http://git.example.org/+<user>/ + #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # http://git.example.org/user/<user>/ + #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # defined list of project roots + RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT] + RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT] + + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ + /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] +</VirtualHost> +-------------------------------------------------------------------------- + +Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT` +environment variable from a web server, so you need to put the following +line in gitweb configuration file ('/etc/gitweb.conf' in above example): +-------------------------------------------------------------------------- +$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; +-------------------------------------------------------------------------- +*Note* that this requires to be set for each request, so either +`$per_request_config` must be false, or the above must be put in code +referenced by `$per_request_config`; + +These configurations enable two things. First, each unix user (`<user>`) of +the server will be able to browse through gitweb git repositories found in +'~/public_git/' with the following url: + + http://git.example.org/~<user>/ + +If you do not want this feature on your server just remove the second +rewrite rule. + +If you already use `mod_userdir` in your virtual host or you don't want to +use the \'~' as first character, just comment or remove the second rewrite +rule, and uncomment one of the following according to what you want. + +Second, repositories found in '/pub/scm/' and '/var/git/' will be accessible +through `http://git.example.org/scm/` and `http://git.example.org/var/`. +You can add as many project roots as you want by adding rewrite rules like +the third and the fourth. + + +PATH_INFO usage +~~~~~~~~~~~~~~~ +If you enable PATH_INFO usage in gitweb by putting +---------------------------------------------------------------------------- +$feature{'pathinfo'}{'default'} = [1]; +---------------------------------------------------------------------------- +in your gitweb configuration file, it is possible to set up your server so +that it consumes and produces URLs in the form + + http://git.example.com/project.git/shortlog/sometag + +i.e. without 'gitweb.cgi' part, by using a configuration such as the +following. This configuration assumes that '/var/www/gitweb' is the +DocumentRoot of your webserver, contains the gitweb.cgi script and +complementary static files (stylesheet, favicon, JavaScript): + +---------------------------------------------------------------------------- +<VirtualHost *:80> + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + <Directory /var/www/gitweb> + Options ExecCGI + AddHandler cgi-script cgi + + DirectoryIndex gitweb.cgi + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^.* /gitweb.cgi/$0 [L,PT] + </Directory> +</VirtualHost> +---------------------------------------------------------------------------- +The rewrite rule guarantees that existing static files will be properly +served, whereas any other URL will be passed to gitweb as PATH_INFO +parameter. + +*Notice* that in this case you don't need special settings for +`@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client" +access to your project .git dirs (described in "Single URL for gitweb and +for fetching" section). A possible workaround for the latter is the +following: in your project root dir (e.g. '/pub/git') have the projects +named *without* a .git extension (e.g. '/pub/git/project' instead of +'/pub/git/project.git') and configure Apache as follows: +---------------------------------------------------------------------------- +<VirtualHost *:80> + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3 + <Directory /var/www/gitweb> + Options ExecCGI + AddHandler cgi-script cgi + + DirectoryIndex gitweb.cgi + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^.* /gitweb.cgi/$0 [L,PT] + </Directory> +</VirtualHost> +---------------------------------------------------------------------------- + +The additional AliasMatch makes it so that + + http://git.example.com/project.git + +will give raw access to the project's git dir (so that the project can be +cloned), while + + http://git.example.com/project + +will provide human-friendly gitweb access. + +This solution is not 100% bulletproof, in the sense that if some project has +a named ref (branch, tag) starting with 'git/', then paths such as + + http://git.example.com/project/command/abranch..git/abranch + +will fail with a 404 error. + + +BUGS +---- +Please report any bugs or feature requests to git@vger.kernel.org, +putting "gitweb" in the subject of email. + +SEE ALSO +-------- +linkgit:gitweb.conf[5], linkgit:git-instaweb[1] + +'gitweb/README', 'gitweb/INSTALL' + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 065441df64..5e4f362ff8 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -7,6 +7,7 @@ gitworkflows - An overview of recommended workflows with git SYNOPSIS -------- +[verse] git * @@ -360,7 +361,7 @@ There are three main tools that can be used for this: * linkgit:git-pull[1] that does fetch and merge in one go. -Note the last point. Do 'not' use 'git-pull' unless you actually want +Note the last point. Do 'not' use 'git pull' unless you actually want to merge the remote branch. Getting changes out is easy: @@ -397,7 +398,7 @@ Please pull from <url> <branch> ------------------------------------- -In that case, 'git-pull' can do the fetch and merge in one go, as +In that case, 'git pull' can do the fetch and merge in one go, as follows. .Push/pull: Merging remote topics @@ -449,7 +450,7 @@ problem. If you receive such a patch series (as maintainer, or perhaps as a reader of the mailing list it was sent to), save the mails to files, -create a new topic branch and use 'git-am' to import the commits: +create a new topic branch and use 'git am' to import the commits: .format-patch/am: Importing patches [caption="Recipe: "] diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 1f029f8aa0..3595b586bc 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -131,7 +131,7 @@ to point at the new commit. you have. In such these cases, you do not make a new <<def_merge,merge>> <<def_commit,commit>> but instead just update to his revision. This will happen frequently on a - <<def_tracking_branch,tracking branch>> of a remote + <<def_remote_tracking_branch,remote-tracking branch>> of a remote <<def_repository,repository>>. [[def_fetch]]fetch:: @@ -161,8 +161,8 @@ to point at the new commit. [[def_head]]head:: A <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a - <<def_branch,branch>>. Heads are stored in - `$GIT_DIR/refs/heads/`, except when using packed refs. (See + <<def_branch,branch>>. Heads are stored in a file in + `$GIT_DIR/refs/heads/` directory, except when using packed refs. (See linkgit:git-pack-refs[1].) [[def_HEAD]]HEAD:: @@ -170,8 +170,8 @@ to point at the new commit. working tree>> is normally derived from the state of the tree referred to by HEAD. HEAD is a reference to one of the <<def_head,heads>> in your repository, except when using a - <<def_detached_HEAD,detached HEAD>>, in which case it may - reference an arbitrary commit. + <<def_detached_HEAD,detached HEAD>>, in which case it directly + references an arbitrary commit. [[def_head_ref]]head ref:: A synonym for <<def_head,head>>. @@ -260,7 +260,7 @@ This commit is referred to as a "merge commit", or sometimes just a The default upstream <<def_repository,repository>>. Most projects have at least one upstream project which they track. By default 'origin' is used for that purpose. New upstream updates - will be fetched into remote <<def_tracking_branch,tracking branches>> named + will be fetched into remote <<def_remote_tracking_branch,remote-tracking branches>> named origin/name-of-upstream-branch, which you can see using `git branch -r`. @@ -273,6 +273,61 @@ This commit is referred to as a "merge commit", or sometimes just a <<def_pack,pack>>, to assist in efficiently accessing the contents of a pack. +[[def_pathspec]]pathspec:: + Pattern used to specify paths. ++ +Pathspecs are used on the command line of "git ls-files", "git +ls-tree", "git add", "git grep", "git diff", "git checkout", +and many other commands to +limit the scope of operations to some subset of the tree or +worktree. See the documentation of each command for whether +paths are relative to the current directory or toplevel. The +pathspec syntax is as follows: + +* any path matches itself +* the pathspec up to the last slash represents a + directory prefix. The scope of that pathspec is + limited to that subtree. +* the rest of the pathspec is a pattern for the remainder + of the pathname. Paths relative to the directory + prefix will be matched against that pattern using fnmatch(3); + in particular, '*' and '?' _can_ match directory separators. ++ +For example, Documentation/*.jpg will match all .jpg files +in the Documentation subtree, +including Documentation/chapter_1/figure_1.jpg. + ++ +A pathspec that begins with a colon `:` has special meaning. In the +short form, the leading colon `:` is followed by zero or more "magic +signature" letters (which optionally is terminated by another colon `:`), +and the remainder is the pattern to match against the path. The optional +colon that terminates the "magic signature" can be omitted if the pattern +begins with a character that cannot be a "magic signature" and is not a +colon. ++ +In the long form, the leading colon `:` is followed by a open +parenthesis `(`, a comma-separated list of zero or more "magic words", +and a close parentheses `)`, and the remainder is the pattern to match +against the path. ++ +The "magic signature" consists of an ASCII symbol that is not +alphanumeric. ++ +-- +top `/`;; + The magic word `top` (mnemonic: `/`) makes the pattern match + from the root of the working tree, even when you are running + the command from inside a subdirectory. +-- ++ +Currently only the slash `/` is recognized as the "magic signature", +but it is envisioned that we will support more types of magic in later +versions of git. ++ +A pathspec with only a colon means "there is no pathspec". This form +should not be combined with other pathspec. + [[def_parent]]parent:: A <<def_commit_object,commit object>> contains a (possibly empty) list of the logical predecessor(s) in the line of development, i.e. its @@ -327,8 +382,9 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_ref]]ref:: A 40-byte hex representation of a <<def_SHA1,SHA1>> or a name that - denotes a particular <<def_object,object>>. These may be stored in - `$GIT_DIR/refs/`. + denotes a particular <<def_object,object>>. They may be stored in + a file under `$GIT_DIR/refs/` directory, or + in the `$GIT_DIR/packed-refs` file. [[def_reflog]]reflog:: A reflog shows the local "history" of a ref. In other words, @@ -349,6 +405,14 @@ This commit is referred to as a "merge commit", or sometimes just a master branch head as to-upstream branch at $URL". See also linkgit:git-push[1]. +[[def_remote_tracking_branch]]remote-tracking branch:: + A regular git <<def_branch,branch>> that is used to follow changes from + another <<def_repository,repository>>. A remote-tracking + branch should not contain direct modifications or have local commits + made to it. A remote-tracking branch can usually be + identified as the right-hand-side <<def_ref,ref>> in a Pull: + <<def_refspec,refspec>>. + [[def_repository]]repository:: A collection of <<def_ref,refs>> together with an <<def_object_database,object database>> containing all objects @@ -396,14 +460,14 @@ This commit is referred to as a "merge commit", or sometimes just a command. [[def_tag]]tag:: - A <<def_ref,ref>> pointing to a <<def_tag_object,tag>> or - <<def_commit_object,commit object>>. In contrast to a <<def_head,head>>, - a tag is not changed by a <<def_commit,commit>>. Tags (not - <<def_tag_object,tag objects>>) are stored in `$GIT_DIR/refs/tags/`. A - git tag has nothing to do with a Lisp tag (which would be - called an <<def_object_type,object type>> in git's context). A - tag is most typically used to mark a particular point in the - commit ancestry <<def_chain,chain>>. + A <<def_ref,ref>> under `refs/tags/` namespace that points to an + object of an arbitrary type (typically a tag points to either a + <<def_tag_object,tag>> or a <<def_commit_object,commit object>>). + In contrast to a <<def_head,head>>, a tag is not updated by + the `commit` command. A git tag has nothing to do with a Lisp + tag (which would be called an <<def_object_type,object type>> + in git's context). A tag is most typically used to mark a particular + point in the commit ancestry <<def_chain,chain>>. [[def_tag_object]]tag object:: An <<def_object,object>> containing a <<def_ref,ref>> pointing to @@ -418,14 +482,6 @@ This commit is referred to as a "merge commit", or sometimes just a that each contain very well defined concepts or small incremental yet related changes. -[[def_tracking_branch]]tracking branch:: - A regular git <<def_branch,branch>> that is used to follow changes from - another <<def_repository,repository>>. A tracking - branch should not contain direct modifications or have local commits - made to it. A tracking branch can usually be - identified as the right-hand-side <<def_ref,ref>> in a Pull: - <<def_refspec,refspec>>. - [[def_tree]]tree:: Either a <<def_working_tree,working tree>>, or a <<def_tree_object,tree object>> together with the dependent <<def_blob_object,blob>> and tree objects diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index d527b30770..8823a37067 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -176,7 +176,7 @@ by doing the following: - Update "What's cooking" message to review the updates to existing topics, newly added topics and graduated topics. - This step is helped with Meta/UWC script (where Meta/ contains + This step is helped with Meta/cook script (where Meta/ contains a checkout of the 'todo' branch). - Merge topics to 'next'. For each branch whose tip is not @@ -197,10 +197,9 @@ by doing the following: - Nothing is next-worthy; do not do anything. - - Rebase topics that do not have any commit in next yet. This - step is optional but sometimes is worth doing when an old - series that is not in next can take advantage of low-level - framework change that is merged to 'master' already. + - [** OBSOLETE **] Optionally rebase topics that do not have any commit + in next yet, when they can take advantage of low-level framework + change that is merged to 'master' already. $ git rebase master ai/topic @@ -209,7 +208,7 @@ by doing the following: pre-rebase hook to make sure that topics that are already in 'next' are not rebased beyond the merged commit. - - Rebuild "pu" to merge the tips of topics not in 'next'. + - [** OBSOLETE **] Rebuild "pu" to merge the tips of topics not in 'next'. $ git checkout pu $ git reset --hard next @@ -241,7 +240,7 @@ by doing the following: - Fetch html and man branches back from k.org, and push four integration branches and the two documentation branches to - repo.or.cz + repo.or.cz and other mirrors. Some observations to be made. diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt index 3b4a390005..6fd711996a 100644 --- a/Documentation/howto/revert-a-faulty-merge.txt +++ b/Documentation/howto/revert-a-faulty-merge.txt @@ -142,6 +142,8 @@ different resolution strategies: revert of a merge was rebuilt from scratch (i.e. rebasing and fixing, as you seem to have interpreted), then re-merging the result without doing anything else fancy would be the right thing to do. + (See the ADDENDUM below for how to rebuild a branch from scratch + without changing its original branching-off point.) However, there are things to keep in mind when reverting a merge (and reverting such a revert). @@ -177,3 +179,91 @@ the answer is: "oops, I really shouldn't have merged it, because it wasn't ready yet, and I really need to undo _all_ of the merge"). So then you really should revert the merge, but when you want to re-do the merge, you now need to do it by reverting the revert. + +ADDENDUM + +Sometimes you have to rewrite one of a topic branch's commits *and* you can't +change the topic's branching-off point. Consider the following situation: + + P---o---o---M---x---x---W---x + \ / + A---B---C + +where commit W reverted commit M because it turned out that commit B was wrong +and needs to be rewritten, but you need the rewritten topic to still branch +from commit P (perhaps P is a branching-off point for yet another branch, and +you want be able to merge the topic into both branches). + +The natural thing to do in this case is to checkout the A-B-C branch and use +"rebase -i P" to change commit B. However this does not rewrite commit A, +because "rebase -i" by default fast-forwards over any initial commits selected +with the "pick" command. So you end up with this: + + P---o---o---M---x---x---W---x + \ / + A---B---C <-- old branch + \ + B'---C' <-- naively rewritten branch + +To merge A-B'-C' into the mainline branch you would still have to first revert +commit W in order to pick up the changes in A, but then it's likely that the +changes in B' will conflict with the original B changes re-introduced by the +reversion of W. + +However, you can avoid these problems if you recreate the entire branch, +including commit A: + + A'---B'---C' <-- completely rewritten branch + / + P---o---o---M---x---x---W---x + \ / + A---B---C + +You can merge A'-B'-C' into the mainline branch without worrying about first +reverting W. Mainline's history would look like this: + + A'---B'---C'------------------ + / \ + P---o---o---M---x---x---W---x---M2 + \ / + A---B---C + +But if you don't actually need to change commit A, then you need some way to +recreate it as a new commit with the same changes in it. The rebase command's +--no-ff option provides a way to do this: + + $ git rebase [-i] --no-ff P + +The --no-ff option creates a new branch A'-B'-C' with all-new commits (all the +SHA IDs will be different) even if in the interactive case you only actually +modify commit B. You can then merge this new branch directly into the mainline +branch and be sure you'll get all of the branch's changes. + +You can also use --no-ff in cases where you just add extra commits to the topic +to fix it up. Let's revisit the situation discussed at the start of this howto: + + P---o---o---M---x---x---W---x + \ / + A---B---C----------------D---E <-- fixed-up topic branch + +At this point, you can use --no-ff to recreate the topic branch: + + $ git checkout E + $ git rebase --no-ff P + +yielding + + A'---B'---C'------------D'---E' <-- recreated topic branch + / + P---o---o---M---x---x---W---x + \ / + A---B---C----------------D---E + +You can merge the recreated branch into the mainline without reverting commit W, +and mainline's history will look like this: + + A'---B'---C'------------D'---E' + / \ + P---o---o---M---x---x---W---x---M2 + \ / + A---B---C diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt index 8c32da6deb..093c656048 100644 --- a/Documentation/howto/revert-branch-rebase.txt +++ b/Documentation/howto/revert-branch-rebase.txt @@ -112,25 +112,19 @@ $ git tag pu-anchor pu $ git rebase master * Applying: Redo "revert" using three-way merge machinery. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: Remove git-apply-patch-script. First trying simple merge strategy to cherry-pick. Simple cherry-pick fails; trying Automatic cherry-pick. Removing Documentation/git-apply-patch-script.txt Removing git-apply-patch-script -Finished one cherry-pick. * Applying: Document "git cherry-pick" and "git revert" First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: mailinfo and applymbox updates First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: Show commits in topo order and name all commits. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: More documentation updates. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. ------------------------------------------------ The temporary tag 'pu-anchor' is me just being careful, in case 'git diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index 0953a50b69..2933056120 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -71,5 +71,5 @@ Additional tips relevant parts of your tree. - Please note that if the other project merges from you, then it will - connects its history to yours, which can be something they don't want + connect its history to yours, which can be something they don't want to. diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index 708da6ca31..625d3154ea 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -21,7 +21,7 @@ project find it more convenient to use legacy encodings, git does not forbid it. However, there are a few things to keep in mind. -. 'git-commit' and 'git-commit-tree' issues +. 'git commit' and 'git commit-tree' issues a warning if the commit log message given to it does not look like a valid UTF-8 string, unless you explicitly say your project uses a legacy encoding. The way to say this is to @@ -37,7 +37,7 @@ of `i18n.commitencoding` in its `encoding` header. This is to help other people who look at them later. Lack of this header implies that the commit log message is encoded in UTF-8. -. 'git-log', 'git-show', 'git-blame' and friends look at the +. 'git log', 'git show', 'git blame' and friends look at the `encoding` header of a commit object, and try to re-code the log message into UTF-8 unless otherwise specified. You can specify the desired output encoding with diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh index 35f440876e..327f69bcf5 100755 --- a/Documentation/install-doc-quick.sh +++ b/Documentation/install-doc-quick.sh @@ -1,31 +1,39 @@ #!/bin/sh -# This requires a branch named in $head -# (usually 'man' or 'html', provided by the git.git repository) -set -e -head="$1" -mandir="$2" -SUBDIRECTORY_OK=t -USAGE='<refname> <target directory>' -. "$(git --exec-path)"/git-sh-setup -cd_to_toplevel +# This requires git-manpages and/or git-htmldocs repositories -test -z "$mandir" && usage -if ! git rev-parse --verify "$head^0" >/dev/null; then - echo >&2 "head: $head does not exist in the current repository" - usage +repository=${1?repository} +destdir=${2?destination} + +head=master GIT_DIR= +for d in "$repository/.git" "$repository" +do + if GIT_DIR="$d" git rev-parse refs/heads/master >/dev/null 2>&1 + then + GIT_DIR="$d" + export GIT_DIR + break + fi +done + +if test -z "$GIT_DIR" +then + echo >&2 "Neither $repository nor $repository/.git is a repository" + exit 1 fi -GIT_INDEX_FILE=`pwd`/.quick-doc.index -export GIT_INDEX_FILE +GIT_WORK_TREE=$(pwd) +GIT_INDEX_FILE=$(pwd)/.quick-doc.$$ +export GIT_INDEX_FILE GIT_WORK_TREE rm -f "$GIT_INDEX_FILE" trap 'rm -f "$GIT_INDEX_FILE"' 0 git read-tree $head -git checkout-index -a -f --prefix="$mandir"/ +git checkout-index -a -f --prefix="$destdir"/ -if test -n "$GZ"; then +if test -n "$GZ" +then git ls-tree -r --name-only $head | - xargs printf "$mandir/%s\n" | + xargs printf "$destdir/%s\n" | xargs gzip -f fi rm -f "$GIT_INDEX_FILE" diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh index 2135a8ee1f..76d69a907b 100755 --- a/Documentation/install-webdoc.sh +++ b/Documentation/install-webdoc.sh @@ -6,13 +6,13 @@ for h in \ *.txt *.html \ howto/*.txt howto/*.html \ technical/*.txt technical/*.html \ - RelNotes-*.txt *.css + RelNotes/*.txt *.css do if test ! -f "$h" then : did not match elif test -f "$T/$h" && - diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h" + $DIFF -u -I'^Last updated ' "$T/$h" "$h" then :; # up to date else @@ -30,7 +30,7 @@ for th in \ do h=`expr "$th" : "$strip_leading"'\(.*\)'` case "$h" in - index.html) continue ;; + RelNotes-*.txt | index.html) continue ;; esac test -f "$h" && continue echo >&2 "# rm -f $th" diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index a403155052..861bd6f553 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -6,25 +6,57 @@ merge.conflictstyle:: a `>>>>>>>` marker. An alternate style, "diff3", adds a `|||||||` marker and the original text before the `=======` marker. +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. + 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 + these tracking branches are merged. + +merge.ff:: + By default, git does not create an extra merge commit when merging + a commit that is a descendant of the current commit. Instead, the + tip of the current branch is fast-forwarded. When set to `false`, + this variable tells git to create an extra merge commit in such + a case (equivalent to giving the `--no-ff` option from the command + line). When set to `only`, only such fast-forward merges are + allowed (equivalent to giving the `--ff-only` option from the + command line). + merge.log:: - Whether to include summaries of merged commits in newly created - merge commit messages. False by default. + In addition to branch names, populate the log message with at + most the specified number of one-line descriptions from the + actual commits that are being merged. Defaults to false, and + true is a synonym for 20. merge.renameLimit:: The number of files to consider when performing rename detection during a merge; if not specified, defaults to the value of diff.renameLimit. +merge.renormalize:: + Tell git that canonical representation of files in the + repository has changed over time (e.g. earlier commits record + text files with CRLF line endings, but recent ones use LF line + endings). In such a repository, git can convert the data + recorded in commits to a canonical form before performing a + merge to reduce unnecessary conflicts. For more information, + see section "Merging branches with differing checkin/checkout + attributes" in linkgit:gitattributes[5]. + merge.stat:: Whether to print the diffstat between ORIG_HEAD and the merge result at the end of the merge. True by default. merge.tool:: Controls which merge resolution program is used by - linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", - "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", - "diffuse", "ecmerge", "tortoisemerge", "p4merge", "araxis" and - "opendiff". Any other value is treated is custom merge tool + linkgit:git-mergetool[1]. Valid built-in values are: "araxis", + "bc3", "diffuse", "ecmerge", "emerge", "gvimdiff", "kdiff3", "meld", + "opendiff", "p4merge", "tkdiff", "tortoisemerge", "vimdiff" + and "xxdiff". Any other value is treated is custom merge tool and there must be a corresponding mergetool.<tool>.cmd option. merge.verbosity:: diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index fec3394305..6bd0b041c3 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -7,6 +7,12 @@ With --no-commit perform the merge but pretend the merge failed and do not autocommit, to give the user a chance to inspect and further tweak the merge result before committing. +--edit:: +-e:: ++ + Invoke editor before committing successful merge to further + edit the default merge message. + --ff:: --no-ff:: Do not generate a merge commit if the merge resolved as @@ -16,11 +22,11 @@ inspect and further tweak the merge result before committing. With --no-ff Generate a merge commit even if the merge resolved as a fast-forward. ---log:: +--log[=<n>]:: --no-log:: In addition to branch names, populate the log message with - one-line descriptions from the actual commits that are being - merged. + one-line descriptions from at most <n> actual commits that are being + merged. See also linkgit:git-fmt-merge-msg[1]. + With --no-log do not list one-line descriptions from the actual commits being merged. @@ -59,18 +65,33 @@ option can be used to override --squash. Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. If there is no `-s` option, a built-in list of strategies - is used instead ('git-merge-recursive' when merging a single - head, 'git-merge-octopus' otherwise). + is used instead ('git merge-recursive' when merging a single + head, 'git merge-octopus' otherwise). + +-X <option>:: +--strategy-option=<option>:: + Pass merge strategy specific option through to the merge + strategy. --summary:: --no-summary:: Synonyms to --stat and --no-stat; these are deprecated and will be removed in the future. +ifndef::git-pull[] -q:: --quiet:: - Operate quietly. + Operate quietly. Implies --no-progress. -v:: --verbose:: Be verbose. + +--progress:: +--no-progress:: + Turn progress on/off explicitly. If neither is specified, + progress is shown if standard error is connected to a terminal. + Note that not all merge strategies may support progress + reporting. + +endif::git-pull[] diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 42910a3d5e..595a3cf1a7 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -1,6 +1,11 @@ MERGE STRATEGIES ---------------- +The merge mechanism ('git-merge' and 'git-pull' commands) allows the +backend 'merge strategies' to be chosen with `-s` option. Some strategies +can also take their own options, which can be passed by giving `-X<option>` +arguments to 'git-merge' and/or 'git-pull'. + resolve:: This can only resolve two heads (i.e. the current branch and another branch you pulled from) using a 3-way merge @@ -20,6 +25,65 @@ recursive:: Additionally this can detect and handle merges involving renames. This is the default merge strategy when pulling or merging one branch. ++ +The 'recursive' strategy can take the following options: + +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. ++ +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'. + +patience;; + With this option, 'merge-recursive' spends a little extra time + to avoid mismerges that sometimes occur due to unimportant + matching lines (e.g., braces from distinct functions). Use + this when the branches to be merged have diverged wildly. + See also linkgit:git-diff[1] `--patience`. + +ignore-space-change;; +ignore-all-space;; +ignore-space-at-eol;; + Treats lines with the indicated type of whitespace change as + unchanged for the sake of a three-way merge. Whitespace + changes mixed with other changes to a line are not ignored. + See also linkgit:git-diff[1] `-b`, `-w`, and + `--ignore-space-at-eol`. ++ +* If 'their' version only introduces whitespace changes to a line, + 'our' version is used; +* If 'our' version introduces whitespace changes but 'their' + version includes a substantial change, 'their' version is used; +* Otherwise, the merge proceeds in the usual way. + +renormalize;; + This runs a virtual check-out and check-in of all three stages + of a file when resolving a three-way merge. This option is + meant to be used when merging branches with different clean + filters or end-of-line normalization rules. See "Merging + branches with differing checkin/checkout attributes" in + linkgit:gitattributes[5] for details. + +no-renormalize;; + Disables the `renormalize` option. This overrides the + `merge.renormalize` configuration variable. + +rename-threshold=<n>;; + Controls the similarity threshold used for rename detection. + See also linkgit:git-diff[1] `-M`. + +subtree[=<path>];; + This option is a more advanced form of 'subtree' strategy, where + the strategy makes a guess on how two trees must be shifted to + match with each other when merging. Instead, the specified path + is prefixed (or stripped from the beginning) to make the shape of + two trees to match. octopus:: This resolves cases with more than two heads, but refuses to do @@ -33,7 +97,8 @@ ours:: merge is always that of the current branch head, effectively ignoring all changes from all other branches. It is meant to be used to supersede old development history of side - branches. + branches. Note that this is different from the -Xours option to + the 'recursive' merge strategy. subtree:: This is a modified recursive strategy. When merging trees A and diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 53a9168ba7..561cc9f7d7 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -11,7 +11,12 @@ have limited your view of history: for example, if you are only interested in changes related to a certain directory or file. -Here are some additional details for each format: +There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +'format:' string, as described below (see +linkgit:git-config[1]). Here are the details of the +built-in formats: * 'oneline' @@ -76,9 +81,9 @@ displayed in full, regardless of whether --abbrev or true parent commits, without taking grafts nor history simplification into account. -* 'format:' +* 'format:<string>' + -The 'format:' format allows you to specify which information +The 'format:<string>' format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with '%n' instead of '\n'. @@ -123,6 +128,7 @@ The placeholders are: - '%s': subject - '%f': sanitized subject line, suitable for a filename - '%b': body +- '%B': raw body (unwrapped subject and body) - '%N': commit notes - '%gD': reflog selector, e.g., `refs/stash@\{1\}` - '%gd': shortened reflog selector, e.g., `stash@\{1\}` @@ -134,6 +140,7 @@ The placeholders are: - '%C(...)': color specification, as described in color.branch.* config option - '%m': left, right or boundary mark - '%n': newline +- '%%': a raw '%' - '%x00': print a byte from a hex code - '%w([<w>[,<i1>[,<i2>]]])': switch line wrapping, like the -w option of linkgit:git-shortlog[1]. @@ -152,6 +159,10 @@ If you add a `-` (minus sign) after '%' of a placeholder, line-feeds that immediately precede the expansion are deleted if and only if the placeholder expands to an empty string. +If you add a ` ` (space) after '%' of a placeholder, a space +is inserted immediately before the expansion if and only if the +placeholder expands to a non-empty string. + * 'tformat:' + The 'tformat:' format works exactly like 'format:', except that it diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index bff94991b6..2a3dc8664f 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -1,10 +1,11 @@ ---pretty[='<format>']:: ---format[='<format>']:: +--pretty[=<format>]:: +--format=<format>:: Pretty-print the contents of the commit logs in a given format, where '<format>' can be one of 'oneline', 'short', 'medium', - 'full', 'fuller', 'email', 'raw' and 'format:<string>'. - When omitted, the format defaults to 'medium'. + 'full', 'fuller', 'email', 'raw' and 'format:<string>'. See + the "PRETTY FORMATS" section for some additional details for each + format. When omitted, the format defaults to 'medium'. + Note: you can specify the default pretty format in the repository configuration (see linkgit:git-config[1]). @@ -18,6 +19,11 @@ configuration (see linkgit:git-config[1]). This should make "--pretty=oneline" a whole lot more readable for people using 80-column terminals. +--no-abbrev-commit:: + Show the full 40-byte hexadecimal commit object name. This negates + `--abbrev-commit` and those options which imply it such as + "--oneline". It also overrides the 'log.abbrevCommit' variable. + --oneline:: This is a shorthand for "--pretty=oneline --abbrev-commit" used together. @@ -28,3 +34,35 @@ people using 80-column terminals. command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this defaults to UTF-8. + +--notes[=<ref>]:: + Show the notes (see linkgit:git-notes[1]) that annotate the + commit, when showing the commit log message. This is the default + for `git log`, `git show` and `git whatchanged` commands when + there is no `--pretty`, `--format` nor `--oneline` option given + on the command line. ++ +By default, the notes shown are from the notes refs listed in the +'core.notesRef' and 'notes.displayRef' variables (or corresponding +environment overrides). See linkgit:git-config[1] for more details. ++ +With an optional '<ref>' argument, show this notes ref instead of the +default notes ref(s). The ref is taken to be in `refs/notes/` if it +is not qualified. ++ +Multiple --notes options can be combined to control which notes are +being displayed. Examples: "--notes=foo" will show only notes from +"refs/notes/foo"; "--notes=foo --notes" will show both notes from +"refs/notes/foo" and from the default notes ref(s). + +--no-notes:: + Do not show notes. This negates the above `--notes` option, by + resetting the list of notes refs from which notes are shown. + Options are parsed in the order given on the command line, so e.g. + "--notes --notes=foo --no-notes --notes=bar" will only show notes + from "refs/notes/bar". + +--show-notes[=<ref>]:: +--[no-]standard-notes:: + These options are deprecated. Use the above --notes/--no-notes + options instead. diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 0551ebdfaf..5dd6e5a0c7 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -38,7 +38,7 @@ must know this is the expected usage pattern for a branch. [NOTE] You never do your own development on branches that appear on the right hand side of a <refspec> colon on `Pull:` lines; -they are to be updated by 'git-fetch'. If you intend to do +they are to be updated by 'git fetch'. If you intend to do development derived from a remote branch `B`, have a `Pull:` line to track it (i.e. `Pull: B:remote-B`), and have a separate branch `my-B` to do your development on top of it. The latter @@ -50,13 +50,13 @@ on the remote branch, merge it into your development branch with + [NOTE] There is a difference between listing multiple <refspec> -directly on 'git-pull' command line and having multiple +directly on 'git pull' command line and having multiple `Pull:` <refspec> lines for a <repository> and running -'git-pull' command without any explicit <refspec> parameters. +'git pull' command without any explicit <refspec> parameters. <refspec> listed explicitly on the command line are always merged into the current branch after fetching. In other words, if you list more than one remote refs, you would be making -an Octopus. While 'git-pull' run without any explicit <refspec> +an Octopus. While 'git pull' run without any explicit <refspec> parameter takes default <refspec>s from `Pull:` lines, it merges only the first <refspec> found into the current branch, after fetching all the remote refs. This is because making an diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 1f57aed337..39e6207269 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -1,148 +1,17 @@ -Commit Formatting -~~~~~~~~~~~~~~~~~ - -ifdef::git-rev-list[] -Using these options, linkgit:git-rev-list[1] will act similar to the -more specialized family of commit log tools: linkgit:git-log[1], -linkgit:git-show[1], and linkgit:git-whatchanged[1] -endif::git-rev-list[] - -include::pretty-options.txt[] - ---relative-date:: - - Synonym for `--date=relative`. - ---date={relative,local,default,iso,rfc,short,raw}:: - - Only takes effect for dates shown in human-readable format, such - as when using "--pretty". `log.date` config variable sets a default - value for log command's --date option. -+ -`--date=relative` shows dates relative to the current time, -e.g. "2 hours ago". -+ -`--date=local` shows timestamps in user's local timezone. -+ -`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. -+ -`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 -format, often found in E-mail messages. -+ -`--date=short` shows only date but not time, in `YYYY-MM-DD` format. -+ -`--date=raw` shows the date in the internal raw git format `%s %z` format. -+ -`--date=default` shows timestamps in the original timezone -(either committer's or author's). - -ifdef::git-rev-list[] ---header:: - - Print the contents of the commit in raw-format; each record is - separated with a NUL character. -endif::git-rev-list[] - ---parents:: - - Print the parents of the commit. Also enables parent - rewriting, see 'History Simplification' below. - ---children:: - - Print the children of the commit. Also enables parent - rewriting, see 'History Simplification' below. - -ifdef::git-rev-list[] ---timestamp:: - Print the raw commit timestamp. -endif::git-rev-list[] - ---left-right:: - - Mark which side of a symmetric diff a commit is reachable from. - Commits from the left side are prefixed with `<` and those from - the right with `>`. If combined with `--boundary`, those - commits are prefixed with `-`. -+ -For example, if you have this topology: -+ ------------------------------------------------------------------------ - y---b---b branch B - / \ / - / . - / / \ - o---x---a---a branch A ------------------------------------------------------------------------ -+ -you would get an output like this: -+ ------------------------------------------------------------------------ - $ git rev-list --left-right --boundary --pretty=oneline A...B - - >bbbbbbb... 3rd on b - >bbbbbbb... 2nd on b - <aaaaaaa... 3rd on a - <aaaaaaa... 2nd on a - -yyyyyyy... 1st on b - -xxxxxxx... 1st on a ------------------------------------------------------------------------ - ---graph:: - - Draw a text-based graphical representation of the commit history - on the left hand side of the output. This may cause extra lines - to be printed in between commits, in order for the graph history - to be drawn properly. -+ -This implies the '--topo-order' option by default, but the -'--date-order' option may also be specified. - -ifndef::git-rev-list[] -Diff Formatting -~~~~~~~~~~~~~~~ - -Below are listed options that control the formatting of diff output. -Some of them are specific to linkgit:git-rev-list[1], however other diff -options may be given. See linkgit:git-diff-files[1] for more options. - --c:: - - This flag changes the way a merge commit is displayed. It shows - the differences from each of the parents to the merge result - simultaneously instead of showing pairwise diff between a parent - and the result one at a time. Furthermore, it lists only files - which were modified from all parents. - ---cc:: - - This flag implies the '-c' options and further compresses the - patch output by omitting uninteresting hunks whose contents in - the parents have only two variants and the merge result picks - one of them without modification. - --r:: - - Show recursive diffs. - --t:: - - Show the tree objects in the diff output. This implies '-r'. -endif::git-rev-list[] - 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. +limiting may be applied. Note that they are applied before commit +ordering and formatting options, such as '--reverse'. -- -n 'number':: --max-count=<number>:: - Limit the number of commits output. + Limit the number of commits to output. --skip=<number>:: @@ -203,11 +72,26 @@ endif::git-rev-list[] --merges:: - Print only merge commits. + Print only merge commits. This is exactly the same as `--min-parents=2`. --no-merges:: - Do not print commits with more than one parent. + Do not print commits with more than one parent. This is + exactly the same as `--max-parents=1`. + +--min-parents=<number>:: +--max-parents=<number>:: +--no-min-parents:: +--no-max-parents:: + + Show only commits which have at least (or at most) that many + commits. In particular, `--max-parents=1` is the same as `--no-merges`, + `--min-parents=2` is the same as `--merges`. `--max-parents=0` + gives all root commits and `--min-parents=3` all octopus merges. ++ +`--no-min-parents` and `--no-max-parents` reset these limits (to no limit) +again. Equivalent forms are `--min-parents=0` (any commit has 0 or more +parents) and `--max-parents=-1` (negative numbers denote no upper limit). --first-parent:: Follow only the first parent commit upon seeing a merge @@ -225,30 +109,47 @@ endif::git-rev-list[] --all:: - Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the + Pretend as if all the refs in `refs/` are listed on the command line as '<commit>'. ---branches:: +--branches[=<pattern>]:: + + Pretend as if all the refs in `refs/heads` are listed + on the command line as '<commit>'. If '<pattern>' is given, limit + branches to ones matching given shell glob. If pattern lacks '?', + '*', or '[', '/*' at the end is implied. + +--tags[=<pattern>]:: + + Pretend as if all the refs in `refs/tags` are listed + on the command line as '<commit>'. If '<pattern>' is given, limit + tags to ones matching given shell glob. If pattern lacks '?', '*', + or '[', '/*' at the end is implied. - Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed - on the command line as '<commit>'. +--remotes[=<pattern>]:: ---tags:: + Pretend as if all the refs in `refs/remotes` are listed + on the command line as '<commit>'. If '<pattern>' is given, limit + remote-tracking branches to ones matching given shell glob. + If pattern lacks '?', '*', or '[', '/*' at the end is implied. - Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed - on the command line as '<commit>'. +--glob=<glob-pattern>:: + Pretend as if all the refs matching shell glob '<glob-pattern>' + are listed on the command line as '<commit>'. Leading 'refs/', + is automatically prepended if missing. If pattern lacks '?', '*', + or '[', '/*' at the end is implied. ---remotes:: +--ignore-missing:: - Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed - on the command line as '<commit>'. + Upon seeing an invalid object name in the input, pretend as if + the bad input was not given. ifndef::git-rev-list[] --bisect:: - Pretend as if the bad bisection ref `$GIT_DIR/refs/bisect/bad` + Pretend as if the bad bisection ref `refs/bisect/bad` was listed and as if it was followed by `--not` and the good - bisection refs `$GIT_DIR/refs/bisect/good-*` on the command + bisection refs `refs/bisect/good-*` on the command line. endif::git-rev-list[] @@ -269,6 +170,11 @@ ifdef::git-rev-list[] to /dev/null as the output does not have to be formatted. endif::git-rev-list[] +--cherry-mark:: + + Like `--cherry-pick` (see below) but mark equivalent commits + with `=` rather than omitting them, and inequivalent ones with `+`. + --cherry-pick:: Omit any commit that introduces the same change as @@ -277,12 +183,33 @@ endif::git-rev-list[] + For example, if you have two branches, `A` and `B`, a usual way to list all commits on only one side of them is with -`--left-right`, like the example above in the description of -that option. It however shows the commits that were cherry-picked +`--left-right` (see the example below in the description of +the `--left-right` option). It however shows the commits that were cherry-picked from the other branch (for example, "3rd on b" may be cherry-picked from branch A). With this option, such pairs of commits are excluded from the output. +--left-only:: +--right-only:: + + List only commits on the respective side of a symmetric range, + i.e. only those which would be marked `<` resp. `>` by + `--left-right`. ++ +For example, `--cherry-pick --right-only A...B` omits those +commits from `B` which are in `A` or are patch-equivalent to a commit in +`A`. In other words, this lists the `{plus}` commits from `git cherry A B`. +More precisely, `--cherry-pick --right-only --no-merges` gives the exact +list. + +--cherry:: + + A synonym for `--right-only --cherry-mark --no-merges`; useful to + limit the output to the commits on our side and mark those that + have been applied to the other side of a forked history with + `git log --cherry upstream...mybranch`, similar to + `git cherry upstream mybranch`. + -g:: --walk-reflogs:: @@ -290,7 +217,7 @@ excluded from the output. reflog entries from the most recent one to older ones. When this option is used you cannot specify commits to exclude (that is, '{caret}commit', 'commit1..commit2', - nor 'commit1...commit2' notations cannot be used). + nor 'commit1\...commit2' notations cannot be used). + With '\--pretty' format other than oneline (for obvious reasons), this causes the output to have two extra lines of information @@ -345,7 +272,7 @@ Default mode:: --full-history:: - As the default mode but does not prune some history. + Same as the default mode, but does not prune some history. --dense:: @@ -362,6 +289,14 @@ Default mode:: merges from the resulting history, as there are no selected commits contributing to this merge. +--ancestry-path:: + + When given a range of commits to display (e.g. 'commit1..commit2' + or 'commit2 {caret}commit1'), only display commits that exist + directly on the ancestry chain between the 'commit1' and + 'commit2', i.e. commits that are both descendants of 'commit1', + and ancestors of 'commit2'. + A more detailed explanation follows. Suppose you specified `foo` as the <paths>. We shall call commits @@ -378,7 +313,7 @@ that you are filtering for a file `foo` in this commit graph: \ / / / / `-------------' ----------------------------------------------------------------------- -The horizontal line of history A--P is taken to be the first parent of +The horizontal line of history A---P is taken to be the first parent of each merge. The commits are: * `I` is the initial commit, in which `foo` exists with contents @@ -418,7 +353,7 @@ This results in: + ----------------------------------------------------------------------- .-A---N---O - / / + / / / I---------D ----------------------------------------------------------------------- + @@ -489,8 +424,6 @@ Note that without '\--full-history', this still simplifies merges: if one of the parents is TREESAME, we follow only that one, so the other sides of the merge are never walked. -Finally, there is a fourth simplification mode available: - --simplify-merges:: First, build a history graph in the same way that @@ -532,6 +465,46 @@ Note the major differences in `N` and `P` over '\--full-history': removed completely, because it had one parent and is TREESAME. -- +Finally, there is a fifth simplification mode available: + +--ancestry-path:: + + Limit the displayed commits to those directly on the ancestry + chain between the "from" and "to" commits in the given commit + range. I.e. only display commits that are ancestor of the "to" + commit, and descendants of the "from" commit. ++ +As an example use case, consider the following commit history: ++ +----------------------------------------------------------------------- + D---E-------F + / \ \ + B---C---G---H---I---J + / \ + A-------K---------------L--M +----------------------------------------------------------------------- ++ +A regular 'D..M' computes the set of commits that are ancestors of `M`, +but excludes the ones that are ancestors of `D`. This is useful to see +what happened to the history leading to `M` since `D`, in the sense +that "what does `M` have that did not exist in `D`". The result in this +example would be all the commits, except `A` and `B` (and `D` itself, +of course). ++ +When we want to find out what commits in `M` are contaminated with the +bug introduced by `D` and need fixing, however, we might want to view +only the subset of 'D..M' that are actually descendants of `D`, i.e. +excluding `C` and `K`. This is exactly what the '\--ancestry-path' +option does. Applied to the 'D..M' range, it results in: ++ +----------------------------------------------------------------------- + E-------F + \ \ + G---H---I---J + \ + L--M +----------------------------------------------------------------------- + The '\--simplify-by-decoration' option allows you to view only the big picture of the topology of the history, by omitting commits that are not referenced by tags. Commits are marked as !TREESAME @@ -548,10 +521,10 @@ Bisection Helpers Limit output to the one commit object which is roughly halfway between included and excluded commits. Note that the bad bisection ref -`$GIT_DIR/refs/bisect/bad` is added to the included commits (if it -exists) and the good bisection refs `$GIT_DIR/refs/bisect/good-*` are +`refs/bisect/bad` is added to the included commits (if it +exists) and the good bisection refs `refs/bisect/good-*` are added to the excluded commits (if they exist). Thus, supposing there -are no refs in `$GIT_DIR/refs/bisect/`, if +are no refs in `refs/bisect/`, if ----------------------------------------------------------------------- $ git rev-list --bisect foo ^bar ^baz @@ -572,7 +545,7 @@ one. --bisect-vars:: This calculates the same as `--bisect`, except that refs in -`$GIT_DIR/refs/bisect/` are not used, and except that this outputs +`refs/bisect/` are not used, and except that this outputs text ready to be eval'ed by the shell. These lines will assign the name of the midpoint revision to the variable `bisect_rev`, and the expected number of commits to be tested after `bisect_rev` is tested @@ -586,7 +559,7 @@ number of commits to be tested if `bisect_rev` turns out to be bad to This outputs all the commit objects between the included and excluded commits, ordered by their distance to the included and excluded -commits. Refs in `$GIT_DIR/refs/bisect/` are not used. The farthest +commits. Refs in `refs/bisect/` are not used. The farthest from them is displayed first. (This is the only one displayed by `--bisect`.) + @@ -653,3 +626,161 @@ These options are mostly targeted for packing of git repositories. --do-walk:: Overrides a previous --no-walk. + +Commit Formatting +~~~~~~~~~~~~~~~~~ + +ifdef::git-rev-list[] +Using these options, linkgit:git-rev-list[1] will act similar to the +more specialized family of commit log tools: linkgit:git-log[1], +linkgit:git-show[1], and linkgit:git-whatchanged[1] +endif::git-rev-list[] + +include::pretty-options.txt[] + +--relative-date:: + + Synonym for `--date=relative`. + +--date=(relative|local|default|iso|rfc|short|raw):: + + Only takes effect for dates shown in human-readable format, such + as when using "--pretty". `log.date` config variable sets a default + value for log command's --date option. ++ +`--date=relative` shows dates relative to the current time, +e.g. "2 hours ago". ++ +`--date=local` shows timestamps in user's local timezone. ++ +`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. ++ +`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 +format, often found in E-mail messages. ++ +`--date=short` shows only date but not time, in `YYYY-MM-DD` format. ++ +`--date=raw` shows the date in the internal raw git format `%s %z` format. ++ +`--date=default` shows timestamps in the original timezone +(either committer's or author's). + +ifdef::git-rev-list[] +--header:: + + Print the contents of the commit in raw-format; each record is + separated with a NUL character. +endif::git-rev-list[] + +--parents:: + + Print also the parents of the commit (in the form "commit parent..."). + Also enables parent rewriting, see 'History Simplification' below. + +--children:: + + Print also the children of the commit (in the form "commit child..."). + Also enables parent rewriting, see 'History Simplification' below. + +ifdef::git-rev-list[] +--timestamp:: + Print the raw commit timestamp. +endif::git-rev-list[] + +--left-right:: + + Mark which side of a symmetric diff a commit is reachable from. + Commits from the left side are prefixed with `<` and those from + the right with `>`. If combined with `--boundary`, those + commits are prefixed with `-`. ++ +For example, if you have this topology: ++ +----------------------------------------------------------------------- + y---b---b branch B + / \ / + / . + / / \ + o---x---a---a branch A +----------------------------------------------------------------------- ++ +you would get an output like this: ++ +----------------------------------------------------------------------- + $ git rev-list --left-right --boundary --pretty=oneline A...B + + >bbbbbbb... 3rd on b + >bbbbbbb... 2nd on b + <aaaaaaa... 3rd on a + <aaaaaaa... 2nd on a + -yyyyyyy... 1st on b + -xxxxxxx... 1st on a +----------------------------------------------------------------------- + +--graph:: + + Draw a text-based graphical representation of the commit history + on the left hand side of the output. This may cause extra lines + to be printed in between commits, in order for the graph history + to be drawn properly. ++ +This enables parent rewriting, see 'History Simplification' below. ++ +This implies the '--topo-order' option by default, but the +'--date-order' option may also be specified. + +ifdef::git-rev-list[] +--count:: + Print a number stating how many commits would have been + listed, and suppress all other output. When used together + with '--left-right', instead print the counts for left and + right commits, separated by a tab. When used together with + '--cherry-mark', omit patch equivalent commits from these + counts and print the count for equivalent commits separated + by a tab. +endif::git-rev-list[] + + +ifndef::git-rev-list[] +Diff Formatting +~~~~~~~~~~~~~~~ + +Below are listed options that control the formatting of diff output. +Some of them are specific to linkgit:git-rev-list[1], however other diff +options may be given. See linkgit:git-diff-files[1] for more options. + +-c:: + + With this option, diff output for a merge commit + shows the differences from each of the parents to the merge result + simultaneously instead of showing pairwise diff between a parent + and the result one at a time. Furthermore, it lists only files + which were modified from all parents. + +--cc:: + + This flag implies the '-c' options and further compresses the + patch output by omitting uninteresting hunks whose contents in + the parents have only two variants and the merge result picks + one of them without modification. + +-m:: + + This flag makes the merge commits show the full diff like + regular commits; for each merge parent, a separate log entry + and diff is generated. An exception is that only diff against + the first parent is shown when '--first-parent' option is given; + in that case, the output represents the changes the merge + brought _into_ the then-current branch. + +-r:: + + Show recursive diffs. + +-t:: + + Show the tree objects in the diff output. This implies '-r'. + +-s:: + Suppress diff output. +endif::git-rev-list[] diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt new file mode 100644 index 0000000000..b290b617d4 --- /dev/null +++ b/Documentation/revisions.txt @@ -0,0 +1,230 @@ +SPECIFYING REVISIONS +-------------------- + +A revision parameter '<rev>' typically, but not necessarily, names a +commit object. It uses what is called an 'extended SHA1' +syntax. Here are various ways to spell object names. The +ones listed near the end of this list name trees and +blobs contained in a commit. + +'<sha1>', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e':: + The full SHA1 object name (40-byte hexadecimal string), or + a leading substring that is unique within the repository. + E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both + name the same commit object if there is no other object in + your repository whose object name starts with dae86e. + +'<describeOutput>', e.g. 'v1.7.4.2-679-g3bee7fb':: + Output from `git describe`; i.e. a closest tag, optionally + followed by a dash and a number of commits, followed by a dash, a + 'g', and an abbreviated object name. + +'<refname>', e.g. 'master', 'heads/master', 'refs/heads/master':: + A symbolic ref name. E.g. 'master' typically means the commit + object referenced by 'refs/heads/master'. If you + happen to have both 'heads/master' and 'tags/master', you can + explicitly say 'heads/master' to tell git which one you mean. + When ambiguous, a '<name>' is disambiguated by taking the + first match in the following rules: + + . If '$GIT_DIR/<name>' exists, that is what you mean (this is usually + useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD' + and 'CHERRY_PICK_HEAD'); + + . otherwise, 'refs/<name>' if it exists; + + . otherwise, 'refs/tags/<refname>' if it exists; + + . otherwise, 'refs/heads/<name>' if it exists; + + . otherwise, 'refs/remotes/<name>' if it exists; + + . otherwise, 'refs/remotes/<name>/HEAD' if it exists. ++ +'HEAD' names the commit on which you based the changes in the working tree. +'FETCH_HEAD' records the branch which you fetched from a remote repository +with your last `git fetch` invocation. +'ORIG_HEAD' is created by commands that move your 'HEAD' in a drastic +way, to record the position of the 'HEAD' before their operation, so that +you can easily change the tip of the branch back to the state before you ran +them. +'MERGE_HEAD' records the commit(s) which you are merging into your branch +when you run `git merge`. +'CHERRY_PICK_HEAD' records the commit which you are cherry-picking +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. + +'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: + A ref followed by the suffix '@' with a date specification + enclosed in a brace + pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 + second ago\}' or '\{1979-02-26 18:30:00\}') specifies the value + of the ref at a prior point in time. This suffix may only be + used immediately following a ref name and the ref must have an + existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state + of your *local* ref at a given time; e.g., what was in your local + 'master' branch last week. If you want to look at commits made during + certain times, see '--since' and '--until'. + +'<refname>@\{<n>\}', e.g. 'master@\{1\}':: + A ref followed by the suffix '@' with an ordinal specification + enclosed in a brace pair (e.g. '\{1\}', '\{15\}') specifies + the n-th prior value of that ref. For example 'master@\{1\}' + is the immediate prior value of 'master' while 'master@\{5\}' + is the 5th prior value of 'master'. This suffix may only be used + immediately following a ref name and the ref must have an existing + log ('$GIT_DIR/logs/<refname>'). + +'@\{<n>\}', e.g. '@\{1\}':: + You can use the '@' construct with an empty ref part to get at a + reflog entry of the current branch. For example, if you are on + branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'. + +'@\{-<n>\}', e.g. '@\{-1\}':: + The construct '@\{-<n>\}' means the <n>th branch checked out + before the current one. + +'<refname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: + The suffix '@\{upstream\}' to a ref (short form '<refname>@\{u\}') refers to + the branch the ref is set to build on top of. A missing ref defaults + to the current branch. + +'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: + A suffix '{caret}' to a revision parameter means the first parent of + that commit object. '{caret}<n>' means the <n>th parent (i.e. + '<rev>{caret}' + is equivalent to '<rev>{caret}1'). As a special rule, + '<rev>{caret}0' means the commit itself and is used when '<rev>' is the + object name of a tag object that refers to a commit object. + +'<rev>{tilde}<n>', e.g. 'master{tilde}3':: + A suffix '{tilde}<n>' to a revision parameter means the commit + object that is the <n>th generation grand-parent of the named + commit object, following only the first parents. I.e. '<rev>{tilde}3' is + equivalent to '<rev>{caret}{caret}{caret}' which is equivalent to + '<rev>{caret}1{caret}1{caret}1'. See below for an illustration of + the usage of this form. + +'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}':: + A suffix '{caret}' followed by an object type name enclosed in + brace pair means the object + could be a tag, and dereference the tag recursively until an + object of that type is found or the object cannot be + dereferenced anymore (in which case, barf). '<rev>{caret}0' + is a short-hand for '<rev>{caret}\{commit\}'. + +'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}':: + A suffix '{caret}' followed by an empty brace pair + means the object could be a tag, + and dereference the tag recursively until a non-tag object is + found. + +'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}':: + A suffix '{caret}' to a revision parameter, followed by a brace + pair that contains a text led by a slash, + is the same as the ':/fix nasty bug' syntax below except that + it returns the youngest matching commit which is reachable from + the '<rev>' before '{caret}'. + +':/<text>', e.g. ':/fix nasty bug':: + A colon, followed by a slash, followed by a text, names + a commit whose commit message matches the specified regular expression. + This name returns the youngest matching commit which is + reachable from any ref. If the commit message starts with a + '!' you have to repeat that; the special sequence ':/!', + followed by something else than '!', is reserved for now. + The regular expression can match any part of the commit message. To + match messages starting with a string, one can use e.g. ':/^foo'. + +'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README':: + A suffix ':' followed by a path names the blob or tree + at the given path in the tree-ish object named by the part + before the colon. + ':path' (with an empty part before the colon) + is a special case of the syntax described next: content + recorded in the index at the given path. + A path starting with './' or '../' is relative to the current working directory. + The given path will be converted to be relative to the working tree's root directory. + This is most useful to address a blob or tree from a commit or tree that has + the same tree structure as the working tree. + +':<n>:<path>', e.g. ':0:README', ':README':: + A colon, optionally followed by a stage number (0 to 3) and a + colon, followed by a path, names a blob object in the + index at the given path. A missing stage number (and the colon + that follows it) names a stage 0 entry. During a merge, stage + 1 is the common ancestor, stage 2 is the target branch's version + (typically the current branch), and stage 3 is the version from + the branch which is being merged. + +Here is an illustration, by Jon Loeliger. Both commit nodes B +and C are parents of commit node A. Parent commits are ordered +left-to-right. + +........................................ +G H I J + \ / \ / + D E F + \ | / \ + \ | / | + \|/ | + B C + \ / + \ / + A +........................................ + + A = = A^0 + B = A^ = A^1 = A~1 + C = A^2 = A^2 + D = A^^ = A^1^1 = A~2 + E = B^2 = A^^2 + F = B^3 = A^^3 + G = A^^^ = A^1^1^1 = A~3 + H = D^2 = B^^2 = A^^^2 = A~2^2 + I = F^ = B^3^ = A^^3^ + J = F^2 = B^3^2 = A^^3^2 + + +SPECIFYING RANGES +----------------- + +History traversing commands such as `git log` operate on a set +of commits, not just a single commit. To these commands, +specifying a single revision with the notation described in the +previous section means the set of commits reachable from that +commit, following the commit ancestry chain. + +To exclude commits reachable from a commit, a prefix '{caret}' +notation is used. E.g. '{caret}r1 r2' means commits reachable +from 'r2' but exclude the ones reachable from 'r1'. + +This set operation appears so often that there is a shorthand +for it. When you have two commits 'r1' and 'r2' (named according +to the syntax explained in SPECIFYING REVISIONS above), you can ask +for commits that are reachable from r2 excluding those that are reachable +from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. + +A similar notation 'r1\...r2' is called symmetric difference +of 'r1' and 'r2' and is defined as +'r1 r2 --not $(git merge-base --all r1 r2)'. +It is the set of commits that are reachable from either one of +'r1' or 'r2' but not from both. + +Two other shorthands for naming a set that is formed by a commit +and its parent commits exist. The 'r1{caret}@' notation means all +parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes +all of its parents. + +Here are a handful of examples: + + D G H D + D F G H I J D F + ^G D H D + ^D B E I J F B + B...C G H D E B C + ^D B C E I J F B C + C^@ I J F + F^! D G H D F diff --git a/Documentation/sequencer.txt b/Documentation/sequencer.txt new file mode 100644 index 0000000000..3e6df338be --- /dev/null +++ b/Documentation/sequencer.txt @@ -0,0 +1,9 @@ +--reset:: + Forget about the current operation in progress. Can be used + to clear the sequencer state after a failed cherry-pick or + revert. + +--continue:: + Continue the operation in progress using the information in + '.git/sequencer'. Can be used to continue after resolving + conflicts in a failed cherry-pick or revert. diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt new file mode 100644 index 0000000000..49b3d52952 --- /dev/null +++ b/Documentation/technical/api-argv-array.txt @@ -0,0 +1,46 @@ +argv-array API +============== + +The argv-array API allows one to dynamically build and store +NULL-terminated lists. An argv-array maintains the invariant that the +`argv` member always points to a non-NULL array, and that the array is +always NULL-terminated at the element pointed to by `argv[argc]`. This +makes the result suitable for passing to functions expecting to receive +argv from main(), or the link:api-run-command.html[run-command API]. + +The link:api-string-list.html[string-list API] is similar, but cannot be +used for these purposes; instead of storing a straight string pointer, +it contains an item structure with a `util` field that is not compatible +with the traditional argv interface. + +Each `argv_array` manages its own memory. Any strings pushed into the +array are duplicated, and all memory is freed by argv_array_clear(). + +Data Structures +--------------- + +`struct argv_array`:: + + A single array. This should be initialized by assignment from + `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv` + member contains the actual array; the `argc` member contains the + number of elements in the array, not including the terminating + NULL. + +Functions +--------- + +`argv_array_init`:: + Initialize an array. This is no different than assigning from + `ARGV_ARRAY_INIT`. + +`argv_array_push`:: + Push a copy of a string onto the end of the array. + +`argv_array_pushf`:: + 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_clear`:: + Free all memory associated with the array and return it to the + initial, empty state. diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index 5cb2b0590a..b0cafe87be 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -49,6 +49,8 @@ Additionally, if `foo` is a new command, there are 3 more things to do: . Add an entry for `git-foo` to `command-list.txt`. +. Add an entry for `/git-foo` to `.gitignore`. + How a built-in is called ------------------------ diff --git a/Documentation/technical/api-diff.txt b/Documentation/technical/api-diff.txt index 20b0241d30..2d2ebc04b7 100644 --- a/Documentation/technical/api-diff.txt +++ b/Documentation/technical/api-diff.txt @@ -32,7 +32,7 @@ Calling sequence * As you find different pairs of files, call `diff_change()` to feed modified files, `diff_addremove()` to feed created or deleted files, - or `diff_unmerged()` to feed a file whose state is 'unmerged' to the + or `diff_unmerge()` to feed a file whose state is 'unmerged' to the API. These are thin wrappers to a lower-level `diff_queue()` function that is flexible enough to record any of these kinds of changes. @@ -50,7 +50,7 @@ Data structures This is the internal representation for a single file (blob). It records the blob object name (if known -- for a work tree file it typically is a NUL SHA-1), filemode and pathname. This is what the -`diff_addremove()`, `diff_change()` and `diff_unmerged()` synthesize and +`diff_addremove()`, `diff_change()` and `diff_unmerge()` synthesize and feed `diff_queue()` function with. * `struct diff_filepair` diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt index 9d97eaa9de..ce363b6305 100644 --- a/Documentation/technical/api-gitattributes.txt +++ b/Documentation/technical/api-gitattributes.txt @@ -11,27 +11,15 @@ Data Structure `struct git_attr`:: An attribute is an opaque object that is identified by its name. - Pass the name and its length to `git_attr()` function to obtain - the object of this type. The internal representation of this - structure is of no interest to the calling programs. + Pass the name to `git_attr()` function to obtain the object of + this type. The internal representation of this structure is + of no interest to the calling programs. The name of the + attribute can be retrieved by calling `git_attr_name()`. `struct git_attr_check`:: This structure represents a set of attributes to check in a call - to `git_checkattr()` function, and receives the results. - - -Calling Sequence ----------------- - -* Prepare an array of `struct git_attr_check` to define the list of - attributes you would want to check. To populate this array, you would - need to define necessary attributes by calling `git_attr()` function. - -* Call git_checkattr() to check the attributes for the path. - -* Inspect `git_attr_check` structure to see how each of the attribute in - the array is defined for the path. + to `git_check_attr()` function, and receives the results. Attribute Values @@ -57,6 +45,19 @@ If none of the above returns true, `.value` member points at a string value of the attribute for the path. +Querying Specific Attributes +---------------------------- + +* Prepare an array of `struct git_attr_check` to define the list of + attributes you would want to check. To populate this array, you would + need to define necessary attributes by calling `git_attr()` function. + +* Call `git_check_attr()` to check the attributes for the path. + +* Inspect `git_attr_check` structure to see how each of the attribute in + the array is defined for the path. + + Example ------- @@ -72,18 +73,18 @@ static void setup_check(void) { if (check[0].attr) return; /* already done */ - check[0].attr = git_attr("crlf", 4); - check[1].attr = git_attr("ident", 5); + check[0].attr = git_attr("crlf"); + check[1].attr = git_attr("ident"); } ------------ -. Call `git_checkattr()` with the prepared array of `struct git_attr_check`: +. Call `git_check_attr()` with the prepared array of `struct git_attr_check`: ------------ const char *path; setup_check(); - git_checkattr(path, ARRAY_SIZE(check), check); + git_check_attr(path, ARRAY_SIZE(check), check); ------------ . Act on `.value` member of the result, left in `check[]`: @@ -108,4 +109,20 @@ static void setup_check(void) } ------------ -(JC) + +Querying All Attributes +----------------------- + +To get the values of all attributes associated with a file: + +* Call `git_all_attrs()`, which returns an array of `git_attr_check` + structures. + +* Iterate over the `git_attr_check` array to examine the attribute + names and values. The name of the attribute described by a + `git_attr_check` object can be retrieved via + `git_attr_name(check[i].attr)`. (Please note that no items will be + returned for unset attributes, so `ATTR_UNSET()` will return false + for all returned `git_array_check` objects.) + +* Free the `git_array_check` array. diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt new file mode 100644 index 0000000000..9dc1bed768 --- /dev/null +++ b/Documentation/technical/api-merge.txt @@ -0,0 +1,104 @@ +merge API +========= + +The merge API helps a program to reconcile two competing sets of +improvements to some files (e.g., unregistered changes from the work +tree versus changes involved in switching to a new branch), reporting +conflicts if found. The library called through this API is +responsible for a few things. + + * determining which trees to merge (recursive ancestor consolidation); + + * lining up corresponding files in the trees to be merged (rename + detection, subtree shifting), reporting edge cases like add/add + and rename/rename conflicts to the user; + + * performing a three-way merge of corresponding files, taking + path-specific merge drivers (specified in `.gitattributes`) + into account. + +Data structures +--------------- + +* `mmbuffer_t`, `mmfile_t` + +These store data usable for use by the xdiff backend, for writing and +for reading, respectively. See `xdiff/xdiff.h` for the definitions +and `diff.c` for examples. + +* `struct ll_merge_options` + +This describes the set of options the calling program wants to affect +the operation of a low-level (single file) merge. Some options: + +`virtual_ancestor`:: + Behave as though this were part of a merge between common + ancestors in a recursive merge. + If a helper program is specified by the + `[merge "<driver>"] recursive` configuration, it will + be used (see linkgit:gitattributes[5]). + +`variant`:: + Resolve local conflicts automatically in favor + of one side or the other (as in 'git merge-file' + `--ours`/`--theirs`/`--union`). Can be `0`, + `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or + `XDL_MERGE_FAVOR_UNION`. + +`renormalize`:: + Resmudge and clean the "base", "theirs" and "ours" files + before merging. Use this when the merge is likely to have + overlapped with a change in smudge/clean or end-of-line + normalization rules. + +Low-level (single file) merge +----------------------------- + +`ll_merge`:: + + Perform a three-way single-file merge in core. This is + a thin wrapper around `xdl_merge` that takes the path and + any merge backend specified in `.gitattributes` or + `.git/info/attributes` into account. Returns 0 for a + clean merge. + +Calling sequence: + +* Prepare a `struct ll_merge_options` to record options. + If you have no special requests, skip this and pass `NULL` + as the `opts` parameter to use the default options. + +* Allocate an mmbuffer_t variable for the result. + +* Allocate and fill variables with the file's original content + and two modified versions (using `read_mmfile`, for example). + +* Call `ll_merge()`. + +* Read the merged content from `result_buf.ptr` and `result_buf.size`. + +* Release buffers when finished. A simple + `free(ancestor.ptr); free(ours.ptr); free(theirs.ptr); + free(result_buf.ptr);` will do. + +If the modifications do not merge cleanly, `ll_merge` will return a +nonzero value and `result_buf` will generally include a description of +the conflict bracketed by markers such as the traditional `<<<<<<<` +and `>>>>>>>`. + +The `ancestor_label`, `our_label`, and `their_label` parameters are +used to label the different sides of a conflict if the merge driver +supports this. + +Everything else +--------------- + +Talk about <merge-recursive.h> and merge_file(): + + - merge_trees() to merge with rename detection + - merge_recursive() for ancestor consolidation + - try_merge_command() for other strategies + - conflict format + - merge options + +(Daniel, Miklos, Stephan, JC) diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 50f9e9ac17..4b92514f60 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -115,13 +115,19 @@ There are some macros to easily define options: `OPT__ABBREV(&int_var)`:: Add `\--abbrev[=<n>]`. -`OPT__DRY_RUN(&int_var)`:: +`OPT__COLOR(&int_var, description)`:: + Add `\--color[=<when>]` and `--no-color`. + +`OPT__DRY_RUN(&int_var, description)`:: Add `-n, \--dry-run`. -`OPT__QUIET(&int_var)`:: +`OPT__FORCE(&int_var, description)`:: + Add `-f, \--force`. + +`OPT__QUIET(&int_var, description)`:: Add `-q, \--quiet`. -`OPT__VERBOSE(&int_var)`:: +`OPT__VERBOSE(&int_var, description)`:: Add `-v, \--verbose`. `OPT_GROUP(description)`:: @@ -129,9 +135,14 @@ There are some macros to easily define options: describes the group or an empty string. Start the description with an upper-case letter. -`OPT_BOOLEAN(short, long, &int_var, description)`:: - Introduce a boolean option. - `int_var` is incremented on each use. +`OPT_BOOL(short, long, &int_var, description)`:: + Introduce a boolean option. `int_var` is set to one with + `--option` and set to zero with `--no-option`. + +`OPT_COUNTUP(short, long, &int_var, description)`:: + Introduce a count-up option. + `int_var` is incremented on each use of `--option`, and + reset to zero with `--no-option`. `OPT_BIT(short, long, &int_var, description, mask)`:: Introduce a boolean option. @@ -142,8 +153,9 @@ There are some macros to easily define options: If used, `int_var` is bitwise-anded with the inverted `mask`. `OPT_SET_INT(short, long, &int_var, description, integer)`:: - Introduce a boolean option. - If used, set `int_var` to `integer`. + Introduce an integer option. + `int_var` is set to `integer` with `--option`, and + reset to zero with `--no-option`. `OPT_SET_PTR(short, long, &ptr_var, description, ptr)`:: Introduce a boolean option. @@ -183,13 +195,27 @@ There are some macros to easily define options: arguments. Short options that happen to be digits take precedence over it. +`OPT_COLOR_FLAG(short, long, &int_var, description)`:: + Introduce an option that takes an optional argument that can + have one of three values: "always", "never", or "auto". If the + argument is not given, it defaults to "always". The `--no-` form + works like `--long=never`; it cannot take an argument. If + "always", set `int_var` to 1; if "never", set `int_var` to 0; if + "auto", set `int_var` to 1 if stdout is a tty or a pager, + 0 otherwise. + +`OPT_NOOP_NOARG(short, long)`:: + Introduce an option that has no effect and takes no arguments. + Use it to hide deprecated options that are still to be recognized + and ignored silently. + The last element of the array must be `OPT_END()`. If not stated otherwise, interpret the arguments as follows: * `short` is a character for the short option - (e.g. `\'e\'` for `-e`, use `0` to omit), + (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit), * `long` is a string for the long option (e.g. `"example"` for `\--example`, use `NULL` to omit), @@ -216,10 +242,10 @@ The function must be defined in this form: The callback mechanism is as follows: * Inside `func`, the only interesting member of the structure - given by `opt` is the void pointer `opt->value`. - `\*opt->value` will be the value that is saved into `var`, if you + given by `opt` is the void pointer `opt\->value`. + `\*opt\->value` will be the value that is saved into `var`, if you use `OPT_CALLBACK()`. - For example, do `*(unsigned long *)opt->value = 42;` to get 42 + For example, do `*(unsigned long *)opt\->value = 42;` to get 42 into an `unsigned long` variable. * Return value `0` indicates success and non-zero return diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt new file mode 100644 index 0000000000..dbbea95db7 --- /dev/null +++ b/Documentation/technical/api-ref-iteration.txt @@ -0,0 +1,81 @@ +ref iteration API +================= + + +Iteration of refs is done by using an iterate function which will call a +callback function for every ref. The callback function has this +signature: + + int handle_one_ref(const char *refname, const unsigned char *sha1, + int flags, void *cb_data); + +There are different kinds of iterate functions which all take a +callback of this type. The callback is then called for each found ref +until the callback returns nonzero. The returned value is then also +returned by the iterate function. + +Iteration functions +------------------- + +* `head_ref()` just iterates the head ref. + +* `for_each_ref()` iterates all refs. + +* `for_each_ref_in()` iterates all refs which have a defined prefix and + strips that prefix from the passed variable refname. + +* `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`, + `for_each_replace_ref()` iterate refs from the respective area. + +* `for_each_glob_ref()` iterates all refs that match the specified glob + pattern. + +* `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined. + +* `head_ref_submodule()`, `for_each_ref_submodule()`, + `for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`, + `for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()` + do the same as the functions descibed above but for a specified + submodule. + +* `for_each_rawref()` can be used to learn about broken ref and symref. + +* `for_each_reflog()` iterates each reflog file. + +Submodules +---------- + +If you want to iterate the refs of a submodule you first need to add the +submodules object database. You can do this by a code-snippet like +this: + + const char *path = "path/to/submodule" + if (!add_submodule_odb(path)) + die("Error submodule '%s' not populated.", path); + +`add_submodule_odb()` will return an non-zero value on success. If you +do not do this you will get an error for each ref that it does not point +to a valid object. + +Note: As a side-effect of this you can not safely assume that all +objects you lookup are available in superproject. All submodule objects +will be available the same way as the superprojects objects. + +Example: +-------- + +---- +static int handle_remote_ref(const char *refname, + const unsigned char *sha1, int flags, void *cb_data) +{ + struct strbuf *output = cb_data; + strbuf_addf(output, "%s\n", refname); + return 0; +} + +... + + struct strbuf output = STRBUF_INIT; + for_each_remote_ref(handle_remote_ref, &output); + printf("%s", output.buf); +---- diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index b26c28133c..f18b4f4817 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -51,7 +51,7 @@ The functions above do the following: ENOENT; a diagnostic is printed only if .silent_exec_failure is 0. . Otherwise, the program is run. If it terminates regularly, its exit - code is returned. No diagnistic is printed, even if the exit code is + code is returned. No diagnostic is printed, even if the exit code is non-zero. . If the program terminated due to a signal, then the return value is the @@ -64,8 +64,8 @@ The functions above do the following: `start_async`:: Run a function asynchronously. Takes a pointer to a `struct - async` that specifies the details and returns a pipe FD - from which the caller reads. See below for details. + async` that specifies the details and returns a set of pipe FDs + for communication with the function. See below for details. `finish_async`:: @@ -135,7 +135,7 @@ stderr as follows: .in: The FD must be readable; it becomes child's stdin. .out: The FD must be writable; it becomes child's stdout. - .err > 0 is not supported. + .err: The FD must be writable; it becomes child's stderr. The specified FD is closed by start_command(), even if it fails to run the sub-process! @@ -180,17 +180,47 @@ The caller: struct async variable; 2. initializes .proc and .data; 3. calls start_async(); -4. processes the data by reading from the fd in .out; -5. closes .out; +4. processes communicates with proc through .in and .out; +5. closes .in and .out; 6. calls finish_async(). +The members .in, .out are used to provide a set of fd's for +communication between the caller and the callee as follows: + +. Specify 0 to have no file descriptor passed. The callee will + receive -1 in the corresponding argument. + +. Specify < 0 to have a pipe allocated; start_async() replaces + with the pipe FD in the following way: + + .in: Returns the writable pipe end into which the caller + writes; the readable end of the pipe becomes the function's + in argument. + + .out: Returns the readable pipe end from which the caller + reads; the writable end of the pipe becomes the function's + out argument. + + The caller of start_async() must close the returned FDs after it + has completed reading from/writing from them. + +. Specify a file descriptor > 0 to be used by the function: + + .in: The FD must be readable; it becomes the function's in. + .out: The FD must be writable; it becomes the function's out. + + The specified FD is closed by start_async(), even if it fails to + run the function. + The function pointer in .proc has the following signature: - int proc(int fd, void *data); + int proc(int in, int out, void *data); -. fd specifies a writable file descriptor to which the function must - write the data that it produces. The function *must* close this - descriptor before it returns. +. in, out specifies a set of file descriptors to which the function + must read/write the data that it needs/produces. The function + *must* close these descriptors before it returns. A descriptor + may be -1 if the caller did not configure a descriptor for that + direction. . data is the value that the caller has specified in the .data member of struct async. @@ -201,12 +231,13 @@ The function pointer in .proc has the following signature: There are serious restrictions on what the asynchronous function can do -because this facility is implemented by a pipe to a forked process on -UNIX, but by a thread in the same address space on Windows: +because this facility is implemented by a thread in the same address +space on most platforms (when pthreads is available), but by a pipe to +a forked process otherwise: . It cannot change the program's state (global variables, environment, - etc.) in a way that the caller notices; in other words, .out is the - only communication channel to the caller. + etc.) in a way that the caller notices; in other words, .in and .out + are the only communication channels to the caller. . It must not change the program's state that the caller of the facility also uses. diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-sha1-array.txt new file mode 100644 index 0000000000..4a4bae8109 --- /dev/null +++ b/Documentation/technical/api-sha1-array.txt @@ -0,0 +1,79 @@ +sha1-array API +============== + +The sha1-array API provides storage and manipulation of sets of SHA1 +identifiers. The emphasis is on storage and processing efficiency, +making them suitable for large lists. Note that the ordering of items is +not preserved over some operations. + +Data Structures +--------------- + +`struct sha1_array`:: + + A single array of SHA1 hashes. This should be initialized by + assignment from `SHA1_ARRAY_INIT`. The `sha1` member contains + the actual data. The `nr` member contains the number of items in + the set. The `alloc` and `sorted` members are used internally, + and should not be needed by API callers. + +Functions +--------- + +`sha1_array_append`:: + Add an item to the set. The sha1 will be placed at the end of + 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 + sha1. If not found, returns a negative integer. If the array is + not sorted, this function has the side effect of sorting it. + +`sha1_array_clear`:: + Free all memory associated with the array and return it to the + initial, empty state. + +`sha1_array_for_each_unique`:: + Efficiently iterate over each unique element of the list, + executing the callback function for each one. If the array is + not sorted, this function has the side effect of sorting it. + +Examples +-------- + +----------------------------------------- +void print_callback(const unsigned char sha1[20], + void *data) +{ + printf("%s\n", sha1_to_hex(sha1)); +} + +void some_func(void) +{ + struct sha1_array hashes = SHA1_ARRAY_INIT; + unsigned char sha1[20]; + + /* Read objects into our set */ + while (read_object_from_stdin(sha1)) + sha1_array_append(&hashes, sha1); + + /* Check if some objects are in our set */ + while (read_object_from_stdin(sha1)) { + if (sha1_array_lookup(&hashes, sha1) >= 0) + printf("it's in there!\n"); + + /* + * Print the unique set of objects. We could also have + * avoided adding duplicate objects in the first place, + * but we would end up re-sorting the array repeatedly. + * Instead, this will sort once and then skip duplicates + * in linear time. + */ + sha1_array_for_each_unique(&hashes, print_callback, NULL); +} +----------------------------------------- diff --git a/Documentation/technical/api-sigchain.txt b/Documentation/technical/api-sigchain.txt new file mode 100644 index 0000000000..9e1189ef01 --- /dev/null +++ b/Documentation/technical/api-sigchain.txt @@ -0,0 +1,41 @@ +sigchain API +============ + +Code often wants to set a signal handler to clean up temporary files or +other work-in-progress when we die unexpectedly. For multiple pieces of +code to do this without conflicting, each piece of code must remember +the old value of the handler and restore it either when: + + 1. The work-in-progress is finished, and the handler is no longer + necessary. The handler should revert to the original behavior + (either another handler, SIG_DFL, or SIG_IGN). + + 2. The signal is received. We should then do our cleanup, then chain + to the next handler (or die if it is SIG_DFL). + +Sigchain is a tiny library for keeping a stack of handlers. Your handler +and installation code should look something like: + +------------------------------------------ + void clean_foo_on_signal(int sig) + { + clean_foo(); + sigchain_pop(sig); + raise(sig); + } + + void other_func() + { + sigchain_push_common(clean_foo_on_signal); + mess_up_foo(); + clean_foo(); + } +------------------------------------------ + +Handlers are given the typedef of sigchain_fun. This is the same type +that is given to signal() or sigaction(). It is perfectly reasonable to +push SIG_DFL or SIG_IGN onto the stack. + +You can sigchain_push and sigchain_pop individual signals. For +convenience, sigchain_push_common will push the handler onto the stack +for many common signals. diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index a0e0f850f8..afe2759951 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -199,6 +199,10 @@ character if the letter `n` appears after a `%`. The function returns the length of the placeholder recognized and `strbuf_expand()` skips over it. + +The format `%%` is automatically expanded to a single `%` as a quoting +mechanism; callers do not need to handle the `%` placeholder themselves, +and the callback function will not be invoked for this placeholder. ++ All other characters (non-percent and not skipped ones) are copied verbatim to the strbuf. If the callback returned zero, meaning that the placeholder is unknown, then the percent sign is copied, too. @@ -214,6 +218,13 @@ which can be used by the programmer of the callback as she sees fit. placeholder and replacement string. The array needs to be terminated by an entry with placeholder set to NULL. +`strbuf_addbuf_percentquote`:: + + Append the contents of one strbuf to another, quoting any + percent signs ("%") into double-percents ("%%") in the + destination. This is useful for literal data to be fed to either + strbuf_expand or to the *printf family of functions. + `strbuf_addf`:: Add a formatted string to the buffer. diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 293bb15d20..ce24eb96f5 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -29,6 +29,9 @@ 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 individual items of an unsorted list using + `unsorted_string_list_delete_item`. + . Finally it should free the list using `string_list_clear`. Example: @@ -38,8 +41,8 @@ struct string_list list; int i; memset(&list, 0, sizeof(struct string_list)); -string_list_append("foo", &list); -string_list_append("bar", &list); +string_list_append(&list, "foo"); +string_list_append(&list, "bar"); for (i = 0; i < list.nr; i++) printf("%s\n", list.items[i].string) ---- @@ -104,10 +107,21 @@ write `string_list_insert(...)->util = ...;`. `unsorted_string_list_has_string`:: It's like `string_list_has_string()` but for unsorted lists. + +`unsorted_string_list_lookup`:: + + It's like `string_list_lookup()` but for unsorted lists. + -This function needs to look through all items, as opposed to its +The above two functions need to look through all items, as opposed to their counterpart for sorted lists, which performs a binary search. +`unsorted_string_list_delete_item`:: + + Remove an item from a string_list. The `string` pointer of the items + will be freed in case the `strdup_strings` member of the string_list + is set. The third parameter controls if the `util` pointer of the + items should be freed or not. + Data structures --------------- diff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt index 55b728632c..14af37c3f1 100644 --- a/Documentation/technical/api-tree-walking.txt +++ b/Documentation/technical/api-tree-walking.txt @@ -42,6 +42,8 @@ information. * `data` can be anything the `fn` callback would want to use. +* `show_all_errors` tells whether to stop at the first error or not. + Initializing ------------ diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt new file mode 100644 index 0000000000..8930b3fabc --- /dev/null +++ b/Documentation/technical/index-format.txt @@ -0,0 +1,186 @@ +GIT index 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. + + - A 12-byte header consisting of + + 4-byte signature: + The signature is { 'D', 'I', 'R', 'C' } (stands for "dircache") + + 4-byte version number: + The current supported versions are 2 and 3. + + 32-bit number of index entries. + + - A number of sorted index entries (see below). + + - Extensions + + Extensions are identified by signature. Optional extensions can + be ignored if GIT does not understand them. + + GIT currently supports cached tree and resolve undo extensions. + + 4-byte extension signature. If the first byte is 'A'..'Z' the + extension is optional and can be ignored. + + 32-bit size of the extension + + Extension data + + - 160-bit SHA-1 over the content of the index file before this + checksum. + +== Index entry + + Index entries are sorted in ascending order on the name field, + interpreted as a string of unsigned bytes (i.e. memcmp() order, no + localization, no special casing of directory separator '/'). Entries + with the same name are sorted by their stage field. + + 32-bit ctime seconds, the last time a file's metadata changed + this is stat(2) data + + 32-bit ctime nanosecond fractions + this is stat(2) data + + 32-bit mtime seconds, the last time a file's data changed + this is stat(2) data + + 32-bit mtime nanosecond fractions + this is stat(2) data + + 32-bit dev + this is stat(2) data + + 32-bit ino + this is stat(2) data + + 32-bit mode, split into (high to low bits) + + 4-bit object type + valid values in binary are 1000 (regular file), 1010 (symbolic link) + and 1110 (gitlink) + + 3-bit unused + + 9-bit unix permission. Only 0755 and 0644 are valid for regular files. + Symbolic links and gitlinks have value 0 in this field. + + 32-bit uid + this is stat(2) data + + 32-bit gid + this is stat(2) data + + 32-bit file size + This is the on-disk size from stat(2), truncated to 32-bit. + + 160-bit SHA-1 for the represented object + + A 16-bit 'flags' field split into (high to low bits) + + 1-bit assume-valid flag + + 1-bit extended flag (must be zero in version 2) + + 2-bit stage (during merge) + + 12-bit name length if the length is less than 0xFFF; otherwise 0xFFF + is stored in this field. + + (Version 3) A 16-bit field, only applicable if the "extended flag" + above is 1, split into (high to low bits). + + 1-bit reserved for future + + 1-bit skip-worktree flag (used by sparse checkout) + + 1-bit intent-to-add flag (used by "git add -N") + + 13-bit unused, must be zero + + Entry path name (variable length) relative to top level directory + (without leading slash). '/' is used as path separator. The special + path components ".", ".." and ".git" (without quotes) are disallowed. + Trailing slash is also disallowed. + + The exact encoding is undefined, but the '.' and '/' characters + are encoded in 7-bit ASCII and the encoding cannot contain a NUL + byte (iow, this is a UNIX pathname). + + 1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes + while keeping the name NUL-terminated. + +== Extensions + +=== Cached tree + + Cached tree extension contains pre-computed hashes for trees that can + be derived from the index. It helps speed up tree object generation + from index for a new commit. + + When a path is updated in index, the path must be invalidated and + removed from tree cache. + + The signature for this extension is { 'T', 'R', 'E', 'E' }. + + A series of entries fill the entire extension; each of which + consists of: + + - NUL-terminated path component (relative to its parent directory); + + - ASCII decimal number of entries in the index that is covered by the + tree this entry represents (entry_count); + + - A space (ASCII 32); + + - ASCII decimal number that represents the number of subtrees this + tree has; + + - A newline (ASCII 10); and + + - 160-bit object name for the object that would result from writing + this span of index as a tree. + + An entry can be in an invalidated state and is represented by having + -1 in the entry_count field. In this case, there is no object name + and the next entry starts immediately after the newline. + + The entries are written out in the top-down, depth-first order. The + first entry represents the root level of the repository, followed by the + first subtree---let's call this A---of the root level (with its name + relative to the root level), followed by the first subtree of A (with + its name relative to A), ... + +=== Resolve undo + + A conflict is represented in the index as a set of higher stage entries. + When a conflict is resolved (e.g. with "git add path"), these higher + stage entries will be removed and a stage-0 entry with proper resoluton + is added. + + When these higher stage entries are removed, they are saved in the + resolve undo extension, so that conflicts can be recreated (e.g. with + "git checkout -m"), in case users want to redo a conflict resolution + from scratch. + + The signature for this extension is { 'R', 'E', 'U', 'C' }. + + A series of entries fill the entire extension; each of which + consists of: + + - NUL-terminated pathname the entry describes (relative to the root of + the repository, i.e. full pathname); + + - Three NUL-terminated ASCII octal numbers, entry mode of entries in + stage 1 to 3 (a missing stage is represented by "0" in this field); + and + + - At most three 160-bit object names of the entry in stages from 1 to 3 + (nothing is written for a missing stage). + diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 7950eeeda4..546980c0a4 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -36,7 +36,7 @@ Git Transport The Git transport starts off by sending the command and repository on the wire using the pkt-line format, followed by a NUL byte and a -hostname paramater, terminated by a NUL byte. +hostname parameter, terminated by a NUL byte. 0032git-upload-pack /project.git\0host=myserver.com\0 @@ -60,6 +60,13 @@ process on the server side over the Git protocol is this: "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" | nc -v example.com 9418 +If the server refuses the request for some reasons, it could abort +gracefully with an error message. + +---- + error-line = PKT-LINE("ERR" SP explanation-text) +---- + SSH Transport ------------- @@ -149,7 +156,7 @@ advertisement list at all, but other refs may still appear. The stream MUST include capability declarations behind a NUL on the first ref. The peeled value of a ref (that is "ref^{}") MUST be immediately after the ref itself, if presented. A conforming server -MUST peel the ref if its an annotated tag. +MUST peel the ref if it's an annotated tag. ---- advertised-refs = (no-refs / list-of-refs) @@ -179,34 +186,36 @@ and descriptions. Packfile Negotiation -------------------- -After reference and capabilities discovery, the client can decide -to terminate the connection by sending a flush-pkt, telling the -server it can now gracefully terminate (as happens with the ls-remote -command) or it can enter the negotiation phase, where the client and -server determine what the minimal packfile necessary for transport is. - -Once the client has the initial list of references that the server -has, as well as the list of capabilities, it will begin telling the -server what objects it wants and what objects it has, so the server -can make a packfile that only contains the objects that the client needs. -The client will also send a list of the capabilities it wants to be in -effect, out of what the server said it could do with the first 'want' line. +After reference and capabilities discovery, the client can decide to +terminate the connection by sending a flush-pkt, telling the server it can +now gracefully terminate, and disconnect, when it does not need any pack +data. This can happen with the ls-remote command, and also can happen when +the client already is up-to-date. + +Otherwise, it enters the negotiation phase, where the client and +server determine what the minimal packfile necessary for transport is, +by telling the server what objects it wants, its shallow objects +(if any), and the maximum commit depth it wants (if any). The client +will also send a list of the capabilities it wants to be in effect, +out of what the server said it could do with the first 'want' line. ---- upload-request = want-list - have-list - compute-end + *shallow-line + *1depth-request + flush-pkt want-list = first-want *additional-want - flush-pkt + + shallow-line = PKT_LINE("shallow" SP obj-id) + + depth-request = PKT_LINE("deepen" SP depth) first-want = PKT-LINE("want" SP obj-id SP capability-list LF) additional-want = PKT-LINE("want" SP obj-id LF) - have-list = *have-line - have-line = PKT-LINE("have" SP obj-id LF) - compute-end = flush-pkt / PKT-LINE("done") + depth = 1*DIGIT ---- Clients MUST send all the obj-ids it wants from the reference @@ -215,21 +224,64 @@ discovery phase as 'want' lines. Clients MUST send at least one obj-id in a 'want' command which did not appear in the response obtained through ref discovery. -If client is requesting a shallow clone, it will now send a 'deepen' -line with the depth it is requesting. +The client MUST write all obj-ids which it only has shallow copies +of (meaning that it does not have the parents of a commit) as +'shallow' lines so that the server is aware of the limitations of +the client's history. Clients MUST NOT mention an obj-id which +it does not know exists on the server. + +The client now sends the maximum commit history depth it wants for +this transaction, which is the number of commits it wants from the +tip of the history, if any, as a 'deepen' line. A depth of 0 is the +same as not making a depth request. The client does not want to receive +any commits beyond this depth, nor objects needed only to complete +those commits. Commits whose parents are not received as a result are +defined as shallow and marked as such in the server. This information +is sent back to the client in the next step. + +Once all the 'want's and 'shallow's (and optional 'deepen') are +transferred, clients MUST send a flush-pkt, to tell the server side +that it is done sending the list. + +Otherwise, if the client sent a positive depth request, the server +will determine which commits will and will not be shallow and +send this information to the client. If the client did not request +a positive depth, this step is skipped. -Once all the "want"s (and optional 'deepen') are transferred, -clients MUST send a flush-pkt. If the client has all the references -on the server, client flushes and disconnects. +---- + shallow-update = *shallow-line + *unshallow-line + flush-pkt + + shallow-line = PKT-LINE("shallow" SP obj-id) + + unshallow-line = PKT-LINE("unshallow" SP obj-id) +---- -TODO: shallow/unshallow response and document the deepen command in the ABNF. +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 +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 +(that is, its parents will now be sent). The server MUST NOT mark +as unshallow anything which the client has not indicated was shallow. Now the client will send a list of the obj-ids it has using 'have' -lines. In multi_ack mode, the canonical implementation will send up -to 32 of these at a time, then will send a flush-pkt. The canonical -implementation will skip ahead and send the next 32 immediately, -so that there is always a block of 32 "in-flight on the wire" at a -time. +lines, so the server can make a packfile that only contains the objects +that the client needs. In multi_ack mode, the canonical implementation +will send up to 32 of these at a time, then will send a flush-pkt. The +canonical implementation will skip ahead and send the next 32 immediately, +so that there is always a block of 32 "in-flight on the wire" at a time. + +---- + upload-haves = have-list + compute-end + + have-list = *have-line + have-line = PKT-LINE("have" SP obj-id LF) + compute-end = flush-pkt / PKT-LINE("done") +---- If the server reads 'have' lines, it then will respond by ACKing any of the obj-ids the client said it had that the server also has. The @@ -261,7 +313,7 @@ Without either multi_ack or multi_ack_detailed: * upload-pack sends "NAK" on a flush-pkt if no common object has been found yet. If one has been found, and thus an ACK - was already sent, its silent on the flush-pkt. + was already sent, it's silent on the flush-pkt. After the client has gotten enough ACK responses that it can determine that the server has enough information to send an efficient packfile @@ -271,9 +323,9 @@ as common with the server, or the --date-order queue is empty), or the client determines that it wants to give up (in the canonical implementation, this is determined when the client sends 256 'have' lines without getting any of them ACKed by the server - meaning there is nothing in common and -the server should just send all it's objects), then the client will send +the server should just send all of its objects), then the client will send a 'done' command. The 'done' command signals to the server that the client -is ready to receive it's packfile data. +is ready to receive its packfile data. However, the 256 limit *only* turns on in the canonical client implementation if we have received at least one "ACK %s continue" @@ -286,7 +338,7 @@ ACK after 'done' if there is at least one common base and multi_ack or multi_ack_detailed is enabled. The server always sends NAK after 'done' if there is no common base found. -Then the server will start sending it's packfile data. +Then the server will start sending its packfile data. ---- server-response = *ack_multi ack / nak @@ -331,7 +383,7 @@ An incremental update (fetch) response might look like this: C: 0009done\n - S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d\n + S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n S: [PACKFILE] ---- @@ -488,7 +540,7 @@ An example client/server communication might look like this: C: 0000 C: [PACKDATA] - S: 000aunpack ok\n - S: 0014ok refs/heads/debug\n - S: 0026ng refs/heads/master non-fast-forward\n + S: 000eunpack ok\n + S: 0018ok refs/heads/debug\n + S: 002ang refs/heads/master non-fast-forward\n ---- diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 1892d3eeac..b15517fa06 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -60,7 +60,7 @@ doesn't, as in the following diagram: If the client wants x,y and starts out by saying have F,S, the server doesn't know what F,S is. Eventually the client says "have d" and the server sends "ACK d continue" to let the client know to stop -walking down that line (so don't send c-b-a), but its not done yet, +walking down that line (so don't send c-b-a), but it's not done yet, it needs a base for x. The client keeps going with S-R-Q, until a gets reached, at which point the server has a clear base and it all ends. @@ -119,7 +119,7 @@ both. ofs-delta --------- -Server can send, and client understand PACKv2 with delta refering to +Server can send, and client understand PACKv2 with delta referring to its base by position in pack rather than by an obj-id. That is, they can send/read OBJ_OFS_DELTA (aka type 6) in a packfile. @@ -181,7 +181,7 @@ delete-refs ----------- If the server sends back the 'delete-refs' capability, it means that -it is capable of accepting an zero-id value as the target +it is capable of accepting a zero-id value as the target value of a reference update. It is not sent back by the client, it simply informs the client that it can be sent zero-id values to delete references. diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index 2a0e7b8944..00f7e79c44 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -52,8 +52,8 @@ following format: ------------ -`Push:` lines are used by 'git-push' and -`Pull:` lines are used by 'git-pull' and 'git-fetch'. +`Push:` lines are used by 'git push' and +`Pull:` lines are used by 'git pull' and 'git fetch'. Multiple `Push:` and `Pull:` lines may be specified for additional branch mappings. diff --git a/Documentation/urls.txt b/Documentation/urls.txt index d813ceb723..289019478d 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -1,50 +1,57 @@ GIT URLS[[URLS]] ---------------- -One of the following notations can be used -to name the remote repository: +In general, URLs contain information about the transport protocol, the +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: -=============================================================== -- rsync://host.xz/path/to/repo.git/ -- http://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- https://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- git://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/ - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git -=============================================================== - -SSH is the default transport protocol over the network. You can -optionally specify which user to log-in as, and an alternate, -scp-like syntax is also supported. Both syntaxes support -username expansion, as does the native git protocol, but -only the former supports port specification. The following -three are identical to the last three above, respectively: - -=============================================================== -- {startsb}user@{endsb}host.xz:/path/to/repo.git/ -- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/ -- {startsb}user@{endsb}host.xz:path/to/repo.git -=============================================================== - -To sync with a local directory, you can use: - -=============================================================== +- git://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- rsync://host.xz/path/to/repo.git/ + +An alternative scp-like syntax may also be used with the ssh protocol: + +- {startsb}user@{endsb}host.xz:path/to/repo.git/ + +The ssh and git protocols additionally support ~username expansion: + +- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ +- git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ +- {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/ + +For local repositories, also supported by git natively, the following +syntaxes may be used: + - /path/to/repo.git/ - file:///path/to/repo.git/ -=============================================================== ifndef::git-clone[] -They are mostly equivalent, except when cloning. See -linkgit:git-clone[1] for details. +These two syntaxes are mostly equivalent, except when cloning, when +the former implies --local option. See linkgit:git-clone[1] for +details. endif::git-clone[] ifdef::git-clone[] -They are equivalent, except the former implies --local option. +These two syntaxes are mostly equivalent, except the former implies +--local option. endif::git-clone[] +When git doesn't know how to handle a certain transport protocol, it +attempts to use the 'remote-<transport>' remote helper, if one +exists. To explicitly request a remote helper, the following syntax +may be used: + +- <transport>::<address> + +where <address> may be a path, a server and path, or an arbitrary +URL-like string recognized by the specific remote helper being +invoked. See linkgit:git-remote-helpers[1] for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index b169836684..f13a846131 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -344,7 +344,8 @@ Examining branches from a remote repository The "master" branch that was created at the time you cloned is a copy of the HEAD in the repository that you cloned from. That repository may also have had other branches, though, and your local repository -keeps branches which track each of those remote branches, which you +keeps branches which track each of those remote branches, called +remote-tracking branches, which you can view using the "-r" option to linkgit:git-branch[1]: ------------------------------------------------ @@ -359,13 +360,23 @@ $ git branch -r origin/todo ------------------------------------------------ -You cannot check out these remote-tracking branches, but you can -examine them on a branch of your own, just as you would a tag: +In this example, "origin" is called a remote repository, or "remote" +for short. The branches of this repository are called "remote +branches" from our point of view. The remote-tracking branches listed +above were created based on the remote branches at clone time and will +be updated by "git fetch" (hence "git pull") and "git push". See +<<Updating-a-repository-With-git-fetch>> for details. + +You might want to build on one of these remote-tracking branches +on a branch of your own, just as you would for a tag: ------------------------------------------------ $ git checkout -b my-todo-copy origin/todo ------------------------------------------------ +You can also check out "origin/todo" directly to examine it or +write a one-off patch. See <<detached-head,detached head>>. + Note that the name "origin" is just the name that git uses by default to refer to the repository that you cloned from. @@ -397,7 +408,7 @@ is usually a shortcut for the HEAD branch in the repository "origin". For the complete list of paths which git checks for references, and the order it uses to decide which to choose when there are multiple references with the same shorthand name, see the "SPECIFYING -REVISIONS" section of linkgit:git-rev-parse[1]. +REVISIONS" section of linkgit:gitrevisions[7]. [[Updating-a-repository-With-git-fetch]] Updating a repository with git fetch @@ -435,7 +446,7 @@ linux-nfs/master origin/master ------------------------------------------------- -If you run "git fetch <remote>" later, the tracking branches for the +If you run "git fetch <remote>" later, the remote-tracking branches for the named <remote> will be updated. If you examine the file .git/config, you will see that git has added @@ -568,7 +579,7 @@ We have seen several ways of naming commits already: - HEAD: refers to the head of the current branch There are many more; see the "SPECIFYING REVISIONS" section of the -linkgit:git-rev-parse[1] man page for the complete list of ways to +linkgit:gitrevisions[7] man page for the complete list of ways to name revisions. Some examples: ------------------------------------------------- @@ -909,7 +920,7 @@ commits reachable from some head but not from any tag in the repository: $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) ------------------------------------------------- -(See linkgit:git-rev-parse[1] for explanations of commit-selecting +(See linkgit:gitrevisions[7] for explanations of commit-selecting syntax such as `--not`.) [[making-a-release]] @@ -955,7 +966,7 @@ echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new" and then he just cut-and-pastes the output commands after verifying that they look OK. -[[Finding-comments-With-given-Content]] +[[Finding-commits-With-given-Content]] Finding commits referencing a file with given content ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1196,7 +1207,7 @@ the time, you will want to commit your changes before you can merge, and if you don't, then linkgit:git-stash[1] can take these changes away while you're doing the merge, and reapply them afterwards. -If the changes are independant enough, Git will automatically complete +If the changes are independent enough, Git will automatically complete the merge and commit the result (or reuse an existing commit in case of <<fast-forwards,fast-forward>>, see below). On the other hand, if there are conflicts--for example, if the same file is @@ -1635,7 +1646,7 @@ you've checked out. The reflogs are kept by default for 30 days, after which they may be pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn how to control this pruning, and see the "SPECIFYING REVISIONS" -section of linkgit:git-rev-parse[1] for details. +section of linkgit:gitrevisions[7] for details. Note that the reflog history is very different from normal git history. While normal history is shared by every repository that works on the @@ -1700,7 +1711,7 @@ may wish to check the original repository for updates and merge them into your own work. We have already seen <<Updating-a-repository-With-git-fetch,how to -keep remote tracking branches up to date>> with linkgit:git-fetch[1], +keep remote-tracking branches up to date>> with linkgit:git-fetch[1], and how to merge two branches. So you can merge in changes from the original repository's master branch with: @@ -1716,15 +1727,21 @@ one step: $ git pull origin master ------------------------------------------------- -In fact, if you have "master" checked out, then by default "git pull" -merges from the HEAD branch of the origin repository. So often you can +In fact, if you have "master" checked out, then this branch has been +configured by "git clone" to get changes from the HEAD branch of the +origin repository. So often you can accomplish the above with just a simple ------------------------------------------------- $ git pull ------------------------------------------------- -More generally, a branch that is created from a remote branch will pull +This command will fetch changes from the remote branches to your +remote-tracking branches `origin/*`, and merge the default branch into +the current branch. + +More generally, a branch that is created from a remote-tracking branch +will pull by default from that branch. See the descriptions of the branch.<name>.remote and branch.<name>.merge options in linkgit:git-config[1], and the discussion of the `--track` option in @@ -2106,7 +2123,7 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git $ cd work ------------------------------------------------- -Linus's tree will be stored in the remote branch named origin/master, +Linus's tree will be stored in the remote-tracking branch named origin/master, and can be updated using linkgit:git-fetch[1]; you can track other public trees using linkgit:git-remote[1] to set up a "remote" and linkgit:git-fetch[1] to keep them up-to-date; see @@ -2171,11 +2188,14 @@ $ git push mytree release Now to apply some patches from the community. Think of a short snappy name for a branch to hold this patch (or related group of -patches), and create a new branch from the current tip of Linus's -branch: +patches), and create a new branch from a recent stable tag of +Linus's branch. Picking a stable base for your branch will: +1) help you: by avoiding inclusion of unrelated and perhaps lightly +tested changes +2) help future bug hunters that use "git bisect" to find problems ------------------------------------------------- -$ git checkout -b speed-up-spinlocks origin +$ git checkout -b speed-up-spinlocks v2.6.35 ------------------------------------------------- Now you apply the patch(es), run some tests, and commit the change(s). If @@ -2439,9 +2459,9 @@ You have performed no merges into mywork, so it is just a simple linear sequence of patches on top of "origin": ................................................ - o--o--o <-- origin + o--o--O <-- origin \ - o--o--o <-- mywork + a--b--c <-- mywork ................................................ Some more interesting work has been done in the upstream project, and @@ -2797,8 +2817,8 @@ Be aware that commits that the old version of example/master pointed at may be lost, as we saw in the previous section. [[remote-branch-configuration]] -Configuring remote branches ---------------------------- +Configuring remote-tracking branches +------------------------------------ We saw above that "origin" is just a shortcut to refer to the repository that you originally cloned from. This information is @@ -3640,6 +3660,26 @@ Did you forget to 'git add'? Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a' ------------------------------------------------- +In older git versions it could be easily forgotten to commit new or modified +files in a submodule, which silently leads to similar problems as not pushing +the submodule changes. Starting with git 1.7.0 both "git status" and "git diff" +in the superproject show submodules as modified when they contain new or +modified files to protect against accidentally committing such a state. "git +diff" will also add a "-dirty" to the work tree side when generating patch +output or used with the --submodule option: + +------------------------------------------------- +$ git diff +diff --git a/sub b/sub +--- a/sub ++++ b/sub +@@ -1 +1 @@ +-Subproject commit 3f356705649b5d566d97ff843cf193359229a453 ++Subproject commit 3f356705649b5d566d97ff843cf193359229a453-dirty +$ git diff --submodule +Submodule sub 3f35670..3f35670-dirty: +------------------------------------------------- + You also should not rewind branches in a submodule beyond commits that were ever recorded in any superproject. @@ -3830,7 +3870,7 @@ You create a commit object by giving it the tree that describes the state at the time of the commit, and a list of parents: ------------------------------------------------- -$ git commit-tree <tree> -p <parent> [-p <parent2> ..] +$ git commit-tree <tree> -p <parent> [(-p <parent2>)...] ------------------------------------------------- and then giving the reason for the commit on stdin (either through @@ -4231,9 +4271,9 @@ Two things are interesting here: negative numbers in case of different errors--and 0 on success. - the variable `sha1` in the function signature of `get_sha1()` is `unsigned - char \*`, but is actually expected to be a pointer to `unsigned + char {asterisk}`, but is actually expected to be a pointer to `unsigned char[20]`. This variable will contain the 160-bit SHA-1 of the given - commit. Note that whenever a SHA-1 is passed as `unsigned char \*`, it + commit. Note that whenever a SHA-1 is passed as `unsigned char {asterisk}`, it is the binary representation, as opposed to the ASCII representation in hex characters, which is passed as `char *`. |