diff options
Diffstat (limited to 'Documentation')
417 files changed, 30889 insertions, 6457 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index d8edd90406..d62aebd848 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -3,8 +3,10 @@ *.[1-8] *.made *.texi +*.pdf git.info gitman.info howto-index.txt doc.dep cmds-*.txt +manpage-base-url.xsl diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index d2a0a76e6c..45577117c2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -21,30 +21,58 @@ code. For git in general, three rough rules are: As for more concrete guidelines, just imitate the existing code (this is a good guideline, no matter which project you are -contributing to). But if you must have a list of rules, -here they are. +contributing to). It is always preferable to match the _local_ +convention. New code added to git suite is expected to match +the overall style of existing code. Modifications to existing +code is expected to match the style the surrounding code already +uses (even if it doesn't match the overall style of existing code). + +But if you must have a list of rules, here they are. For shell scripts specifically (not exhaustive): + - We use tabs for indentation. + + - Case arms are indented at the same depth as case and esac lines. + + - Redirection operators should be written with space before, but no + space after them. In other words, write 'echo test >"$file"' + instead of 'echo test> $file' or 'echo test > $file'. Note that + even though it is not required by POSIX to double-quote the + redirection target in a variable (as shown above), our code does so + because some versions of bash issue a warning without the quotes. + - 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. + - If you want to find out if a command is available on the user's + $PATH, you should use 'type <command>', instead of 'which <command>'. + The output of 'which' is not machine parseable and its exit code + is not reliable across platforms. - - We use ${parameter#word} and its [#%] siblings, and their - doubled "longest matching" form. + - We use POSIX compliant parameter substitutions and avoid bashisms; + namely: - - We use Arithmetic Expansion $(( ... )). + - We use ${parameter-word} and its [-=?+] siblings, and their + colon'ed "unset or null" form. + + - 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). @@ -65,6 +93,10 @@ For shell scripts specifically (not exhaustive): are ERE elements not BRE (note that \? and \+ are not even part of BRE -- making them accessible from BRE is a GNU extension). + - Use Git's gettext wrappers in git-sh-i18n to make the user + interface translatable. See "Marking strings for translation" in + po/README. + For C programs: - We use tabs to indent, and interpret tabs as taking up to @@ -105,7 +137,7 @@ For C programs: - Use the API. No, really. We have a strbuf (variable length string), several arrays with the ALLOC_GROW() macro, a - path_list for sorted string lists, a hash map (mapping struct + string_list for sorted string lists, a hash map (mapping struct objects) named "struct decorate", amongst other things. - When you come up with an API, document it. @@ -124,3 +156,61 @@ For C programs: used in the git core command set (unless your command is clearly separate from it, such as an importer to convert random-scm-X repositories to git). + + - When we pass <string, length> pair to functions, we should try to + pass them in that order. + + - Use Git's gettext wrappers to make the user interface + translatable. See "Marking strings for translation" in po/README. + +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 62269e39c4..5d76a84078 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,12 +1,13 @@ 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 + gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt +MAN7_TXT += gitcredentials.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) @@ -17,8 +18,12 @@ DOC_HTML=$(MAN_HTML) ARTICLES = howto-index ARTICLES += everyday ARTICLES += git-tools +ARTICLES += git-bisect-lk2009 # with their own formatting rules. -SP_ARTICLES = howto/revert-branch-rebase howto/using-merge-subtree user-manual +SP_ARTICLES = user-manual +SP_ARTICLES += howto/revert-branch-rebase +SP_ARTICLES += howto/using-merge-subtree +SP_ARTICLES += howto/using-signed-tag-in-pull-request API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) SP_ARTICLES += technical/api-index @@ -32,6 +37,7 @@ DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) prefix?=$(HOME) bindir?=$(prefix)/bin htmldir?=$(prefix)/share/doc/git-doc +pdfdir?=$(prefix)/share/doc/git-doc mandir?=$(prefix)/share/man man1dir=$(mandir)/man1 man5dir=$(mandir)/man5 @@ -40,15 +46,18 @@ man7dir=$(mandir)/man7 ASCIIDOC=asciidoc ASCIIDOC_EXTRA = -MANPAGE_XSL = callouts.xsl +MANPAGE_XSL = manpage-normal.xsl +XMLTO_EXTRA = INSTALL?=install RM ?= rm -f -DOC_REF = origin/man +MAN_REPO = ../../git-manpages +HTML_REPO = ../../git-htmldocs infodir?=$(prefix)/share/info MAKEINFO=makeinfo INSTALL_INFO=install-info DOCBOOK2X_TEXI=docbook2x-texi +DBLATEX=dblatex ifndef PERL_PATH PERL_PATH = /usr/bin/perl endif @@ -56,12 +65,73 @@ endif -include ../config.mak.autogen -include ../config.mak -ifdef ASCIIDOC8 +# +# For asciidoc ... +# -7.1.2, set ASCIIDOC7 +# 8.0-, no extra settings are needed +# + +# +# For docbook-xsl ... +# -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, set ASCIIDOC_ROFF? +# 1.72.0, set DOCBOOK_XSL_172. +# 1.73.0-, no extra settings are needed +# + +ifndef ASCIIDOC7 ASCIIDOC_EXTRA += -a asciidoc7compatible endif ifdef DOCBOOK_XSL_172 -ASCIIDOC_EXTRA += -a docbook-xsl-172 +ASCIIDOC_EXTRA += -a git-asciidoc-no-roff MANPAGE_XSL = manpage-1.72.xsl +else + 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 + endif +endif +ifdef MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m manpage-suppress-sp.xsl +endif + +# Newer DocBook stylesheet emits warning cruft in the output when +# this is not set, and if set it shows an absolute link. Older +# stylesheets simply ignore this parameter. +# +# Distros may want to use MAN_BASE_URL=file:///path/to/git/docs/ +# or similar. +ifndef MAN_BASE_URL +MAN_BASE_URL = file://$(htmldir)/ +endif +XMLTO_EXTRA += -m manpage-base-url.xsl + +# If your target system uses GNU groff, it may try to render +# apostrophes as a "pretty" apostrophe using unicode. This breaks +# cut&paste, so you should set GNU_ROFF to force them to be ASCII +# apostrophes. Unfortunately does not work with non-GNU roff. +ifdef GNU_ROFF +XMLTO_EXTRA += -m manpage-quote-apos.xsl +endif + +SHELL_PATH ?= $(SHELL) +# Shell quote; +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) + +ifdef DEFAULT_PAGER +DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER)) +ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)' +endif + +ifdef DEFAULT_EDITOR +DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) +ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' endif # @@ -73,6 +143,32 @@ endif # yourself - yes, all 6 characters of it! # +QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir +QUIET_SUBDIR1 = + +ifneq ($(findstring $(MAKEFLAGS),w),w) +PRINT_DIR = --no-print-directory +else # "make -w" +NO_SUBDIR = : +endif + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifndef V + QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; + QUIET_XMLTO = @echo ' ' XMLTO $@; + QUIET_DB2TEXI = @echo ' ' DB2TEXI $@; + QUIET_MAKEINFO = @echo ' ' MAKEINFO $@; + QUIET_DBLATEX = @echo ' ' DBLATEX $@; + QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; + QUIET_GEN = @echo ' ' GEN $@; + QUIET_STDERR = 2> /dev/null + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif + all: html man html: $(DOC_HTML) @@ -86,7 +182,11 @@ man7: $(DOC_MAN7) info: git.info gitman.info -install: man +pdf: user-manual.pdf + +install: install-man + +install-man: man $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir) $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir) $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) @@ -104,11 +204,15 @@ install-info: info echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \ fi +install-pdf: pdf + $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir) + $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir) + install-html: html - sh ./install-webdoc.sh $(DESTDIR)$(htmldir) + '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir) -../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE - $(MAKE) -C ../ GIT-VERSION-FILE +../GIT-VERSION-FILE: FORCE + $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE -include ../GIT-VERSION-FILE @@ -116,8 +220,8 @@ install-html: html # Determine "include::" file references in asciidoc files. # doc.dep : $(wildcard *.txt) build-docdep.perl - $(RM) $@+ $@ - $(PERL_PATH) ./build-docdep.perl >$@+ + $(QUIET_GEN)$(RM) $@+ $@ && \ + $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \ mv $@+ $@ -include doc.dep @@ -135,91 +239,127 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) - $(RM) $@ - $(PERL_PATH) ./cmd-list.perl ../command-list.txt + $(QUIET_GEN)$(RM) $@ && \ + $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \ date >$@ clean: $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 - $(RM) *.texi *.texi+ git.info gitman.info + $(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 + $(RM) manpage-base-url.xsl $(MAN_HTML): %.html : %.txt - $(RM) $@+ $@ + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ -%.1 %.5 %.7 : %.xml - $(RM) $@ - xmlto -m $(MANPAGE_XSL) man $< +manpage-base-url.xsl: manpage-base-url.xsl.in + sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ + +%.1 %.5 %.7 : %.xml manpage-base-url.xsl + $(QUIET_XMLTO)$(RM) $@ && \ + xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< %.xml : %.txt - $(RM) $@+ $@ + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf - $(ASCIIDOC) -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)) - cd technical && sh ./api-index.sh + $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt - $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ + $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css -user-manual.html: user-manual.xml - xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< +user-manual.html: user-manual.xml $(XSLT) + $(QUIET_XSLTPROC)$(RM) $@+ $@ && \ + xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \ + mv $@+ $@ git.info: user-manual.texi - $(MAKEINFO) --no-split -o $@ user-manual.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi user-manual.texi: user-manual.xml - $(RM) $@+ $@ - $(DOCBOOK2X_TEXI) user-manual.xml --to-stdout | $(PERL_PATH) fix-texi.perl >$@+ + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \ + $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \ + rm $@++ && \ + mv $@+ $@ + +user-manual.pdf: user-manual.xml + $(QUIET_DBLATEX)$(RM) $@+ $@ && \ + $(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $< && \ mv $@+ $@ gitman.texi: $(MAN_XML) cat-texi.perl - $(RM) $@+ $@ - ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --to-stdout $(xml);)) | \ - $(PERL_PATH) cat-texi.perl $@ >$@+ + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \ + --to-stdout $(xml) &&) true) > $@++ && \ + $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \ + rm $@++ && \ mv $@+ $@ gitman.info: gitman.texi - $(MAKEINFO) --no-split $*.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml - $(RM) $@+ $@ - $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \ mv $@+ $@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) - $(RM) $@+ $@ - sh ./howto-index.sh $(wildcard howto/*.txt) >$@+ + $(QUIET_GEN)$(RM) $@+ $@ && \ + '$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \ mv $@+ $@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt - $(ASCIIDOC) -b xhtml11 $*.txt + $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt WEBDOC_DEST = /pub/software/scm/git/docs +howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt - $(RM) $@+ $@ - sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+ + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \ mv $@+ $@ install-webdoc : html - sh ./install-webdoc.sh $(WEBDOC_DEST) + '$(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 + +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: - sh ./install-doc-quick.sh $(DOC_REF) $(DESTDIR)$(mandir) +quick-install-html: require-htmlrepo + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) -.PHONY: .FORCE-GIT-VERSION-FILE +.PHONY: FORCE 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 f6393f8a94..7bfa341750 100644 --- a/Documentation/RelNotes-1.5.2.2.txt +++ b/Documentation/RelNotes/1.5.2.2.txt @@ -45,7 +45,7 @@ Fixes since v1.5.2.1 correctly when the branch name had slash in it. - The email address of the user specified with user.email - configuration was overriden by EMAIL environment variable. + configuration was overridden by EMAIL environment variable. - The tree parser did not warn about tree entries with nonsense file modes, and assumed they must be blobs. 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 6195715dc7..e8328d090a 100644 --- a/Documentation/RelNotes-1.5.2.txt +++ b/Documentation/RelNotes/1.5.2.txt @@ -36,7 +36,7 @@ Updates since v1.5.1 expansion). These conversions apply when checking files in or out, and exporting via git-archive. -* The packfile format now optionally suports 64-bit index. +* The packfile format now optionally supports 64-bit index. This release supports the "version 2" format of the .idx file. This is automatically enabled when a huge packfile 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 d03894b926..0668d3c0ca 100644 --- a/Documentation/RelNotes-1.5.3.txt +++ b/Documentation/RelNotes/1.5.3.txt @@ -86,7 +86,7 @@ Updates since v1.5.2 - "git rev-list" learned --regexp-ignore-case and --extended-regexp options to tweak its matching logic used - for --grep fitering. + for --grep filtering. - "git describe --contains" is a handier way to call more obscure command "git name-rev --tags". @@ -243,7 +243,7 @@ Updates since v1.5.2 - We used to have core.legacyheaders configuration, when set to false, allowed git to write loose objects in a format - that mimicks the format used by objects stored in packs. It + that mimics the format used by objects stored in packs. It turns out that this was not so useful. Although we will continue to read objects written in that format, we do not honor that configuration anymore and create loose objects in @@ -302,7 +302,7 @@ Updates since v1.5.2 small enough delta results it creates while looking for the best delta candidates. - - "git pack-objects" learned a new heuristcs to prefer delta + - "git pack-objects" learned a new heuristic to prefer delta that is shallower in depth over the smallest delta possible. This improves both overall packfile access performance and packfile density. 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 89fa6d03bc..323c1a88c7 100644 --- a/Documentation/RelNotes-1.5.4.4.txt +++ b/Documentation/RelNotes/1.5.4.4.txt @@ -55,7 +55,7 @@ Fixes since v1.5.4.3 * "git log --merge" did not work well with --left-right option. - * "git svn" promprted for client cert password every time it accessed the + * "git svn" prompted for client cert password every time it accessed the server. * The reset command in "git fast-import" data stream was documented to diff --git a/Documentation/RelNotes-1.5.4.5.txt b/Documentation/RelNotes/1.5.4.5.txt index 0282341398..bbd130e36d 100644 --- a/Documentation/RelNotes-1.5.4.5.txt +++ b/Documentation/RelNotes/1.5.4.5.txt @@ -9,7 +9,7 @@ Fixes since v1.5.4.4 1.5.4). * Bogus refspec configuration such as "remote.there.fetch = =" were not - detected as errors (regressionin 1.5.4). + detected as errors (regression in 1.5.4). * You couldn't specify a custom editor whose path contains a whitespace via GIT_EDITOR (and core.editor). diff --git a/Documentation/RelNotes/1.5.4.6.txt b/Documentation/RelNotes/1.5.4.6.txt new file mode 100644 index 0000000000..3e3c3e55a3 --- /dev/null +++ b/Documentation/RelNotes/1.5.4.6.txt @@ -0,0 +1,43 @@ +GIT v1.5.4.6 Release Notes +========================== + +I personally do not think there is any reason anybody should want to +run v1.5.4.X series these days, because 'master' version is always +more stable than any tagged released version of git. + +This is primarily to futureproof "git-shell" to accept requests +without a dash between "git" and subcommand name (e.g. "git +upload-pack") which the newer client will start to make sometime in +the future. + +Fixes since v1.5.4.5 +-------------------- + + * Command line option "-n" to "git-repack" was not correctly parsed. + + * Error messages from "git-apply" when the patchfile cannot be opened + have been improved. + + * Error messages from "git-bisect" when given nonsense revisions have + been improved. + + * reflog syntax that uses time e.g. "HEAD@{10 seconds ago}:path" did not + stop parsing at the closing "}". + + * "git rev-parse --symbolic-full-name ^master^2" printed solitary "^", + but it should print nothing. + + * "git apply" did not enforce "match at the beginning" correctly. + + * a path specification "a/b" in .gitattributes file should not match + "sub/a/b", but it did. + + * "git log --date-order --topo-order" did not override the earlier + date-order with topo-order as expected. + + * "git fast-export" did not export octopus merges correctly. + + * "git archive --prefix=$path/" mishandled gitattributes. + +As usual, it also comes with many documentation fixes and clarifications. + diff --git a/Documentation/RelNotes/1.5.4.7.txt b/Documentation/RelNotes/1.5.4.7.txt new file mode 100644 index 0000000000..9065a0e273 --- /dev/null +++ b/Documentation/RelNotes/1.5.4.7.txt @@ -0,0 +1,10 @@ +GIT v1.5.4.7 Release Notes +========================== + +Fixes since 1.5.4.7 +------------------- + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. diff --git a/Documentation/RelNotes-1.5.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 new file mode 100644 index 0000000000..30fa3615c7 --- /dev/null +++ b/Documentation/RelNotes/1.5.5.5.txt @@ -0,0 +1,11 @@ +GIT v1.5.5.5 Release Notes +========================== + +I personally do not think there is any reason anybody should want to +run v1.5.5.X series these days, because 'master' version is always +more stable than any tagged released version of git. + +This is primarily to futureproof "git-shell" to accept requests +without a dash between "git" and subcommand name (e.g. "git +upload-pack") which the newer client will start to make sometime in +the future. diff --git a/Documentation/RelNotes/1.5.5.6.txt b/Documentation/RelNotes/1.5.5.6.txt new file mode 100644 index 0000000000..d5e85cb70e --- /dev/null +++ b/Documentation/RelNotes/1.5.5.6.txt @@ -0,0 +1,10 @@ +GIT v1.5.5.6 Release Notes +========================== + +Fixes since 1.5.5.5 +------------------- + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. diff --git a/Documentation/RelNotes-1.5.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 new file mode 100644 index 0000000000..4864b16445 --- /dev/null +++ b/Documentation/RelNotes/1.5.6.1.txt @@ -0,0 +1,28 @@ +GIT v1.5.6.1 Release Notes +========================== + +Fixes since v1.5.6 +------------------ + +* Last minute change broke loose object creation on AIX. + +* (performance fix) We used to make $GIT_DIR absolute path early in the + programs but keeping it relative to the current directory internally + gives 1-3 per-cent performance boost. + +* bash completion knows the new --graph option to git-log family. + + +* git-diff -c/--cc showed unnecessary "deletion" lines at the context + boundary. + +* git-for-each-ref ignored %(object) and %(type) requests for tag + objects. + +* git-merge usage had a typo. + +* Rebuilding of git-svn metainfo database did not take rewriteRoot + option into account. + +* Running "git-rebase --continue/--skip/--abort" before starting a + rebase gave nonsense error messages. diff --git a/Documentation/RelNotes/1.5.6.2.txt b/Documentation/RelNotes/1.5.6.2.txt new file mode 100644 index 0000000000..5902a85a78 --- /dev/null +++ b/Documentation/RelNotes/1.5.6.2.txt @@ -0,0 +1,40 @@ +GIT v1.5.6.2 Release Notes +========================== + +Futureproof +----------- + + * "git-shell" accepts requests without a dash between "git" and + subcommand name (e.g. "git upload-pack") which the newer client will + start to make sometime in the future. + +Fixes since v1.5.6.1 +-------------------- + +* "git clone" from a remote that is named with url.insteadOf setting in + $HOME/.gitconfig did not work well. + +* "git describe --long --tags" segfaulted when the described revision was + tagged with a lightweight tag. + +* "git diff --check" did not report the result via its exit status + reliably. + +* When remote side used to have branch 'foo' and git-fetch finds that now + it has branch 'foo/bar', it refuses to lose the existing remote tracking + branch and its reflog. The error message has been improved to suggest + pruning the remote if the user wants to proceed and get the latest set + of branches from the remote, including such 'foo/bar'. + +* "git reset file" should mean the same thing as "git reset HEAD file", + but we required disambiguating -- even when "file" is not ambiguous. + +* "git show" segfaulted when an annotated tag that points at another + annotated tag was given to it. + +* Optimization for a large import via "git-svn" introduced in v1.5.6 had a + serious memory and temporary file leak, which made it unusable for + moderately large import. + +* "git-svn" mangled remote nickname used in the configuration file + unnecessarily. diff --git a/Documentation/RelNotes/1.5.6.3.txt b/Documentation/RelNotes/1.5.6.3.txt new file mode 100644 index 0000000000..f61dd3504a --- /dev/null +++ b/Documentation/RelNotes/1.5.6.3.txt @@ -0,0 +1,52 @@ +GIT v1.5.6.3 Release Notes +========================== + +Fixes since v1.5.6.2 +-------------------- + +* 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. + +* Setting GIT_TRACE will report spawning of external process via run_command(). + +* Using an object with very deep delta chain pinned memory needed for extracting + intermediate base objects unnecessarily long, leading to excess memory usage. + +* Bash completion script did not notice '--' marker on the command + line and tried the relatively slow "ref completion" even when + completing arguments after one. + +* Registering a non-empty blob racily and then truncating the working + tree file for it confused "racy-git avoidance" logic into thinking + that the path is now unchanged. + +* The section that describes attributes related to git-archive were placed + in a wrong place in the gitattributes(5) manual page. + +* "git am" was not helpful to the users when it detected that the committer + information is not set up properly yet. + +* "git clone" had a leftover debugging fprintf(). + +* "git clone -q" was not quiet enough as it used to and gave object count + and progress reports. + +* "git clone" marked downloaded packfile with .keep; this could be a + good thing if the remote side is well packed but otherwise not, + especially for a project that is not really big. + +* "git daemon" used to call syslog() from a signal handler, which + could raise signals of its own but generally is not reentrant. This + was fixed by restructuring the code to report syslog() after the handler + returns. + +* When "git push" tries to remove a remote ref, and corresponding + tracking ref is missing, we used to report error (i.e. failure to + remove something that does not exist). + +* "git mailinfo" (hence "git am") did not handle commit log messages in a + MIME multipart mail correctly. + +Contains other various documentation fixes. diff --git a/Documentation/RelNotes/1.5.6.4.txt b/Documentation/RelNotes/1.5.6.4.txt new file mode 100644 index 0000000000..d8968f1ecb --- /dev/null +++ b/Documentation/RelNotes/1.5.6.4.txt @@ -0,0 +1,47 @@ +GIT v1.5.6.4 Release Notes +========================== + +Fixes since v1.5.6.3 +-------------------- + +* Various commands could overflow its internal buffer on a platform + with small PATH_MAX value in a repository that has contents with + long pathnames. + +* There wasn't a way to make --pretty=format:%<> specifiers to honor + .mailmap name rewriting for authors and committers. Now you can with + %aN and %cN. + +* Bash completion wasted too many cycles; this has been optimized to be + usable again. + +* Bash completion lost ref part when completing something like "git show + pu:Makefile". + +* "git-cvsserver" did not clean up its temporary working area after annotate + request. + +* "git-daemon" called syslog() from its signal handler, which was a + no-no. + +* "git-fetch" into an empty repository used to remind that the fetch will + be huge by saying "no common commits", but this was an unnecessary + noise; it is already known by the user anyway. + +* "git-http-fetch" would have segfaulted when pack idx file retrieved + from the other side was corrupt. + +* "git-index-pack" used too much memory when dealing with a deep delta chain. + +* "git-mailinfo" (hence "git-am") did not correctly handle in-body [PATCH] + line to override the commit title taken from the mail Subject header. + +* "git-rebase -i -p" lost parents that are not involved in the history + being rewritten. + +* "git-rm" lost track of where the index file was when GIT_DIR was + specified as a relative path. + +* "git-rev-list --quiet" was not quiet as advertised. + +Contains other various documentation fixes. diff --git a/Documentation/RelNotes/1.5.6.5.txt b/Documentation/RelNotes/1.5.6.5.txt new file mode 100644 index 0000000000..47ca172462 --- /dev/null +++ b/Documentation/RelNotes/1.5.6.5.txt @@ -0,0 +1,29 @@ +GIT v1.5.6.5 Release Notes +========================== + +Fixes since v1.5.6.4 +-------------------- + +* "git cvsimport" used to spit out "UNKNOWN LINE..." diagnostics to stdout. + +* "git commit -F filename" and "git tag -F filename" run from subdirectories + did not read the right file. + +* "git init --template=" with blank "template" parameter linked files + under root directories to .git, which was a total nonsense. Instead, it + means "I do not want to use anything from the template directory". + +* "git diff-tree" and other diff plumbing ignored diff.renamelimit configuration + variable when the user explicitly asked for rename detection. + +* "git name-rev --name-only" did not work when "--stdin" option was in effect. + +* "git show-branch" mishandled its 8th branch. + +* Addition of "git update-index --ignore-submodules" that happened during + 1.5.6 cycle broke "git update-index --ignore-missing". + +* "git send-email" did not parse charset from an existing Content-type: + header properly. + +Contains other various documentation fixes. diff --git a/Documentation/RelNotes/1.5.6.6.txt b/Documentation/RelNotes/1.5.6.6.txt new file mode 100644 index 0000000000..79da23db5a --- /dev/null +++ b/Documentation/RelNotes/1.5.6.6.txt @@ -0,0 +1,10 @@ +GIT v1.5.6.6 Release Notes +========================== + +Fixes since 1.5.6.5 +------------------- + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. diff --git a/Documentation/RelNotes-1.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 new file mode 100644 index 0000000000..49d7a1cafa --- /dev/null +++ b/Documentation/RelNotes/1.6.0.1.txt @@ -0,0 +1,36 @@ +GIT v1.6.0.1 Release Notes +========================== + +Fixes since v1.6.0 +------------------ + +* "git diff --cc" did not honor content mangling specified by + gitattributes and core.autocrlf when reading from the work tree. + +* "git diff --check" incorrectly detected new trailing blank lines when + whitespace check was in effect. + +* "git for-each-ref" tried to dereference NULL when asked for '%(body)" on + a tag with a single incomplete line as its payload. + +* "git format-patch" peeked before the beginning of a string when + "format.headers" variable is empty (a misconfiguration). + +* "git help help" did not work correctly. + +* "git mailinfo" (hence "git am") was unhappy when MIME multipart message + contained garbage after the finishing boundary. + +* "git mailinfo" also was unhappy when the "From: " line only had a bare + e-mail address. + +* "git merge" did not refresh the index correctly when a merge resulted in + a fast-forward. + +* "git merge" did not resolve a truly trivial merges that can be done + without content level merges. + +* "git svn dcommit" to a repository with URL that has embedded usernames + did not work correctly. + +Contains other various documentation fixes. diff --git a/Documentation/RelNotes/1.6.0.2.txt b/Documentation/RelNotes/1.6.0.2.txt new file mode 100644 index 0000000000..e1e24b3295 --- /dev/null +++ b/Documentation/RelNotes/1.6.0.2.txt @@ -0,0 +1,87 @@ +GIT v1.6.0.2 Release Notes +========================== + +Fixes since v1.6.0.1 +-------------------- + +* Installation on platforms that needs .exe suffix to git-* programs were + broken in 1.6.0.1. + +* Installation on filesystems without symbolic links support did not + work well. + +* In-tree documentations and test scripts now use "git foo" form to set a + better example, instead of the "git-foo" form (which is an acceptable + form if you have "PATH=$(git --exec-path):$PATH" in your script) + +* Many commands did not use the correct working tree location when used + with GIT_WORK_TREE environment settings. + +* Some systems need to use compatibility fnmatch and regex libraries + independent from each other; the compat/ area has been reorganized to + allow this. + + +* "git apply --unidiff-zero" incorrectly applied a -U0 patch that inserts + a new line before the second line. + +* "git blame -c" did not exactly work like "git annotate" when range + boundaries are involved. + +* "git checkout file" when file is still unmerged checked out contents from + a random high order stage, which was confusing. + +* "git clone $there $here/" with extra trailing slashes after explicit + local directory name $here did not work as expected. + +* "git diff" on tracked contents with CRLF line endings did not drive "less" + intelligently when showing added or removed lines. + +* "git diff --dirstat -M" did not add changes in subdirectories up + correctly for renamed paths. + +* "git diff --cumulative" did not imply "--dirstat". + +* "git for-each-ref refs/heads/" did not work as expected. + +* "git gui" allowed users to feed patch without any context to be applied. + +* "git gui" botched parsing "diff" output when a line that begins with two + dashes and a space gets removed or a line that begins with two pluses + and a space gets added. + +* "git gui" translation updates and i18n fixes. + +* "git index-pack" is more careful against disk corruption while completing + a thin pack. + +* "git log -i --grep=pattern" did not ignore case; neither "git log -E + --grep=pattern" triggered extended regexp. + +* "git log --pretty="%ad" --date=short" did not use short format when + showing the timestamp. + +* "git log --author=author" match incorrectly matched with the + timestamp part of "author " line in commit objects. + +* "git log -F --author=author" did not work at all. + +* Build procedure for "git shell" that used stub versions of some + functions and globals was not understood by linkers on some platforms. + +* "git stash" was fooled by a stat-dirty but otherwise unmodified paths + and refused to work until the user refreshed the index. + +* "git svn" was broken on Perl before 5.8 with recent fixes to reduce + use of temporary files. + +* "git verify-pack -v" did not work correctly when given more than one + packfile. + +Also contains many documentation updates. + +-- +exec >/var/tmp/1 +O=v1.6.0.1-78-g3632cfc +echo O=$(git describe maint) +git shortlog --no-merges $O..maint diff --git a/Documentation/RelNotes/1.6.0.3.txt b/Documentation/RelNotes/1.6.0.3.txt new file mode 100644 index 0000000000..ae0577836a --- /dev/null +++ b/Documentation/RelNotes/1.6.0.3.txt @@ -0,0 +1,117 @@ +GIT v1.6.0.3 Release Notes +========================== + +Fixes since v1.6.0.2 +-------------------- + +* "git archive --format=zip" did not honor core.autocrlf while + --format=tar did. + +* Continuing "git rebase -i" was very confused when the user left modified + files in the working tree while resolving conflicts. + +* Continuing "git rebase -i" was also very confused when the user left + some staged changes in the index after "edit". + +* "git rebase -i" now honors the pre-rebase hook, just like the + other rebase implementations "git rebase" and "git rebase -m". + +* "git rebase -i" incorrectly aborted when there is no commit to replay. + +* Behaviour of "git diff --quiet" was inconsistent with "diff --exit-code" + with the output redirected to /dev/null. + +* "git diff --no-index" on binary files no longer outputs a bogus + "diff --git" header line. + +* "git diff" hunk header patterns with multiple elements separated by LF + were not used correctly. + +* Hunk headers in "git diff" default to using extended regular + expressions, fixing some of the internal patterns on non-GNU + platforms. + +* New config "diff.*.xfuncname" exposes extended regular expressions + for user specified hunk header patterns. + +* "git gc" when ejecting otherwise unreachable objects from packfiles into + loose form leaked memory. + +* "git index-pack" was recently broken and mishandled objects added by + thin-pack completion processing under memory pressure. + +* "git index-pack" was recently broken and misbehaved when run from inside + .git/objects/pack/ directory. + +* "git stash apply sash@{1}" was fixed to error out. Prior versions + would have applied stash@{0} incorrectly. + +* "git stash apply" now offers a better suggestion on how to continue + if the working tree is currently dirty. + +* "git for-each-ref --format=%(subject)" fixed for commits with no + no newline in the message body. + +* "git remote" fixed to protect printf from user input. + +* "git remote show -v" now displays all URLs of a remote. + +* "git checkout -b branch" was confused when branch already existed. + +* "git checkout -q" once again suppresses the locally modified file list. + +* "git clone -q", "git fetch -q" asks remote side to not send + progress messages, actually making their output quiet. + +* Cross-directory renames are no longer used when creating packs. This + allows more graceful behavior on filesystems like sshfs. + +* Stale temporary files under $GIT_DIR/objects/pack are now cleaned up + automatically by "git prune". + +* "git merge" once again removes directories after the last file has + been removed from it during the merge. + +* "git merge" did not allocate enough memory for the structure itself when + enumerating the parents of the resulting commit. + +* "git blame -C -C" no longer segfaults while trying to pass blame if + it encounters a submodule reference. + +* "git rm" incorrectly claimed that you have local modifications when a + path was merely stat-dirty. + +* "git svn" fixed to display an error message when 'set-tree' failed, + instead of a Perl compile error. + +* "git submodule" fixed to handle checking out a different commit + than HEAD after initializing the submodule. + +* The "git commit" error message when there are still unmerged + files present was clarified to match "git write-tree". + +* "git init" was confused when core.bare or core.sharedRepository are set + in system or user global configuration file by mistake. When --bare or + --shared is given from the command line, these now override such + settings made outside the repositories. + +* Some segfaults due to uncaught NULL pointers were fixed in multiple + tools such as apply, reset, update-index. + +* Solaris builds now default to OLD_ICONV=1 to avoid compile warnings; + Solaris 8 does not define NEEDS_LIBICONV by default. + +* "Git.pm" tests relied on unnecessarily more recent version of Perl. + +* "gitweb" triggered undef warning on commits without log messages. + +* "gitweb" triggered undef warnings on missing trees. + +* "gitweb" now removes PATH_INFO from its URLs so users don't have + to manually set the URL in the gitweb configuration. + +* Bash completion removed support for legacy "git-fetch", "git-push" + and "git-pull" as these are no longer installed. Dashless form + ("git fetch") is still however supported. + +Many other documentation updates. diff --git a/Documentation/RelNotes/1.6.0.4.txt b/Documentation/RelNotes/1.6.0.4.txt new file mode 100644 index 0000000000..d522661d31 --- /dev/null +++ b/Documentation/RelNotes/1.6.0.4.txt @@ -0,0 +1,39 @@ +GIT v1.6.0.4 Release Notes +========================== + +Fixes since v1.6.0.3 +-------------------- + +* 'git add -p' said "No changes" when only binary files were changed. + +* 'git archive' did not work correctly in bare repositories. + +* 'git checkout -t -b newbranch' when you are on detached HEAD was broken. + +* when we refuse to detect renames because there are too many new or + deleted files, 'git diff' did not say how many there are. + +* 'git push --mirror' tried and failed to push the stash; there is no + point in sending it to begin with. + +* 'git push' did not update the remote tracking reference if the corresponding + ref on the remote end happened to be already up to date. + +* 'git pull $there $branch:$current_branch' did not work when you were on + a branch yet to be born. + +* when giving up resolving a conflicted merge, 'git reset --hard' failed + to remove new paths from the working tree. + +* 'git send-email' had a small fd leak while scanning directory. + +* 'git status' incorrectly reported a submodule directory as an untracked + directory. + +* 'git svn' used deprecated 'git-foo' form of subcommand invocation. + +* 'git update-ref -d' to remove a reference did not honor --no-deref option. + +* Plugged small memleaks here and there. + +* Also contains many documentation updates. diff --git a/Documentation/RelNotes/1.6.0.5.txt b/Documentation/RelNotes/1.6.0.5.txt new file mode 100644 index 0000000000..a08bb96738 --- /dev/null +++ b/Documentation/RelNotes/1.6.0.5.txt @@ -0,0 +1,56 @@ +GIT v1.6.0.5 Release Notes +========================== + +Fixes since v1.6.0.4 +-------------------- + +* "git checkout" used to crash when your HEAD was pointing at a deleted + branch. + +* "git checkout" from an un-checked-out state did not allow switching out + of the current branch. + +* "git diff" always allowed GIT_EXTERNAL_DIFF and --no-ext-diff was no-op for + the command. + +* Giving 3 or more tree-ish to "git diff" is supposed to show the combined + diff from second and subsequent trees to the first one, but the order was + screwed up. + +* "git fast-export" did not export all tags. + +* "git ls-files --with-tree=<tree>" did not work with options other + than -c, most notably with -m. + +* "git pack-objects" did not make its best effort to honor --max-pack-size + option when a single first object already busted the given limit and + placed many objects in a single pack. + +* "git-p4" fast import frontend was too eager to trigger its keyword expansion + logic, even on a keyword-looking string that does not have closing '$' on the + same line. + +* "git push $there" when the remote $there is defined in $GIT_DIR/branches/$there + behaves more like what cg-push from Cogito used to work. + +* when giving up resolving a conflicted merge, "git reset --hard" failed + to remove new paths from the working tree. + +* "git tag" did not complain when given mutually incompatible set of options. + +* The message constructed in the internal editor was discarded when "git + tag -s" failed to sign the message, which was often caused by the user + not configuring GPG correctly. + +* "make check" cannot be run without sparse; people may have meant to say + "make test" instead, so suggest that. + +* Internal diff machinery had a corner case performance bug that choked on + a large file with many repeated contents. + +* "git repack" used to grab objects out of packs marked with .keep + into a new pack. + +* Many unsafe call to sprintf() style varargs functions are corrected. + +* Also contains quite a few documentation updates. diff --git a/Documentation/RelNotes/1.6.0.6.txt b/Documentation/RelNotes/1.6.0.6.txt new file mode 100644 index 0000000000..64ece1ffd5 --- /dev/null +++ b/Documentation/RelNotes/1.6.0.6.txt @@ -0,0 +1,33 @@ +GIT v1.6.0.6 Release Notes +========================== + +Fixes since 1.6.0.5 +------------------- + + * "git fsck" had a deep recursion that wasted stack space. + + * "git fast-export" and "git fast-import" choked on an old style + annotated tag that lack the tagger information. + + * "git mergetool -- file" did not correctly skip "--" marker that + signals the end of options list. + + * "git show $tag" segfaulted when an annotated $tag pointed at a + nonexistent object. + + * "git show 2>error" when the standard output is automatically redirected + to the pager redirected the standard error to the pager as well; there + was no need to. + + * "git send-email" did not correctly handle list of addresses when + they had quoted comma (e.g. "Lastname, Givenname" <mail@addre.ss>). + + * Logic to discover branch ancestry in "git svn" was unreliable when + the process to fetch history was interrupted. + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. + +Also contains numerous documentation typofixes. diff --git a/Documentation/RelNotes/1.6.0.txt b/Documentation/RelNotes/1.6.0.txt new file mode 100644 index 0000000000..de7ef166b6 --- /dev/null +++ b/Documentation/RelNotes/1.6.0.txt @@ -0,0 +1,258 @@ +GIT v1.6.0 Release Notes +======================== + +User visible changes +-------------------- + +With the default Makefile settings, most of the programs are now +installed outside your $PATH, except for "git", "gitk" and +some server side programs that need to be accessible for technical +reasons. Invoking a git subcommand as "git-xyzzy" from the command +line has been deprecated since early 2006 (and officially announced in +1.5.4 release notes); use of them from your scripts after adding +output from "git --exec-path" to the $PATH is still supported in this +release, but users are again strongly encouraged to adjust their +scripts to use "git xyzzy" form, as we will stop installing +"git-xyzzy" hardlinks for built-in commands in later releases. + +An earlier change to page "git status" output was overwhelmingly unpopular +and has been reverted. + +Source changes needed for porting to MinGW environment are now all in the +main git.git codebase. + +By default, packfiles created with this version uses delta-base-offset +encoding introduced in v1.4.4. Pack idx files are using version 2 that +allows larger packs and added robustness thanks to its CRC checking, +introduced in v1.5.2 and v1.4.4.5. If you want to keep your repositories +backwards compatible past these versions, set repack.useDeltaBaseOffset +to false or pack.indexVersion to 1, respectively. + +We used to prevent sample hook scripts shipped in templates/ from +triggering by default by relying on the fact that we install them as +unexecutable, but on some filesystems, this approach does not work. +They are now shipped with ".sample" suffix. If you want to activate +any of these samples as-is, rename them to drop the ".sample" suffix, +instead of running "chmod +x" on them. For example, you can rename +hooks/post-update.sample to hooks/post-update to enable the sample +hook that runs update-server-info, in order to make repositories +friendly to dumb protocols (i.e. HTTP). + +GIT_CONFIG, which was only documented as affecting "git config", but +actually affected all git commands, now only affects "git config". +GIT_LOCAL_CONFIG, also only documented as affecting "git config" and +not different from GIT_CONFIG in a useful way, is removed. + +The ".dotest" temporary area "git am" and "git rebase" use is now moved +inside the $GIT_DIR, to avoid mistakes of adding it to the project by +accident. + +An ancient merge strategy "stupid" has been removed. + + +Updates since v1.5.6 +-------------------- + +(subsystems) + +* git-p4 in contrib learned "allowSubmit" configuration to control on + which branch to allow "submit" subcommand. + +* git-gui learned to stage changes per-line. + +(portability) + +* Changes for MinGW port have been merged, thanks to Johannes Sixt and + gangs. + +* Sample hook scripts shipped in templates/ are now suffixed with + *.sample. + +* perl's in-place edit (-i) does not work well without backup files on Windows; + some tests are rewritten to cope with this. + +(documentation) + +* Updated howto/update-hook-example + +* Got rid of usage of "git-foo" from the tutorial and made typography + more consistent. + +* Disambiguating "--" between revs and paths is finally documented. + +(performance, robustness, sanity etc.) + +* index-pack used too much memory when dealing with a deep delta chain. + This has been optimized. + +* reduced excessive inlining to shrink size of the "git" binary. + +* verify-pack checks the object CRC when using version 2 idx files. + +* When an object is corrupt in a pack, the object became unusable even + when the same object is available in a loose form, We now try harder to + fall back to these redundant objects when able. In particular, "git + repack -a -f" can be used to fix such a corruption as long as necessary + objects are available. + +* Performance of "git-blame -C -C" operation is vastly improved. + +* git-clone does not create refs in loose form anymore (it behaves as + if you immediately ran git-pack-refs after cloning). This will help + repositories with insanely large number of refs. + +* core.fsyncobjectfiles configuration can be used to ensure that the loose + objects created will be fsync'ed (this is only useful on filesystems + that does not order data writes properly). + +* "git commit-tree" plumbing can make Octopus with more than 16 parents. + "git commit" has been capable of this for quite some time. + +(usability, bells and whistles) + +* even more documentation pages are now accessible via "man" and "git help". + +* A new environment variable GIT_CEILING_DIRECTORIES can be used to stop + the discovery process of the toplevel of working tree; this may be useful + when you are working in a slow network disk and are outside any working tree, + as bash-completion and "git help" may still need to run in these places. + +* By default, stash entries never expire. Set reflogexpire in [gc + "refs/stash"] to a reasonable value to get traditional auto-expiration + behaviour back + +* Longstanding latency issue with bash completion script has been + addressed. This will need to be backmerged to 'maint' later. + +* pager.<cmd> configuration variable can be used to enable/disable the + default paging behaviour per command. + +* "git-add -i" has a new action 'e/dit' to allow you edit the patch hunk + manually. + +* git-am records the original tip of the branch in ORIG_HEAD before it + starts applying patches. + +* git-apply can handle a patch that touches the same path more than once + much better than before. + +* git-apply can be told not to trust the line counts recorded in the input + patch but recount, with the new --recount option. + +* git-apply can be told to apply a patch to a path deeper than what the + patch records with --directory option. + +* git-archive can be told to omit certain paths from its output using + export-ignore attributes. + +* git-archive uses the zlib default compression level when creating + zip archive. + +* git-archive's command line options --exec and --remote can take their + parameters as separate command line arguments, similar to other commands. + IOW, both "--exec=path" and "--exec path" are now supported. + +* With -v option, git-branch describes the remote tracking statistics + similar to the way git-checkout reports by how many commits your branch + is ahead/behind. + +* git-branch's --contains option used to always require a commit parameter + to limit the branches with; it now defaults to list branches that + contains HEAD if this parameter is omitted. + +* git-branch's --merged and --no-merged option used to always limit the + branches relative to the HEAD, but they can now take an optional commit + argument that is used in place of HEAD. + +* git-bundle can read the revision arguments from the standard input. + +* git-cherry-pick can replay a root commit now. + +* git-clone can clone from a remote whose URL would be rewritten by + configuration stored in $HOME/.gitconfig now. + +* "git-clone --mirror" is a handy way to set up a bare mirror repository. + +* git-cvsserver learned to respond to "cvs co -c". + +* git-diff --check now checks leftover merge conflict markers. + +* "git-diff -p" learned to grab a better hunk header lines in + BibTex, Pascal/Delphi, and Ruby files and also pays attention to + chapter and part boundary in TeX documents. + +* When remote side used to have branch 'foo' and git-fetch finds that now + it has branch 'foo/bar', it refuses to lose the existing remote tracking + branch and its reflog. The error message has been improved to suggest + pruning the remote if the user wants to proceed and get the latest set + of branches from the remote, including such 'foo/bar'. + +* fast-export learned to export and import marks file; this can be used to + interface with fast-import incrementally. + +* fast-import and fast-export learned to export and import gitlinks. + +* "gitk" left background process behind after being asked to dig very deep + history and the user killed the UI; the process is killed when the UI goes + away now. + +* git-rebase records the original tip of branch in ORIG_HEAD before it is + rewound. + +* "git rerere" can be told to update the index with auto-reused resolution + with rerere.autoupdate configuration variable. + +* git-rev-parse learned $commit^! and $commit^@ notations used in "log" + family. These notations are available in gitk as well, because the gitk + command internally uses rev-parse to interpret its arguments. + +* git-rev-list learned --children option to show child commits it + encountered during the traversal, instead of showing parent commits. + +* git-send-mail can talk not just over SSL but over TLS now. + +* git-shortlog honors custom output format specified with "--pretty=format:". + +* "git-stash save" learned --keep-index option. This lets you stash away the + local changes and bring the changes staged in the index to your working + tree for examination and testing. + +* git-stash also learned branch subcommand to create a new branch out of + stashed changes. + +* git-status gives the remote tracking statistics similar to the way + git-checkout reports by how many commits your branch is ahead/behind. + +* "git-svn dcommit" is now aware of auto-props setting the subversion user + has. + +* You can tell "git status -u" to even more aggressively omit checking + untracked files with --untracked-files=no. + +* Original SHA-1 value for "update-ref -d" is optional now. + +* Error codes from gitweb are made more descriptive where possible, rather + than "403 forbidden" as we used to issue everywhere. + +(internal) + +* git-merge has been reimplemented in C. + + +Fixes since v1.5.6 +------------------ + +All of the fixes in v1.5.6 maintenance series are included in +this release, unless otherwise noted. + + * git-clone ignored its -u option; the fix needs to be backported to + 'maint'; + + * git-mv used to lose the distinction between changes that are staged + and that are only in the working tree, by staging both in the index + after moving such a path. + + * "git-rebase -i -p" rewrote the parents to wrong ones when amending + (either edit or squash) was involved, and did not work correctly + when fast forwarding. + diff --git a/Documentation/RelNotes/1.6.1.1.txt b/Documentation/RelNotes/1.6.1.1.txt new file mode 100644 index 0000000000..8c594ba02f --- /dev/null +++ b/Documentation/RelNotes/1.6.1.1.txt @@ -0,0 +1,59 @@ +GIT v1.6.1.1 Release Notes +========================== + +Fixes since v1.6.1 +------------------ + +* "git add frotz/nitfol" when "frotz" is a submodule should have errored + out, but it didn't. + +* "git apply" took file modes from the patch text and updated the mode + bits of the target tree even when the patch was not about mode changes. + +* "git bisect view" on Cygwin did not launch gitk + +* "git checkout $tree" did not trigger an error. + +* "git commit" tried to remove COMMIT_EDITMSG from the work tree by mistake. + +* "git describe --all" complained when a commit is described with a tag, + which was nonsense. + +* "git diff --no-index --" did not trigger no-index (aka "use git-diff as + a replacement of diff on untracked files") behaviour. + +* "git format-patch -1 HEAD" on a root commit failed to produce patch + text. + +* "git fsck branch" did not work as advertised; instead it behaved the same + way as "git fsck". + +* "git log --pretty=format:%s" did not handle a multi-line subject the + same way as built-in log listers (i.e. shortlog, --pretty=oneline, etc.) + +* "git daemon", and "git merge-file" are more careful when freopen fails + and barf, instead of going on and writing to unopened filehandle. + +* "git http-push" did not like some RFC 4918 compliant DAV server + responses. + +* "git merge -s recursive" mistakenly overwritten an untracked file in the + work tree upon delete/modify conflict. + +* "git merge -s recursive" didn't leave the index unmerged for entries with + rename/delete conflicts. + +* "git merge -s recursive" clobbered untracked files in the work tree. + +* "git mv -k" with more than one erroneous paths misbehaved. + +* "git read-tree -m -u" hence branch switching incorrectly lost a + subdirectory in rare cases. + +* "git rebase -i" issued an unnecessary error message upon a user error of + marking the first commit to be "squash"ed. + +* "git shortlog" did not format a commit message with multi-line + subject correctly. + +Many documentation updates. diff --git a/Documentation/RelNotes/1.6.1.2.txt b/Documentation/RelNotes/1.6.1.2.txt new file mode 100644 index 0000000000..be37cbb858 --- /dev/null +++ b/Documentation/RelNotes/1.6.1.2.txt @@ -0,0 +1,39 @@ +GIT v1.6.1.2 Release Notes +========================== + +Fixes since v1.6.1.1 +-------------------- + +* The logic for rename detection in internal diff used by commands like + "git diff" and "git blame" has been optimized to avoid loading the same + blob repeatedly. + +* We did not allow writing out a blob that is larger than 2GB for no good + reason. + +* "git format-patch -o $dir", when $dir is a relative directory, used it + as relative to the root of the work tree, not relative to the current + directory. + +* v1.6.1 introduced an optimization for "git push" into a repository (A) + that borrows its objects from another repository (B) to avoid sending + objects that are available in repository B, when they are not yet used + by repository A. However the code on the "git push" sender side was + buggy and did not work when repository B had new objects that are not + known by the sender. This caused pushing into a "forked" repository + served by v1.6.1 software using "git push" from v1.6.1 sometimes did not + work. The bug was purely on the "git push" sender side, and has been + corrected. + +* "git status -v" did not paint its diff output in colour even when + color.ui configuration was set. + +* "git ls-tree" learned --full-tree option to help Porcelain scripts that + want to always see the full path regardless of the current working + directory. + +* "git grep" incorrectly searched in work tree paths even when they are + marked as assume-unchanged. It now searches in the index entries. + +* "git gc" with no grace period needlessly ejected packed but unreachable + objects in their loose form, only to delete them right away. diff --git a/Documentation/RelNotes/1.6.1.3.txt b/Documentation/RelNotes/1.6.1.3.txt new file mode 100644 index 0000000000..6f0bde156a --- /dev/null +++ b/Documentation/RelNotes/1.6.1.3.txt @@ -0,0 +1,32 @@ +GIT v1.6.1.3 Release Notes +========================== + +Fixes since v1.6.1.2 +-------------------- + +* "git diff --binary | git apply" pipeline did not work well when + a binary blob is changed to a symbolic link. + +* Some combinations of -b/-w/--ignore-space-at-eol to "git diff" did + not work as expected. + +* "git grep" did not pass the -I (ignore binary) option when + calling out an external grep program. + +* "git log" and friends include HEAD to the set of starting points + when --all is given. This makes a difference when you are not + on any branch. + +* "git mv" to move an untracked file to overwrite a tracked + contents misbehaved. + +* "git merge -s octopus" with many potential merge bases did not + work correctly. + +* RPM binary package installed the html manpages in a wrong place. + +Also includes minor documentation fixes and updates. + + +-- +git shortlog --no-merges v1.6.1.2-33-gc789350.. diff --git a/Documentation/RelNotes/1.6.1.4.txt b/Documentation/RelNotes/1.6.1.4.txt new file mode 100644 index 0000000000..0ce6316d75 --- /dev/null +++ b/Documentation/RelNotes/1.6.1.4.txt @@ -0,0 +1,44 @@ +GIT v1.6.1.4 Release Notes +========================== + +Fixes since v1.6.1.3 +-------------------- + +* .gitignore learned to handle backslash as a quoting mechanism for + comment introduction character "#". + This fix was first merged to 1.6.2.1. + +* "git fast-export" produced wrong output with some parents missing from + commits, when the history is clock-skewed. + +* "git fast-import" sometimes failed to read back objects it just wrote + out and aborted, because it failed to flush stale cached data. + +* "git-ls-tree" and "git-diff-tree" used a pathspec correctly when + deciding to descend into a subdirectory but they did not match the + individual paths correctly. This caused pathspecs "abc/d ab" to match + "abc/0" ("abc/d" made them decide to descend into the directory "abc/", + and then "ab" incorrectly matched "abc/0" when it shouldn't). + This fix was first merged to 1.6.2.3. + +* import-zips script (in contrib) did not compute the common directory + prefix correctly. + This fix was first merged to 1.6.2.2. + +* "git init" segfaulted when given an overlong template location via + the --template= option. + This fix was first merged to 1.6.2.4. + +* "git repack" did not error out when necessary object was missing in the + repository. + +* git-repack (invoked from git-gc) did not work as nicely as it should in + a repository that borrows objects from neighbours via alternates + mechanism especially when some packs are marked with the ".keep" flag + to prevent them from being repacked. + This fix was first merged to 1.6.2.3. + +Also includes minor documentation fixes and updates. + +-- +git shortlog --no-merges v1.6.1.3.. diff --git a/Documentation/RelNotes/1.6.1.txt b/Documentation/RelNotes/1.6.1.txt new file mode 100644 index 0000000000..adb7ccab0a --- /dev/null +++ b/Documentation/RelNotes/1.6.1.txt @@ -0,0 +1,286 @@ +GIT v1.6.1 Release Notes +======================== + +Updates since v1.6.0 +-------------------- + +When some commands (e.g. "git log", "git diff") spawn pager internally, we +used to make the pager the parent process of the git command that produces +output. This meant that the exit status of the whole thing comes from the +pager, not the underlying git command. We swapped the order of the +processes around and you will see the exit code from the command from now +on. + +(subsystems) + +* gitk can call out to git-gui to view "git blame" output; git-gui in turn + can run gitk from its blame view. + +* Various git-gui updates including updated translations. + +* Various gitweb updates from repo.or.cz installation. + +* Updates to emacs bindings. + +(portability) + +* A few test scripts used nonportable "grep" that did not work well on + some platforms, e.g. Solaris. + +* Sample pre-auto-gc script has OS X support. + +* Makefile has support for (ancient) FreeBSD 4.9. + +(performance) + +* Many operations that are lstat(3) heavy can be told to pre-execute + necessary lstat(3) in parallel before their main operations, which + potentially gives much improved performance for cold-cache cases or in + environments with weak metadata caching (e.g. NFS). + +* The underlying diff machinery to produce textual output has been + optimized, which would result in faster "git blame" processing. + +* Most of the test scripts (but not the ones that try to run servers) + can be run in parallel. + +* Bash completion of refnames in a repository with massive number of + refs has been optimized. + +* Cygwin port uses native stat/lstat implementations when applicable, + which leads to improved performance. + +* "git push" pays attention to alternate repositories to avoid sending + unnecessary objects. + +* "git svn" can rebuild an out-of-date rev_map file. + +(usability, bells and whistles) + +* When you mistype a command name, git helpfully suggests what it guesses + you might have meant to say. help.autocorrect configuration can be set + to a non-zero value to accept the suggestion when git can uniquely + guess. + +* The packfile machinery hopefully is more robust when dealing with + corrupt packs if redundant objects involved in the corruption are + available elsewhere. + +* "git add -N path..." adds the named paths as an empty blob, so that + subsequent "git diff" will show a diff as if they are creation events. + +* "git add" gained a built-in synonym for people who want to say "stage + changes" instead of "add contents to the staging area" which amounts + to the same thing. + +* "git apply" learned --include=paths option, similar to the existing + --exclude=paths option. + +* "git bisect" is careful about a user mistake and suggests testing of + merge base first when good is not a strict ancestor of bad. + +* "git bisect skip" can take a range of commits. + +* "git blame" re-encodes the commit metainfo to UTF-8 from i18n.commitEncoding + by default. + +* "git check-attr --stdin" can check attributes for multiple paths. + +* "git checkout --track origin/hack" used to be a syntax error. It now + DWIMs to create a corresponding local branch "hack", i.e. acts as if you + said "git checkout --track -b hack origin/hack". + +* "git checkout --ours/--theirs" can be used to check out one side of a + conflicting merge during conflict resolution. + +* "git checkout -m" can be used to recreate the initial conflicted state + during conflict resolution. + +* "git cherry-pick" can also utilize rerere for conflict resolution. + +* "git clone" learned to be verbose with -v + +* "git commit --author=$name" can look up author name from existing + commits. + +* output from "git commit" has been reworded in a more concise and yet + more informative way. + +* "git count-objects" reports the on-disk footprint for packfiles and + their corresponding idx files. + +* "git daemon" learned --max-connections=<count> option. + +* "git daemon" exports REMOTE_ADDR to record client address, so that + spawned programs can act differently on it. + +* "git describe --tags" favours closer lightweight tags than farther + annotated tags now. + +* "git diff" learned to mimic --suppress-blank-empty from GNU diff via a + configuration option. + +* "git diff" learned to put more sensible hunk headers for Python, + HTML and ObjC contents. + +* "git diff" learned to vary the a/ vs b/ prefix depending on what are + being compared, controlled by diff.mnemonicprefix configuration. + +* "git diff" learned --dirstat-by-file to count changed files, not number + of lines, when summarizing the global picture. + +* "git diff" learned "textconv" filters --- a binary or hard-to-read + contents can be munged into human readable form and the difference + between the results of the conversion can be viewed (obviously this + cannot produce a patch that can be applied, so this is disabled in + format-patch among other things). + +* "--cached" option to "git diff has an easier to remember synonym "--staged", + to ask "what is the difference between the given commit and the + contents staged in the index?" + +* "git for-each-ref" learned "refname:short" token that gives an + unambiguously abbreviated refname. + +* Auto-numbering of the subject lines is the default for "git + format-patch" now. + +* "git grep" learned to accept -z similar to GNU grep. + +* "git help" learned to use GIT_MAN_VIEWER environment variable before + using "man" program. + +* "git imap-send" can optionally talk SSL. + +* "git index-pack" is more careful against disk corruption while + completing a thin pack. + +* "git log --check" and "git log --exit-code" passes their underlying diff + status with their exit status code. + +* "git log" learned --simplify-merges, a milder variant of --full-history; + "gitk --simplify-merges" is easier to view than with --full-history. + +* "git log" learned "--source" to show what ref each commit was reached + from. + +* "git log" also learned "--simplify-by-decoration" to show the + birds-eye-view of the topology of the history. + +* "git log --pretty=format:" learned "%d" format element that inserts + names of tags that point at the commit. + +* "git merge --squash" and "git merge --no-ff" into an unborn branch are + noticed as user errors. + +* "git merge -s $strategy" can use a custom built strategy if you have a + command "git-merge-$strategy" on your $PATH. + +* "git pull" (and "git fetch") can be told to operate "-v"erbosely or + "-q"uietly. + +* "git push" can be told to reject deletion of refs with receive.denyDeletes + configuration. + +* "git rebase" honours pre-rebase hook; use --no-verify to bypass it. + +* "git rebase -p" uses interactive rebase machinery now to preserve the merges. + +* "git reflog expire branch" can be used in place of "git reflog expire + refs/heads/branch". + +* "git remote show $remote" lists remote branches one-per-line now. + +* "git send-email" can be given revision range instead of files and + maildirs on the command line, and automatically runs format-patch to + generate patches for the given revision range. + +* "git submodule foreach" subcommand allows you to iterate over checked + out submodules. + +* "git submodule sync" subcommands allows you to update the origin URL + recorded in submodule directories from the toplevel .gitmodules file. + +* "git svn branch" can create new branches on the other end. + +* "gitweb" can use more saner PATH_INFO based URL. + +(internal) + +* "git hash-object" learned to lie about the path being hashed, so that + correct gitattributes processing can be done while hashing contents + stored in a temporary file. + +* various callers of git-merge-recursive avoid forking it as an external + process. + +* Git class defined in "Git.pm" can be subclasses a bit more easily. + +* We used to link GNU regex library as a compatibility layer for some + platforms, but it turns out it is not necessary on most of them. + +* Some path handling routines used fixed number of buffers used alternately + but depending on the call depth, this arrangement led to hard to track + bugs. This issue is being addressed. + + +Fixes since v1.6.0 +------------------ + +All of the fixes in v1.6.0.X maintenance series are included in this +release, unless otherwise noted. + +* Porcelains implemented as shell scripts were utterly confused when you + entered to a subdirectory of a work tree from sideways, following a + symbolic link (this may need to be backported to older releases later). + +* Tracking symbolic links would work better on filesystems whose lstat() + returns incorrect st_size value for them. + +* "git add" and "git update-index" incorrectly allowed adding S/F when S + is a tracked symlink that points at a directory D that has a path F in + it (we still need to fix a similar nonsense when S is a submodule and F + is a path in it). + +* "git am" after stopping at a broken patch lost --whitespace, -C, -p and + --3way options given from the command line initially. + +* "git diff --stdin" used to take two trees on a line and compared them, + but we dropped support for such a use case long time ago. This has + been resurrected. + +* "git filter-branch" failed to rewrite a tag name with slashes in it. + +* "git http-push" did not understand URI scheme other than opaquelocktoken + when acquiring a lock from the server (this may need to be backported to + older releases later). + +* After "git rebase -p" stopped with conflicts while replaying a merge, + "git rebase --continue" did not work (may need to be backported to older + releases). + +* "git revert" records relative to which parent a revert was made when + reverting a merge. Together with new documentation that explains issues + around reverting a merge and merging from the updated branch later, this + hopefully will reduce user confusion (this may need to be backported to + older releases later). + +* "git rm --cached" used to allow an empty blob that was added earlier to + be removed without --force, even when the file in the work tree has + since been modified. + +* "git push --tags --all $there" failed with generic usage message without + telling saying these two options are incompatible. + +* "git log --author/--committer" match used to potentially match the + timestamp part, exposing internal implementation detail. Also these did + not work with --fixed-strings match at all. + +* "gitweb" did not mark non-ASCII characters imported from external HTML fragments + correctly. + +-- +exec >/var/tmp/1 +O=v1.6.1-rc3-74-gf66bc5f +echo O=$(git describe master) +git shortlog --no-merges $O..master ^maint diff --git a/Documentation/RelNotes/1.6.2.1.txt b/Documentation/RelNotes/1.6.2.1.txt new file mode 100644 index 0000000000..dfa36416af --- /dev/null +++ b/Documentation/RelNotes/1.6.2.1.txt @@ -0,0 +1,19 @@ +GIT v1.6.2.1 Release Notes +========================== + +Fixes since v1.6.2 +------------------ + +* .gitignore learned to handle backslash as a quoting mechanism for + comment introduction character "#". + +* timestamp output in --date=relative mode used to display timestamps that + are long time ago in the default mode; it now uses "N years M months + ago", and "N years ago". + +* git-add -i/-p now works with non-ASCII pathnames. + +* "git hash-object -w" did not read from the configuration file from the + correct .git directory. + +* git-send-email learned to correctly handle multiple Cc: addresses. diff --git a/Documentation/RelNotes/1.6.2.2.txt b/Documentation/RelNotes/1.6.2.2.txt new file mode 100644 index 0000000000..fafa9986b0 --- /dev/null +++ b/Documentation/RelNotes/1.6.2.2.txt @@ -0,0 +1,45 @@ +GIT v1.6.2.2 Release Notes +========================== + +Fixes since v1.6.2.1 +-------------------- + +* A longstanding confusing description of what --pickaxe option of + git-diff does has been clarified in the documentation. + +* "git-blame -S" did not quite work near the commits that were given + on the command line correctly. + +* "git diff --pickaxe-regexp" did not count overlapping matches + correctly. + +* "git diff" did not feed files in work-tree representation to external + diff and textconv. + +* "git-fetch" in a repository that was not cloned from anywhere said + it cannot find 'origin', which was hard to understand for new people. + +* "git-format-patch --numbered-files --stdout" did not have to die of + incompatible options; it now simply ignores --numbered-files as no files + are produced anyway. + +* "git-ls-files --deleted" did not work well with GIT_DIR&GIT_WORK_TREE. + +* "git-read-tree A B C..." without -m option has been broken for a long + time. + +* git-send-email ignored --in-reply-to when --no-thread was given. + +* 'git-submodule add' did not tolerate extra slashes and ./ in the path it + accepted from the command line; it now is more lenient. + +* git-svn misbehaved when the project contained a path that began with + two dashes. + +* import-zips script (in contrib) did not compute the common directory + prefix correctly. + +* miscompilation of negated enum constants by old gcc (2.9) affected the + codepaths to spawn subprocesses. + +Many small documentation updates are included as well. diff --git a/Documentation/RelNotes/1.6.2.3.txt b/Documentation/RelNotes/1.6.2.3.txt new file mode 100644 index 0000000000..4d3c1ac91c --- /dev/null +++ b/Documentation/RelNotes/1.6.2.3.txt @@ -0,0 +1,22 @@ +GIT v1.6.2.3 Release Notes +========================== + +Fixes since v1.6.2.2 +-------------------- + +* Setting an octal mode value to core.sharedrepository configuration to + restrict access to the repository to group members did not work as + advertised. + +* A fairly large and trivial memory leak while rev-list shows list of + reachable objects has been identified and plugged. + +* "git-commit --interactive" did not abort when underlying "git-add -i" + signaled a failure. + +* git-repack (invoked from git-gc) did not work as nicely as it should in + a repository that borrows objects from neighbours via alternates + mechanism especially when some packs are marked with the ".keep" flag + to prevent them from being repacked. + +Many small documentation updates are included as well. diff --git a/Documentation/RelNotes/1.6.2.4.txt b/Documentation/RelNotes/1.6.2.4.txt new file mode 100644 index 0000000000..f4bf1d0986 --- /dev/null +++ b/Documentation/RelNotes/1.6.2.4.txt @@ -0,0 +1,39 @@ +GIT v1.6.2.4 Release Notes +========================== + +Fixes since v1.6.2.3 +-------------------- + +* The configuration parser had a buffer overflow while parsing an overlong + value. + +* pruning reflog entries that are unreachable from the tip of the ref + during "git reflog prune" (hence "git gc") was very inefficient. + +* "git-add -p" lacked a way to say "q"uit to refuse staging any hunks for + the remaining paths. You had to say "d" and then ^C. + +* "git-checkout <tree-ish> <submodule>" did not update the index entry at + the named path; it now does. + +* "git-fast-export" choked when seeing a tag that does not point at commit. + +* "git init" segfaulted when given an overlong template location via + the --template= option. + +* "git-ls-tree" and "git-diff-tree" used a pathspec correctly when + deciding to descend into a subdirectory but they did not match the + individual paths correctly. This caused pathspecs "abc/d ab" to match + "abc/0" ("abc/d" made them decide to descend into the directory "abc/", + and then "ab" incorrectly matched "abc/0" when it shouldn't). + +* "git-merge-recursive" was broken when a submodule entry was involved in + a criss-cross merge situation. + +Many small documentation updates are included as well. + +--- +exec >/var/tmp/1 +echo O=$(git describe maint) +O=v1.6.2.3-38-g318b847 +git shortlog --no-merges $O..maint diff --git a/Documentation/RelNotes/1.6.2.5.txt b/Documentation/RelNotes/1.6.2.5.txt new file mode 100644 index 0000000000..b23f9e95d1 --- /dev/null +++ b/Documentation/RelNotes/1.6.2.5.txt @@ -0,0 +1,21 @@ +GIT v1.6.2.5 Release Notes +========================== + +Fixes since v1.6.2.4 +-------------------- + +* "git apply" mishandled if you fed a git generated patch that renames + file A to B and file B to A at the same time. + +* "git diff -c -p" (and "diff --cc") did not expect to see submodule + differences and instead refused to work. + +* "git grep -e '('" segfaulted, instead of diagnosing a mismatched + parentheses error. + +* "git fetch" generated packs with offset-delta encoding when both ends of + the connection are capable of producing one; this cannot be read by + ancient git and the user should be able to disable this by setting + repack.usedeltabaseoffset configuration to false. + + diff --git a/Documentation/RelNotes/1.6.2.txt b/Documentation/RelNotes/1.6.2.txt new file mode 100644 index 0000000000..ad060f4f89 --- /dev/null +++ b/Documentation/RelNotes/1.6.2.txt @@ -0,0 +1,164 @@ +GIT v1.6.2 Release Notes +======================== + +With the next major release, "git push" into a branch that is +currently checked out will be refused by default. You can choose +what should happen upon such a push by setting the configuration +variable receive.denyCurrentBranch in the receiving repository. + +To ease the transition plan, the receiving repository of such a +push running this release will issue a big warning when the +configuration variable is missing. Please refer to: + + http://git.or.cz/gitwiki/GitFaq#non-bare + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + +for more details on the reason why this change is needed and the +transition plan. + +For a similar reason, "git push $there :$killed" to delete the branch +$killed in a remote repository $there, if $killed branch is the current +branch pointed at by its HEAD, gets a large warning. You can choose what +should happen upon such a push by setting the configuration variable +receive.denyDeleteCurrent in the receiving repository. + + +Updates since v1.6.1 +-------------------- + +(subsystems) + +* git-svn updates. + +* gitweb updates, including a new patch view and RSS/Atom feed + improvements. + +* (contrib/emacs) git.el now has commands for checking out a branch, + creating a branch, cherry-picking and reverting commits; vc-git.el + is not shipped with git anymore (it is part of official Emacs). + +(performance) + +* pack-objects autodetects the number of CPUs available and uses threaded + version. + +(usability, bells and whistles) + +* automatic typo correction works on aliases as well + +* @{-1} is a way to refer to the last branch you were on. This is + accepted not only where an object name is expected, but anywhere + a branch name is expected and acts as if you typed the branch name. + E.g. "git branch --track mybranch @{-1}", "git merge @{-1}", and + "git rev-parse --symbolic-full-name @{-1}" would work as expected. + +* When refs/remotes/origin/HEAD points at a remote tracking branch that + has been pruned away, many git operations issued warning when they + internally enumerated the refs. We now warn only when you say "origin" + to refer to that pruned branch. + +* The location of .mailmap file can be configured, and its file format was + enhanced to allow mapping an incorrect e-mail field as well. + +* "git add -p" learned 'g'oto action to jump directly to a hunk. + +* "git add -p" learned to find a hunk with given text with '/'. + +* "git add -p" optionally can be told to work with just the command letter + without Enter. + +* when "git am" stops upon a patch that does not apply, it shows the + title of the offending patch. + +* "git am --directory=<dir>" and "git am --reject" passes these options + to underlying "git apply". + +* "git am" learned --ignore-date option. + +* "git blame" aligns author names better when they are spelled in + non US-ASCII encoding. + +* "git clone" now makes its best effort when cloning from an empty + repository to set up configuration variables to refer to the remote + repository. + +* "git checkout -" is a shorthand for "git checkout @{-1}". + +* "git cherry" defaults to whatever the current branch is tracking (if + exists) when the <upstream> argument is not given. + +* "git cvsserver" can be told not to add extra "via git-CVS emulator" to + the commit log message it serves via gitcvs.commitmsgannotation + configuration. + +* "git cvsserver" learned to handle 'noop' command some CVS clients seem + to expect to work. + +* "git diff" learned a new option --inter-hunk-context to coalesce close + hunks together and show context between them. + +* The definition of what constitutes a word for "git diff --color-words" + can be customized via gitattributes, command line or a configuration. + +* "git diff" learned --patience to run "patience diff" algorithm. + +* "git filter-branch" learned --prune-empty option that discards commits + that do not change the contents. + +* "git fsck" now checks loose objects in alternate object stores, instead + of misreporting them as missing. + +* "git gc --prune" was resurrected to allow "git gc --no-prune" and + giving non-default expiration period e.g. "git gc --prune=now". + +* "git grep -w" and "git grep" for fixed strings have been optimized. + +* "git mergetool" learned -y(--no-prompt) option to disable prompting. + +* "git rebase -i" can transplant a history down to root to elsewhere + with --root option. + +* "git reset --merge" is a new mode that works similar to the way + "git checkout" switches branches, taking the local changes while + switching to another commit. + +* "git submodule update" learned --no-fetch option. + +* "git tag" learned --contains that works the same way as the same option + from "git branch". + + +Fixes since v1.6.1 +------------------ + +All of the fixes in v1.6.1.X maintenance series are included in this +release, unless otherwise noted. + +Here are fixes that this release has, but have not been backported to +v1.6.1.X series. + +* "git-add sub/file" when sub is a submodule incorrectly added the path to + the superproject. + +* "git bundle" did not exclude annotated tags even when a range given + from the command line wanted to. + +* "git filter-branch" unnecessarily refused to work when you had + checked out a different commit from what is recorded in the superproject + index in a submodule. + +* "git filter-branch" incorrectly tried to update a nonexistent work tree + at the end when it is run in a bare repository. + +* "git gc" did not work if your repository was created with an ancient git + and never had any pack files in it before. + +* "git mergetool" used to ignore autocrlf and other attributes + based content rewriting. + +* branch switching and merges had a silly bug that did not validate + the correct directory when making sure an existing subdirectory is + clean. + +* "git -p cmd" when cmd is not a built-in one left the display in funny state + when killed in the middle. diff --git a/Documentation/RelNotes/1.6.3.1.txt b/Documentation/RelNotes/1.6.3.1.txt new file mode 100644 index 0000000000..2400b72ef7 --- /dev/null +++ b/Documentation/RelNotes/1.6.3.1.txt @@ -0,0 +1,10 @@ +GIT v1.6.3.1 Release Notes +========================== + +Fixes since v1.6.3 +------------------ + +* "git checkout -b new-branch" with a staged change in the index + incorrectly primed the in-index cache-tree, resulting a wrong tree + object to be written out of the index. This is a grave regression + since the last 1.6.2.X maintenance release. diff --git a/Documentation/RelNotes/1.6.3.2.txt b/Documentation/RelNotes/1.6.3.2.txt new file mode 100644 index 0000000000..b2f3f0293c --- /dev/null +++ b/Documentation/RelNotes/1.6.3.2.txt @@ -0,0 +1,61 @@ +GIT v1.6.3.2 Release Notes +========================== + +Fixes since v1.6.3.1 +-------------------- + + * A few codepaths picked up the first few bytes from an sha1[] by + casting the (char *) pointer to (int *); GCC 4.4 did not like this, + and aborted compilation. + + * Some unlink(2) failures went undiagnosed. + + * The "recursive" merge strategy misbehaved when faced rename/delete + conflicts while coming up with an intermediate merge base. + + * The low-level merge algorithm did not handle a degenerate case of + merging a file with itself using itself as the common ancestor + gracefully. It should produce the file itself, but instead + produced an empty result. + + * GIT_TRACE mechanism segfaulted when tracing a shell-quoted aliases. + + * OpenBSD also uses st_ctimspec in "struct stat", instead of "st_ctim". + + * With NO_CROSS_DIRECTORY_HARDLINKS, "make install" can be told not to + create hardlinks between $(gitexecdir)/git-$builtin_commands and + $(bindir)/git. + + * command completion code in bash did not reliably detect that we are + in a bare repository. + + * "git add ." in an empty directory complained that pathspec "." did not + match anything, which may be technically correct, but not useful. We + silently make it a no-op now. + + * "git add -p" (and "patch" action in "git add -i") was broken when + the first hunk that adds a line at the top was split into two and + both halves are marked to be used. + + * "git blame path" misbehaved at the commit where path became file + from a directory with some files in it. + + * "git for-each-ref" had a segfaulting bug when dealing with a tag object + created by an ancient git. + + * "git format-patch -k" still added patch numbers if format.numbered + configuration was set. + + * "git grep --color ''" did not terminate. The command also had + subtle bugs with its -w option. + + * http-push had a small use-after-free bug. + + * "git push" was converting OFS_DELTA pack representation into less + efficient REF_DELTA representation unconditionally upon transfer, + making the transferred data unnecessarily larger. + + * "git remote show origin" segfaulted when origin was still empty. + +Many other general usability updates around help text, diagnostic messages +and documentation are included as well. diff --git a/Documentation/RelNotes/1.6.3.3.txt b/Documentation/RelNotes/1.6.3.3.txt new file mode 100644 index 0000000000..1c28398bb6 --- /dev/null +++ b/Documentation/RelNotes/1.6.3.3.txt @@ -0,0 +1,38 @@ +GIT v1.6.3.3 Release Notes +========================== + +Fixes since v1.6.3.2 +-------------------- + + * "git archive" running on Cygwin can get stuck in an infinite loop. + + * "git daemon" did not correctly parse the initial line that carries + virtual host request information. + + * "git diff --textconv" leaked memory badly when the textconv filter + errored out. + + * The built-in regular expressions to pick function names to put on + hunk header lines for java and objc were very inefficiently written. + + * in certain error situations git-fetch (and git-clone) on Windows didn't + detect connection abort and ended up waiting indefinitely. + + * import-tars script (in contrib) did not import symbolic links correctly. + + * http.c used CURLOPT_SSLKEY even on libcURL version 7.9.2, even though + it was only available starting 7.9.3. + + * low-level filelevel merge driver used return value from strdup() + without checking if we ran out of memory. + + * "git rebase -i" left stray closing parenthesis in its reflog message. + + * "git remote show" did not show all the URLs associated with the named + remote, even though "git remote -v" did. Made them consistent by + making the former show all URLs. + + * "whitespace" attribute that is set was meant to detect all errors known + to git, but it told git to ignore trailing carriage-returns. + +Includes other documentation fixes. diff --git a/Documentation/RelNotes/1.6.3.4.txt b/Documentation/RelNotes/1.6.3.4.txt new file mode 100644 index 0000000000..cad461bc76 --- /dev/null +++ b/Documentation/RelNotes/1.6.3.4.txt @@ -0,0 +1,36 @@ +GIT v1.6.3.4 Release Notes +========================== + +Fixes since v1.6.3.3 +-------------------- + + * "git add --no-ignore-errors" did not override configured + add.ignore-errors configuration. + + * "git apply --whitespace=fix" did not fix trailing whitespace on an + incomplete line. + + * "git branch" opened too many commit objects unnecessarily. + + * "git checkout -f $commit" with a path that is a file (or a symlink) in + the work tree to a commit that has a directory at the path issued an + unnecessary error message. + + * "git diff -c/--cc" was very inefficient in coalescing the removed lines + shared between parents. + + * "git diff -c/--cc" showed removed lines at the beginning of a file + incorrectly. + + * "git remote show nickname" did not honor configured + remote.nickname.uploadpack when inspecting the branches at the remote. + + * "git request-pull" when talking to the terminal for a preview + showed some of the output in the pager. + + * "git request-pull start nickname [end]" did not honor configured + remote.nickname.uploadpack when it ran git-ls-remote against the remote + repository to learn the current tip of branches. + +Includes other documentation updates and minor fixes. + diff --git a/Documentation/RelNotes/1.6.3.txt b/Documentation/RelNotes/1.6.3.txt new file mode 100644 index 0000000000..418c685cf8 --- /dev/null +++ b/Documentation/RelNotes/1.6.3.txt @@ -0,0 +1,182 @@ +GIT v1.6.3 Release Notes +======================== + +With the next major release, "git push" into a branch that is +currently checked out will be refused by default. You can choose +what should happen upon such a push by setting the configuration +variable receive.denyCurrentBranch in the receiving repository. + +To ease the transition plan, the receiving repository of such a +push running this release will issue a big warning when the +configuration variable is missing. Please refer to: + + http://git.or.cz/gitwiki/GitFaq#non-bare + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + +for more details on the reason why this change is needed and the +transition plan. + +For a similar reason, "git push $there :$killed" to delete the branch +$killed in a remote repository $there, if $killed branch is the current +branch pointed at by its HEAD, gets a large warning. You can choose what +should happen upon such a push by setting the configuration variable +receive.denyDeleteCurrent in the receiving repository. + +When the user does not tell "git push" what to push, it has always +pushed matching refs. For some people it is unexpected, and a new +configuration variable push.default has been introduced to allow +changing a different default behaviour. To advertise the new feature, +a big warning is issued if this is not configured and a git push without +arguments is attempted. + + +Updates since v1.6.2 +-------------------- + +(subsystems) + +* various git-svn updates. + +* git-gui updates, including an update to Russian translation, and a + fix to an infinite loop when showing an empty diff. + +* gitk updates, including an update to Russian translation and improved Windows + support. + +(performance) + +* many uses of lstat(2) in the codepath for "git checkout" have been + optimized out. + +(usability, bells and whistles) + +* Boolean configuration variable yes/no can be written as on/off. + +* rsync:/path/to/repo can be used to run git over rsync for local + repositories. It may not be useful in practice; meant primarily for + testing. + +* http transport learned to prompt and use password when fetching from or + pushing to http://user@host.xz/ URL. + +* (msysgit) progress output that is sent over the sideband protocol can + be handled appropriately in Windows console. + +* "--pretty=<style>" option to the log family of commands can now be + spelled as "--format=<style>". In addition, --format=%formatstring + is a short-hand for --pretty=tformat:%formatstring. + +* "--oneline" is a synonym for "--pretty=oneline --abbrev-commit". + +* "--graph" to the "git log" family can draw the commit ancestry graph + in colors. + +* If you realize that you botched the patch when you are editing hunks + with the 'edit' action in git-add -i/-p, you can abort the editor to + tell git not to apply it. + +* @{-1} is a new way to refer to the last branch you were on introduced in + 1.6.2, but the initial implementation did not teach this to a few + commands. Now the syntax works with "branch -m @{-1} newname". + +* git-archive learned --output=<file> option. + +* git-archive takes attributes from the tree being archived; strictly + speaking, this is an incompatible behaviour change, but is a good one. + Use --worktree-attributes option to allow it to read attributes from + the work tree as before (deprecated git-tar tree command always reads + attributes from the work tree). + +* git-bisect shows not just the number of remaining commits whose goodness + is unknown, but also shows the estimated number of remaining rounds. + +* You can give --date=<format> option to git-blame. + +* "git-branch -r" shows HEAD symref that points at a remote branch in + interest of each tracked remote repository. + +* "git-branch -v -v" is a new way to get list of names for branches and the + "upstream" branch for them. + +* git-config learned -e option to open an editor to edit the config file + directly. + +* git-clone runs post-checkout hook when run without --no-checkout. + +* git-difftool is now part of the officially supported command, primarily + maintained by David Aguilar. + +* git-for-each-ref learned a new "upstream" token. + +* git-format-patch can be told to use attachment with a new configuration, + format.attach. + +* git-format-patch can be told to produce deep or shallow message threads. + +* git-format-patch can be told to always add sign-off with a configuration + variable. + +* git-format-patch learned format.headers configuration to add extra + header fields to the output. This behaviour is similar to the existing + --add-header=<header> option of the command. + +* git-format-patch gives human readable names to the attached files, when + told to send patches as attachments. + +* git-grep learned to highlight the found substrings in color. + +* git-imap-send learned to work around Thunderbird's inability to easily + disable format=flowed with a new configuration, imap.preformattedHTML. + +* git-rebase can be told to rebase the series even if your branch is a + descendant of the commit you are rebasing onto with --force-rebase + option. + +* git-rebase can be told to report diffstat with the --stat option. + +* Output from git-remote command has been vastly improved. + +* "git remote update --prune $remote" updates from the named remote and + then prunes stale tracking branches. + +* git-send-email learned --confirm option to review the Cc: list before + sending the messages out. + +(developers) + +* Test scripts can be run under valgrind. + +* Test scripts can be run with installed git. + +* Makefile learned 'coverage' option to run the test suites with + coverage tracking enabled. + +* Building the manpages with docbook-xsl between 1.69.1 and 1.71.1 now + requires setting DOCBOOK_SUPPRESS_SP to work around a docbook-xsl bug. + This workaround used to be enabled by default, but causes problems + with newer versions of docbook-xsl. In addition, there are a few more + knobs you can tweak to work around issues with various versions of the + docbook-xsl package. See comments in Documentation/Makefile for details. + +* Support for building and testing a subset of git on a system without a + working perl has been improved. + + +Fixes since v1.6.2 +------------------ + +All of the fixes in v1.6.2.X maintenance series are included in this +release, unless otherwise noted. + +Here are fixes that this release has, but have not been backported to +v1.6.2.X series. + +* "git-apply" rejected a patch that swaps two files (i.e. renames A to B + and B to A at the same time). May need to be backported by cherry + picking d8c81df and then 7fac0ee). + +* The initial checkout did not read the attributes from the .gitattribute + file that is being checked out. + +* git-gc spent excessive amount of time to decide if an object appears + in a locally existing pack (if needed, backport by merging 69e020a). diff --git a/Documentation/RelNotes/1.6.4.1.txt b/Documentation/RelNotes/1.6.4.1.txt new file mode 100644 index 0000000000..e439e45b96 --- /dev/null +++ b/Documentation/RelNotes/1.6.4.1.txt @@ -0,0 +1,46 @@ +GIT v1.6.4.1 Release Notes +========================== + +Fixes since v1.6.4 +------------------ + + * An unquoted value in the configuration file, when it contains more than + one whitespaces in a row, got them replaced with a single space. + + * "git am" used to accept a single piece of e-mail per file (not a mbox) + as its input, but multiple input format support in v1.6.4 broke it. + Apparently many people have been depending on this feature. + + * The short help text for "git filter-branch" command was a single long + line, wrapped by terminals, and was hard to read. + + * The "recursive" strategy of "git merge" segfaulted when a merge has + more than one merge-bases, and merging of these merge-bases involves + a rename/rename or a rename/add conflict. + + * "git pull --rebase" did not use the right fork point when the + repository has already fetched from the upstream that rewinds the + branch it is based on in an earlier fetch. + + * Explain the concept of fast-forward more fully in "git push" + documentation, and hint to refer to it from an error message when the + command refuses an update to protect the user. + + * The default value for pack.deltacachesize, used by "git repack", is now + 256M, instead of unbounded. Otherwise a repack of a moderately sized + repository would needlessly eat into swap. + + * Document how "git repack" (hence "git gc") interacts with a repository + that borrows its objects from other repositories (e.g. ones created by + "git clone -s"). + + * "git show" on an annotated tag lacked a delimiting blank line between + the tag itself and the contents of the object it tags. + + * "git verify-pack -v" erroneously reported number of objects with too + deep delta depths as "chain length 0" objects. + + * Long names of authors and committers outside US-ASCII were sometimes + incorrectly shown in "gitweb". + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.4.2.txt b/Documentation/RelNotes/1.6.4.2.txt new file mode 100644 index 0000000000..c11ec0115c --- /dev/null +++ b/Documentation/RelNotes/1.6.4.2.txt @@ -0,0 +1,32 @@ +GIT v1.6.4.2 Release Notes +========================== + +Fixes since v1.6.4.1 +-------------------- + +* --date=relative output between 1 and 5 years ago rounded the number of + years when saying X years Y months ago, instead of rounding it down. + +* "git add -p" did not handle changes in executable bits correctly + (a regression around 1.6.3). + +* "git apply" did not honor GNU diff's convention to mark the creation/deletion + event with UNIX epoch timestamp on missing side. + +* "git checkout" incorrectly removed files in a directory pointed by a + symbolic link during a branch switch that replaces a directory with + a symbolic link. + +* "git clean -d -f" happily descended into a subdirectory that is managed by a + separate git repository. It now requires two -f options for safety. + +* "git fetch/push" over http transports had two rather grave bugs. + +* "git format-patch --cover-letter" did not prepare the cover letter file + for use with non-ASCII strings when there are the series contributors with + non-ASCII names. + +* "git pull origin branch" and "git fetch origin && git merge origin/branch" + left different merge messages in the resulting commit. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.4.3.txt b/Documentation/RelNotes/1.6.4.3.txt new file mode 100644 index 0000000000..5643e6537d --- /dev/null +++ b/Documentation/RelNotes/1.6.4.3.txt @@ -0,0 +1,29 @@ +GIT v1.6.4.3 Release Notes +========================== + +Fixes since v1.6.4.2 +-------------------- + +* "git clone" from an empty repository gave unnecessary error message, + even though it did everything else correctly. + +* "git cvsserver" invoked git commands via "git-foo" style, which has long + been deprecated. + +* "git fetch" and "git clone" had an extra sanity check to verify the + 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 + clone over HTTP from some of their repositories. As a workaround, this + verification has been removed (as it is not absolutely necessary). + +* "git grep" did not like relative pathname to refer outside the current + directory when run from a subdirectory. + +* an error message from "git push" was formatted in a very ugly way. + +* "git svn" did not quote the subversion user name correctly when + running its author-prog helper program. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.4.4.txt b/Documentation/RelNotes/1.6.4.4.txt new file mode 100644 index 0000000000..0ead45fc72 --- /dev/null +++ b/Documentation/RelNotes/1.6.4.4.txt @@ -0,0 +1,26 @@ +GIT v1.6.4.4 Release Notes +========================== + +Fixes since v1.6.4.4 +-------------------- + +* The workaround for Github server that sometimes gave 500 (Internal server + error) response to HEAD requests in 1.6.4.3 introduced a regression that + caused re-fetching projects over http to segfault in certain cases due + to uninitialized pointer being freed. + +* "git pull" on an unborn branch used to consider anything in the work + tree and the index discardable. + +* "git diff -b/w" did not work well on the incomplete line at the end of + the file, due to an incorrect hashing of lines in the low-level xdiff + routines. + +* "git checkout-index --prefix=$somewhere" used to work when $somewhere is + a symbolic link to a directory elsewhere, but v1.6.4.2 broke it. + +* "git unpack-objects --strict", invoked when receive.fsckobjects + configuration is set in the receiving repository of "git push", did not + properly check the objects, especially the submodule links, it received. + +Other minor documentation updates are included. 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 new file mode 100644 index 0000000000..7a904419f7 --- /dev/null +++ b/Documentation/RelNotes/1.6.4.txt @@ -0,0 +1,147 @@ +GIT v1.6.4 Release Notes +======================== + +With the next major release, "git push" into a branch that is +currently checked out will be refused by default. You can choose +what should happen upon such a push by setting the configuration +variable receive.denyCurrentBranch in the receiving repository. + +To ease the transition plan, the receiving repository of such a +push running this release will issue a big warning when the +configuration variable is missing. Please refer to: + + http://git.or.cz/gitwiki/GitFaq#non-bare + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + +for more details on the reason why this change is needed and the +transition plan. + +For a similar reason, "git push $there :$killed" to delete the branch +$killed in a remote repository $there, if $killed branch is the current +branch pointed at by its HEAD, gets a large warning. You can choose what +should happen upon such a push by setting the configuration variable +receive.denyDeleteCurrent in the receiving repository. + + +Updates since v1.6.3 +-------------------- + +(subsystems) + + * gitweb Perl style clean-up. + + * git-svn updates, including a new --authors-prog option to map author + names by invoking an external program, 'git svn reset' to unwind + 'git svn fetch', support for more than one branches, documenting + of the useful --minimize-url feature, new "git svn gc" command, etc. + +(portability) + + * We feed iconv with "UTF-8" instead of "utf8"; the former is + understood more widely. Similarly updated test scripts to use + encoding names more widely understood (e.g. use "ISO8859-1" instead + of "ISO-8859-1"). + + * Various portability fixes/workarounds for different vintages of + SunOS, IRIX, and Windows. + + * Git-over-ssh transport on Windows supports PuTTY plink and TortoisePlink. + +(performance) + + * Many repeated use of lstat() are optimized out in "checkout" codepath. + + * git-status (and underlying git-diff-index --cached) are optimized + to take advantage of cache-tree information in the index. + +(usability, bells and whistles) + + * "git add --edit" lets users edit the whole patch text to fine-tune what + is added to the index. + + * "git am" accepts StGIT series file as its input. + + * "git bisect skip" skips to a more randomly chosen place in the hope + to avoid testing a commit that is too close to a commit that is + already known to be untestable. + + * "git cvsexportcommit" learned -k option to stop CVS keywords expansion + + * "git fast-export" learned to handle history simplification more + gracefully. + + * "git fast-export" learned an option --tag-of-filtered-object to handle + dangling tags resulting from history simplification more usefully. + + * "git grep" learned -p option to show the location of the match using the + same context hunk marker "git diff" uses. + + * https transport can optionally be told that the used client + certificate is password protected, in which case it asks the + password only once. + + * "git imap-send" is IPv6 aware. + + * "git log --graph" draws graphs more compactly by using horizontal lines + when able. + + * "git log --decorate" shows shorter refnames by stripping well-known + refs/* prefix. + + * "git push $name" honors remote.$name.pushurl if present before + using remote.$name.url. In other words, the URL used for fetching + and pushing can be different. + + * "git send-email" understands quoted aliases in .mailrc files (might + have to be backported to 1.6.3.X). + + * "git send-email" can fetch the sender address from the configuration + variable "sendmail.from" (and "sendmail.<identity>.from"). + + * "git show-branch" can color its output. + + * "add" and "update" subcommands to "git submodule" learned --reference + option to use local clone with references. + + * "git submodule update" learned --rebase option to update checked + out submodules by rebasing the local changes. + + * "gitweb" can optionally use gravatar to adorn author/committer names. + +(developers) + + * A major part of the "git bisect" wrapper has moved to C. + + * Formatting with the new version of AsciiDoc 8.4.1 is now supported. + +Fixes since v1.6.3 +------------------ + +All of the fixes in v1.6.3.X maintenance series are included in this +release, unless otherwise noted. + +Here are fixes that this release has, but have not been backported to +v1.6.3.X series. + + * "git diff-tree -r -t" used to omit new or removed directories from + the output. df533f3 (diff-tree -r -t: include added/removed + directories in the output, 2009-06-13) may need to be cherry-picked + to backport this fix. + + * The way Git.pm sets up a Repository object was not friendly to callers + that chdir around. It now internally records the repository location + as an absolute path when autodetected. + + * Removing a section with "git config --remove-section", when its + section header has a variable definition on the same line, lost + that variable definition. + + * "git rebase -p --onto" used to always leave side branches of a merge + intact, even when both branches are subject to rewriting. + + * "git repack" used to faithfully follow grafts and considered true + parents recorded in the commit object unreachable from the commit. + After such a repacking, you cannot remove grafts without corrupting + the repository. + + * "git send-email" did not detect erroneous loops in alias expansion. diff --git a/Documentation/RelNotes/1.6.5.1.txt b/Documentation/RelNotes/1.6.5.1.txt new file mode 100644 index 0000000000..309ba181b2 --- /dev/null +++ b/Documentation/RelNotes/1.6.5.1.txt @@ -0,0 +1,20 @@ +GIT v1.6.5.1 Release Notes +========================== + +Fixes since v1.6.5 +------------------ + + * An corrupt pack could make codepath to read objects into an + infinite loop. + + * Download throughput display was always shown in KiB/s but on fast links + it is more appropriate to show it in MiB/s. + + * "git grep -f filename" used uninitialized variable and segfaulted. + + * "git clone -b branch" gave a wrong commit object name to post-checkout + hook. + + * "git pull" over http did not work on msys. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.5.2.txt b/Documentation/RelNotes/1.6.5.2.txt new file mode 100644 index 0000000000..aa7ccce3a2 --- /dev/null +++ b/Documentation/RelNotes/1.6.5.2.txt @@ -0,0 +1,19 @@ +GIT v1.6.5.2 Release Notes +========================== + +Fixes since v1.6.5.1 +-------------------- + + * Installation of templates triggered a bug in busybox when using tar + implementation from it. + + * "git add -i" incorrectly ignored paths that are already in the index + if they matched .gitignore patterns. + + * "git describe --always" should have produced some output even there + were no tags in the repository, but it didn't. + + * "git ls-files" when showing tracked files incorrectly paid attention + to the exclude patterns. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.5.3.txt b/Documentation/RelNotes/1.6.5.3.txt new file mode 100644 index 0000000000..b2fad1b22e --- /dev/null +++ b/Documentation/RelNotes/1.6.5.3.txt @@ -0,0 +1,63 @@ +Git v1.6.5.3 Release Notes +========================== + +Fixes since v1.6.5.2 +-------------------- + + * info/grafts file didn't ignore trailing CR at the end of lines. + + * Packages generated on newer FC were unreadable by older versions of + RPM as the new default is to use stronger hash. + + * output from "git blame" was unreadable when the file ended in an + incomplete line. + + * "git add -i/-p" didn't handle deletion of empty files correctly. + + * "git clone" takes up to two parameters, but did not complain when + given more arguments than necessary and silently ignored them. + + * "git cvsimport" did not read files given as command line arguments + correctly when it is run from a subdirectory. + + * "git diff --color-words -U0" didn't work correctly. + + * The handling of blank lines at the end of file by "git diff/apply + --whitespace" was inconsistent with the other kinds of errors. + They are now colored, warned against, and fixed the same way as others. + + * There was no way to allow blank lines at the end of file without + allowing extra blanks at the end of lines. You can use blank-at-eof + and blank-at-eol whitespace error class to specify them separately. + The old trailing-space error class is now a short-hand to set both. + + * "-p" option to "git format-patch" was supposed to suppress diffstat + generation, but it was broken since 1.6.1. + + * "git imap-send" did not compile cleanly with newer OpenSSL. + + * "git help -a" outside of a git repository was broken. + + * "git ls-files -i" was supposed to be inverse of "git ls-files" without -i + with respect to exclude patterns, but it was broken since 1.6.5.2. + + * "git ls-remote" outside of a git repository over http was broken. + + * "git rebase -i" gave bogus error message when the command word was + misspelled. + + * "git receive-pack" that is run in response to "git push" did not run + garbage collection nor update-server-info, but in larger hosting sites, + these almost always need to be run. To help site administrators, the + command now runs "gc --auto" and "u-s-i" by setting receive.autogc + and receive.updateserverinfo configuration variables, respectively. + + * Release notes spelled the package name with incorrect capitalization. + + * "gitweb" did not escape non-ascii characters correctly in the URL. + + * "gitweb" showed "patch" link even for merge commits. + + * "gitweb" showed incorrect links for blob line numbers in pathinfo mode. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.5.4.txt b/Documentation/RelNotes/1.6.5.4.txt new file mode 100644 index 0000000000..d3a2a3e712 --- /dev/null +++ b/Documentation/RelNotes/1.6.5.4.txt @@ -0,0 +1,32 @@ +Git v1.6.5.4 Release Notes +========================== + +Fixes since v1.6.5.3 +-------------------- + + * "git help" (without argument) used to check if you are in a directory + under git control. There was no breakage in behaviour per-se, but this + was unnecessary. + + * "git prune-packed" gave progress output even when its standard error is + not connected to a terminal; this caused cron jobs that run it to + produce crufts. + + * "git pack-objects --all-progress" is an option to ask progress output + from write-object phase _if_ progress output were to be produced, and + shouldn't have forced the progress output. + + * "git apply -p<n> --directory=<elsewhere>" did not work well for a + non-default value of n. + + * "git merge foo HEAD" was misparsed as an old-style invocation of the + command and produced a confusing error message. As it does not specify + any other branch to merge, it shouldn't be mistaken as such. We will + remove the old style "git merge <message> HEAD <commit>..." syntax in + 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 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 new file mode 100644 index 0000000000..ecfc57d875 --- /dev/null +++ b/Documentation/RelNotes/1.6.5.5.txt @@ -0,0 +1,49 @@ +Git v1.6.5.5 Release Notes +========================== + +Fixes since v1.6.5.4 +-------------------- + + * Manual pages can be formatted with older xmlto again. + + * GREP_OPTIONS exported from user's environment could have broken + our scripted commands. + + * In configuration files, a few variables that name paths can begin with + ~/ and ~username/ and they are expanded as expected. This is not a + bugfix but 1.6.6 will have this and without backporting users cannot + easily use the same ~/.gitconfig across versions. + + * "git diff -B -M" did the same computation to hash lines of contents + twice, and held onto memory after it has used the data in it + unnecessarily before it freed. + + * "git diff -B" and "git diff --dirstat" was not counting newly added + contents correctly. + + * "git format-patch revisions... -- path" issued an incorrect error + message that suggested to use "--" on the command line when path + does not exist in the current work tree (it is a separate matter if + it makes sense to limit format-patch with pathspecs like that + without using the --full-diff option). + + * "git grep -F -i StRiNg" did not work as expected. + + * Enumeration of available merge strategies iterated over the list of + commands in a wrong way, sometimes producing an incorrect result. + + * "git shortlog" did not honor the "encoding" header embedded in the + commit object like "git log" did. + + * Reading progress messages that come from the remote side while running + "git pull" is given precedence over reading the actual pack data to + prevent garbled progress message on the user's terminal. + + * "git rebase" got confused when the log message began with certain + strings that looked like Subject:, Date: or From: header. + + * "git reset" accidentally run in .git/ directory checked out the + work tree contents in there. + + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes/1.6.5.6.txt b/Documentation/RelNotes/1.6.5.6.txt new file mode 100644 index 0000000000..a9eaf76f62 --- /dev/null +++ b/Documentation/RelNotes/1.6.5.6.txt @@ -0,0 +1,23 @@ +Git v1.6.5.6 Release Notes +========================== + +Fixes since v1.6.5.5 +-------------------- + + * "git add -p" had a regression since v1.6.5.3 that broke deletion of + non-empty files. + + * "git archive -o o.zip -- Makefile" produced an archive in o.zip + but in POSIX tar format. + + * Error message given to "git pull --rebase" when the user didn't give + enough clue as to what branch to integrate with still talked about + "merging with" the branch. + + * Error messages given by "git merge" when the merge resulted in a + fast-forward still were in plumbing lingo, even though in v1.6.5 + we reworded messages in other cases. + + * The post-upload-hook run by upload-pack in response to "git fetch" has + been removed, due to security concerns (the hook first appeared in + 1.6.5). diff --git a/Documentation/RelNotes/1.6.5.7.txt b/Documentation/RelNotes/1.6.5.7.txt new file mode 100644 index 0000000000..dc5302c21c --- /dev/null +++ b/Documentation/RelNotes/1.6.5.7.txt @@ -0,0 +1,19 @@ +Git v1.6.5.7 Release Notes +========================== + +Fixes since v1.6.5.6 +-------------------- + +* If a user specifies a color for a <slot> (i.e. a class of things to show + in a particular color) that is known only by newer versions of git + (e.g. "color.diff.func" was recently added for upcoming 1.6.6 release), + 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 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 + repository, e.g. "rev-list HEAD -- /home", the code tried to run + strlen() on NULL, which is the result of get_git_work_tree(), and + segfaulted. 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 new file mode 100644 index 0000000000..ee141c19ad --- /dev/null +++ b/Documentation/RelNotes/1.6.5.txt @@ -0,0 +1,169 @@ +GIT v1.6.5 Release Notes +======================== + +In git 1.7.0, which was planned to be the release after 1.6.5, "git +push" into a branch that is currently checked out will be refused by +default. + +You can choose what should happen upon such a push by setting the +configuration variable receive.denyCurrentBranch in the receiving +repository. + +Also, "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. + +You can choose what should happen upon such a push by setting the +configuration variable receive.denyDeleteCurrent in the receiving +repository. + +To ease the transition plan, the receiving repository of such a +push running this release will issue a big warning when the +configuration variable is missing. Please refer to: + + http://git.or.cz/gitwiki/GitFaq#non-bare + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + +for more details on the reason why this change is needed and the +transition plan. + +Updates since v1.6.4 +-------------------- + +(subsystems) + + * various updates to gitk, git-svn and gitweb. + +(portability) + + * more improvements on mingw port. + + * mingw will also give FRSX as the default value for the LESS + environment variable when the user does not have one. + + * initial support to compile git on Windows with MSVC. + +(performance) + + * On major platforms, the system can be compiled to use with Linus's + block-sha1 implementation of the SHA-1 hash algorithm, which + outperforms the default fallback implementation we borrowed from + Mozilla. + + * Unnecessary inefficiency in deepening of a shallow repository has + been removed. + + * "git clone" does not grab objects that it does not need (i.e. + referenced only from refs outside refs/heads and refs/tags + hierarchy) anymore. + + * The "git" main binary used to link with libcurl, which then dragged + in a large number of external libraries. When using basic plumbing + commands in scripts, this unnecessarily slowed things down. We now + implement http/https/ftp transfer as a separate executable as we + used to. + + * "git clone" run locally hardlinks or copies the files in .git/ to + newly created repository. It used to give new mtime to copied files, + but this delayed garbage collection to trigger unnecessarily in the + cloned repository. We now preserve mtime for these files to avoid + this issue. + +(usability, bells and whistles) + + * Human writable date format to various options, e.g. --since=yesterday, + master@{2000.09.17}, are taught to infer some omitted input properly. + + * A few programs gave verbose "advice" messages to help uninitiated + people when issuing error messages. An infrastructure to allow + users to squelch them has been introduced, and a few such messages + can be silenced now. + + * refs/replace/ hierarchy is designed to be usable as a replacement + of the "grafts" mechanism, with the added advantage that it can be + transferred across repositories. + + * "git am" learned to optionally ignore whitespace differences. + + * "git am" handles input e-mail files that has CRLF line endings sensibly. + + * "git am" learned "--scissors" option to allow you to discard early part + of an incoming e-mail. + + * "git archive -o output.zip" works without being told what format to + use with an explicit "--format=zip".option. + + * "git checkout", "git reset" and "git stash" learned to pick and + choose to use selected changes you made, similar to "git add -p". + + * "git clone" learned a "-b" option to pick a HEAD to check out + different from the remote's default branch. + + * "git clone" learned --recursive option. + + * "git clone" from a local repository on a different filesystem used to + copy individual object files without preserving the old timestamp, giving + them extra lifetime in the new repository until they gc'ed. + + * "git commit --dry-run $args" is a new recommended way to ask "what would + happen if I try to commit with these arguments." + + * "git commit --dry-run" and "git status" shows conflicted paths in a + separate section to make them easier to spot during a merge. + + * "git cvsimport" now supports password-protected pserver access even + when the password is not taken from ~/.cvspass file. + + * "git fast-export" learned --no-data option that can be useful when + reordering commits and trees without touching the contents of + blobs. + + * "git fast-import" has a pair of new front-end in contrib/ area. + + * "git init" learned to mkdir/chdir into a directory when given an + extra argument (i.e. "git init this"). + + * "git instaweb" optionally can use mongoose as the web server. + + * "git log --decorate" can optionally be told with --decorate=full to + give the reference name in full. + + * "git merge" issued an unnecessarily scary message when it detected + that the merge may have to touch the path that the user has local + uncommitted changes to. The message has been reworded to make it + clear that the command aborted, without doing any harm. + + * "git push" can be told to be --quiet. + + * "git push" pays attention to url.$base.pushInsteadOf and uses a URL + that is derived from the URL used for fetching. + + * informational output from "git reset" that lists the locally modified + paths is made consistent with that of "git checkout $another_branch". + + * "git submodule" learned to give submodule name to scripts run with + "foreach" subcommand. + + * various subcommands to "git submodule" learned --recursive option. + + * "git submodule summary" learned --files option to compare the work + tree vs the commit bound at submodule path, instead of comparing + the index. + + * "git upload-pack", which is the server side support for "git clone" and + "git fetch", can call a new post-upload-pack hook for statistics purposes. + +(developers) + + * With GIT_TEST_OPTS="--root=/p/a/t/h", tests can be run outside the + source directory; using tmpfs may give faster turnaround. + + * With NO_PERL_MAKEMAKER set, DESTDIR= is now honoured, so you can + build for one location, and install into another location to tar it + up. + +Fixes since v1.6.4 +------------------ + +All of the fixes in v1.6.4.X maintenance series are included in this +release, unless otherwise noted. 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 new file mode 100644 index 0000000000..c50b59c495 --- /dev/null +++ b/Documentation/RelNotes/1.6.6.txt @@ -0,0 +1,224 @@ +Git v1.6.6 Release Notes +======================== + +Notes on behaviour change +------------------------- + + * In this release, "git fsck" defaults to "git fsck --full" and + checks packfiles, and because of this it will take much longer to + complete than before. If you prefer a quicker check only on loose + objects (the old default), you can say "git fsck --no-full". This + has been supported by 1.5.4 and newer versions of git, so it is + safe to write it in your script even if you use slightly older git + on some of your machines. + +Preparing yourselves for compatibility issues in 1.7.0 +------------------------------------------------------ + +In git 1.7.0, which is planned to be the release after 1.6.6, there will +be a handful of behaviour changes that will break backward compatibility. + +These changes were discussed long time ago and existing behaviours have +been identified as more problematic to the userbase than keeping them for +the sake of backward compatibility. + +When necessary, a transition strategy for existing users has been designed +not to force them running around setting configuration variables and +updating their scripts in order to either keep the traditional behaviour +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 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. + +For changes decided to be in 1.7.0, commands that will be affected +have been much louder to strongly discourage such procrastination, and +they continue to be in this release. If you have been using recent +versions of git, you would have seen warnings issued when you used +features whose behaviour will change, with a clear instruction on how +to keep the existing behaviour if you want to. You hopefully are +already well prepared. + +Of course, we have also been giving "this and that will change in +1.7.0; prepare yourselves" warnings in the release notes and +announcement messages for the past few releases. Let's see how well +users will fare this time. + + * "git push" into a branch that is currently checked out (i.e. pointed by + HEAD in a repository that is not bare) will be 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. Versions of git + since 1.6.2 have issued a loud warning when you tried to do these + operations without setting the configuration, so repositories of + people who still need to be able to perform such a push should + already have been future proofed. + + Please refer to: + + http://git.or.cz/gitwiki/GitFaq#non-bare + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + + for more details on the reason why this change is needed and the + transition process that already took place so far. + + * "git send-email" will 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. Git 1.6.6 (this + release) will issue a warning about the upcoming default change, when + it uses the traditional "deep threading" behaviour as the built-in + default. To squelch the warning but still use the "deep threading" + behaviour, give --chain-reply-to option or set sendemail.chainreplyto + to true. + + It has been possible to configure send-email to send "shallow thread" + by setting sendemail.chainreplyto configuration variable to false. + The only thing 1.7.0 release will do is to change the default when + you haven't configured that variable. + + * "git status" will not be "git commit --dry-run". This change does not + affect you if you run the command without pathspec. + + Nobody sane found the current behaviour of "git status Makefile" useful + nor meaningful, and it confused users. "git commit --dry-run" has been + provided as a way to get the current behaviour of this command since + 1.6.5. + + * "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 1.7.0, the "ignore whitespaces" will affect the semantics of the + diff operation itself. A change that does not affect anything but + whitespaces will be reported with zero exit status when run with + --exit-code, and there will not be "diff --git" header for such a + change. + + +Updates since v1.6.5 +-------------------- + +(subsystems) + + * various gitk updates including use of themed widgets under Tk 8.5, + Japanese translation, a fix to a bug when running "gui blame" from + a subdirectory, etc. + + * various git-gui updates including new translations, wm states fixes, + Tk bug workaround after quitting, improved heuristics to trigger gc, + etc. + + * various git-svn updates. + + * "git fetch" over http learned a new mode that is different from the + traditional "dumb commit walker". + +(portability) + + * imap-send can be built on mingw port. + +(performance) + + * "git diff -B" has smaller memory footprint. + +(usability, bells and whistles) + + * The object replace mechanism can be bypassed with --no-replace-objects + global option given to the "git" program. + + * In configuration files, a few variables that name paths can begin with ~/ + and ~username/ and they are expanded as expected. + + * "git subcmd -h" now shows short usage help for many more subcommands. + + * "git bisect reset" can reset to an arbitrary commit. + + * "git checkout frotz" when there is no local branch "frotz" but there + is only one remote tracking branch "frotz" is taken as a request to + start the named branch at the corresponding remote tracking branch. + + * "git commit -c/-C/--amend" can be told with a new "--reset-author" option + to ignore authorship information in the commit it is taking the message + from. + + * "git describe" can be told to add "-dirty" suffix with "--dirty" option. + + * "git diff" learned --submodule option to show a list of one-line logs + instead of differences between the commit object names. + + * "git diff" learned to honor diff.color.func configuration to paint + function name hint printed on the hunk header "@@ -j,k +l,m @@" line + in the specified color. + + * "git fetch" learned --all and --multiple options, to run fetch from + many repositories, and --prune option to remove remote tracking + branches that went stale. These make "git remote update" and "git + remote prune" less necessary (there is no plan to remove "remote + update" nor "remote prune", though). + + * "git fsck" by default checks the packfiles (i.e. "--full" is the + default); you can turn it off with "git fsck --no-full". + + * "git grep" can use -F (fixed strings) and -i (ignore case) together. + + * import-tars contributed fast-import frontend learned more types of + compressed tarballs. + + * "git instaweb" knows how to talk with mod_cgid to apache2. + + * "git log --decorate" shows the location of HEAD as well. + + * "git log" and "git rev-list" learned to take revs and pathspecs from + the standard input with the new "--stdin" option. + + * "--pretty=format" option to "log" family of commands learned: + + . to wrap text with the "%w()" specifier. + . to show reflog information with "%g[sdD]" specifier. + + * "git notes" command to annotate existing commits. + + * "git merge" (and "git pull") learned --ff-only option to make it fail + if the merge does not result in a fast-forward. + + * "git mergetool" learned to use p4merge. + + * "git rebase -i" learned "reword" that acts like "edit" but immediately + starts an editor to tweak the log message without returning control to + the shell, which is done by "edit" to give an opportunity to tweak the + contents. + + * "git send-email" can be told with "--envelope-sender=auto" to use the + same address as "From:" address as the envelope sender address. + + * "git send-email" will issue a warning when it defaults to the + --chain-reply-to behaviour without being told by the user and + instructs to prepare for the change of the default in 1.7.0 release. + + * In "git submodule add <repository> <path>", <path> is now optional and + inferred from <repository> the same way "git clone <repository>" does. + + * "git svn" learned to read SVN 1.5+ and SVK merge tickets. + + * "git svn" learned to recreate empty directories tracked only by SVN. + + * "gitweb" can optionally render its "blame" output incrementally (this + requires JavaScript on the client side). + + * Author names shown in gitweb output are links to search commits by the + author. + +Fixes since v1.6.5 +------------------ + +All of the fixes in v1.6.5.X maintenance series are included in this +release, unless otherwise noted. 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.10.1.txt b/Documentation/RelNotes/1.7.10.1.txt new file mode 100644 index 0000000000..806a965a1b --- /dev/null +++ b/Documentation/RelNotes/1.7.10.1.txt @@ -0,0 +1,78 @@ +Git v1.7.10.1 Release Notes +=========================== + +Additions since v1.7.10 +----------------------- + +Localization message files for Danish and German have been added. + + +Fixes since v1.7.10 +------------------- + + * "git add -p" is not designed to deal with unmerged paths but did + not exclude them and tried to apply funny patches only to fail. + + * "git blame" started missing quite a few changes from the origin + since we stopped using the diff minimalization by default in v1.7.2 + era. + + * When PATH contains an unreadable directory, alias expansion code + did not kick in, and failed with an error that said "git-subcmd" + was not found. + + * "git clean -d -f" (not "-d -f -f") is supposed to protect nested + working trees of independent git repositories that exist in the + current project working tree from getting removed, but the + protection applied only to such working trees that are at the + top-level of the current project by mistake. + + * "git commit --author=$name" did not tell the name that was being + recorded in the resulting commit to hooks, even though it does do + so when the end user overrode the authorship via the + "GIT_AUTHOR_NAME" environment variable. + + * When "git commit --template F" errors out because the user did not + touch the message, it claimed that it aborts due to "empty + message", which was utterly wrong. + + * The regexp configured with diff.wordregex was incorrectly reused + across files. + + * An age-old corner case bug in combine diff (only triggered with -U0 + and the hunk at the beginning of the file needs to be shown) has + been fixed. + + * Rename detection logic used to match two empty files as renames + during merge-recursive, leading to unnatural mismerges. + + * The parser in "fast-import" did not diagnose ":9" style references + that is not followed by required SP/LF as an error. + + * When "git fetch" encounters repositories with too many references, + the command line of "fetch-pack" that is run by a helper + e.g. remote-curl, may fail to hold all of them. Now such an + internal invocation can feed the references through the standard + input of "fetch-pack". + + * "git fetch" that recurses into submodules on demand did not check + if it needs to go into submodules when non branches (most notably, + tags) are fetched. + + * "log -p --graph" used with "--stat" had a few formatting error. + + * Running "notes merge --commit" failed to perform correctly when run + from any directory inside $GIT_DIR/. When "notes merge" stops with + conflicts, $GIT_DIR/NOTES_MERGE_WORKTREE is the place a user edits + to resolve it. + + * The 'push to upstream' implementation was broken in some corner + cases. "git push $there" without refspec, when the current branch + is set to push to a remote different from $there, used to push to + $there using the upstream information to a remote unreleated to + $there. + + * Giving "--continue" to a conflicted "rebase -i" session skipped a + commit that only results in changes to submodules. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.2.txt b/Documentation/RelNotes/1.7.10.2.txt new file mode 100644 index 0000000000..7a7e9d6fd1 --- /dev/null +++ b/Documentation/RelNotes/1.7.10.2.txt @@ -0,0 +1,85 @@ +Git v1.7.10.2 Release Notes +=========================== + +Fixes since v1.7.10.1 +--------------------- + + * The test scaffolding for git-daemon was flaky. + + * The test scaffolding for fast-import was flaky. + + * The filesystem boundary was not correctly reported when .git directory + discovery stopped at a mount point. + + * HTTP transport that requires authentication did not work correctly when + multiple connections are used simultaneously. + + * Minor memory leak during unpack_trees (hence "merge" and "checkout" + to check out another branch) has been plugged. + + * In the older days, the header "Conflicts:" in "cherry-pick" and "merge" + was separated by a blank line from the list of paths that follow for + readability, but when "merge" was rewritten in C, we lost it by + mistake. Remove the newline from "cherry-pick" to make them match + again. + + * The command line parser choked "git cherry-pick $name" when $name can + be both revision name and a pathname, even though $name can never be a + path in the context of the command. + + * The "include.path" facility in the configuration mechanism added in + 1.7.10 forgot to interpret "~/path" and "~user/path" as it should. + + * "git config --rename-section" to rename an existing section into a + bogus one did not check the new name. + + * The "diff --no-index" codepath used limited-length buffers, risking + pathnames getting truncated. Update it to use the strbuf API. + + * The report from "git fetch" said "new branch" even for a non branch + ref. + + * The http-backend (the server side of the smart http transfer) used + to overwrite GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL with the + value obtained from REMOTE_USER unconditionally, making it + impossible for the server side site-specific customization to use + different identity sources to affect the names logged. It now uses + REMOTE_USER only as a fallback value. + + * "log --graph" was not very friendly with "--stat" option and its + output had line breaks at wrong places. + + * Octopus merge strategy did not reduce heads that are recorded in the + final commit correctly. + + * "git push" over smart-http lost progress output a few releases ago; + this release resurrects it. + + * The error and advice messages given by "git push" when it fails due + to non-ff were not very helpful to new users; it has been broken + into three cases, and each is given a separate advice message. + + * The insn sheet given by "rebase -i" did not make it clear that the + insn lines can be re-ordered to affect the order of the commits in + the resulting history. + + * "git repack" used to write out unreachable objects as loose objects + when repacking, even if such loose objects will immediately pruned + due to its age. + + * A contrib script "rerere-train" did not work out of the box unless + user futzed with her $PATH. + + * "git rev-parse --show-prefix" used to emit nothing when run at the + top-level of the working tree, but now it gives a blank line. + + * The i18n of error message "git stash save" was not properly done. + + * "git submodule" used a sed script that some platforms mishandled. + + * When using a Perl script on a system where "perl" found on user's + $PATH could be ancient or otherwise broken, we allow builders to + specify the path to a good copy of Perl with $PERL_PATH. The + gitweb test forgot to use that Perl when running its test. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.3.txt b/Documentation/RelNotes/1.7.10.3.txt new file mode 100644 index 0000000000..703fbf1d60 --- /dev/null +++ b/Documentation/RelNotes/1.7.10.3.txt @@ -0,0 +1,43 @@ +Git v1.7.10.3 Release Notes +=========================== + +Fixes since v1.7.10.2 +--------------------- + + * The message file for German translation has been updated a bit. + + * Running "git checkout" on an unborn branch used to corrupt HEAD. + + * When checking out another commit from an already detached state, we + used to report all commits that are not reachable from any of the + refs as lossage, but some of them might be reachable from the new + HEAD, and there is no need to warn about them. + + * Some time ago, "git clone" lost the progress output for its + "checkout" phase; when run without any "--quiet" option, it should + give progress to the lengthy operation. + + * The directory path used in "git diff --no-index", when it recurses + down, was broken with a recent update after v1.7.10.1 release. + + * "log -z --pretty=tformat:..." did not terminate each record with + NUL. The fix is not entirely correct when the output also asks for + --patch and/or --stat, though. + + * The DWIM behaviour for "log --pretty=format:%gd -g" was somewhat + broken and gave undue precedence to configured log.date, causing + "git stash list" to show "stash@{time stamp string}". + + * "git status --porcelain" ignored "--branch" option by mistake. The + output for "git status --branch -z" was also incorrect and did not + terminate the record for the current branch name with NUL as asked. + + * When a submodule repository uses alternate object store mechanism, + some commands that were started from the superproject did not + notice it and failed with "No such object" errors. The subcommands + of "git submodule" command that recursed into the submodule in a + separate process were OK; only the ones that cheated and peeked + directly into the submodule's repository from the primary process + were affected. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.4.txt b/Documentation/RelNotes/1.7.10.4.txt new file mode 100644 index 0000000000..326670df6e --- /dev/null +++ b/Documentation/RelNotes/1.7.10.4.txt @@ -0,0 +1,29 @@ +Git v1.7.10.4 Release Notes +=========================== + +Fixes since v1.7.10.3 +--------------------- + + * The message file for Swedish translation has been updated a bit. + + * A name taken from mailmap was copied into an internal buffer + incorrectly and could overun the buffer if it is too long. + + * A malformed commit object that has a header line chomped in the + middle could kill git with a NULL pointer dereference. + + * An author/committer name that is a single character was mishandled + as an invalid name by mistake. + + * The progress indicator for a large "git checkout" was sent to + stderr even if it is not a terminal. + + * "git grep -e '$pattern'", unlike the case where the patterns are + read from a file, did not treat individual lines in the given + pattern argument as separate regular expressions as it should. + + * When "git rebase" was given a bad commit to replay the history on, + its error message did not correctly give the command line argument + it had trouble parsing. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.txt b/Documentation/RelNotes/1.7.10.txt new file mode 100644 index 0000000000..58100bf04e --- /dev/null +++ b/Documentation/RelNotes/1.7.10.txt @@ -0,0 +1,219 @@ +Git v1.7.10 Release Notes +========================= + +Compatibility Notes +------------------- + + * From this release on, the "git merge" command in an interactive + session will start an editor when it automatically resolves the + merge for the user to explain the resulting commit, just like the + "git commit" command does when it wasn't given a commit message. + + If you have a script that runs "git merge" and keeps its standard + input and output attached to the user's terminal, and if you do not + want the user to explain the resulting merge commits, you can + export GIT_MERGE_AUTOEDIT environment variable set to "no", like + this: + + #!/bin/sh + GIT_MERGE_AUTOEDIT=no + export GIT_MERGE_AUTOEDIT + + to disable this behavior (if you want your users to explain their + merge commits, you do not have to do anything). Alternatively, you + can give the "--no-edit" option to individual invocations of the + "git merge" command if you know everybody who uses your script has + Git v1.7.8 or newer. + + * The "--binary/-b" options to "git am" have been a no-op for quite a + while and were deprecated in mid 2008 (v1.6.0). When you give these + options to "git am", it will now warn and ask you not to use them. + + * When you do not tell which branches and tags to push to the "git + push" command in any way, the command used "matching refs" rule to + update remote branches and tags with branches and tags with the + same name you locally have. In future versions of Git, this will + change to push out only your current branch according to either the + "upstream" or the "current" rule. Although "upstream" may be more + powerful once the user understands Git better, the semantics + "current" gives is simpler and easier to understand for beginners + and may be a safer and better default option. We haven't decided + yet which one to switch to. + + +Updates since v1.7.9 +-------------------- + +UI, Workflows & Features + + * various "gitk" updates. + - show the path to the top level directory in the window title + - update preference edit dialog + - display file list correctly when directories are given on command line + - make "git-describe" output in the log message into a clickable link + - avoid matching the UNIX timestamp part when searching all fields + - give preference to symbolic font names like sans & monospace + - allow comparing two commits using a mark + - "gitk" honors log.showroot configuration. + + * Teams for localizing the messages from the Porcelain layer of + commands are starting to form, thanks to Jiang Xin who volunteered + to be the localization coordinator. Translated messages for + simplified Chinese, Swedish and Portuguese are available. + + * The configuration mechanism learned an "include" facility; an + assignment to the include.path pseudo-variable causes the named + file to be included in-place when Git looks up configuration + variables. + + * A content filter (clean/smudge) used to be just a way to make the + recorded contents "more useful", and allowed to fail; a filter can + now optionally be marked as "required". + + * Options whose names begin with "--no-" (e.g. the "--no-verify" + option of the "git commit" command) can be negated by omitting + "no-" from its name, e.g. "git commit --verify". + + * "git am" learned to pass "-b" option to underlying "git mailinfo", so + that a bracketed string other than "PATCH" at the beginning can be kept. + + * "git clone" learned "--single-branch" option to limit cloning to a + single branch (surprise!); tags that do not point into the history + of the branch are not fetched. + + * "git clone" learned to detach the HEAD in the resulting repository + when the user specifies a tag with "--branch" (e.g., "--branch=v1.0"). + Clone also learned to print the usual "detached HEAD" advice in such + a case, similar to "git checkout v1.0". + + * When showing a patch while ignoring whitespace changes, the context + lines are taken from the postimage, in order to make it easier to + view the output. + + * "git diff --stat" learned to adjust the width of the output on + wider terminals, and give more columns to pathnames as needed. + + * "diff-highlight" filter (in contrib/) was updated to produce more + aesthetically pleasing output. + + * "fsck" learned "--no-dangling" option to omit dangling object + information. + + * "git log -G" and "git log -S" learned to pay attention to the "-i" + option. With "-i", "log -G" ignores the case when finding patch + hunks that introduce or remove a string that matches the given + pattern. Similarly with "-i", "log -S" ignores the case when + finding the commit the given block of text appears or disappears + from the file. + + * "git merge" in an interactive session learned to spawn the editor + by default to let the user edit the auto-generated merge message, + to encourage people to explain their merges better. Legacy scripts + can export GIT_MERGE_AUTOEDIT=no to retain the historical behavior. + Both "git merge" and "git pull" can be given --no-edit from the + command line to accept the auto-generated merge message. + + * The advice message given when the user didn't give enough clue on + what to merge to "git pull" and "git merge" has been updated to + be more concise and easier to understand. + + * "git push" learned the "--prune" option, similar to "git fetch". + + * The whole directory that houses a top-level superproject managed by + "git submodule" can be moved to another place. + + * "git symbolic-ref" learned the "--short" option to abbreviate the + refname it shows unambiguously. + + * "git tag --list" can be given "--points-at <object>" to limit its + output to those that point at the given object. + + * "gitweb" allows intermediate entries in the directory hierarchy + that leads to a project to be clicked, which in turn shows the + list of projects inside that directory. + + * "gitweb" learned to read various pieces of information for the + repositories lazily, instead of reading everything that could be + needed (including the ones that are not necessary for a specific + task). + + * Project search in "gitweb" shows the substring that matched in the + project name and description highlighted. + + * HTTP transport learned to authenticate with a proxy if needed. + + * A new script "diffall" is added to contrib/; it drives an + external tool to perform a directory diff of two Git revisions + in one go, unlike "difftool" that compares one file at a time. + +Foreign Interface + + * Improved handling of views, labels and branches in "git-p4" (in contrib). + + * "git-p4" (in contrib) suffered from unnecessary merge conflicts when + p4 expanded the embedded $RCS$-like keywords; it can be now told to + unexpand them. + + * Some "git-svn" updates. + + * "vcs-svn"/"svn-fe" learned to read dumps with svn-deltas and + support incremental imports. + + * "git difftool/mergetool" learned to drive DeltaWalker. + +Performance + + * Unnecessary calls to parse_object() "git upload-pack" makes in + response to "git fetch", have been eliminated, to help performance + in repositories with excessive number of refs. + +Internal Implementation (please report possible regressions) + + * Recursive call chains in "git index-pack" to deal with long delta + chains have been flattened, to reduce the stack footprint. + + * Use of add_extra_ref() API is now gone, to make it possible to + cleanly restructure the overall refs API. + + * The command line parser of "git pack-objects" now uses parse-options + API. + + * The test suite supports the new "test_pause" helper function. + + * Parallel to the test suite, there is a beginning of performance + benchmarking framework. + + * t/Makefile is adjusted to prevent newer versions of GNU make from + running tests in seemingly random order. + + * The code to check if a path points at a file beyond a symbolic link + has been restructured to be thread-safe. + + * When pruning directories that has become empty during "git prune" + and "git prune-packed", call closedir() that iterates over a + directory before rmdir() it. + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.9 +------------------ + +Unless otherwise noted, all the fixes since v1.7.9 in the maintenance +releases are contained in this release (see release notes to them for +details). + + * Build with NO_PERL_MAKEMAKER was broken and Git::I18N did not work + with versions of Perl older than 5.8.3. + (merge 5eb660e ab/perl-i18n later to maint). + + * "git tag -s" honored "gpg.program" configuration variable since + 1.7.9, but "git tag -v" and "git verify-tag" didn't. + (merge a2c2506 az/verify-tag-use-gpg-config later to maint). + + * "configure" script learned to take "--with-sane-tool-path" from the + command line to record SANE_TOOL_PATH (used to avoid broken platform + tools in /usr/bin) in config.mak.autogen. This may be useful for + people on Solaris who have saner tools outside /usr/xpg[46]/bin. + + * zsh port of bash completion script needed another workaround. diff --git a/Documentation/RelNotes/1.7.11.txt b/Documentation/RelNotes/1.7.11.txt new file mode 100644 index 0000000000..a1f7994cec --- /dev/null +++ b/Documentation/RelNotes/1.7.11.txt @@ -0,0 +1,143 @@ +Git v1.7.11 Release Notes +========================= + +Updates since v1.7.10 +--------------------- + +UI, Workflows & Features + + * A new mode for push, "simple", which is a cross between "current" + and "upstream", has been introduced. "git push" without any refspec + will push the current branch out to the same name at the remote + repository only when it is set to track the branch with the same + name over there. The plan is to make this mode the new default + value when push.default is not configured. + + * A couple of commands learned the "--column" option to produce + columnar output. + + * A third-party tool "git subtree" is distributed in contrib/ + + * A remote helper that acts as a proxy and caches ssl session for the + https:// transport is added to the contrib/ area. + + * Error messages given when @{u} is used for a branch without its + upstream configured have been clarified. + + * Even with the "-q"uiet option, "checkout" used to report setting up + tracking. Also "branch" learned the "-q"uiet option to squelch + informational message. + + * Your build platform may support hardlinks but you may prefer not to + use them, e.g. when installing to DESTDIR to make a tarball and + untarring on a filesystem that has poor support for hardlinks. + There is a Makefile option NO_INSTALL_HARDLINKS for you. + + * The smart-http backend used to always override GIT_COMMITTER_* + variables with REMOTE_USER and REMOTE_ADDR, but these variables are + now preserved when set. + + * "git am" learned the "--include" option, which is an opposite of + existing the "--exclude" option. + + * When "git am -3" needs to fall back to an application of the patch + to a synthesized preimage followed by a 3-way merge, the paths that + needed such treatment are now reported to the end user, so that the + result in them can be eyeballed with extra care. + + * The output from "diff/log --stat" used to always allocate 4 columns + to show the number of modified lines, but not anymore. + + * "git difftool" learned the "--dir-diff" option to spawn external + diff tools that can compare two directory hierarchies at a time + after populating two temporary directories, instead of running an + instance of the external tool once per a file pair. + + * The "fmt-merge-msg" command learned to list the primary contributors + involved in the side topic you are merging. + + * "git rebase" learned to optionally keep commits that do not + introduce any change in the original history. + + * "git push --recurse-submodules" learned to optionally look into the + histories of submodules bound to the superproject and push them + out. + + * A 'snapshot' request to "gitweb" honors If-Modified-Since: header, + based on the commit date. + + * "gitweb" learned to highlight the patch it outputs even more. + +Foreign Interface + + * "git svn" used to die with unwanted SIGPIPE when talking with an HTTP + server that uses keep-alive. + + * "git svn" learned to use platform specific authentication + providers, e.g. gnome-keyring, kwallet, etc. + + * "git p4" has been moved out of the contrib/ area and has seen more + work on importing labels as tags from (and exporting tags as labels + to) p4. + +Performance and Internal Implementation (please report possible regressions) + + * Bash completion script (in contrib/) have been cleaned up to make + future work on it simpler. + + * An experimental "version 4" format of the index file has been + introduced to reduce on-disk footprint and I/O overhead. + + * "git archive" learned to produce its output without reading the + blob object it writes out in memory in its entirety. + + * "git index-pack" that runs when fetching or pushing objects to + complete the packfile on the receiving end learned to use multiple + threads to do its job when available. + + * The code to compute hash values for lines used by the internal diff + engine was optimized on little-endian machines, using the same + trick the kernel folks came up with. + + * "git apply" had some memory leaks plugged. + + * Setting up a revision traversal with many starting points was + inefficient as these were placed in a date-order priority queue + one-by-one. Now they are collected in the queue unordered first, + and sorted immediately before getting used. + + * More lower-level commands learned to use the streaming API to read + from the object store without keeping everything in core. + + * The weighting parameters to suggestion command name typo have been + tweaked, so that "git tags" will suggest "tag?" and not "stage?". + + * Because "sh" on the user's PATH may be utterly broken on some + systems, run-command API now uses SHELL_PATH, not /bin/sh, when + spawning an external command (not applicable to Windows port). + + * The API to iterate over the refs/ hierarchy has been tweaked to + allow walking only a subset of it more efficiently. + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.10 +------------------- + +Unless otherwise noted, all the fixes since v1.7.10 in the maintenance +releases are contained in this release (see release notes to them for +details). + + * "git rebase -p" used to pay attention to rebase.autosquash which + was wrong. "git rebase -p -i" should, but "git rebase -p" by + itself should not. + (cherry-pick 8a6dae1 vr/rebase-autosquash-does-not-imply-i later to maint). + + * "git submodule init" used to report "registered for path ..." + even for submodules that were registered earlier. + (cherry-pick c1c259e jl/submodule-report-new-path-once later to maint). + + * "git diff --stat" used to fully count a binary file with modified + execution bits whose contents is unmodified, which was not quite + right. 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.5.txt b/Documentation/RelNotes/1.7.6.5.txt new file mode 100644 index 0000000000..6713132a9e --- /dev/null +++ b/Documentation/RelNotes/1.7.6.5.txt @@ -0,0 +1,26 @@ +Git v1.7.6.5 Release Notes +========================== + +Fixes since v1.7.6.4 +-------------------- + + * The date parser did not accept timezone designators that lack minutes + part and also has a colon between "hh:mm". + + * After fetching from a remote that has very long refname, the reporting + output could have corrupted by overrunning a static buffer. + + * "git mergetool" did not use its arguments as pathspec, but as a path to + the file that may not even have any conflict. + + * "git name-rev --all" tried to name all _objects_, naturally failing to + describe many blobs and trees, instead of showing only commits as + advertised in its documentation. + + * "git remote rename $a $b" were not careful to match the remote name + against $a (i.e. source side of the remote nickname). + + * "gitweb" used to produce a non-working link while showing the contents + of a blob, when JavaScript actions are enabled. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.6.txt b/Documentation/RelNotes/1.7.6.6.txt new file mode 100644 index 0000000000..5343e00400 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.6.txt @@ -0,0 +1,16 @@ +Git v1.7.6.6 Release Notes +========================== + +Fixes since v1.7.6.5 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + +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.4.txt b/Documentation/RelNotes/1.7.7.4.txt new file mode 100644 index 0000000000..e5234485e7 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.4.txt @@ -0,0 +1,14 @@ +Git v1.7.7.4 Release Notes +========================== + +Fixes since v1.7.7.3 +-------------------- + + * A few header dependencies were missing from the Makefile. + + * Some newer parts of the code used C99 __VA_ARGS__ while we still + try to cater to older compilers. + + * "git name-rev --all" tried to name all _objects_, naturally failing to + describe many blobs and trees, instead of showing only commits as + advertised in its documentation. diff --git a/Documentation/RelNotes/1.7.7.5.txt b/Documentation/RelNotes/1.7.7.5.txt new file mode 100644 index 0000000000..7b0931987b --- /dev/null +++ b/Documentation/RelNotes/1.7.7.5.txt @@ -0,0 +1,14 @@ +Git v1.7.7.5 Release Notes +========================== + +Fixes since v1.7.7.4 +-------------------- + + * After fetching from a remote that has very long refname, the reporting + output could have corrupted by overrunning a static buffer. + + * "git checkout" and "git merge" treated in-tree .gitignore and exclude + file in $GIT_DIR/info/ directory inconsistently when deciding which + untracked files are ignored and expendable. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.7.6.txt b/Documentation/RelNotes/1.7.7.6.txt new file mode 100644 index 0000000000..8df606d452 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.6.txt @@ -0,0 +1,20 @@ +Git v1.7.7.6 Release Notes +========================== + +Fixes since v1.7.7.5 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * A wildcard that matches deeper hierarchy given to the "diff-index" command, + e.g. "git diff-index HEAD -- '*.txt'", incorrectly reported additions of + matching files even when there is no change. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.7.7.txt b/Documentation/RelNotes/1.7.7.7.txt new file mode 100644 index 0000000000..e79118d063 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.7.txt @@ -0,0 +1,13 @@ +Git v1.7.7.7 Release Notes +========================== + +Fixes since v1.7.7.6 +-------------------- + + * An error message from 'git bundle' had an unmatched single quote pair in it. + + * 'git diff --histogram' option was not described. + + * 'git imap-send' carried an unused dead code. + +Also contains minor fixes and documentation updates. 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.1.txt b/Documentation/RelNotes/1.7.8.1.txt new file mode 100644 index 0000000000..33dc948b94 --- /dev/null +++ b/Documentation/RelNotes/1.7.8.1.txt @@ -0,0 +1,38 @@ +Git v1.7.8.1 Release Notes +========================== + +Fixes since v1.7.8 +------------------ + + * In some codepaths (notably, checkout and merge), the ignore patterns + recorded in $GIT_DIR/info/exclude were not honored. They now are. + + * "git apply --check" did not error out when given an empty input + without any patch. + + * "git archive" mistakenly allowed remote clients to ask for commits + that are not at the tip of any ref. + + * "git checkout" and "git merge" treated in-tree .gitignore and exclude + file in $GIT_DIR/info/ directory inconsistently when deciding which + untracked files are ignored and expendable. + + * LF-to-CRLF streaming filter used when checking out a large-ish blob + fell into an infinite loop with a rare input. + + * The function header pattern for files with "diff=cpp" attribute did + not consider "type *funcname(type param1,..." as the beginning of a + function. + + * The error message from "git diff" and "git status" when they fail + to inspect changes in submodules did not report which submodule they + had trouble with. + + * After fetching from a remote that has very long refname, the reporting + output could have corrupted by overrunning a static buffer. + + * "git pack-objects" avoids creating cyclic dependencies among deltas + when seeing a broken packfile that records the same object in both + the deflated form and as a delta. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.2.txt b/Documentation/RelNotes/1.7.8.2.txt new file mode 100644 index 0000000000..e74f4ef1ef --- /dev/null +++ b/Documentation/RelNotes/1.7.8.2.txt @@ -0,0 +1,71 @@ +Git v1.7.8.2 Release Notes +========================== + +Fixes since v1.7.8.1 +-------------------- + + * Porcelain commands like "git reset" did not distinguish deletions + and type-changes from ordinary modification, and reported them with + the same 'M' moniker. They now use 'D' (for deletion) and 'T' (for + type-change) to match "git status -s" and "git diff --name-status". + + * The configuration file parser used for sizes (e.g. bigFileThreshold) + did not correctly interpret 'g' suffix. + + * The replacement implemention for snprintf used on platforms with + native snprintf that is broken did not use va_copy correctly. + + * LF-to-CRLF streaming filter replaced all LF with CRLF, which might + be techinically correct but not friendly to people who are trying + to recover from earlier mistakes of using CRLF in the repository + data in the first place. It now refrains from doing so for LF that + follows a CR. + + * git native connection going over TCP (not over SSH) did not set + SO_KEEPALIVE option which failed to receive link layer errors. + + * "git branch -m <current branch> HEAD" is an obvious no-op but was not + allowed. + + * "git checkout -m" did not recreate the conflicted state in a "both + sides added, without any common ancestor version" conflict + situation. + + * "git cherry-pick $commit" (not a range) created an unnecessary + sequencer state and interfered with valid workflow to use the + command during a session to cherry-pick multiple commits. + + * You could make "git commit" segfault by giving the "--no-message" + option. + + * "fast-import" did not correctly update an existing notes tree, + possibly corrupting the fan-out. + + * "git fetch-pack" accepted unqualified refs that do not begin with + refs/ by mistake and compensated it by matching the refspec with + tail-match, which was doubly wrong. This broke fetching from a + repository with a funny named ref "refs/foo/refs/heads/master" and a + 'master' branch with "git fetch-pack refs/heads/master", as the + command incorrectly considered the former a "match". + + * "git log --follow" did not honor the rename threshold score given + with the -M option (e.g. "-M50%"). + + * "git mv" gave suboptimal error/warning messages when it overwrites + target files. It also did not pay attention to "-v" option. + + * Authenticated "git push" over dumb HTTP were broken with a recent + change and failed without asking for password when username is + given. + + * "git push" to an empty repository over HTTP were broken with a + recent change to the ref handling. + + * "git push -v" forgot how to be verbose by mistake. It now properly + becomes verbose when asked to. + + * When a "reword" action in "git rebase -i" failed to run "commit --amend", + we did not give the control back to the user to resolve the situation, and + instead kept the original commit log message. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.3.txt b/Documentation/RelNotes/1.7.8.3.txt new file mode 100644 index 0000000000..a92714c14b --- /dev/null +++ b/Documentation/RelNotes/1.7.8.3.txt @@ -0,0 +1,16 @@ +Git v1.7.8.3 Release Notes +========================== + +Fixes since v1.7.8.2 +-------------------- + + * Attempt to fetch from an empty file pretending it to be a bundle did + not error out correctly. + + * gitweb did not correctly fall back to configured $fallback_encoding + that is not 'latin1'. + + * "git clone --depth $n" did not catch a non-number given as $n as an + error. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.4.txt b/Documentation/RelNotes/1.7.8.4.txt new file mode 100644 index 0000000000..9bebdbf13d --- /dev/null +++ b/Documentation/RelNotes/1.7.8.4.txt @@ -0,0 +1,23 @@ +Git v1.7.8.4 Release Notes +========================== + +Fixes since v1.7.8.3 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * A wildcard that matches deeper hierarchy given to the "diff-index" command, + e.g. "git diff-index HEAD -- '*.txt'", incorrectly reported additions of + matching files even when there is no change. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + + * "git send-email" did not properly treat sendemail.multiedit as a + boolean (e.g. setting it to "false" did not turn it off). + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.5.txt b/Documentation/RelNotes/1.7.8.5.txt new file mode 100644 index 0000000000..011fd2a428 --- /dev/null +++ b/Documentation/RelNotes/1.7.8.5.txt @@ -0,0 +1,19 @@ +Git v1.7.8.5 Release Notes +========================== + +Fixes since v1.7.8.4 +-------------------- + + * Dependency on our thread-utils.h header file was missing for + objects that depend on it in the Makefile. + + * "git am" when fed an empty file did not correctly finish reading it + when it attempts to guess the input format. + + * "git grep -P" (when PCRE is enabled in the build) did not match the + beginning and the end of the line correctly with ^ and $. + + * "git rebase -m" tried to run "git notes copy" needlessly when + nothing was rewritten. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.6.txt b/Documentation/RelNotes/1.7.8.6.txt new file mode 100644 index 0000000000..d9bf2b741a --- /dev/null +++ b/Documentation/RelNotes/1.7.8.6.txt @@ -0,0 +1,22 @@ +Git v1.7.8.6 Release Notes +========================== + +Fixes since v1.7.8.5 +-------------------- + + * An error message from 'git bundle' had an unmatched single quote pair in it. + + * 'git diff --histogram' option was not described. + + * Documentation for 'git rev-list' had minor formatting errors. + + * 'git imap-send' carried an unused dead code. + + * The way 'git fetch' implemented its connectivity check over + received objects was overly pessimistic, and wasted a lot of + cycles. + + * Various minor backports of fixes from the 'master' and the 'maint' + branch. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.txt b/Documentation/RelNotes/1.7.8.txt new file mode 100644 index 0000000000..b4d90bba0f --- /dev/null +++ b/Documentation/RelNotes/1.7.8.txt @@ -0,0 +1,161 @@ +Git v1.7.8 Release Notes +======================== + +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" and "--abort". + + * "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. + + * "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). + + * 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). + + * Help text for "git remote set-url" and "git remote set-branches" + were misspelled. + (merge c49904e fc/remote-seturl-usage-fix later to maint). + (merge 656cdf0 jc/remote-setbranches-usage-fix later to maint). diff --git a/Documentation/RelNotes/1.7.9.1.txt b/Documentation/RelNotes/1.7.9.1.txt new file mode 100644 index 0000000000..6957183dbb --- /dev/null +++ b/Documentation/RelNotes/1.7.9.1.txt @@ -0,0 +1,63 @@ +Git v1.7.9.1 Release Notes +========================== + +Fixes since v1.7.9 +------------------ + + * The makefile allowed environment variable X seep into it result in + command names suffixed with unnecessary strings. + + * The set of included header files in compat/inet-{ntop,pton} + wrappers was updated for Windows some time ago, but in a way that + broke Solaris build. + + * rpmbuild noticed an unpackaged but installed *.mo file and failed. + + * Subprocesses spawned from various git programs were often left running + to completion even when the top-level process was killed. + + * "git add -e" learned not to show a diff for an otherwise unmodified + submodule that only has uncommitted local changes in the patch + prepared by for the user to edit. + + * Typo in "git branch --edit-description my-tpoic" was not diagnosed. + + * Using "git grep -l/-L" together with options -W or --break may not + make much sense as the output is to only count the number of hits + and there is no place for file breaks, but the latter options made + "-l/-L" to miscount the hits. + + * "git log --first-parent $pathspec" did not stay on the first parent + chain and veered into side branch from which the whole change to the + specified paths came. + + * "git merge --no-edit $tag" failed to honor the --no-edit option. + + * "git merge --ff-only $tag" failed because it cannot record the + required mergetag without creating a merge, but this is so common + operation for branch that is used _only_ to follow the upstream, so + it was changed to allow fast-forwarding without recording the mergetag. + + * "git mergetool" now gives an empty file as the common base version + to the backend when dealing with the "both sides added, differently" + case. + + * "git push -q" was not sufficiently quiet. + + * When "git push" fails to update any refs, the client side did not + report an error correctly to the end user. + + * "rebase" and "commit --amend" failed to work on commits with ancient + timestamps near year 1970. + + * When asking for a tag to be pulled, "request-pull" did not show the + name of the tag prefixed with "tags/", which would have helped older + clients. + + * "git submodule add $path" forgot to recompute the name to be stored + in .gitmodules when the submodule at $path was once added to the + superproject and already initialized. + + * Many small corner case bugs on "git tag -n" was corrected. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.2.txt b/Documentation/RelNotes/1.7.9.2.txt new file mode 100644 index 0000000000..e500da75dd --- /dev/null +++ b/Documentation/RelNotes/1.7.9.2.txt @@ -0,0 +1,69 @@ +Git v1.7.9.2 Release Notes +========================== + +Fixes since v1.7.9.1 +-------------------- + + * Bash completion script (in contrib/) did not like a pattern that + begins with a dash to be passed to __git_ps1 helper function. + + * Adaptation of the bash completion script (in contrib/) for zsh + incorrectly listed all subcommands when "git <TAB><TAB>" was given + to ask for list of porcelain subcommands. + + * The build procedure for profile-directed optimized binary was not + working very well. + + * Some systems need to explicitly link -lcharset to get locale_charset(). + + * t5541 ignored user-supplied port number used for HTTP server testing. + + * The error message emitted when we see an empty loose object was + not phrased correctly. + + * The code to ask for password did not fall back to the terminal + input when GIT_ASKPASS is set but does not work (e.g. lack of X + with GUI askpass helper). + + * We failed to give the true terminal width to any subcommand when + they are invoked with the pager, i.e. "git -p cmd". + + * map_user() was not rewriting its output correctly, which resulted + in the user visible symptom that "git blame -e" sometimes showed + excess '>' at the end of email addresses. + + * "git checkout -b" did not allow switching out of an unborn branch. + + * When you have both .../foo and .../foo.git, "git clone .../foo" did not + favor the former but the latter. + + * "git commit" refused to create a commit when entries added with + "add -N" remained in the index, without telling Git what their content + in the next commit should be. We should have created the commit without + these paths. + + * "git diff --stat" said "files", "insertions", and "deletions" even + when it is showing one "file", one "insertion" or one "deletion". + + * The output from "git diff --stat" for two paths that have the same + amount of changes showed graph bars of different length due to the + way we handled rounding errors. + + * "git grep" did not pay attention to -diff (hence -binary) attribute. + + * The transport programs (fetch, push, clone)ignored --no-progress + and showed progress when sending their output to a terminal. + + * Sometimes error status detected by a check in an earlier phase of + "git receive-pack" (the other end of "git push") was lost by later + checks, resulting in false indication of success. + + * "git rev-list --verify" sometimes skipped verification depending on + the phase of the moon, which dates back to 1.7.8.x series. + + * Search box in "gitweb" did not accept non-ASCII characters correctly. + + * Search interface of "gitweb" did not show multiple matches in the same file + correctly. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.3.txt b/Documentation/RelNotes/1.7.9.3.txt new file mode 100644 index 0000000000..91c65012f9 --- /dev/null +++ b/Documentation/RelNotes/1.7.9.3.txt @@ -0,0 +1,51 @@ +Git v1.7.9.3 Release Notes +========================== + +Fixes since v1.7.9.2 +-------------------- + + * "git p4" (in contrib/) submit the changes to a wrong place when the + "--use-client-spec" option is set. + + * The config.mak.autogen generated by optional autoconf support tried + to link the binary with -lintl even when libintl.h is missing from + the system. + + * When the filter driver exits before reading the content before the + main git process writes the contents to be filtered to the pipe to + it, the latter could be killed with SIGPIPE instead of ignoring + such an event as an error. + + * "git add --refresh <pathspec>" used to warn about unmerged paths + outside the given pathspec. + + * The bulk check-in codepath in "git add" streamed contents that + needs smudge/clean filters without running them, instead of punting + and delegating to the codepath to run filters after slurping + everything to core. + + * "git branch --with $that" assumed incorrectly that the user will never + ask the question with nonsense value in $that. + + * "git bundle create" produced a corrupt bundle file upon seeing + commits with excessively long subject line. + + * When a remote helper exits before reading the blank line from the + main git process to signal the end of commands, the latter could be + killed with SIGPIPE. Instead we should ignore such event as a + non-error. + + * The commit log template given with "git merge --edit" did not have + a short instructive text like what "git commit" gives. + + * "git rev-list --verify-objects -q" omitted the extra verification + it needs to do over "git rev-list --objects -q" by mistake. + + * "gitweb" used to drop warnings in the log file when "heads" view is + accessed in a repository whose HEAD does not point at a valid + branch. + + * An invalid regular expression pattern given by an end user made + "gitweb" to return garbled response. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.4.txt b/Documentation/RelNotes/1.7.9.4.txt new file mode 100644 index 0000000000..e5217a1889 --- /dev/null +++ b/Documentation/RelNotes/1.7.9.4.txt @@ -0,0 +1,24 @@ +Git v1.7.9.4 Release Notes +========================== + +Fixes since v1.7.9.3 +-------------------- + + * The code to synthesize the fake ancestor tree used by 3-way merge + fallback in "git am" was not prepared to read a patch created with + a non-standard -p<num> value. + + * "git bundle" did not record boundary commits correctly when there + are many of them. + + * "git diff-index" and its friends at the plumbing level showed the + "diff --git" header and nothing else for a path whose cached stat + info is dirty without actual difference when asked to produce a + patch. This was a longstanding bug that we could have fixed long + time ago. + + * "gitweb" did use quotemeta() to prepare search string when asked to + do a fixed-string project search, but did not use it by mistake and + used the user-supplied string instead. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.5.txt b/Documentation/RelNotes/1.7.9.5.txt new file mode 100644 index 0000000000..95cc2bbf2c --- /dev/null +++ b/Documentation/RelNotes/1.7.9.5.txt @@ -0,0 +1,23 @@ +Git v1.7.9.5 Release Notes +========================== + +Fixes since v1.7.9.4 +-------------------- + + * When "git config" diagnoses an error in a configuration file and + shows the line number for the offending line, it miscounted if the + error was at the end of line. + + * "git fast-import" accepted "ls" command with an empty path by + mistake. + + * Various new-ish output decoration modes of "git grep" were not + documented in the manual's synopsis section. + + * The "remaining" subcommand to "git rerere" was not documented. + + * "gitweb" used to drop warnings in the log file when "heads" view is + accessed in a repository whose HEAD does not point at a valid + branch. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.6.txt b/Documentation/RelNotes/1.7.9.6.txt new file mode 100644 index 0000000000..74bf8825e2 --- /dev/null +++ b/Documentation/RelNotes/1.7.9.6.txt @@ -0,0 +1,12 @@ +Git v1.7.9.6 Release Notes +========================== + +Fixes since v1.7.9.5 +-------------------- + + * "git merge $tag" to merge an annotated tag always opens the editor + during an interactive edit session. v1.7.10 series introduced an + environment variable GIT_MERGE_AUTOEDIT to help older scripts decline + this behaviour, but the maintenance track should also support it. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.7.txt b/Documentation/RelNotes/1.7.9.7.txt new file mode 100644 index 0000000000..59667d0f2a --- /dev/null +++ b/Documentation/RelNotes/1.7.9.7.txt @@ -0,0 +1,13 @@ +Git v1.7.9.7 Release Notes +========================== + +Fixes since v1.7.9.6 +-------------------- + + * An error message from 'git bundle' had an unmatched single quote pair in it. + + * The way 'git fetch' implemented its connectivity check over + received objects was overly pessimistic, and wasted a lot of + cycles. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.txt b/Documentation/RelNotes/1.7.9.txt new file mode 100644 index 0000000000..95320aad5d --- /dev/null +++ b/Documentation/RelNotes/1.7.9.txt @@ -0,0 +1,112 @@ +Git v1.7.9 Release Notes +======================== + +Updates since v1.7.8 +-------------------- + + * gitk updates accumulated since early 2011. + + * git-gui updated to 0.16.0. + + * git-p4 (in contrib/) updates. + + * Git uses gettext to translate its most common interface messages + into the user's language if translations are available and the + locale is appropriately set. Distributors can drop new PO files + in po/ to add new translations. + + * The code to handle username/password for HTTP transactions used in + "git push" & "git fetch" learned to talk "credential API" to + external programs to cache or store them, to allow integration with + platform native keychain mechanisms. + + * The input prompts in the terminal use our own getpass() replacement + when possible. HTTP transactions used to ask for the username without + echoing back what was typed, but with this change you will see it as + you type. + + * The internals of "revert/cherry-pick" have been tweaked to prepare + building more generic "sequencer" on top of the implementation that + drives them. + + * "git rev-parse FETCH_HEAD" after "git fetch" without specifying + what to fetch from the command line will now show the commit that + would be merged if the command were "git pull". + + * "git add" learned to stream large files directly into a packfile + instead of writing them into individual loose object files. + + * "git checkout -B <current branch> <elsewhere>" is a more intuitive + way to spell "git reset --keep <elsewhere>". + + * "git checkout" and "git merge" learned "--no-overwrite-ignore" option + to tell Git that untracked and ignored files are not expendable. + + * "git commit --amend" learned "--no-edit" option to say that the + user is amending the tree being recorded, without updating the + commit log message. + + * "git commit" and "git reset" re-learned the optimization to prime + the cache-tree information in the index, which makes it faster to + write a tree object out after the index entries are updated. + + * "git commit" detects and rejects an attempt to stuff NUL byte in + the commit log message. + + * "git commit" learned "-S" to GPG-sign the commit; this can be shown + with the "--show-signature" option to "git log". + + * fsck and prune are relatively lengthy operations that still go + silent while making the end-user wait. They learned to give progress + output like other slow operations. + + * The set of built-in function-header patterns for various languages + knows MATLAB. + + * "git log --format='<format>'" learned new %g[nNeE] specifiers to + show information from the reflog entries when walking the reflog + (i.e. with "-g"). + + * "git pull" can be used to fetch and merge an annotated/signed tag, + instead of the tip of a topic branch. The GPG signature from the + signed tag is recorded in the resulting merge commit for later + auditing. + + * "git log" learned "--show-signature" option to show the signed tag + that was merged that is embedded in the merge commit. It also can + show the signature made on the commit with "git commit -S". + + * "git branch --edit-description" can be used to add descriptive text + to explain what a topic branch is about. + + * "git fmt-merge-msg" learned to take the branch description into + account when preparing a merge summary that "git merge" records + when merging a local branch. + + * "git request-pull" has been updated to convey more information + useful for integrators to decide if a topic is worth merging and + what is pulled is indeed what the requestor asked to pull, + including: + + - the tip of the branch being requested to be merged; + - the branch description describing what the topic is about; + - the contents of the annotated tag, when requesting to pull a tag. + + * "git pull" learned to notice 'pull.rebase' configuration variable, + which serves as a global fallback for setting 'branch.<name>.rebase' + configuration variable per branch. + + * "git tag" learned "--cleanup" option to control how the whitespaces + and empty lines in tag message are cleaned up. + + * "gitweb" learned to show side-by-side diff. + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.8 +------------------ + +Unless otherwise noted, all the fixes since v1.7.8 in the maintenance +releases are contained in this release (see release notes to them for +details). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0e155c936c..0dbf2c9843 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -6,14 +6,25 @@ Checklist (and a short version for the impatient): - check for unnecessary whitespace with "git diff --check" before committing - do not check in commented out code or unneeded files - - provide a meaningful commit message - the first line of the commit message should be a short - description and should skip the full stop - - 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 + 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: + . 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 @@ -37,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: @@ -49,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. @@ -58,10 +98,20 @@ 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. +That being said, patches which plainly describe the things that +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, 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 @@ -71,7 +121,7 @@ run git diff --check on your changes before you commit. (1a) Try to be nice to older C compilers -We try to support wide range of C compilers to compile +We try to support a wide range of C compilers to compile git with. That means that you should not use C99 initializers, even if a lot of compilers grok it. @@ -84,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 @@ -158,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 @@ -222,12 +270,24 @@ D-C-O. Indeed you are encouraged to do so. Do not forget to place an in-body "From: " line at the beginning to properly attribute the change to its true author (see (2) above). -Some people also put extra tags at the end. +Also notice that a real name is used in the Signed-off-by: line. Please +don't hide your real name. + +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 @@ -265,54 +325,38 @@ people play with it without having to pick up and apply the patch to their trees themselves. ------------------------------------------------ -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. +Know the status of your patch after submission -* Save that patch to a file in UNIX mailbox format. Call it say - a.patch. +* You can use Git itself to find out when your patch is merged in + master. 'git pull --rebase' will automatically skip already-applied + patches, and will let you know. This works only if you rebase on top + of the branch in which your patch has been merged (i.e. it will not + tell you if your patch is merged in pu if you rebase on top of + master). -* Try to apply to the tip of the "master" branch from the - git.git public repository: +* Read the git mailing list, the maintainer regularly posts messages + entitled "What's cooking in git.git" and "What's in git.git" giving + the status of various proposed changes. - $ git fetch http://kernel.org/pub/scm/git/git.git 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. +------------------------------------------------ +MUA specific hints -* 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. +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. -* Your MUA corrupted your patch; "am" would complain that - the patch does not apply. Look at .dotest/ subdirectory and - see what 'patch' file contains and check for the common - corruption patterns mentioned above. +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). -* 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 @@ -368,57 +412,10 @@ that or Gentoo did it.) So you need to set the it. -Thunderbird ------------ - -(A Large Angry SCM) - -Here are some hints on how to successfully submit patches inline using -Thunderbird. - -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*] - -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 +Thunderbird, KMail, GMail +------------------------- +See the MUA-SPECIFIC HINTS section of git-format-patch(1). Gnus ---- @@ -433,21 +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. diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 10c1a151a4..6d06271ffe 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -7,12 +7,20 @@ # Show GIT link as: <command>(<section>); if section is defined, else just show # the command. +[macros] +(?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= + [attributes] +asterisk=* plus=+ caret=^ startsb=[ endsb=] +backslash=\ tilde=~ +apostrophe=' +backtick=` +litdd=-- ifdef::backend-docbook[] [linkgit-inlinemacro] @@ -23,7 +31,7 @@ ifdef::backend-docbook[] endif::backend-docbook[] ifdef::backend-docbook[] -ifndef::docbook-xsl-172[] +ifndef::git-asciidoc-no-roff[] # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. # v1.72 breaks with this because it replaces dots not in roff requests. [listingblock] @@ -38,7 +46,28 @@ ifdef::doctype-manpage[] endif::doctype-manpage[] </literallayout> {title#}</example> -endif::docbook-xsl-172[] +endif::git-asciidoc-no-roff[] + +ifdef::git-asciidoc-no-roff[] +ifdef::doctype-manpage[] +# The following two small workarounds insert a simple paragraph after screen +[listingblock] +<example><title>{title}</title> +<literallayout> +| +</literallayout><simpara></simpara> +{title#}</example> + +[verseblock] +<formalpara{id? id="{id}"}><title>{title}</title><para> +{title%}<literallayout{id? id="{id}"}> +{title#}<literallayout> +| +</literallayout> +{title#}</para></formalpara> +{title%}<simpara></simpara> +endif::doctype-manpage[] +endif::git-asciidoc-no-roff[] endif::backend-docbook[] ifdef::doctype-manpage[] @@ -62,5 +91,5 @@ endif::doctype-manpage[] ifdef::backend-xhtml11[] [linkgit-inlinemacro] -<a href="{target}.html">{target}{0?({0})}</a> +<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a> endif::backend-xhtml11[] diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 5428111d73..d4a51da464 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -39,16 +39,35 @@ of lines before or after the line given by <start>. Show raw timestamp (Default: off). -S <revs-file>:: - Use revs from revs-file instead of calling linkgit:git-rev-list[1]. + Use revisions from revs-file instead of calling linkgit:git-rev-list[1]. + +--reverse:: + Walk history forward instead of backward. Instead of showing + the revision in which a line appeared, this shows the last + revision in which a line has existed. This requires a range of + revision like START..END where the path to blame exists in + START. -p:: --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. +--encoding=<encoding>:: + Specifies the encoding used to output author names + and commit summaries. Setting it to `none` makes blame + output unconverted data. For more information see the + discussion about encoding in the linkgit:git-log[1] + manual page. + --contents <file>:: When <rev> is not specified, the command annotates the changes starting backwards from the working tree copy. @@ -56,34 +75,46 @@ of lines before or after the line given by <start>. tree copy has the contents of the named file (specify `-` to make the command read from the standard input). +--date <format>:: + The value is one of the following alternatives: + {relative,local,default,iso,rfc,short}. If --date is not + provided, the value of the blame.date config variable is + used. If the blame.date config variable is also not set, the + iso format is used. For more information, See the discussion + 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), 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, - the command looks for copies from all other files in the - parent for the commit that creates the file in addition. + the command additionally looks for copies from other + files in the commit that creates the file. When this + option is given three times, the command additionally + 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/callouts.xsl b/Documentation/callouts.xsl deleted file mode 100644 index 6a361a2136..0000000000 --- a/Documentation/callouts.xsl +++ /dev/null @@ -1,30 +0,0 @@ -<!-- callout.xsl: converts asciidoc callouts to man page format --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> -<xsl:template match="co"> - <xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/> -</xsl:template> -<xsl:template match="calloutlist"> - <xsl:text>.sp </xsl:text> - <xsl:apply-templates/> - <xsl:text> </xsl:text> -</xsl:template> -<xsl:template match="callout"> - <xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/> - <xsl:apply-templates/> - <xsl:text>.br </xsl:text> -</xsl:template> - -<!-- sorry, this is not about callouts, but attempts to work around - spurious .sp at the tail of the line docbook stylesheets seem to add --> -<xsl:template match="simpara"> - <xsl:variable name="content"> - <xsl:apply-templates/> - </xsl:variable> - <xsl:value-of select="normalize-space($content)"/> - <xsl:if test="not(ancestor::authorblurb) and - not(ancestor::personblurb)"> - <xsl:text> </xsl:text> - </xsl:if> -</xsl:template> - -</xsl:stylesheet> diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl index dbc133cd3c..828ec62554 100755 --- a/Documentation/cat-texi.perl +++ b/Documentation/cat-texi.perl @@ -18,8 +18,12 @@ close TMP; printf '\input texinfo @setfilename gitman.info -@documentencoding us-ascii -@node Top,,%s +@documentencoding UTF-8 +@dircategory Development +@direntry +* Git Man Pages: (gitman). Manual pages for Git revision control system +@end direntry +@node Top,,, (dir) @top Git Manual Pages @documentlanguage en @menu diff --git a/Documentation/config.txt b/Documentation/config.txt index 5331b450ea..915cb5a547 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2,18 +2,19 @@ CONFIGURATION FILE ------------------ The git configuration file contains a number of variables that affect -the git command's behavior. `.git/config` file for each repository -is used to store the information for that repository, and -`$HOME/.gitconfig` is used to store per user information to give -fallback values for `.git/config` file. The file `/etc/gitconfig` -can be used to store system-wide defaults. - -They can be used by both the git plumbing -and the porcelains. The variables are divided into sections, where -in the fully qualified variable name the variable itself is the last +the git command's behavior. The `.git/config` file in each repository +is used to store the configuration for that repository, and +`$HOME/.gitconfig` is used to store a per-user configuration as +fallback values for the `.git/config` file. The file `/etc/gitconfig` +can be used to store a system-wide default configuration. + +The configuration variables are used by both the git plumbing +and the porcelains. The variables are divided into sections, wherein +the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last -dot. The variable names are case-insensitive and only alphanumeric -characters are allowed. Some variables may appear multiple times. +dot. The variable names are case-insensitive, allow only alphanumeric +characters and `-`, and must start with an alphabetic character. Some +variables may appear multiple times. Syntax ~~~~~~ @@ -25,62 +26,78 @@ blank lines are ignored. The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next section begins. Section names are not case sensitive. Only alphanumeric -characters, '`-`' and '`.`' are allowed in section names. Each variable -must belong to some section, which means that there must be section -header before first setting of a variable. +characters, `-` and `.` are allowed in section names. Each variable +must belong to some section, which means that there must be a section +header before the first setting of a variable. Sections can be further divided into subsections. To begin a subsection put its name in double quotes, separated by space from the section name, -in the section header, like in example below: +in the section header, like in the example below: -------- [section "subsection"] -------- -Subsection names can contain any characters except newline (doublequote -'`"`' and backslash have to be escaped as '`\"`' and '`\\`', -respectively) and are case sensitive. Section header cannot span multiple +Subsection names are case sensitive and can contain any characters except +newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`, +respectively). Section headers cannot span multiple 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 (case insensitive) alternative `[section.subsection]` syntax. -In this syntax subsection names follow the same restrictions as for section -name. +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 are recognized as setting variables, in the form +All the other lines (and the remainder of the line after the section +header) are recognized as setting variables, in the form 'name = value'. If there is no equal sign on the line, the entire line is taken as 'name' and the variable is recognized as boolean "true". -The variable names are case-insensitive and only alphanumeric -characters and '`-`' are allowed. There can be more than one value -for a given variable; we say then that variable is multivalued. +The variable names are case-insensitive, allow only alphanumeric characters +and `-`, and must start with an alphabetic character. There can be more +than one value for a given variable; we say then that the variable is +multivalued. Leading and trailing whitespace in a variable value is discarded. 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 or true/false. 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 value in double quotes if you want to -preserve leading or trailing whitespace, or if variable value contains -beginning of comment characters (if it contains '#' or ';'). -Double quote '`"`' and backslash '`\`' characters in variable value must -be escaped: use '`\"`' for '`"`' and '`\\`' for '`\`'. - -The following escape sequences (beside '`\"`' and '`\\`') are recognized: -'`\n`' for newline character (NL), '`\t`' for horizontal tabulation (HT, TAB) -and '`\b`' for backspace (BS). No other char escape sequence, nor octal +You need to enclose variable values in double quotes if you want to +preserve leading or trailing whitespace, or if the variable value contains +comment characters (i.e. it contains '#' or ';'). +Double quote `"` and backslash `\` characters in variable values must +be escaped: use `\"` for `"` and `\\` for `\`. + +The following escape sequences (beside `\"` and `\\`) are recognized: +`\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB) +and `\b` for backspace (BS). No other char escape sequence, nor octal char sequences are valid. -Variable value ending in a '`\`' is continued on the next line in the +Variable values ending in a `\` are continued on the next line in the customary UNIX fashion. -Some variables may require special value format. +Some variables may require a special value format. + +Includes +~~~~~~~~ + +You can include one config file from another by setting the special +`include.path` variable to the name of the file to be included. The +included file is expanded immediately, as if its contents had been +found at the location of the include directive. If the value of the +`include.path` variable is a relative path, the path is considered to be +relative to the configuration file in which the include directive was +found. The value of `include.path` is subject to tilde expansion: `~/` +is expanded to the value of `$HOME`, and `~user/` to the specified +user's home directory. See below for examples. Example ~~~~~~~ @@ -92,7 +109,7 @@ Example # Our diff algorithm [diff] - external = "/usr/local/bin/gnu-diff -u" + external = /usr/local/bin/diff-wrapper renames = true [branch "devel"] @@ -104,6 +121,11 @@ Example gitProxy="ssh" for "kernel.org" gitProxy=default-proxy ; for the rest + [include] + path = /path/to/foo.inc ; include by absolute path + path = foo ; expand "foo" relative to the current file + path = ~/foo ; expand "foo" in your $HOME directory + Variables ~~~~~~~~~ @@ -112,14 +134,92 @@ For command-specific variables, you will find a more detailed description in the appropriate manual page. You will find a description of non-core porcelain configuration variables in the respective porcelain documentation. +advice.*:: + These variables control various optional help messages designed to + aid new users. All 'advice.*' variables default to 'true', and you + can tell Git that you do not need help by setting these to 'false': ++ +-- + pushNonFastForward:: + Set this variable to 'false' if you want to disable + 'pushNonFFCurrent', 'pushNonFFDefault', and + 'pushNonFFMatching' simultaneously. + pushNonFFCurrent:: + Advice shown when linkgit:git-push[1] fails due to a + non-fast-forward update to the current branch. + pushNonFFDefault:: + Advice to set 'push.default' to 'upstream' or 'current' + when you ran linkgit:git-push[1] and pushed 'matching + refs' by default (i.e. you did not provide an explicit + refspec, and no 'push.default' configuration was set) + and it resulted in a non-fast-forward error. + pushNonFFMatching:: + Advice shown when you ran linkgit:git-push[1] and pushed + 'matching refs' explicitly (i.e. you used ':', or + specified a refspec that isn't your current branch) and + it resulted in a non-fast-forward error. + statusHints:: + Directions on how to stage/unstage/add shown in the + output of linkgit:git-status[1] and the template shown + when writing commit messages. + commitBeforeMerge:: + Advice shown when linkgit:git-merge[1] refuses to + merge to avoid overwriting local changes. + resolveConflict:: + Advices shown by various commands when conflicts + prevent the operation from being performed. + implicitIdentity:: + Advice on how to set your identity configuration when + your information is guessed from the system username and + domain name. + 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. +-- + 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] +will probe and set core.fileMode false if appropriate when the +repository is created. + +core.ignoreCygwinFSTricks:: + This option is only used by Cygwin implementation of Git. If false, + the Cygwin stat() and lstat() functions are used. This may be useful + if your repository consists of a few separate directories joined in + one hierarchy using Cygwin mount. If true, Git uses native Win32 API + whenever it is possible and falls back to Cygwin functions only to + handle symbol links. The native mode is more than twice faster than + normal Cygwin l/stat() functions. True by default, unless core.filemode + is true, in which case ignoreCygwinFSTricks is ignored as Cygwin's + POSIX emulation is required to support core.filemode. + +core.ignorecase:: + If true, this option enables various workarounds to enable + git to work better on filesystems that are not case sensitive, + like FAT. For example, if a directory listing finds + "makefile" when git expects "Makefile", git will assume + it is really the same file, and continue to remember it as + "Makefile". ++ +The default is false, except linkgit:git-clone[1] or linkgit:git-init[1] +will probe and set core.ignorecase true if appropriate when the repository +is created. + +core.trustctime:: + If false, the ctime differences between the index and the + 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. core.quotepath:: - The commands that output paths (e.g. `ls-files`, - `diff`), when not given the `-z` option, will quote + The commands that output paths (e.g. 'ls-files', + 'diff'), when not given the `-z` option, will quote "unusual" characters in the pathname by enclosing the pathname in a double-quote pair and with backslashes the same way strings in C source code are quoted. If this @@ -129,19 +229,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. Currently, which paths to consider - "text" (i.e. be subjected to the autocrlf mechanism) is - decided purely based on the contents. +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 @@ -151,7 +249,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 @@ -175,21 +273,35 @@ 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 linkgit:git-add[1] will not change the recorded type to regular file. Useful on filesystems like FAT that do not support - symbolic links. True by default. + symbolic links. ++ +The default is true, except linkgit:git-clone[1] or linkgit:git-init[1] +will probe and set core.symlinks false if appropriate when the repository +is created. core.gitProxy:: A "proxy command" to execute (as 'command host port') instead @@ -203,12 +315,17 @@ core.gitProxy:: Can be overridden by the 'GIT_PROXY_COMMAND' environment variable (which always applies universally, without the special "for" handling). ++ +The special string `none` can be used as the proxy command to +specify that no proxy be used for a given domain pattern. +This is useful for excluding servers inside a firewall from +proxy use, while defaulting to a common proxy for external domains. 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]. @@ -233,17 +350,26 @@ false), while all other repositories are assumed to be bare (bare = true). core.worktree:: - 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 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 - a 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 + 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 top directory + 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 +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 the "/path/to" directory will +still use "/different/path" as the root of the work tree and can cause +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 @@ -251,7 +377,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". @@ -272,8 +400,10 @@ core.sharedRepository:: group-shareable. When 'umask' (or 'false'), git will use permissions reported by umask(2). When '0xxx', where '0xxx' is an octal number, files in the repository will have this mode value. '0xxx' will override - user's umask value, and thus, users with a safe umask (0077) can use - this option. Examples: '0660' is equivalent to 'group'. '0640' is a + user's umask value (whereas the other options will only override + requested parts of the user's umask value). Examples: '0660' will make + the repo read/write-able for the owner and group, but inaccessible to + others (equivalent to 'group' unless umask is e.g. '0022'). '0640' is a repository that is group-readable but not group-writable. See linkgit:git-init[1]. False by default. @@ -325,7 +455,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. @@ -336,41 +466,151 @@ 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 - of files which are not meant to be tracked. See - linkgit:gitignore[5]. + of files which are not meant to be tracked. "`~/`" is expanded + to the value of `$HOME` and "`~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. The order of preference is - `GIT_EDITOR` environment, `core.editor`, `VISUAL` and - `EDITOR` environment variables and then finally `vi`. + `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 variable. + The command that git will use to paginate output. Can + be overridden with the `GIT_PAGER` environment + variable. Note that git sets the `LESS` environment + variable to `FRSX` if it is unset when it runs the + pager. One can change these settings by setting the + `LESS` variable to some other value. Alternately, + these settings can be overridden on a project or + global basis by setting the `core.pager` option. + Setting `core.pager` has no affect on the `LESS` + environment variable behaviour above, so if you want + to override git's default settings this way, you need + to be explicit. For example, to disable the S option + in a backward compatible manner, set `core.pager` + to `less -+$LESS -FRX`. This will be passed to the + shell by git, which will translate the final command to + `LESS=FRSX less -+FRSX -FRX`. 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 - consider them as errors: + 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`): + -* `trailing-space` treats trailing whitespaces at the end of the line +* `blank-at-eol` treats trailing whitespaces at the end of the line as an error (enabled by default). * `space-before-tab` treats a space character that appears immediately before a tab character in the initial indent part of the line as an error (enabled by default). * `indent-with-non-tab` treats a line that is indented with 8 or more space characters as an error (not enabled by default). +* `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 + `blank-at-eof`. * `cr-at-eol` treats a carriage-return at the end of line as 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. ++ +This is a total waste of time and effort on a filesystem that orders +data writes properly, but can be useful for filesystems that do not use +journalling (traditional UNIX filesystems) or that only journal metadata +and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback"). + +core.preloadindex:: + Enable parallel index preload for operations like 'git diff' ++ +This can speed up operations like 'git diff' and 'git status' especially +on filesystems like NFS that have weak caching semantics and thus +relatively high IO latencies. With this set to 'true', git will do the +index comparison to the filesystem data in parallel, allowing +overlapping IO's. + +core.createObject:: + You can set this to 'link', in which case a hardlink followed by + a delete of the source are used to make sure that object creation + will not overwrite existing objects. ++ +On some file system/operating system combinations, this is unreliable. +Set this config setting to 'rename' there; However, This will remove the +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. 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 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:: +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]. 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. @@ -385,32 +625,52 @@ If the alias expansion is prefixed with an exclamation point, it will be treated as a shell command. For example, defining "alias.new = !gitk --all --not ORIG_HEAD", the invocation "git new" is equivalent to running the shell command -"gitk --all --not ORIG_HEAD". +"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 + whitespace, in the same way as the '--ignore-space-change' + option. + 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 setup 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 @@ -418,42 +678,48 @@ branch.autosetuprebase:: This option defaults to never. branch.<name>.remote:: - When in branch <name>, it tells `git fetch` which remote to fetch. - If this option is not given, `git fetch` defaults to remote "origin". + 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:: - When in branch <name>, it tells `git fetch` the default + Defines, together with branch.<name>.remote, the upstream branch + 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. branch.<name>.mergeoptions:: Sets default options for merging into branch <name>. The syntax and - supported options are equal to that of linkgit:git-merge[1], but + supported options are the same as those of linkgit:git-merge[1], but option values containing whitespace characters are currently not supported. branch.<name>.rebase:: When true, rebase the branch <name> on top of the fetched branch, instead of merging the default branch from the default remote when - "git pull" is run. - *NOTE*: this is a possibly dangerous operation; do *not* use - it unless you understand the implications (see linkgit:git-rebase[1] - for details). + "git pull" is run. See "pull.rebase" for doing this in a non + branch-specific manner. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand the implications (see linkgit:git-rebase[1] +for details). 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 @@ -473,7 +739,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 @@ -485,36 +751,83 @@ 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 which part of the patch to use the specified color, and is one of `plain` (context text), `meta` (metainformation), `frag` - (hunk header), `old` (removed lines), `new` (added lines), - `commit` (commit headers), or `whitespace` (highlighting - whitespace errors). The values of these variables may be specified as - in color.branch.<slot>. + (hunk header), 'func' (function in hunk header), `old` (removed lines), + `new` (added lines), `commit` (commit headers), or `whitespace` + (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.<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 - and displays (such as those used by "git add --interactive"). + and displays (such as those used by "git-add --interactive"). When false (or `never`), never. When set to `true` or `auto`, use colors only when the output is to the terminal. Defaults to false. color.interactive.<slot>:: - Use customized color for `git add --interactive` - output. `<slot>` may be `prompt`, `header`, or `help`, for - three distinct types of normal output from interactive - programs. The values of these variables may be specified as + 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 in color.branch.<slot>. color.pager:: A boolean to enable/disable colored output when the pager is in use (default is true). +color.showbranch:: + A boolean to enable/disable color in the output of + linkgit:git-show-branch[1]. May be set to `always`, + `false` (or `never`) or `auto` (or `true`), in which case colors are used + only when the output is to a terminal. Defaults to false. + color.status:: A boolean to enable/disable color in the output of linkgit:git-status[1]. May be set to `always`, @@ -526,46 +839,132 @@ 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:: + 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. + +column.ui:: + Specify whether supported commands should output in columns. + This variable consists of a list of tokens separated by spaces + or commas: ++ +-- +`always`;; + always show in columns +`never`;; + never show in columns +`auto`;; + show in columns if the output is to the terminal +`column`;; + fill columns before rows (default) +`row`;; + fill rows before columns +`plain`;; + show in one column +`dense`;; + make unequal size columns to utilize more space +`nodense`;; + make equal size columns +-- ++ + This option defaults to 'never'. + +column.branch:: + Specify whether to output branch listing in `git branch` in columns. + See `column.ui` for details. + +column.status:: + Specify whether to output untracked files in `git status` in columns. + See `column.ui` for details. + +column.tag:: + Specify whether to output tag listing in `git tag` in columns. + See `column.ui` for details. + +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. + commit.template:: Specify a file to use as the template for new commit messages. + "`~/`" is expanded to the value of `$HOME` and "`~user/`" to the + specified user's home directory. + +credential.helper:: + Specify an external helper to be called when a username or + password credential is needed; the helper may consult external + storage to avoid prompting the user for the credentials. See + linkgit:gitcredentials[7] for details. + +credential.useHttpPath:: + When acquiring credentials, consider the "path" component of an http + or https URL to be important. Defaults to false. See + linkgit:gitcredentials[7] for more information. + +credential.username:: + If no username is set for a network authentication, use this username + by default. See credential.<context>.* below, and + linkgit:gitcredentials[7]. + +credential.<url>.*:: + Any of the credential.* options above can be applied selectively to + some credentials. For example "credential.https://example.com.username" + would set the default username only for https connections to + example.com. See linkgit:gitcredentials[7] for details on how URLs are + matched. + +include::diff-config.txt[] + +difftool.<tool>.path:: + Override the path for the given tool. This is useful in case + your tool is not in the PATH. -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. - -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. 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.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. +difftool.<tool>.cmd:: + Specify the command to invoke the specified diff tool. + The specified command is evaluated in shell 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. + +difftool.prompt:: + Prompt before each invocation of the diff tool. + +diff.wordRegex:: + A POSIX Extended Regular Expression used to determine what is a "word" + when performing word-by-word difference calculations. Character + sequences that match the regular expression are "words", all other + characters are *ignorable* whitespace. + +fetch.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 @@ -578,16 +977,40 @@ fetch.unpackLimit:: especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead. -format.numbered:: - A boolean which can enable sequence numbers in patch subjects. - Setting this option to "auto" will enable it only if there is - more than one patch. See --numbered option in +format.attach:: + Enable multipart/mixed attachments as the default for + 'format-patch'. The value can also be a double quoted string + which will enable attachments as the default and set the + value as the boundary. See the --attach option in linkgit:git-format-patch[1]. +format.numbered:: + A boolean which can enable or disable sequence numbers in patch + subjects. It defaults to "auto" which enables it only if there + is more than one patch. It can be enabled or disabled for all + messages by setting it to "true" or "false". See --numbered + option in linkgit:git-format-patch[1]. + 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 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 @@ -598,10 +1021,37 @@ format.pretty:: See linkgit:git-log[1], linkgit:git-show[1], linkgit:git-whatchanged[1]. +format.thread:: + 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 + `--in-reply-to`, and the first patch mail, in this order. + `deep` threading makes every mail a reply to the previous one. + A true boolean value is the same as `shallow`, and a false + value disables threading. + +format.signoff:: + A boolean value which lets you enable the `-s/--signoff` option of + format-patch by default. *Note:* Adding the Signed-off-by: line to a + patch should be a conscious act and means that you certify you have + 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. + to 250. gc.auto:: When there are approximately more than this many loose @@ -617,45 +1067,47 @@ gc.autopacklimit:: default value is 50. Setting this to 0 disables it. gc.packrefs:: - `git gc` does not run `git pack-refs` in a bare repository by - default so that older dumb-transport clients can still fetch - from the repository. Setting this to `true` lets `git - gc` to run `git pack-refs`. Setting this to `false` tells - `git gc` never to run `git pack-refs`. The default setting is - `notbare`. Enable it only when you know you do not have to - support such clients. The default setting will change to `true` - at some stage, and setting this to `false` will continue to - prevent `git pack-refs` from being run from `git gc`. + 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 `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`. - Override the grace period with this config variable. + 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]. -rerere.enabled:: - Activate recording of resolved conflicts, so that identical - conflict hunks can be resolved automatically, should they - be encountered again. linkgit:git-rerere[1] command is by - default enabled if you create `rr-cache` directory under - `$GIT_DIR`, but can be disabled by setting this option to false. +gitcvs.commitmsgannotation:: + Append this string to each commit message. Set to empty string + to disable this feature. Defaults to "via git-CVS emulator". gitcvs.enabled:: Whether the CVS server interface is enabled for this repository. @@ -665,14 +1117,16 @@ gitcvs.logfile:: Path to a log file where the CVS server interface well... logs 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 - will be set with '-kb' mode, which supresses any newline munging - the client might otherwise do. If `crlf` is not specified, - then 'gitcvs.allbinary' is used. See linkgit:gitattribute[5]. +gitcvs.usecrlfattr:: + If true, the server will look up the end-of-line conversion + attributes for files to determine the '-k' modes to use. If + the attributes force git to treat a file as text, + the '-k' mode will be left blank so CVS clients will + treat it as text. If they suppress text conversion, the file + will be set with '-kb' mode, which suppresses any newline munging + the client might otherwise do. If the attributes do not allow + 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 @@ -719,6 +1173,40 @@ 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. + +gpg.program:: + Use this custom program instead of "gpg" found on $PATH when + making or verifying a PGP signature. The program must support the + same command line interface as GPG, namely, to verify a detached + signature, "gpg --verify $file - <$signature" is run, and the + program is expected to signal a good signature by exiting with + code 0, and to generate an ascii-armored detached signature, the + standard input of "gpg -bsau $key" is fed with the contents to be + signed, and the program is expected to send the result to its + standard output. + gui.commitmsgwidth:: Defines how wide the commit message window is in the linkgit:git-gui[1]. "75" is the default. @@ -727,6 +1215,14 @@ gui.diffcontext:: Specifies how many context lines should be used in calls to diff made by the linkgit:git-gui[1]. The default is "5". +gui.encoding:: + Specifies the default encoding to use for displaying of + file contents in linkgit:git-gui[1] and linkgit:gitk[1]. + It can be overridden by setting the 'encoding' attribute + for relevant files (see linkgit:gitattributes[5]). + If this option is not set, the tools default to the + locale encoding. + gui.matchtrackingbranch:: Determines if new branches created with linkgit:git-gui[1] should default to tracking remote branches with matching names or @@ -737,7 +1233,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:: @@ -749,6 +1245,73 @@ gui.spellingdictionary:: the linkgit:git-gui[1]. When set to "none" spell checking is turned off. +gui.fastcopyblame:: + If true, 'git gui blame' uses `-C` instead of `-C -C` for original + location detection. It makes blame significantly faster on huge + repositories at the expense of less thorough copy detection. + +gui.copyblamethreshold:: + Specifies the threshold to use in 'git gui blame' original location + detection, measured in alphanumeric characters. See the + linkgit:git-blame[1] manual for more information on copy detection. + +gui.blamehistoryctx:: + Specifies the radius of history context in days to show in + linkgit:gitk[1] for the selected commit, when the `Show History + Context` menu item is invoked from 'git gui blame'. If this + variable is set to zero, the whole history is shown. + +guitool.<name>.cmd:: + Specifies the shell command line to execute when the corresponding item + of the linkgit:git-gui[1] `Tools` menu is invoked. This option is + mandatory for every tool. The command is executed from the root of + the working directory, and in the environment it receives the name of + the tool as 'GIT_GUITOOL', the name of the currently selected file as + 'FILENAME', and the name of the current branch as 'CUR_BRANCH' (if + the head is detached, 'CUR_BRANCH' is empty). + +guitool.<name>.needsfile:: + Run the tool only if a diff is selected in the GUI. It guarantees + that 'FILENAME' is not empty. + +guitool.<name>.noconsole:: + Run the command silently, without creating a window to display its + output. + +guitool.<name>.norescan:: + Don't rescan the working directory for changes after the tool + finishes execution. + +guitool.<name>.confirm:: + Show a confirmation dialog before actually running the tool. + +guitool.<name>.argprompt:: + Request a string argument from the user, and pass it to the tool + through the 'ARGS' environment variable. Since requesting an + argument implies confirmation, the 'confirm' option has no effect + if this is enabled. If the option is set to 'true', 'yes', or '1', + the dialog uses a built-in generic prompt; otherwise the exact + value of the variable is used. + +guitool.<name>.revprompt:: + Request a single valid revision from the user, and set the + 'REVISION' environment variable. In other aspects this option + is similar to 'argprompt', and can be used together with it. + +guitool.<name>.revunmerged:: + Show only unmerged branches in the 'revprompt' subdialog. + This is useful for tools similar to merge or rebase, but not + for things like checkout or reset. + +guitool.<name>.title:: + Specifies the title to use for the prompt dialog. The default + is the tool name. + +guitool.<name>.prompt:: + Specifies the general prompt string to display at the top of + the dialog, before subsections for 'argprompt' and 'revprompt'. + The default value includes the actual command. + help.browser:: Specify the browser that will be used to display help in the 'web' format. See linkgit:git-help[1]. @@ -758,10 +1321,28 @@ help.format:: Values 'man', 'info', 'web' and 'html' are supported. 'man' is the default. 'web' and 'html' are the same. +help.autocorrect:: + Automatically correct and execute mistyped commands after + waiting for the given number of deciseconds (0.1 sec). If more + than one command can be deduced from the entered text, nothing + will be executed. If the value of this option is negative, + the corrected command will be executed immediately. If the + value is 0 - the command will be just shown but not executed. + This is the default. + http.proxy:: - Override the HTTP proxy, normally configured using the 'http_proxy' - environment variable (see linkgit:curl[1]). This can be overridden - on a per-remote basis; see remote.<name>.proxy + Override the HTTP proxy, normally configured using the 'http_proxy', + 'https_proxy', and 'all_proxy' environment variables (see + `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 @@ -778,6 +1359,12 @@ http.sslKey:: over HTTPS. Can be overridden by the 'GIT_SSL_KEY' environment variable. +http.sslCertPasswordProtected:: + Enable git's password prompt for the SSL certificate. Otherwise + OpenSSL will prompt the user, possibly many times, if the + certificate or private key is encrypted. Can be overridden by the + 'GIT_SSL_CERT_PASSWORD_PROTECTED' environment variable. + http.sslCAInfo:: File containing the certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the @@ -792,6 +1379,20 @@ http.maxRequests:: How many HTTP requests to launch in parallel. Can be overridden by the 'GIT_HTTP_MAX_REQUESTS' environment variable. Default is 5. +http.minSessions:: + The number of curl sessions (counted across slots) to be kept across + requests. They will not be ended with curl_easy_cleanup() until + http_cleanup() is invoked. If USE_CURL_MULTI is not defined, this + value will be capped at 1. Defaults to 1. + +http.postBuffer:: + Maximum size in bytes of the buffer used by smart HTTP + transports when POSTing data to the remote system. + For requests larger than this buffer size, HTTP/1.1 and + Transfer-Encoding: chunked is used to avoid creating a + massive pack file locally. Default is 1 MiB, which is + sufficient for most requests. + http.lowSpeedLimit, http.lowSpeedTime:: If the HTTP transfer speed is less than 'http.lowSpeedLimit' for longer than 'http.lowSpeedTime' seconds, the transfer is aborted. @@ -804,6 +1405,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 @@ -813,7 +1423,15 @@ 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 @@ -828,17 +1446,41 @@ 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 linkgit:git-instaweb[1]. +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 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 - 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. @@ -846,12 +1488,18 @@ log.showroot:: Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which normally hide the root commit will now show it. True by default. +mailmap.file:: + The location of an augmenting mailmap file. The default + mailmap, located in the root of the repository, is loaded + first, then the mailmap file pointed to by this variable. + The location of the mailmap file may be in a repository + subdirectory, or somewhere outside of the repository itself. + See linkgit:git-shortlog[1] and linkgit:git-blame[1]. + man.viewer:: Specify the programs that may be used to display help in the 'man' format. See linkgit:git-help[1]. -include::merge-config.txt[] - man.<tool>.cmd:: Specify the command to invoke the specified man viewer. The specified command is evaluated in shell with the man page @@ -861,6 +1509,8 @@ man.<tool>.path:: Override the path for the given tool that may be used to display help in the 'man' format. See linkgit:git-help[1]. +include::merge-config.txt[] + mergetool.<tool>.path:: Override the path for the given tool. This is useful in case your tool is not in the PATH. @@ -890,6 +1540,64 @@ mergetool.keepBackup:: is set to `false` then this file is not preserved. Defaults to `true` (i.e. keep the backup files). +mergetool.keepTemporaries:: + When invoking a custom merge tool, git uses a set of temporary + files to pass to the tool. If the tool returns an error and this + variable is set to `true`, then these temporary files will be + preserved, otherwise they will be removed after the tool has + exited. Defaults to `false`. + +mergetool.prompt:: + Prompt before each invocation of the merge resolution program. + +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. @@ -912,15 +1620,27 @@ 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 - linkgit:git-pack-objects[1]. - A value of 0 means no limit. Defaults to 0. + linkgit:git-pack-objects[1] before writing them out to a pack. + This cache is used to speed up the writing object phase by not + having to recompute the final delta result once the best match + for all objects is found. Repacking large repositories on machines + which are tight with memory might be badly impacted by this though, + especially if this cache pushes the system into swapping. + A value of 0 means no limit. The smallest size of 1 byte may be + used to virtually disable this cache. Defaults to 256 MiB. pack.deltaCacheLimit:: The maximum size of a delta, that is cached in - linkgit:git-pack-objects[1]. Defaults to 1000. + linkgit:git-pack-objects[1]. This cache is used to speed up the + writing object phase by not having to recompute the final delta + result once the best match for all objects is found. Defaults to 1000. pack.threads:: Specifies the number of threads to spawn when searching for best @@ -937,15 +1657,55 @@ pack.indexVersion:: legacy pack index used by Git versions prior to 1.5.2, and 2 for the new pack index with capabilities for packs larger than 4 GB as well as proper protection against the repacking of corrupted - packs. Version 2 is selected and this config option ignored - whenever the corresponding pack is larger than 2 GB. Otherwise - the default is 1. + packs. Version 2 is the default. Note that version 2 is enforced + and this config option ignored whenever the corresponding pack is + larger than 2 GB. ++ +If you have an old git that does not understand the version 2 `*.idx` file, +cloning or fetching over a non native protocol (e.g. "http" and "rsync") +that will copy both `*.pack` file and corresponding `*.idx` file from the +other side may give you a repository that cannot be accessed with your +older version of git. If the `*.pack` file is smaller than 2 GB, however, +you can use linkgit:git-index-pack[1] on the *.pack file to regenerate +the `*.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>:: + 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:* %H %s"` + would cause the invocation `git log --pretty=changelog` + to be equivalent to running `git log "--pretty=format:* %H %s"`. + Note that an alias with the same name as a built-in format + will be silently ignored. + +pull.rebase:: + When true, rebase branches on top of the fetched branch, instead + of merging the default branch from the default remote when "git + pull" is run. See "branch.<name>.rebase" for setting this on a + per-branch basis. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand the implications (see linkgit:git-rebase[1] +for details). pull.octopus:: The default merge strategy to use when pulling multiple branches @@ -954,10 +1714,101 @@ pull.octopus:: pull.twohead:: The default merge strategy to use when pulling a single branch. +push.default:: + Defines the action git push should take if no refspec is given + on the command line, no refspec is configured in the remote, and + 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 branches having the same name in both ends. + This is for those who prepare all the branches into a publishable + shape and then push them out with a single command. It is not + appropriate for pushing into a repository shared by multiple users, + since locally stalled branches will attempt a non-fast forward push + if other users updated the branch. + + + This is currently the default, but Git 2.0 will change the default + to `simple`. +* `upstream` - push the current branch to its upstream branch. + With this, `git push` will update the same remote ref as the one which + is merged by `git pull`, making `push` and `pull` symmetrical. + See "branch.<name>.merge" for how to configure the upstream branch. +* `simple` - like `upstream`, but refuses to push if the upstream + branch's name is different from the local one. This is the safest + option and is well-suited for beginners. It will become the default + in Git 2.0. +* `current` - push the current branch to a branch of the same name. + + + The `simple`, `current` and `upstream` modes are for those who want to + push out a single branch after finishing work, even when the other + branches are not yet ready to be pushed out. If you are working with + other people to push into the same shared repository, you would want + to use one of these. + +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 + it by setting this variable to false. + +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. 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 + limit then the objects will be unpacked into loose object + files. However if the number of received objects equals or + exceeds this limit then the received pack will be stored as + a pack, after adding any missing delta bases. Storing the + pack from a push can make the push operation complete faster, + especially on slow filesystems. If not set, the value of + `transfer.unpackLimit` is used instead. + +receive.denyDeletes:: + If set to true, git-receive-pack will deny a ref update that deletes + the ref. Use this to prevent such a ref deletion via a push. + +receive.denyDeleteCurrent:: + If set to true, git-receive-pack will deny a ref update that + deletes the currently checked out branch of a non-bare repository. + +receive.denyCurrentBranch:: + If set to true or "refuse", git-receive-pack will deny a ref update + to the currently checked out branch of a non-bare repository. + 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 "refuse". + +receive.denyNonFastForwards:: + If set to true, git-receive-pack will deny a ref update which is + not a fast-forward. Use this to prevent such an update via a push, + even if that push is forced. This configuration variable is + set when initializing a shared repository. + +receive.updateserverinfo:: + If set to true, git-receive-pack will run git-update-server-info + after receiving data from git-push and updating refs. + remote.<name>.url:: The URL of a remote repository. See linkgit:git-fetch[1] or linkgit:git-push[1]. +remote.<name>.pushurl:: + The push URL of a remote repository. See linkgit:git-push[1]. + remote.<name>.proxy:: For remotes that require curl (http, https and ftp), the URL to the proxy to use for that remote. Set to the empty string to @@ -973,11 +1824,17 @@ remote.<name>.push:: remote.<name>.mirror:: If true, pushing to this remote will automatically behave - as if the `\--mirror` option was given on the command line. + as if the `--mirror` option was given on the command line. remote.<name>.skipDefaultUpdate:: If true, this remote will be skipped by default when updating - using the update subcommand of linkgit:git-remote[1]. + using linkgit:git-fetch[1] or the `update` subcommand of + linkgit:git-remote[1]. + +remote.<name>.skipFetchAll:: + If true, this remote will be skipped by default when updating + using linkgit:git-fetch[1] or the `update` subcommand of + linkgit:git-remote[1]. remote.<name>.receivepack:: The default program to execute on the remote side when pushing. See @@ -989,19 +1846,86 @@ 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 + the remote with the git-remote-<vcs> helper. remotes.<group>:: The list of remotes which are fetched by "git remote update <group>". See linkgit:git-remote[1]. repack.usedeltabaseoffset:: - Allow linkgit:git-repack[1] to create packs that uses - delta-base offset. Defaults to false. + By default, linkgit:git-repack[1] creates packs that use + delta-base offset. If you need to share your repository with + git older than version 1.4.4, either directly or via a dumb + protocol such as http, then you need to set this option to + "false" and repack. Access from old git versions over the + native protocol are unaffected by this option. + +rerere.autoupdate:: + When set to true, `git-rerere` updates the index with the + resulting contents after it cleanly resolves conflicts using + previously recorded resolution. Defaults to false. -show.difftree:: - The default linkgit:git-diff-tree[1] arguments to be used - for linkgit:git-show[1]. +rerere.enabled:: + Activate recording of resolved conflicts, so that identical + conflict hunks can be resolved automatically, should they be + encountered again. By default, linkgit:git-rerere[1] is + enabled if there is an `rr-cache` directory under the + `$GIT_DIR`, e.g. if "rerere" was previously used in the + repository. + +sendemail.identity:: + A configuration identity. When given, causes values in the + 'sendemail.<identity>' subsection to take precedence over + values in the 'sendemail' section. The default identity is + the value of 'sendemail.identity'. + +sendemail.smtpencryption:: + See linkgit:git-send-email[1] for description. Note that this + setting is not subject to the 'identity' mechanism. + +sendemail.smtpssl:: + Deprecated alias for 'sendemail.smtpencryption = ssl'. + +sendemail.<identity>.*:: + Identity-specific versions of the 'sendemail.*' parameters + found below, taking precedence over those when the this + identity is selected, through command-line or + 'sendemail.identity'. + +sendemail.aliasesfile:: +sendemail.aliasfiletype:: +sendemail.bcc:: +sendemail.cc:: +sendemail.cccmd:: +sendemail.chainreplyto:: +sendemail.confirm:: +sendemail.envelopesender:: +sendemail.from:: +sendemail.multiedit:: +sendemail.signedoffbycc:: +sendemail.smtppass:: +sendemail.suppresscc:: +sendemail.suppressfrom:: +sendemail.to:: +sendemail.smtpdomain:: +sendemail.smtpserver:: +sendemail.smtpserverport:: +sendemail.smtpserveroption:: +sendemail.smtpuser:: +sendemail.thread:: +sendemail.validate:: + See linkgit:git-send-email[1] for description. + +sendemail.signedoffcc:: + Deprecated alias for 'sendemail.signedoffbycc'. showbranch.default:: The default set of branches for linkgit:git-show-branch[1]. @@ -1013,6 +1937,61 @@ status.relativePaths:: relative to the repository root (this was the default for git prior to v1.5.4). +status.showUntrackedFiles:: + By default, linkgit:git-status[1] and linkgit:git-commit[1] show + files which are not currently tracked by Git. Directories which + contain only untracked files, are shown with the directory name + only. Showing untracked files means that Git needs to lstat() all + all the files in the whole repository, which might be slow on some + systems. So, this variable controls how the commands displays + the untracked files. Possible values are: ++ +-- +* `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 @@ -1020,6 +1999,16 @@ 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. + The default value is 100. + url.<base>.insteadOf:: Any URL that starts with this value will be rewritten to start, instead, with <base>. In cases where some site serves a @@ -1031,6 +2020,19 @@ url.<base>.insteadOf:: never-before-seen repository on the site. When more than one insteadOf strings match a given URL, the longest match is used. +url.<base>.pushInsteadOf:: + Any URL that starts with this value will not be pushed to; + instead, it will be rewritten to start with <base>, and the + resulting URL will be pushed to. In cases where some site serves + a large number of repositories, and serves them with multiple + access methods, some of which do not allow push, this feature + allows people to specify a pull-only URL and have git + automatically use an appropriate URL to push, even for a + never-before-seen repository on the site. When more than one + pushInsteadOf strings match a given URL, the longest match is + used. If a remote has an explicit pushurl, git will ignore this + setting for that remote. + user.email:: Your email address to be recorded in any newly created commits. Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and @@ -1048,41 +2050,6 @@ user.signingkey:: unchanged to gpg's --local-user parameter, so you may specify a key using any method that gpg supports. -whatchanged.difftree:: - The default linkgit:git-diff-tree[1] arguments to be used - for linkgit:git-whatchanged[1]. - -imap:: - The configuration variables in the 'imap' section are described - in linkgit:git-imap-send[1]. - -receive.fsckObjects:: - If it is set to true, git-receive-pack will check all received - objects. It will abort in the case of a malformed object or a - broken link. The result of an abort are only dangling objects. - Defaults to false. - -receive.unpackLimit:: - If the number of objects received in a push is below this - limit then the objects will be unpacked into loose object - files. However if the number of received objects equals or - exceeds this limit then the received pack will be stored as - a pack, after adding any missing delta bases. Storing the - pack from a push can make the push operation complete faster, - especially on slow filesystems. If not set, the value of - `transfer.unpackLimit` is used instead. - -receive.denyNonFastForwards:: - If set to true, git-receive-pack will deny a ref update which is - not a fast forward. Use this to prevent such an update via a push, - even if that push is forced. This configuration variable is - set when initializing a shared repository. - -transfer.unpackLimit:: - When `fetch.unpackLimit` or `receive.unpackLimit` are - not set, the value of this variable is used instead. - The default value is 100. - web.browser:: Specify a web browser that may be used by some commands. Currently only linkgit:git-instaweb[1] and linkgit:git-help[1] diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt new file mode 100644 index 0000000000..c000f08a9d --- /dev/null +++ b/Documentation/date-formats.txt @@ -0,0 +1,26 @@ +DATE FORMATS +------------ + +The GIT_AUTHOR_DATE, GIT_COMMITTER_DATE environment variables +ifdef::git-commit[] +and the `--date` option +endif::git-commit[] +support the following date formats: + +Git internal format:: + It is `<unix timestamp> <timezone offset>`, where `<unix + timestamp>` is the number of seconds since the UNIX epoch. + `<timezone offset>` is a positive or negative offset from UTC. + For example CET (which is 2 hours ahead UTC) is `+0200`. + +RFC 2822:: + The standard email format as described by RFC 2822, for example + `Thu, 07 Apr 2005 22:13:13 +0200`. + +ISO 8601:: + Time and date specified by the ISO 8601 standard, for example + `2005-04-07T22:13:13`. The parser accepts a space instead of the + `T` character as well. ++ +NOTE: In addition, the date part is accepted in the following formats: +`YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`. diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt new file mode 100644 index 0000000000..6aa1be0478 --- /dev/null +++ b/Documentation/diff-config.txt @@ -0,0 +1,140 @@ +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.statGraphWidth:: + Limit the width of the graph part in --stat output. If set, applies + to all commands generating --stat outuput except format-patch. + +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 400cbb3b1c..15c7e794f4 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -1,4 +1,7 @@ -The output format from "git-diff-index", "git-diff-tree", +Raw output format +----------------- + +The raw output format from "git-diff-index", "git-diff-tree", "git-diff-files" and "git diff --raw" are very similar. These commands all compare two sets of things; what is @@ -16,6 +19,9 @@ 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 output by printing the hash of +what is being compared. After that, all the commands print one output +line per changed file. An output line is formatted this way: @@ -46,6 +52,22 @@ That is, from the left to the right: . path for "dst"; only exists for C or R. . an LF or a NUL when '-z' option is used, to terminate the record. +Possible status letters are: + +- A: addition of a file +- C: copy of a file into a new one +- D: deletion of a file +- M: modification of the contents or mode of a file +- R: renaming of a file +- T: change in the type of the file +- U: file is unmerged (you must complete the merge before it can +be committed) +- X: "unknown" change type (most probably a bug, please report it) + +Status letters C and R are always followed by a score (denoting the +percentage of similarity between the source and target of the move or +copy), and are the only ones to be so. + <sha1> is shown as all 0's if a file is new on the filesystem and it is out of sync with the index. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 029c5f2b82..55f499a160 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: ------------ @@ -96,7 +120,7 @@ index fabadb8,cc95eb0..4866510 + or like this (when '--cc' option is used): - diff --c file + diff --cc file 2. It is followed by one or more extended header lines (this example shows a merge with two parents): @@ -143,15 +167,15 @@ different from it. A `-` character in the column N means that the line appears in fileN but it does not appear in the result. A `+` character -in the column N means that the line appears in the last file, +in the column N means that the line appears in the result, and fileN does not have that line (in other words, the line was added, from the point of view of that parent). In the above example output, the function signature was changed from both files (hence two `-` removals from both file1 and file2, plus `++` to mean one line that was added does not appear -in either file1 nor file2). Also two other lines are the same -from file1 but do not appear in file2 (hence prefixed with ` +`). +in either file1 nor file2). Also eight other lines are the same +from file1 but do not appear in file2 (hence prefixed with `+`). When shown by `git diff-tree -c`, it compares the parents of a merge commit with the merge result (i.e. file1..fileN are the diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 572154834b..6cfedd85dc 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -14,70 +14,148 @@ endif::git-format-patch[] ifdef::git-format-patch[] -p:: - Generate patches without diffstat. +--no-stat:: + Generate plain patches without any diffstats. 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[] --u:: - Synonym for "-p". - -U<n>:: - Shorthand for "--unified=<n>". - --unified=<n>:: Generate diffs with <n> lines of context instead of - the usual three. Implies "-p". + the usual three. +ifndef::git-format-patch[] + Implies `-p`. +endif::git-format-patch[] +ifndef::git-format-patch[] --raw:: Generate the raw format. {git-diff-core? This is the default.} +endif::git-format-patch[] +ifndef::git-format-patch[] --patch-with-raw:: - Synonym for "-p --raw". + Synonym for `-p --raw`. +endif::git-format-patch[] ---stat[=width[,name-width]]:: - Generate a diffstat. You can override the default - 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. +--minimal:: + Spend extra time to make sure the smallest possible + diff is produced. + +--patience:: + Generate a diff using the "patience diff" algorithm. + +--histogram:: + Generate a diff using the "histogram diff" algorithm. + +--stat[=<width>[,<name-width>[,<count>]]]:: + Generate a diffstat. By default, as much space as necessary + will be used for the filename part, and the rest for the graph + part. Maximum width defaults to terminal width, or 80 columns + if not connected to a terminal, and can be overriden by + `<width>`. The width of the filename part can be limited by + giving another width `<name-width>` after a comma. The width + of the graph part can be limited by using + `--stat-graph-width=<width>` (affects all commands generating + a stat graph) or by setting `diff.statGraphWidth=<width>` + (does not affect `git format-patch`). + 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 + Similar to `--stat`, but shows number of added and deleted lines in decimal notation and pathname without abbreviation, to make it more machine friendly. For binary files, outputs two `-` instead of saying `0 0`. --shortstat:: - Output only the last line of the --stat format containing total + Output only the last line of the `--stat` format containing total number of modified files, as well as number of added and deleted lines. ---dirstat[=limit]:: - Output only the sub-directories that are impacted by a diff, - and to what degree they are impacted. You can override the - default cut-off in percent (3) by "--dirstat=limit". If you - want to enable "cumulative" directory statistics, you can use - the "--cumulative" flag, which adds up percentages recursively - even when they have been already reported for a sub-directory. +--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 such as creations, renames and mode changes. +ifndef::git-format-patch[] --patch-with-stat:: - Synonym for "-p --stat". - {git-format-patch? This is the default.} + Synonym for `-p --stat`. +endif::git-format-patch[] + +ifndef::git-format-patch[] -z:: - NUL-line termination on output. This affects the --raw - output field terminator. Also output from commands such - as "git-log" will be delimited with NUL between commits. +ifdef::git-log[] + Separate the commits with NULs instead of with new newlines. ++ +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`, `--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, +and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`, +respectively, and the pathname will be enclosed in double quotes if +any of those replacements occurred. --name-only:: Show only names of changed files. @@ -86,62 +164,156 @@ endif::git-format-patch[] Show only names and status of changed files. See the description of the `--diff-filter` option on what the status letters mean. ---color:: +--submodule[=<format>]:: + Specify how differences in submodules are shown. When `--submodule` + or `--submodule=log` is given, the 'log' format is used. This format lists + the commits in the range like linkgit:git-submodule[1] `summary` does. + Omitting the `--submodule` option or specifying `--submodule=short`, + uses the 'short' format. This format just shows the names of the commits + at the beginning and end of the range. + +--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. - ---color-words:: - Show colored word diff, i.e. color words which have changed. + 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`. + +--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. ++ +Every non-overlapping match of the +<regex> is considered a word. Anything between these matches is +considered whitespace and ignored(!) for the purposes of finding +differences. You may want to append `|[^[:space:]]` to your regular +expression to make sure that it matches all non-whitespace characters. +A match that contains a newline is silently truncated(!) at the +newline. ++ +The regex can also be set via a diff driver or configuration option, see +linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly +overrides any diff driver or configuration setting. Diff drivers +override configuration settings. + +--color-words[=<regex>]:: + Equivalent to `--word-diff=color` plus (if a regex was + specified) `--word-diff-regex=<regex>`. +endif::git-format-patch[] --no-renames:: Turn off rename detection, even when the configuration file gives the default to do so. +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:: - Instead of the first handful characters, show full - object name of pre- and post-image blob on the "index" - line when generating a patch format output. + Instead of the first handful of characters, show the full + pre- and post-image blob object names on the "index" + line when generating patch format output. --binary:: - In addition to --full-index, output "binary diff" that - can be applied with "git apply". + In addition to `--full-index`, output a binary diff that + can be applied with `git-apply`. --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header - lines, show only handful hexdigits prefix. This is - independent of --full-index option above, which controls + lines, show only a partial prefix. This is + independent of the `--full-index` option above, which controls 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:: + digits can be specified with `--abbrev=<n>`. + +-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`. - ---diff-filter=[ACDMRTUXB*]:: - Select only files that are Added (`A`), Copied (`C`), - Deleted (`D`), Modified (`M`), Renamed (`R`), have their - type (mode) 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. + 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 @@ -152,29 +324,64 @@ 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>:: - -M and -C options require O(n^2) processing time where n + The `-M` and `-C` options require O(n^2) processing time where n is the number of potential rename/copy targets. This option prevents rename/copy detection from running if the number of rename/copy targets exceeds the specified 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 contain the change in <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>. --pickaxe-regex:: Make the <string> not a plain string but an extended POSIX regex to match. +endif::git-format-patch[] -O<orderfile>:: Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. +ifndef::git-format-patch[] -R:: Swap two inputs; that is, show differences from index or on-disk file to tree contents. @@ -186,39 +393,46 @@ endif::git-format-patch[] not in a subdirectory (e.g. in a bare repository), you can name which subdirectory to make the output relative to by giving a <path> as an argument. +endif::git-format-patch[] +-a:: --text:: Treat all files as text. --a:: - Shorthand for "--text". - --ignore-space-at-eol:: Ignore changes in whitespace at EOL. +-b:: --ignore-space-change:: Ignore changes in amount of whitespace. This ignores whitespace at line end, and considers all other sequences of one or more whitespace characters to be equivalent. --b:: - Shorthand for "--ignore-space-change". - +-w:: --ignore-all-space:: Ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none. --w:: - Shorthand for "--ignore-all-space". +--inter-hunk-context=<lines>:: + Show the context between diff hunks, up to the specified number + of lines, thereby fusing hunks that are close to each other. + +-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 0 means no differences. --quiet:: - Disable all output of the program. Implies --exit-code. + Disable all output of the program. Implies `--exit-code`. +endif::git-log[] +endif::git-format-patch[] --ext-diff:: Allow an external diff helper to be executed. If you set an @@ -228,8 +442,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/". @@ -241,4 +476,4 @@ endif::git-format-patch[] Do not show any source or destination prefix. For more detailed explanation on these common options, see also -linkgit:gitdiffcore[7][diffcore documentation]. +linkgit:gitdiffcore[7]. diff --git a/Documentation/docbook-xsl.css b/Documentation/docbook-xsl.css index b878b385c6..e11c8f053a 100644 --- a/Documentation/docbook-xsl.css +++ b/Documentation/docbook-xsl.css @@ -16,6 +16,7 @@ body blockquote { html body { margin: 1em 5% 1em 5%; line-height: 1.2; + font-family: sans-serif; } body div { @@ -128,6 +129,15 @@ body pre { tt.literal, code.literal { color: navy; + font-family: sans-serif; +} + +code.literal:before { content: "'"; } +code.literal:after { content: "'"; } + +em { + font-style: italic; + color: #064; } div.literallayout p { @@ -137,7 +147,6 @@ div.literallayout p { div.literallayout { font-family: monospace; -# margin: 0.5em 10% 0.5em 1em; margin: 0em; color: navy; border: 1px solid silver; @@ -187,7 +196,8 @@ dt { } dt span.term { - font-style: italic; + font-style: normal; + color: navy; } div.variablelist dd p { 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 e598cdda45..048337b40f 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. @@ -98,7 +55,7 @@ Use a tarball as a starting point for a new repository.:: ------------ $ tar zxf frotz.tar.gz $ cd frotz -$ git-init +$ git init $ git add . <1> $ git commit -m "import of frotz source tree." $ git tag v2.43 <2> @@ -141,8 +98,8 @@ you originally wrote. <9> switch to the master branch. <10> merge a topic branch into your master branch. <11> review commit logs; other forms to limit output can be -combined and include `\--max-count=10` (show 10 commits), -`\--until=2005-12-10`, etc. +combined and include `--max-count=10` (show 10 commits), +`--until=2005-12-10`, etc. <12> view only the changes that touch what's in `curses/` directory, since `v2.43` tag. @@ -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 85c87180db..39d326abc6 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -1,11 +1,5 @@ --q:: ---quiet:: - Pass --quiet to git-fetch-pack and silence any other internally - used programs. - --v:: ---verbose:: - Be verbose. +--all:: + Fetch all remotes. -a:: --append:: @@ -13,20 +7,39 @@ existing contents of `.git/FETCH_HEAD`. Without this option old data in `.git/FETCH_HEAD` will be overwritten. ---upload-pack <upload-pack>:: - When given, and the repository to fetch from is handled - 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. +--depth=<depth>:: + Deepen the history of a 'shallow' repository created by + `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) + by the specified number of commits. + +ifndef::git-pull[] +--dry-run:: + Show what would be done, without making any changes. +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 overrides that check. +-k:: +--keep:: + Keep downloaded pack. + +ifndef::git-pull[] +--multiple:: + Allow several <repository> and <group> arguments to be + specified. No <refspec>s may be specified. + +-p:: +--prune:: + After fetching, remove any remote-tracking branches which + no longer exist on the remote. +endif::git-pull[] + ifdef::git-pull[] --no-tags:: endif::git-pull[] @@ -36,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 @@ -45,22 +61,68 @@ 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]. --k:: ---keep:: - Keep downloaded pack. +--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. ---depth=<depth>:: - Deepen the history of a 'shallow' repository created by - `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) - by the specified number of commits. +--upload-pack <upload-pack>:: + When given, and the repository to fetch from is handled + 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. + +ifndef::git-pull[] +-q:: +--quiet:: + Pass --quiet to git-fetch-pack and silence any other internally + 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 b8e3fa6759..9c1d395722 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -8,34 +8,39 @@ git-add - Add file contents to the index SYNOPSIS -------- [verse] -'git-add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] - [--update | -u] [--refresh] [--ignore-errors] [--] - <filepattern>... +'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] + [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N] + [--refresh] [--ignore-errors] [--ignore-missing] [--] + [<filepattern>...] DESCRIPTION ----------- -This command adds the current content of new or modified files to the -index, thus staging that content for inclusion in the next commit. +This command updates the index using the current content found in +the working tree, to prepare the content staged for the next commit. +It typically adds the current content of existing paths as a whole, +but with some options it can also be used to add content with +only part of the changes made to the working tree files applied, or +remove paths that do not exist in the working tree anymore. The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus after making any changes to the working directory, and before running -the commit command, you must use the 'add' command to add any new or +the commit command, you must use the `add` command to add any new or modified files to the index. This command can be performed multiple times before a commit. It only adds the content of the specified file(s) at the time the add command is run; if you want subsequent changes included in the next commit, then -you must run 'git add' again to add the new content to the index. +you must run `git add` again to add the new content to the index. -The 'git status' command can be used to obtain a summary of which +The `git status` command can be used to obtain a summary of which files have changes that are staged for the next commit. -The 'git add' command will not add ignored files by default. If any -ignored files were explicitly specified on the command line, 'git add' +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 @@ -53,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:: @@ -72,19 +78,53 @@ OPTIONS -p:: --patch:: - Similar to Interactive mode but the initial command loop is - bypassed and the 'patch' subcommand is invoked using each of - the specified filepatterns before exiting. + Interactively choose hunks of patch between the index and the + work tree and add them to the index. This gives the user a chance + to review the difference before adding modified contents to the + index. ++ +This effectively runs `add --interactive`, but bypasses the +initial command menu and directly jumps to the `patch` subcommand. +See ``Interactive mode'' for details. + +-e, \--edit:: + Open the diff vs. the index in an editor and let the user + edit it. After the editor was closed, adjust the hunk headers + and apply the patch to the index. ++ +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:: - Update only files that git already knows about, staging modified - content for commit and marking deleted files for removal. This - is similar - to what "git commit -a" does in preparation for making a commit, - except that the update is limited to paths specified on the - command line. If no paths are specified, all tracked files in the - current directory and its subdirectories are updated. + Only match <filepattern> against already tracked files in + the index rather than the working tree. That means that it + will never stage new files, but that it will stage modified + new contents of tracked files and that it will remove files + from the index if the corresponding files in the working tree + have been removed. ++ +If no <filepattern> is given, default to "."; in other words, +update all tracked files in the current directory and its +subdirectories. + +-A:: +--all:: + Like `-u`, but match <filepattern> against files in the + working tree in addition to the index. That means that it + will find new files as well as staging modified content and + removing files that are no longer in the working tree. + +-N:: +--intent-to-add:: + Record only the fact that the path will be added later. An entry + for the path is placed in the index with no content. This is + useful for, among other things, showing the unstaged content of + such files with `git diff` and committing them with `git commit + -a`. --refresh:: Don't add the file(s), but only refresh their stat() @@ -94,6 +134,14 @@ OPTIONS 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 @@ -104,24 +152,24 @@ OPTIONS Configuration ------------- -The optional configuration variable 'core.excludesfile' indicates a path to a +The optional configuration variable `core.excludesfile` indicates a path to a file containing patterns of file names to exclude from git-add, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to -those in info/exclude. See linkgit:gitrepository-layout[5][repository layout]. +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 -example; this lets the command to include the files from +Note that the asterisk `*` is quoted from the shell in this +example; this lets the command include the files from subdirectories of `Documentation/` directory. * Considers adding content from all git-*.sh scripts: @@ -130,7 +178,7 @@ subdirectories of `Documentation/` directory. $ git add git-*.sh ------------ + -Because this example lets shell expand the asterisk (i.e. you are +Because this example lets the shell expand the asterisk (i.e. you are listing the files explicitly), it does not consider `subdir/git-foo.sh`. @@ -152,7 +200,7 @@ and type return, like this: What now> 1 ------------ -You also could say "s" or "sta" or "status" above as long as the +You also could say `s` or `sta` or `status` above as long as the choice is unique. The main command loop has 6 subcommands (plus help and quit). @@ -160,9 +208,9 @@ The main command loop has 6 subcommands (plus help and quit). status:: This shows the change between HEAD and index (i.e. what will be - committed if you say "git commit"), and between index and + committed if you say `git commit`), and between index and working tree files (i.e. what you could stage further before - "git commit" using "git-add") for each path. A sample output + `git commit` using `git add`) for each path. A sample output looks like this: + ------------ @@ -176,19 +224,20 @@ 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). update:: - This shows the status information and gives prompt - "Update>>". When the prompt ends with double '>>', you can + This shows the status information and issues an "Update>>" + prompt. When the prompt ends with double '>>', you can make more than one selection, concatenated with whitespace or comma. Also you can say ranges. E.g. "2-5 7,9" to choose - 2,3,4,5,7,9 from the list. You can say '*' to choose - everything. + 2,3,4,5,7,9 from the list. If the second number in a range is + omitted, all remaining patches are taken. E.g. "7-" to choose + 7,8,9 from the list. You can say '*' to choose everything. + What you chose are then highlighted with '*', like this: @@ -222,36 +271,109 @@ add untracked:: patch:: - This lets you choose one path out of 'status' like selection. - After choosing the path, it presents diff between the index + 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 - 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 J - leave this hunk undecided, see next hunk k - leave this hunk undecided, see previous undecided hunk K - leave this hunk undecided, see previous hunk s - split the current hunk into smaller hunks + e - manually edit the current hunk ? - print help + 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). -Bugs ----- -The interactive mode does not work with files whose names contain -characters that need C-quoting. `core.quotepath` configuration can be -used to work this limitation around to some degree, but backslash, -double-quote and control characters will still have problems. + +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 -------- @@ -262,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 46544a0769..19d57a80f5 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,11 +9,14 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git-am' [--signoff] [--keep] [--utf8 | --no-utf8] - [--3way] [--interactive] [--binary] - [--whitespace=<option>] [-C<n>] [-p<n>] - <mbox>|<Maildir>... -'git-am' [--skip | --resolved] +'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>] + [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] + [--scissors | --no-scissors] + [(<mbox> | <Maildir>)...] +'git am' (--continue | --skip | --abort) DESCRIPTION ----------- @@ -23,55 +26,75 @@ current branch. OPTIONS ------- -<mbox>|<Maildir>...:: +(<mbox>|<Maildir>)...:: The list of mailbox files to read patches from. If you do not - supply this argument, reads from the standard input. If you supply - directories, they'll be treated as Maildirs. + supply this argument, the command reads from the standard input. + If you supply directories, they will be treated as Maildirs. -s:: --signoff:: - Add `Signed-off-by:` line to the commit message, using + Add a `Signed-off-by:` line to the commit message, using the committer identity of yourself. -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-non-patch:: + Pass `-b` 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:: + Ignore scissors lines (see linkgit:git-mailinfo[1]). + +-q:: +--quiet:: + Be quiet. Only print error messages. -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 preferred encoding if it is not UTF-8). + This was optional in prior versions of git, but now it is the -default. You could use `--no-utf8` to override this. +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:: --3way:: When the patch does not apply cleanly, fall back on - 3-way merge, if the patch records the identity of blobs - it is supposed to apply to, and we have those blobs + 3-way merge if the patch records the identity of blobs + it is supposed to apply to and we have those blobs available locally. --b:: ---binary:: - Pass `--allow-binary-replacement` flag to `git-apply` - (see linkgit:git-apply[1]). - +--ignore-date:: +--ignore-space-change:: +--ignore-whitespace:: --whitespace=<option>:: - This flag is passed to the `git-apply` (see linkgit:git-apply[1]) - program that applies - the patch. - -C<n>:: -p<n>:: - These flags are passed to the `git-apply` (see linkgit:git-apply[1]) +--directory=<dir>:: +--exclude=<path>:: +--include=<path>:: +--reject:: + These flags are passed to the 'git apply' (see linkgit:git-apply[1]) program that applies the patch. @@ -79,10 +102,25 @@ default. You could use `--no-utf8` to override this. --interactive:: Run interactively. +--committer-date-is-author-date:: + By default the command records the date from the e-mail + message as the commit author date, and uses the time of + commit creation as the committer date. This allows the + user to lie about the committer date by using the same + value as the author date. + +--ignore-date:: + By default the command records the date from the e-mail + message as the commit author date, and uses the time of + commit creation as the committer date. This allows the + user to lie about the author date by using the same + value as the committer date. + --skip:: 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 @@ -97,30 +135,31 @@ default. You could 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. DISCUSSION ---------- The commit author name is taken from the "From: " line of the -message, and commit author time is taken from the "Date: " line +message, and commit author date is taken from the "Date: " line of the message. The "Subject: " line is used as the title of the commit, after stripping common prefix "[PATCH <anything>]". -It is supposed to describe what the commit is about concisely as -a one line text. +The "Subject: " line is supposed to concisely describe what the +commit is about in one line of text. -The body of the message (iow, after a blank line that terminates -RFC2822 headers) can begin with "Subject: " and "From: " lines -that are different from those of the mail header, to override -the values of these fields. +"From: " and "Subject: " lines starting the body override the respective +commit author name and title values taken from the headers. The commit message is formed by the title taken from the "Subject: ", a blank line and the body of the message up to -where the patch begins. Excess whitespaces at the end of the -lines are automatically stripped. +where the patch begins. Excess whitespace at the end of each +line is automatically stripped. The patch is expected to be inline, directly following the -message. Any line that is of form: +message. Any line that is of the form: * three-dashes and end-of-line, or * a line that begins with "diff -", or @@ -129,36 +168,33 @@ message. Any line that is of form: is taken as the beginning of a patch, and the commit log message is terminated before the first occurrence of such a line. -When initially invoking it, you give it names of the mailboxes -to crunch. Upon seeing the first patch that does not apply, it -aborts in the middle,. You can recover from this in one of two ways: +When initially invoking `git am`, you give it the names of the mailboxes +to process. Upon seeing the first patch that does not apply, it +aborts in the middle. You can recover from this in one of two ways: -. skip the current patch by re-running the command with '--skip' +. skip the current patch by re-running the command with the '--skip' option. . hand resolve the conflict in the working directory, and update - the index file to bring it in a state that the patch should - have produced. Then run the command with '--resolved' option. + 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 `.dotest` -directory exists, so if you decide to start over from scratch, -run `rm -f -r .dotest` 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 +current branch. This is useful if you have problems with multiple +commits, like running 'git am' on the wrong branch or an error in the +commits that is more easily fixed by changing the mailbox (e.g. +errors in the "From:" lines). + SEE ALSO -------- linkgit:git-apply[1]. - -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -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 da15379ae5..05fd482b74 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -3,16 +3,22 @@ git-annotate(1) NAME ---- -git-annotate - Annotate file lines with commit info +git-annotate - Annotate file lines with commit information SYNOPSIS -------- -git-annotate [options] file [revision] +[verse] +'git annotate' [options] file [revision] DESCRIPTION ----------- Annotates each line in the given file with information from the commit -which introduced the line. Optionally annotate from a given revision. +which introduced the line. Optionally annotates from a given revision. + +The only difference between this command and linkgit:git-blame[1] is that +they use slightly different output formats, and this command exists only +for backward compatibility to support existing scripts, and provide a more +familiar command name for people coming from other SCM systems. OPTIONS ------- @@ -22,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 c8347637da..afd2c9ae59 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -3,28 +3,37 @@ git-apply(1) NAME ---- -git-apply - Apply a patch on a git index file and a working tree +git-apply - Apply a patch to files and/or to the index SYNOPSIS -------- [verse] -'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] - [--apply] [--no-add] [--build-fake-ancestor <file>] [-R | --reverse] +'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] [--cached] - [--whitespace=<nowarn|warn|fix|error|error-all>] - [--exclude=PATH] [--verbose] [<patch>...] + [-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>] + [--verbose] [<patch>...] DESCRIPTION ----------- -Reads supplied diff output and applies it on a git index file -and a work tree. +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 `--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>...:: - The files to read patch from. '-' can be used to read + The files to read the patch from. '-' can be used to read from the standard input. --stat:: @@ -32,8 +41,8 @@ OPTIONS input. Turns off "apply". --numstat:: - Similar to \--stat, but shows number of added and - deleted lines in decimal notation and pathname without + Similar to `--stat`, but shows the number of added and + deleted lines in decimal notation and the pathname without abbreviation, to make it more machine friendly. For binary files, outputs two `-` instead of saying `0 0`. Turns off "apply". @@ -46,28 +55,28 @@ OPTIONS --check:: Instead of applying the patch, see if the patch is - applicable to the current work tree and/or the index + applicable to the current working tree and/or the index file and detects errors. Turns off "apply". --index:: - When --check is in effect, or when applying the patch + When `--check` is in effect, or when applying the patch (which is the default when none of the options that disables it is in effect), make sure the patch is applicable to what the current index file records. If - the file to be patched in the work tree is not + the file to be patched in the working tree is not up-to-date, it is flagged as an error. This flag also causes the index file to be updated. --cached:: - Apply a patch without touching the working tree. Instead, take the - cached data, apply the patch, and store the result in the index, - without using the working tree. This implies '--index'. + Apply a patch without touching the working tree. Instead take the + cached data, apply the patch, and store the result in the index + without using the working tree. This implies `--index`. ---build-fake-ancestor <file>:: - Newer git-diff output has embedded 'index information' +--build-fake-ancestor=<file>:: + Newer 'git diff' output has embedded 'index information' for each blob to help identify the original version that the patch applies to. When this flag is given, and if - the original versions of the blobs is available locally, + the original versions of the blobs are available locally, builds a temporary index containing those blobs. + When a pure mode change is encountered (which has no index information), @@ -78,18 +87,20 @@ the information is read from the current index instead. Apply the patch in reverse. --reject:: - For atomicity, linkgit:git-apply[1] 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 rejected hunks in corresponding *.rej files. -z:: - When showing the index information, do not munge paths, - but use NUL terminated machine readable format. Without - this flag, the pathnames output will have TAB, LF, and - backslash characters replaced with `\t`, `\n`, and `\\`, - respectively. + When `--numstat` has been given, do not munge pathnames, + but use a NUL-terminated machine-readable format. ++ +Without this option, each pathname output will have TAB, LF, double quotes, +and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`, +respectively, and the pathname will be enclosed in double quotes if +any of those replacements occurred. -p<n>:: Remove <n> leading slashes from traditional diff paths. The @@ -102,28 +113,28 @@ the information is read from the current index instead. ever ignored. --unidiff-zero:: - By default, linkgit:git-apply[1] 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 - checks use '--unidiff-zero'. + applying a diff generated with `--unified=0`. To bypass these + checks use `--unidiff-zero`. + -Note, for the reasons stated above usage of context-free patches are +Note, for the reasons stated above usage of context-free patches is discouraged. --apply:: If you use any of the options marked "Turns off - 'apply'" above, linkgit:git-apply[1] reads and outputs the - information you asked without actually applying 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. --no-add:: When applying a patch, ignore additions made by the patch. This can be used to extract the common part between - two files by first running `diff` on them and applying + two files by first running 'diff' on them and applying the result with this option, which would apply the - deletion part but not addition part. + deletion part but not the addition part. --allow-binary-replacement:: --binary:: @@ -137,6 +148,25 @@ discouraged. be useful when importing patchsets, where you want to exclude certain files or directories. +--include=<path-pattern>:: + Apply changes to files matching the given path pattern. This can + be useful when importing patchsets, where you want to include certain + files or directories. ++ +When `--exclude` and `--include` patterns are used, they are examined in the +order they appear on the command line, and the first match determines if a +patch to each path is used. A patch to a path that does not match any +include/exclude pattern is used by default if there is no include pattern +on the command line, and ignored if there is any include pattern. + +--ignore-space-change:: +--ignore-whitespace:: + When applying a patch, ignore changes in whitespace in context + lines if necessary. + Context lines will preserve their whitespace, and they will not + undergo whitespace fixing regardless of the value of the + `--whitespace` option. New lines will still be fixed, though. + --whitespace=<action>:: When applying a patch, detect a new or modified line that has whitespace errors. What are considered whitespace errors is @@ -147,10 +177,10 @@ discouraged. considered whitespace errors. + By default, the command outputs warning messages but applies the patch. -When linkgit:git-apply[1] is used for statistics and not applying a +When `git-apply` is used for statistics and not applying a patch, it defaults to `nowarn`. + -You can use different `<action>` to control this +You can use different `<action>` values to control this behavior: + * `nowarn` turns off the trailing whitespace warning. @@ -158,16 +188,16 @@ behavior: patch as-is (default). * `fix` outputs warnings for a few such errors, and applies the patch after fixing them (`strip` is a synonym --- the tool - used to consider only trailing whitespaces as errors, and the + used to consider only trailing whitespace characters as errors, and the fix involved 'stripping' them, but modern gits do more). * `error` outputs warnings for a few such errors, and refuses to apply the patch. * `error-all` is similar to `error` but shows all errors. --inaccurate-eof:: - Under certain circumstances, some versions of diff do not correctly + Under certain circumstances, some versions of 'diff' do not correctly detect a missing new-line at the end of the file. As a result, patches - created by such diff programs do not record incomplete lines + created by such 'diff' programs do not record incomplete lines correctly. This option adds support for applying such patches by working around this bug. @@ -177,35 +207,48 @@ behavior: current patch being applied will be printed. This option will cause additional information to be reported. +--recount:: + Do not trust the line counts in the hunk headers, but infer them + by inspecting the patch (e.g. after editing the patch without + adjusting the hunk headers appropriately). + +--directory=<root>:: + Prepend <root> to all filenames. If a "-p" argument was also passed, + it is applied before prepending the new root. ++ +For example, a patch that talks about updating `a/git-gui.sh` to `b/git-gui.sh` +can be applied to the file in the working tree `modules/git-gui/git-gui.sh` by +running `git apply --directory=modules/git-gui`. + Configuration ------------- +apply.ignorewhitespace:: + Set to 'change' if you want changes in whitespace to be ignored by default. + Set to one of: no, none, never, false if you want changes in + whitespace to be significant. apply.whitespace:: When no `--whitespace` flag is given from the command line, this configuration item is used as the default. Submodules ---------- -If the patch contains any changes to submodules then linkgit:git-apply[1] +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 +If `--index` is specified (explicitly or implicitly), then the submodule commits must match the index exactly for the patch to apply. If any of the submodules are checked-out, then these check-outs are completely ignored, i.e., they are not required to be up-to-date or clean and they are not updated. -If --index is not specified, then the submodule commits in the patch -are ignored and only the absence of presence of the corresponding +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 603117c796..f4504ba9bf 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -9,7 +9,7 @@ git-archimport - Import an Arch repository into git SYNOPSIS -------- [verse] -'git-archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] +'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] <archive/branch>[:<git-branch>] ... DESCRIPTION @@ -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 9b5f3ae5ed..59d73e532f 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -9,9 +9,10 @@ git-archive - Create an archive of files from a named tree SYNOPSIS -------- [verse] -'git-archive' --format=<fmt> [--list] [--prefix=<prefix>/] [<extra>] +'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] + [-o | --output=<file>] [--worktree-attributes] [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> - [path...] + [<path>...] DESCRIPTION ----------- @@ -20,21 +21,24 @@ 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 modification time of each file in the archive. In the latter +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 ------- --format=<fmt>:: - Format of the resulting archive: 'tar' or 'zip'. The default - is 'tar'. + Format of the resulting archive: 'tar' or 'zip'. If this option + is not given, and the output file is specified, the format is + inferred from the filename if possible (e.g. writing to "foo.zip" + makes the output to be in the zip format). Otherwise the output + format is `tar`. -l:: --list:: @@ -47,24 +51,32 @@ OPTIONS --prefix=<prefix>/:: Prepend <prefix>/ to each filename in the archive. +-o <file>:: +--output=<file>:: + Write the archive to <file> instead of stdout. + +--worktree-attributes:: + Look for attributes in .gitattributes in working directory too. + <extra>:: - This can be any options that the archiver backend understand. + This can be any options that the archiver backend understands. See next section. --remote=<repo>:: - Instead of making a tar archive from local repository, + Instead of making a tar archive from the local repository, retrieve a tar archive from a remote repository. --exec=<git-upload-archive>:: Used with --remote to specify the path to the - git-upload-archive executable on the remote side. + 'git-upload-archive' on the remote side. <tree-ish>:: The tree or commit to produce an archive for. -path:: - If one or more paths are specified, include only these in the - archive, otherwise include all files and subdirectories. +<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. BACKEND EXTRA OPTIONS --------------------- @@ -86,37 +98,94 @@ 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 +---------- + +export-ignore:: + Files and directories with the attribute export-ignore won't be + added to archive files. See linkgit:gitattributes[5] for details. + +export-subst:: + If the attribute export-subst is set for a file then git will + 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 extracts it in + 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^{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/'. -Author ------- -Written by Franck Bui-Huu and Rene Scharfe. +`git archive -o latest.zip HEAD`:: -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + 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] GIT --- diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt new file mode 100644 index 0000000000..8a2ba37904 --- /dev/null +++ b/Documentation/git-bisect-lk2009.txt @@ -0,0 +1,1358 @@ +Fighting regressions with git bisect +==================================== +:Author: Christian Couder +:Email: chriscool@tuxfamily.org +:Date: 2009/11/08 + +Abstract +-------- + +"git bisect" enables software users and developers to easily find the +commit that introduced a regression. We show why it is important to +have good tools to fight regressions. We describe how "git bisect" +works from the outside and the algorithms it uses inside. Then we +explain how to take advantage of "git bisect" to improve current +practices. And we discuss how "git bisect" could improve in the +future. + + +Introduction to "git bisect" +---------------------------- + +Git is a Distributed Version Control system (DVCS) created by Linus +Torvalds and maintained by Junio Hamano. + +In Git like in many other Version Control Systems (VCS), the different +states of the data that is managed by the system are called +commits. And, as VCS are mostly used to manage software source code, +sometimes "interesting" changes of behavior in the software are +introduced in some commits. + +In fact people are specially interested in commits that introduce a +"bad" behavior, called a bug or a regression. They are interested in +these commits because a commit (hopefully) contains a very small set +of source code changes. And it's much easier to understand and +properly fix a problem when you only need to check a very small set of +changes, than when you don't know where look in the first place. + +So to help people find commits that introduce a "bad" behavior, the +"git bisect" set of commands was invented. And it follows of course +that in "git bisect" parlance, commits where the "interesting +behavior" is present are called "bad" commits, while other commits are +called "good" commits. And a commit that introduce the behavior we are +interested in is called a "first bad commit". Note that there could be +more than one "first bad commit" in the commit space we are searching. + +So "git bisect" is designed to help find a "first bad commit". And to +be as efficient as possible, it tries to perform a binary search. + + +Fighting regressions overview +----------------------------- + +Regressions: a big problem +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Regressions are a big problem in the software industry. But it's +difficult to put some real numbers behind that claim. + +There are some numbers about bugs in general, like a NIST study in +2002 <<1>> that said: + +_____________ +Software bugs, or errors, are so prevalent and so detrimental that +they cost the U.S. economy an estimated $59.5 billion annually, or +about 0.6 percent of the gross domestic product, according to a newly +released study commissioned by the Department of Commerce's National +Institute of Standards and Technology (NIST). At the national level, +over half of the costs are borne by software users and the remainder +by software developers/vendors. The study also found that, although +all errors cannot be removed, more than a third of these costs, or an +estimated $22.2 billion, could be eliminated by an improved testing +infrastructure that enables earlier and more effective identification +and removal of software defects. These are the savings associated with +finding an increased percentage (but not 100 percent) of errors closer +to the development stages in which they are introduced. Currently, +over half of all errors are not found until "downstream" in the +development process or during post-sale software use. +_____________ + +And then: + +_____________ +Software developers already spend approximately 80 percent of +development costs on identifying and correcting defects, and yet few +products of any type other than software are shipped with such high +levels of errors. +_____________ + +Eventually the conclusion started with: + +_____________ +The path to higher software quality is significantly improved software +testing. +_____________ + +There are other estimates saying that 80% of the cost related to +software is about maintenance <<2>>. + +Though, according to Wikipedia <<3>>: + +_____________ +A common perception of maintenance is that it is merely fixing +bugs. However, studies and surveys over the years have indicated that +the majority, over 80%, of the maintenance effort is used for +non-corrective actions (Pigosky 1997). This perception is perpetuated +by users submitting problem reports that in reality are functionality +enhancements to the system. +_____________ + +But we can guess that improving on existing software is very costly +because you have to watch out for regressions. At least this would +make the above studies consistent among themselves. + +Of course some kind of software is developed, then used during some +time without being improved on much, and then finally thrown away. In +this case, of course, regressions may not be a big problem. But on the +other hand, there is a lot of big software that is continually +developed and maintained during years or even tens of years by a lot +of people. And as there are often many people who depend (sometimes +critically) on such software, regressions are a really big problem. + +One such software is the linux kernel. And if we look at the linux +kernel, we can see that a lot of time and effort is spent to fight +regressions. The release cycle start with a 2 weeks long merge +window. Then the first release candidate (rc) version is tagged. And +after that about 7 or 8 more rc versions will appear with around one +week between each of them, before the final release. + +The time between the first rc release and the final release is +supposed to be used to test rc versions and fight bugs and especially +regressions. And this time is more than 80% of the release cycle +time. But this is not the end of the fight yet, as of course it +continues after the release. + +And then this is what Ingo Molnar (a well known linux kernel +developer) says about his use of git bisect: + +_____________ +I most actively use it during the merge window (when a lot of trees +get merged upstream and when the influx of bugs is the highest) - and +yes, there have been cases that i used it multiple times a day. My +average is roughly once a day. +_____________ + +So regressions are fought all the time by developers, and indeed it is +well known that bugs should be fixed as soon as possible, so as soon +as they are found. That's why it is interesting to have good tools for +this purpose. + +Other tools to fight regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +So what are the tools used to fight regressions? They are nearly the +same as those used to fight regular bugs. The only specific tools are +test suites and tools similar as "git bisect". + +Test suites are very nice. But when they are used alone, they are +supposed to be used so that all the tests are checked after each +commit. This means that they are not very efficient, because many +tests are run for no interesting result, and they suffer from +combinational explosion. + +In fact the problem is that big software often has many different +configuration options and that each test case should pass for each +configuration after each commit. So if you have for each release: N +configurations, M commits and T test cases, you should perform: + +------------- +N * M * T tests +------------- + +where N, M and T are all growing with the size your software. + +So very soon it will not be possible to completely test everything. + +And if some bugs slip through your test suite, then you can add a test +to your test suite. But if you want to use your new improved test +suite to find where the bug slipped in, then you will either have to +emulate a bisection process or you will perhaps bluntly test each +commit backward starting from the "bad" commit you have which may be +very wasteful. + +"git bisect" overview +--------------------- + +Starting a bisection +~~~~~~~~~~~~~~~~~~~~ + +The first "git bisect" subcommand to use is "git bisect start" to +start the search. Then bounds must be set to limit the commit +space. This is done usually by giving one "bad" and at least one +"good" commit. They can be passed in the initial call to "git bisect +start" like this: + +------------- +$ git bisect start [BAD [GOOD...]] +------------- + +or they can be set using: + +------------- +$ git bisect bad [COMMIT] +------------- + +and: + +------------- +$ git bisect good [COMMIT...] +------------- + +where BAD, GOOD and COMMIT are all names that can be resolved to a +commit. + +Then "git bisect" will checkout a commit of its choosing and ask the +user to test it, like this: + +------------- +$ git bisect start v2.6.27 v2.6.25 +Bisecting: 10928 revisions left to test after this (roughly 14 steps) +[2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit +------------- + +Note that the example that we will use is really a toy example, we +will be looking for the first commit that has a version like +"2.6.26-something", that is the commit that has a "SUBLEVEL = 26" line +in the top level Makefile. This is a toy example because there are +better ways to find this commit with git than using "git bisect" (for +example "git blame" or "git log -S<string>"). + +Driving a bisection manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At this point there are basically 2 ways to drive the search. It can +be driven manually by the user or it can be driven automatically by a +script or a command. + +If the user is driving it, then at each step of the search, the user +will have to test the current commit and say if it is "good" or "bad" +using the "git bisect good" or "git bisect bad" commands respectively +that have been described above. For example: + +------------- +$ git bisect bad +Bisecting: 5480 revisions left to test after this (roughly 13 steps) +[66c0b394f08fd89236515c1c84485ea712a157be] KVM: kill file->f_count abuse in kvm +------------- + +And after a few more steps like that, "git bisect" will eventually +find a first bad commit: + +------------- +$ git bisect bad +2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit +commit 2ddcca36c8bcfa251724fe342c8327451988be0d +Author: Linus Torvalds <torvalds@linux-foundation.org> +Date: Sat May 3 11:59:44 2008 -0700 + + Linux 2.6.26-rc1 + +:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M Makefile +------------- + +At this point we can see what the commit does, check it out (if it's +not already checked out) or tinker with it, for example: + +------------- +$ git show HEAD +commit 2ddcca36c8bcfa251724fe342c8327451988be0d +Author: Linus Torvalds <torvalds@linux-foundation.org> +Date: Sat May 3 11:59:44 2008 -0700 + + Linux 2.6.26-rc1 + +diff --git a/Makefile b/Makefile +index 5cf8258..4492984 100644 +--- a/Makefile ++++ b/Makefile +@@ -1,7 +1,7 @@ + VERSION = 2 + PATCHLEVEL = 6 +-SUBLEVEL = 25 +-EXTRAVERSION = ++SUBLEVEL = 26 ++EXTRAVERSION = -rc1 + NAME = Funky Weasel is Jiggy wit it + + # *DOCUMENTATION* +------------- + +And when we are finished we can use "git bisect reset" to go back to +the branch we were in before we started bisecting: + +------------- +$ git bisect reset +Checking out files: 100% (21549/21549), done. +Previous HEAD position was 2ddcca3... Linux 2.6.26-rc1 +Switched to branch 'master' +------------- + +Driving a bisection automatically +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The other way to drive the bisection process is to tell "git bisect" +to launch a script or command at each bisection step to know if the +current commit is "good" or "bad". To do that, we use the "git bisect +run" command. For example: + +------------- +$ git bisect start v2.6.27 v2.6.25 +Bisecting: 10928 revisions left to test after this (roughly 14 steps) +[2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit +$ +$ git bisect run grep '^SUBLEVEL = 25' Makefile +running grep ^SUBLEVEL = 25 Makefile +Bisecting: 5480 revisions left to test after this (roughly 13 steps) +[66c0b394f08fd89236515c1c84485ea712a157be] KVM: kill file->f_count abuse in kvm +running grep ^SUBLEVEL = 25 Makefile +SUBLEVEL = 25 +Bisecting: 2740 revisions left to test after this (roughly 12 steps) +[671294719628f1671faefd4882764886f8ad08cb] V4L/DVB(7879): Adding cx18 Support for mxl5005s +... +... +running grep ^SUBLEVEL = 25 Makefile +Bisecting: 0 revisions left to test after this (roughly 0 steps) +[2ddcca36c8bcfa251724fe342c8327451988be0d] Linux 2.6.26-rc1 +running grep ^SUBLEVEL = 25 Makefile +2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit +commit 2ddcca36c8bcfa251724fe342c8327451988be0d +Author: Linus Torvalds <torvalds@linux-foundation.org> +Date: Sat May 3 11:59:44 2008 -0700 + + Linux 2.6.26-rc1 + +:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M Makefile +bisect run success +------------- + +In this example, we passed "grep '^SUBLEVEL = 25' Makefile" as +parameter to "git bisect run". This means that at each step, the grep +command we passed will be launched. And if it exits with code 0 (that +means success) then git bisect will mark the current state as +"good". If it exits with code 1 (or any code between 1 and 127 +included, except the special code 125), then the current state will be +marked as "bad". + +Exit code between 128 and 255 are special to "git bisect run". They +make it stop immediately the bisection process. This is useful for +example if the command passed takes too long to complete, because you +can kill it with a signal and it will stop the bisection process. + +It can also be useful in scripts passed to "git bisect run" to "exit +255" if some very abnormal situation is detected. + +Avoiding untestable commits +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes it happens that the current state cannot be tested, for +example if it does not compile because there was a bug preventing it +at that time. This is what the special exit code 125 is for. It tells +"git bisect run" that the current commit should be marked as +untestable and that another one should be chosen and checked out. + +If the bisection process is driven manually, you can use "git bisect +skip" to do the same thing. (In fact the special exit code 125 makes +"git bisect run" use "git bisect skip" in the background.) + +Or if you want more control, you can inspect the current state using +for example "git bisect visualize". It will launch gitk (or "git log" +if the DISPLAY environment variable is not set) to help you find a +better bisection point. + +Either way, if you have a string of untestable commits, it might +happen that the regression you are looking for has been introduced by +one of these untestable commits. In this case it's not possible to +tell for sure which commit introduced the regression. + +So if you used "git bisect skip" (or the run script exited with +special code 125) you could get a result like this: + +------------- +There are only 'skip'ped commits left to test. +The first bad commit could be any of: +15722f2fa328eaba97022898a305ffc8172db6b1 +78e86cf3e850bd755bb71831f42e200626fbd1e0 +e15b73ad3db9b48d7d1ade32f8cd23a751fe0ace +070eab2303024706f2924822bfec8b9847e4ac1b +We cannot bisect more! +------------- + +Saving a log and replaying it +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to show other people your bisection process, you can get a +log using for example: + +------------- +$ git bisect log > bisect_log.txt +------------- + +And it is possible to replay it using: + +------------- +$ git bisect replay bisect_log.txt +------------- + + +"git bisect" details +-------------------- + +Bisection algorithm +~~~~~~~~~~~~~~~~~~~ + +As the Git commits form a directed acyclic graph (DAG), finding the +best bisection commit to test at each step is not so simple. Anyway +Linus found and implemented a "truly stupid" algorithm, later improved +by Junio Hamano, that works quite well. + +So the algorithm used by "git bisect" to find the best bisection +commit when there are no skipped commits is the following: + +1) keep only the commits that: + +a) are ancestor of the "bad" commit (including the "bad" commit itself), +b) are not ancestor of a "good" commit (excluding the "good" commits). + +This means that we get rid of the uninteresting commits in the DAG. + +For example if we start with a graph like this: + +------------- +G-Y-G-W-W-W-X-X-X-X + \ / + W-W-B + / +Y---G-W---W + \ / \ +Y-Y X-X-X-X + +-> time goes this way -> +------------- + +where B is the "bad" commit, "G" are "good" commits and W, X, and Y +are other commits, we will get the following graph after this first +step: + +------------- +W-W-W + \ + W-W-B + / +W---W +------------- + +So only the W and B commits will be kept. Because commits X and Y will +have been removed by rules a) and b) respectively, and because commits +G are removed by rule b) too. + +Note for git users, that it is equivalent as keeping only the commit +given by: + +------------- +git rev-list BAD --not GOOD1 GOOD2... +------------- + +Also note that we don't require the commits that are kept to be +descendants of a "good" commit. So in the following example, commits W +and Z will be kept: + +------------- +G-W-W-W-B + / +Z-Z +------------- + +2) starting from the "good" ends of the graph, associate to each +commit the number of ancestors it has plus one + +For example with the following graph where H is the "bad" commit and A +and D are some parents of some "good" commits: + +------------- +A-B-C + \ + F-G-H + / +D---E +------------- + +this will give: + +------------- +1 2 3 +A-B-C + \6 7 8 + F-G-H +1 2/ +D---E +------------- + +3) associate to each commit: min(X, N - X) + +where X is the value associated to the commit in step 2) and N is the +total number of commits in the graph. + +In the above example we have N = 8, so this will give: + +------------- +1 2 3 +A-B-C + \2 1 0 + F-G-H +1 2/ +D---E +------------- + +4) the best bisection point is the commit with the highest associated +number + +So in the above example the best bisection point is commit C. + +5) note that some shortcuts are implemented to speed up the algorithm + +As we know N from the beginning, we know that min(X, N - X) can't be +greater than N/2. So during steps 2) and 3), if we would associate N/2 +to a commit, then we know this is the best bisection point. So in this +case we can just stop processing any other commit and return the +current commit. + +Bisection algorithm debugging +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For any commit graph, you can see the number associated with each +commit using "git rev-list --bisect-all". + +For example, for the above graph, a command like: + +------------- +$ git rev-list --bisect-all BAD --not GOOD1 GOOD2 +------------- + +would output something like: + +------------- +e15b73ad3db9b48d7d1ade32f8cd23a751fe0ace (dist=3) +15722f2fa328eaba97022898a305ffc8172db6b1 (dist=2) +78e86cf3e850bd755bb71831f42e200626fbd1e0 (dist=2) +a1939d9a142de972094af4dde9a544e577ddef0e (dist=2) +070eab2303024706f2924822bfec8b9847e4ac1b (dist=1) +a3864d4f32a3bf5ed177ddef598490a08760b70d (dist=1) +a41baa717dd74f1180abf55e9341bc7a0bb9d556 (dist=1) +9e622a6dad403b71c40979743bb9d5be17b16bd6 (dist=0) +------------- + +Bisection algorithm discussed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First let's define "best bisection point". We will say that a commit X +is a best bisection point or a best bisection commit if knowing its +state ("good" or "bad") gives as much information as possible whether +the state of the commit happens to be "good" or "bad". + +This means that the best bisection commits are the commits where the +following function is maximum: + +------------- +f(X) = min(information_if_good(X), information_if_bad(X)) +------------- + +where information_if_good(X) is the information we get if X is good +and information_if_bad(X) is the information we get if X is bad. + +Now we will suppose that there is only one "first bad commit". This +means that all its descendants are "bad" and all the other commits are +"good". And we will suppose that all commits have an equal probability +of being good or bad, or of being the first bad commit, so knowing the +state of c commits gives always the same amount of information +wherever these c commits are on the graph and whatever c is. (So we +suppose that these commits being for example on a branch or near a +good or a bad commit does not give more or less information). + +Let's also suppose that we have a cleaned up graph like one after step +1) in the bisection algorithm above. This means that we can measure +the information we get in terms of number of commit we can remove from +the graph.. + +And let's take a commit X in the graph. + +If X is found to be "good", then we know that its ancestors are all +"good", so we want to say that: + +------------- +information_if_good(X) = number_of_ancestors(X) (TRUE) +------------- + +And this is true because at step 1) b) we remove the ancestors of the +"good" commits. + +If X is found to be "bad", then we know that its descendants are all +"bad", so we want to say that: + +------------- +information_if_bad(X) = number_of_descendants(X) (WRONG) +------------- + +But this is wrong because at step 1) a) we keep only the ancestors of +the bad commit. So we get more information when a commit is marked as +"bad", because we also know that the ancestors of the previous "bad" +commit that are not ancestors of the new "bad" commit are not the +first bad commit. We don't know if they are good or bad, but we know +that they are not the first bad commit because they are not ancestor +of the new "bad" commit. + +So when a commit is marked as "bad" we know we can remove all the +commits in the graph except those that are ancestors of the new "bad" +commit. This means that: + +------------- +information_if_bad(X) = N - number_of_ancestors(X) (TRUE) +------------- + +where N is the number of commits in the (cleaned up) graph. + +So in the end this means that to find the best bisection commits we +should maximize the function: + +------------- +f(X) = min(number_of_ancestors(X), N - number_of_ancestors(X)) +------------- + +And this is nice because at step 2) we compute number_of_ancestors(X) +and so at step 3) we compute f(X). + +Let's take the following graph as an example: + +------------- + G-H-I-J + / \ +A-B-C-D-E-F O + \ / + K-L-M-N +------------- + +If we compute the following non optimal function on it: + +------------- +g(X) = min(number_of_ancestors(X), number_of_descendants(X)) +------------- + +we get: + +------------- + 4 3 2 1 + G-H-I-J +1 2 3 4 5 6/ \0 +A-B-C-D-E-F O + \ / + K-L-M-N + 4 3 2 1 +------------- + +but with the algorithm used by git bisect we get: + +------------- + 7 7 6 5 + G-H-I-J +1 2 3 4 5 6/ \0 +A-B-C-D-E-F O + \ / + K-L-M-N + 7 7 6 5 +------------- + +So we chose G, H, K or L as the best bisection point, which is better +than F. Because if for example L is bad, then we will know not only +that L, M and N are bad but also that G, H, I and J are not the first +bad commit (since we suppose that there is only one first bad commit +and it must be an ancestor of L). + +So the current algorithm seems to be the best possible given what we +initially supposed. + +Skip algorithm +~~~~~~~~~~~~~~ + +When some commits have been skipped (using "git bisect skip"), then +the bisection algorithm is the same for step 1) to 3). But then we use +roughly the following steps: + +6) sort the commit by decreasing associated value + +7) if the first commit has not been skipped, we can return it and stop +here + +8) otherwise filter out all the skipped commits in the sorted list + +9) use a pseudo random number generator (PRNG) to generate a random +number between 0 and 1 + +10) multiply this random number with its square root to bias it toward +0 + +11) multiply the result by the number of commits in the filtered list +to get an index into this list + +12) return the commit at the computed index + +Skip algorithm discussed +~~~~~~~~~~~~~~~~~~~~~~~~ + +After step 7) (in the skip algorithm), we could check if the second +commit has been skipped and return it if it is not the case. And in +fact that was the algorithm we used from when "git bisect skip" was +developed in git version 1.5.4 (released on February 1st 2008) until +git version 1.6.4 (released July 29th 2009). + +But Ingo Molnar and H. Peter Anvin (another well known linux kernel +developer) both complained that sometimes the best bisection points +all happened to be in an area where all the commits are +untestable. And in this case the user was asked to test many +untestable commits, which could be very inefficient. + +Indeed untestable commits are often untestable because a breakage was +introduced at one time, and that breakage was fixed only after many +other commits were introduced. + +This breakage is of course most of the time unrelated to the breakage +we are trying to locate in the commit graph. But it prevents us to +know if the interesting "bad behavior" is present or not. + +So it is a fact that commits near an untestable commit have a high +probability of being untestable themselves. And the best bisection +commits are often found together too (due to the bisection algorithm). + +This is why it is a bad idea to just chose the next best unskipped +bisection commit when the first one has been skipped. + +We found that most commits on the graph may give quite a lot of +information when they are tested. And the commits that will not on +average give a lot of information are the one near the good and bad +commits. + +So using a PRNG with a bias to favor commits away from the good and +bad commits looked like a good choice. + +One obvious improvement to this algorithm would be to look for a +commit that has an associated value near the one of the best bisection +commit, and that is on another branch, before using the PRNG. Because +if such a commit exists, then it is not very likely to be untestable +too, so it will probably give more information than a nearly randomly +chosen one. + +Checking merge bases +~~~~~~~~~~~~~~~~~~~~ + +There is another tweak in the bisection algorithm that has not been +described in the "bisection algorithm" above. + +We supposed in the previous examples that the "good" commits were +ancestors of the "bad" commit. But this is not a requirement of "git +bisect". + +Of course the "bad" commit cannot be an ancestor of a "good" commit, +because the ancestors of the good commits are supposed to be +"good". And all the "good" commits must be related to the bad commit. +They cannot be on a branch that has no link with the branch of the +"bad" commit. But it is possible for a good commit to be related to a +bad commit and yet not be neither one of its ancestor nor one of its +descendants. + +For example, there can be a "main" branch, and a "dev" branch that was +forked of the main branch at a commit named "D" like this: + +------------- +A-B-C-D-E-F-G <--main + \ + H-I-J <--dev +------------- + +The commit "D" is called a "merge base" for branch "main" and "dev" +because it's the best common ancestor for these branches for a merge. + +Now let's suppose that commit J is bad and commit G is good and that +we apply the bisection algorithm like it has been previously +described. + +As described in step 1) b) of the bisection algorithm, we remove all +the ancestors of the good commits because they are supposed to be good +too. + +So we would be left with only: + +------------- +H-I-J +------------- + +But what happens if the first bad commit is "B" and if it has been +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 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 +released. + +In fact development teams often maintain both a development branch and +a maintenance branch, and it would be quite easy for them if "git +bisect" just worked when they want to bisect a regression on the +development branch that is not on the maintenance branch. They should +be able to start bisecting using: + +------------- +$ git bisect start dev main +------------- + +To enable that additional nice feature, when a bisection is started +and when some good commits are not ancestors of the bad commit, we +first compute the merge bases between the bad and the good commits and +we chose these merge bases as the first commits that will be checked +out and tested. + +If it happens that one merge base is bad, then the bisection process +is stopped with a message like: + +------------- +The merge base BBBBBB is bad. +This means the bug has been fixed between BBBBBB and [GGGGGG,...]. +------------- + +where BBBBBB is the sha1 hash of the bad merge base and [GGGGGG,...] +is a comma separated list of the sha1 of the good commits. + +If some of the merge bases are skipped, then the bisection process +continues, but the following message is printed for each skipped merge +base: + +------------- +Warning: the merge base between BBBBBB and [GGGGGG,...] must be skipped. +So we cannot be sure the first bad commit is between MMMMMM and BBBBBB. +We continue anyway. +------------- + +where BBBBBB is the sha1 hash of the bad commit, MMMMMM is the sha1 +hash of the merge base that is skipped and [GGGGGG,...] is a comma +separated list of the sha1 of the good commits. + +So if there is no bad merge base, the bisection process continues as +usual after this step. + +Best bisecting practices +------------------------ + +Using test suites and git bisect together +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you both have a test suite and use git bisect, then it becomes less +important to check that all tests pass after each commit. Though of +course it is probably a good idea to have some checks to avoid +breaking too many things because it could make bisecting other bugs +more difficult. + +You can focus your efforts to check at a few points (for example rc +and beta releases) that all the T test cases pass for all the N +configurations. And when some tests don't pass you can use "git +bisect" (or better "git bisect run"). So you should perform roughly: + +------------- +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 +you would test everything after each commit. + +This means that test suites are good to prevent some bugs from being +committed and they are also quite good to tell you that you have some +bugs. But they are not so good to tell you where some bugs have been +introduced. To tell you that efficiently, git bisect is needed. + +The other nice thing with test suites, is that when you have one, you +already know how to test for bad behavior. So you can use this +knowledge to create a new test case for "git bisect" when it appears +that there is a regression. So it will be easier to bisect the bug and +fix it. And then you can add the test case you just created to your +test suite. + +So if you know how to create test cases and how to bisect, you will be +subject to a virtuous circle: + +more tests => easier to create tests => easier to bisect => more tests + +So test suites and "git bisect" are complementary tools that are very +powerful and efficient when used together. + +Bisecting build failures +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can very easily automatically bisect broken builds using something +like: + +------------- +$ git bisect start BAD GOOD +$ git bisect run make +------------- + +Passing sh -c "some commands" to "git bisect run" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For example: + +------------- +$ git bisect run sh -c "make || exit 125; ./my_app | grep 'good output'" +------------- + +On the other hand if you do this often, then it can be worth having +scripts to avoid too much typing. + +Finding performance regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here is an example script that comes slightly modified from a real +world script used by Junio Hamano <<4>>. + +This script can be passed to "git bisect run" to find the commit that +introduced a performance regression: + +------------- +#!/bin/sh + +# Build errors are not what I am interested in. +make my_app || exit 255 + +# We are checking if it stops in a reasonable amount of time, so +# let it run in the background... + +./my_app >log 2>&1 & + +# ... and grab its process ID. +pid=$! + +# ... and then wait for sufficiently long. +sleep $NORMAL_TIME + +# ... and then see if the process is still there. +if kill -0 $pid +then + # It is still running -- that is bad. + kill $pid; sleep 1; kill $pid; + exit 1 +else + # It has already finished (the $pid process was no more), + # and we are happy. + exit 0 +fi +------------- + +Following general best practices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is obviously a good idea not to have commits with changes that +knowingly break things, even if some other commits later fix the +breakage. + +It is also a good idea when using any VCS to have only one small +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 committer. + +Another good idea is to have good commit messages. They can be very +helpful to understand why some changes were made. + +These general best practices are very helpful if you bisect often. + +Avoiding bug prone merges +~~~~~~~~~~~~~~~~~~~~~~~~~ + +First merges by themselves can introduce some regressions even when +the merge needs no source code conflict resolution. This is because a +semantic change can happen in one branch while the other branch is not +aware of it. + +For example one branch can change the semantic of a function while the +other branch add more calls to the same function. + +This is made much worse if many files have to be fixed to resolve +conflicts. That's why such merges are called "evil merges". They can +make regressions very difficult to track down. It can even be +misleading to know the first bad commit if it happens to be such a +merge, because people might think that the bug comes from bad conflict +resolution when it comes from a semantic change in one branch. + +Anyway "git rebase" can be used to linearize history. This can be used +either to avoid merging in the first place. Or it can be used to +bisect on a linear history instead of the non linear one, as this +should give more information in case of a semantic change in one +branch. + +Merges can be also made simpler by using smaller branches or by using +many topic branches instead of only long version related branches. + +And testing can be done more often in special integration branches +like linux-next for the linux kernel. + +Adapting your work-flow +~~~~~~~~~~~~~~~~~~~~~~~ + +A special work-flow to process regressions can give great results. + +Here is an example of a work-flow used by Andreas Ericsson: + +* write, in the test suite, a test script that exposes the regression +* use "git bisect run" to find the commit that introduced it +* fix the bug that is often made obvious by the previous step +* commit both the fix and the test script (and if needed more tests) + +And here is what Andreas said about this work-flow <<5>>: + +_____________ +To give some hard figures, we used to have an average report-to-fix +cycle of 142.6 hours (according to our somewhat weird bug-tracker +which just measures wall-clock time). Since we moved to git, we've +lowered that to 16.2 hours. Primarily because we can stay on top of +the bug fixing now, and because everyone's jockeying to get to fix +bugs (we're quite proud of how lazy we are to let git find the bugs +for us). Each new release results in ~40% fewer bugs (almost certainly +due to how we now feel about writing tests). +_____________ + +Clearly this work-flow uses the virtuous circle between test suites +and "git bisect". In fact it makes it the standard procedure to deal +with regression. + +In other messages Andreas says that they also use the "best practices" +described above: small logical commits, topic branches, no evil +merge,... These practices all improve the bisectability of the commit +graph, by making it easier and more useful to bisect. + +So a good work-flow should be designed around the above points. That +is making bisecting easier, more useful and standard. + +Involving QA people and if possible end users +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One nice about "git bisect" is that it is not only a developer +tool. It can effectively be used by QA people or even end users (if +they have access to the source code or if they can get access to all +the builds). + +There was a discussion at one point on the linux kernel mailing list +of whether it was ok to always ask end user to bisect, and very good +points were made to support the point of view that it is ok. + +For example David Miller wrote <<6>>: + +_____________ +What people don't get is that this is a situation where the "end node +principle" applies. When you have limited resources (here: developers) +you don't push the bulk of the burden upon them. Instead you push +things out to the resource you have a lot of, the end nodes (here: +users), so that the situation actually scales. +_____________ + +This means that it is often "cheaper" if QA people or end users can do +it. + +What is interesting too is that end users that are reporting bugs (or +QA people that reproduced a bug) have access to the environment where +the bug happens. So they can often more easily reproduce a +regression. And if they can bisect, then more information will be +extracted from the environment where the bug happens, which means that +it will be easier to understand and then fix the bug. + +For open source projects it can be a good way to get more useful +contributions from end users, and to introduce them to QA and +development activities. + +Using complex scripts +~~~~~~~~~~~~~~~~~~~~~ + +In some cases like for kernel development it can be worth developing +complex scripts to be able to fully automate bisecting. + +Here is what Ingo Molnar says about that <<7>>: + +_____________ +i have a fully automated bootup-hang bisection script. It is based on +"git-bisect run". I run the script, it builds and boots kernels fully +automatically, and when the bootup fails (the script notices that via +the serial log, which it continuously watches - or via a timeout, if +the system does not come up within 10 minutes it's a "bad" kernel), +the script raises my attention via a beep and i power cycle the test +box. (yeah, i should make use of a managed power outlet to 100% +automate it) +_____________ + +Combining test suites, git bisect and other systems together +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We have seen that test suites an git bisect are very powerful when +used together. It can be even more powerful if you can combine them +with other systems. + +For example some test suites could be run automatically at night with +some unusual (or even random) configurations. And if a regression is +found by a test suite, then "git bisect" can be automatically +launched, and its result can be emailed to the author of the first bad +commit found by "git bisect", and perhaps other people too. And a new +entry in the bug tracking system could be automatically created too. + + +The future of bisecting +----------------------- + +"git replace" +~~~~~~~~~~~~~ + +We saw earlier that "git bisect skip" is now using a PRNG to try to +avoid areas in the commit graph where commits are untestable. The +problem is that sometimes the first bad commit will be in an +untestable area. + +To simplify the discussion we will suppose that the untestable area is +a simple string of commits and that it was created by a breakage +introduced by one commit (let's call it BBC for bisect breaking +commit) and later fixed by another one (let's call it BFC for bisect +fixing commit). + +For example: + +------------- +...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z-... +------------- + +where we know that Y is good and BFC is bad, and where BBC and X1 to +X6 are untestable. + +In this case if you are bisecting manually, what you can do is create +a special branch that starts just before the BBC. The first commit in +this branch should be the BBC with the BFC squashed into it. And the +other commits in the branch should be the commits between BBC and BFC +rebased on the first commit of the branch and then the commit after +BFC also rebased on. + +For example: + +------------- + (BBC+BFC)-X1'-X2'-X3'-X4'-X5'-X6'-Z' + / +...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z-... +------------- + +where commits quoted with ' have been rebased. + +You can easily create such a branch with Git using interactive rebase. + +For example using: + +------------- +$ git rebase -i Y Z +------------- + +and then moving BFC after BBC and squashing it. + +After that you can start bisecting as usual in the new branch and you +should eventually find the first bad commit. + +For example: + +------------- +$ git bisect start Z' Y +------------- + +If you are using "git bisect run", you can use the same manual fix up +as above, and then start another "git bisect run" in the special +branch. Or as the "git bisect" man page says, the script passed to +"git bisect run" can apply a patch before it compiles and test the +software <<8>>. The patch should turn a current untestable commits +into a testable one. So the testing will result in "good" or "bad" and +"git bisect" will be able to find the first bad commit. And the script +should not forget to remove the patch once the testing is done before +exiting from the script. + +(Note that instead of a patch you can use "git cherry-pick BFC" to +apply the fix, and in this case you should use "git reset --hard +HEAD^" to revert the cherry-pick after testing and before returning +from the script.) + +But the above ways to work around untestable areas are a little bit +clunky. Using special branches is nice because these branches can be +shared by developers like usual branches, but the risk is that people +will get many such branches. And it disrupts the normal "git bisect" +work-flow. So, if you want to use "git bisect run" completely +automatically, you have to add special code in your script to restart +bisection in the special branches. + +Anyway one can notice in the above special branch example that the Z' +and Z commits should point to the same source code state (the same +"tree" in git parlance). That's because Z' result from applying the +same changes as Z just in a slightly different order. + +So if we could just "replace" Z by Z' when we bisect, then we would +not need to add anything to a script. It would just work for anyone in +the project sharing the special branches and the replacements. + +With the example above that would give: + +------------- + (BBC+BFC)-X1'-X2'-X3'-X4'-X5'-X6'-Z'-... + / +...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z +------------- + +That's why the "git replace" command was created. Technically it +stores replacements "refs" in the "refs/replace/" hierarchy. These +"refs" are like branches (that are stored in "refs/heads/") or tags +(that are stored in "refs/tags"), and that means that they can +automatically be shared like branches or tags among developers. + +"git replace" is a very powerful mechanism. It can be used to fix +commits in already released history, for example to change the commit +message or the author. And it can also be used instead of git "grafts" +to link a repository with another old repository. + +In fact it's this last feature that "sold" it to the git community, so +it is now in the "master" branch of git's git repository and it should +be released in git 1.6.5 in October or November 2009. + +One problem with "git replace" is that currently it stores all the +replacements refs in "refs/replace/", but it would be perhaps better +if the replacement refs that are useful only for bisecting would be in +"refs/replace/bisect/". This way the replacement refs could be used +only for bisecting, while other refs directly in "refs/replace/" would +be used nearly all the time. + +Bisecting sporadic bugs +~~~~~~~~~~~~~~~~~~~~~~~ + +Another possible improvement to "git bisect" would be to optionally +add some redundancy to the tests performed so that it would be more +reliable when tracking sporadic bugs. + +This has been requested by some kernel developers because some bugs +called sporadic bugs do not appear in all the kernel builds because +they are very dependent on the compiler output. + +The idea is that every 3 test for example, "git bisect" could ask the +user to test a commit that has already been found to be "good" or +"bad" (because one of its descendants or one of its ancestors has been +found to be "good" or "bad" respectively). If it happens that a commit +has been previously incorrectly classified then the bisection can be +aborted early, hopefully before too many mistakes have been made. Then +the user will have to look at what happened and then restart the +bisection using a fixed bisect log. + +There is already a project called BBChop created by Ealdwulf Wuffinga +on Github that does something like that using Bayesian Search Theory +<<9>>: + +_____________ +BBChop is like 'git bisect' (or equivalent), but works when your bug +is intermittent. That is, it works in the presence of false negatives +(when a version happens to work this time even though it contains the +bug). It assumes that there are no false positives (in principle, the +same approach would work, but adding it may be non-trivial). +_____________ + +But BBChop is independent of any VCS and it would be easier for Git +users to have something integrated in Git. + +Conclusion +---------- + +We have seen that regressions are an important problem, and that "git +bisect" has nice features that complement very well practices and +other tools, especially test suites, that are generally used to fight +regressions. But it might be needed to change some work-flows and +(bad) habits to get the most out of it. + +Some improvements to the algorithms inside "git bisect" are possible +and some new features could help in some cases, but overall "git +bisect" works already very well, is used a lot, and is already very +useful. To back up that last claim, let's give the final word to Ingo +Molnar when he was asked by the author how much time does he think +"git bisect" saves him when he uses it: + +_____________ +a _lot_. + +About ten years ago did i do my first 'bisection' of a Linux patch +queue. That was prior the Git (and even prior the BitKeeper) days. I +literally days spent sorting out patches, creating what in essence +were standalone commits that i guessed to be related to that bug. + +It was a tool of absolute last resort. I'd rather spend days looking +at printk output than do a manual 'patch bisection'. + +With Git bisect it's a breeze: in the best case i can get a ~15 step +kernel bisection done in 20-30 minutes, in an automated way. Even with +manual help or when bisecting multiple, overlapping bugs, it's rarely +more than an hour. + +In fact it's invaluable because there are bugs i would never even +_try_ to debug if it wasn't for git bisect. In the past there were bug +patterns that were immediately hopeless for me to debug - at best i +could send the crash/bug signature to lkml and hope that someone else +can think of something. + +And even if a bisection fails today it tells us something valuable +about the bug: that it's non-deterministic - timing or kernel image +layout dependent. + +So git bisect is unconditional goodness - and feel free to quote that +;-) +_____________ + +Acknowledgements +---------------- + +Many thanks to Junio Hamano for his help in reviewing this paper, for +reviewing the patches I sent to the git mailing list, for discussing +some ideas and helping me improve them, for improving "git bisect" a +lot and for his awesome work in maintaining and developing Git. + +Many thanks to Ingo Molnar for giving me very useful information that +appears in this paper, for commenting on this paper, for his +suggestions to improve "git bisect" and for evangelizing "git bisect" +on the linux kernel mailing lists. + +Many thanks to Linus Torvalds for inventing, developing and +evangelizing "git bisect", Git and Linux. + +Many thanks to the many other great people who helped one way or +another when I worked on git, especially to Andreas Ericsson, Johannes +Schindelin, H. Peter Anvin, Daniel Barkalow, Bill Lear, John Hawley, +Shawn O. Pierce, Jeff King, Sam Vilain, Jon Seymour. + +Many thanks to the Linux-Kongress program committee for choosing the +author to given a talk and for publishing this paper. + +References +---------- + +- [[[1]]] http://www.nist.gov/public_affairs/releases/n02-10.htm['Software Errors Cost U.S. Economy $59.5 Billion Annually'. Nist News Release.] +- [[[2]]] http://java.sun.com/docs/codeconv/html/CodeConventions.doc.html#16712['Code Conventions for the Java Programming Language'. Sun Microsystems.] +- [[[3]]] http://en.wikipedia.org/wiki/Software_maintenance['Software maintenance'. Wikipedia.] +- [[[4]]] http://article.gmane.org/gmane.comp.version-control.git/45195/[Junio C Hamano. 'Automated bisect success story'. Gmane.] +- [[[5]]] http://lwn.net/Articles/317154/[Christian Couder. 'Fully automated bisecting with "git bisect run"'. LWN.net.] +- [[[6]]] http://lwn.net/Articles/277872/[Jonathan Corbet. 'Bisection divides users and developers'. LWN.net.] +- [[[7]]] http://article.gmane.org/gmane.linux.scsi/36652/[Ingo Molnar. 'Re: BUG 2.6.23-rc3 can't see sd partitions on Alpha'. Gmane.] +- [[[8]]] http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html[Junio C Hamano and the git-list. 'git-bisect(1) Manual Page'. Linux Kernel Archives.] +- [[[9]]] http://github.com/Ealdwulf/bbchop[Ealdwulf. 'bbchop'. GitHub.] diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 3ca0d330ad..e4f46bc18d 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -3,11 +3,12 @@ git-bisect(1) NAME ---- -git-bisect - Find the change that introduced a bug by binary search +git-bisect - Find by binary search the change that introduced a bug SYNOPSIS -------- +[verse] 'git bisect' <subcommand> <options> DESCRIPTION @@ -16,17 +17,17 @@ 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>...] - git bisect reset [<branch>] + git bisect skip [(<rev>|<range>)...] + git bisect reset [<commit>] git bisect visualize git bisect replay <logfile> git bisect log git bisect run <cmd>... -This command uses 'git-rev-list --bisect' option to help drive the +This command uses 'git rev-list --bisect' to help drive the binary search process to find which change introduced a bug, given an old "good" commit object name and a later "bad" commit object name. @@ -39,7 +40,8 @@ help" or "git bisect -h" to get a long usage description. Basic bisect commands: start, bad, good ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The way you use it is: +Using the Linux kernel tree as an example, basic use of the bisect +command is as follows: ------------------------------------------------ $ git bisect start @@ -48,61 +50,74 @@ $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version # tested that was good ------------------------------------------------ -When you give at least one bad and one good versions, it will bisect -the revision tree and say something like: +When you have specified at least one bad and one good version, the +command bisects the revision tree and outputs something similar to +the following: ------------------------------------------------ Bisecting: 675 revisions left to test after this ------------------------------------------------ -and check out the state in the middle. Now, compile that kernel, and -boot it. Now, let's say that this booted kernel works fine, then just -do +The state in the middle of the set of revisions is then checked out. +You would now compile that kernel and boot it. If the booted kernel +works correctly, you would then issue the following command: ------------------------------------------------ $ git bisect good # this one is good ------------------------------------------------ -which will now say +The output of this command would be something similar to the following: ------------------------------------------------ Bisecting: 337 revisions left to test after this ------------------------------------------------ -and you continue along, compiling that one, testing it, and depending -on whether it is good or bad, you say "git bisect good" or "git bisect -bad", and ask for the next bisection. +You keep repeating this process, compiling the tree, testing it, and +depending on whether it is good or bad issuing the command "git bisect good" +or "git bisect bad" to ask for the next bisection. -Until you have no more left, and you'll have been left with the first -bad kernel rev in "refs/bisect/bad". +Eventually there will be no more revisions left to bisect, and you +will have been left with the first bad kernel revision in "refs/bisect/bad". Bisect reset ~~~~~~~~~~~~ -Oh, and then after you want to reset to the original head, do a +After a bisect session, to clean up the bisection state and return to +the original HEAD, issue the following command: ------------------------------------------------ $ git bisect reset ------------------------------------------------ -to get back to the original branch, instead of being on the bisection -commit ("git bisect start" will do that for you too, actually: it will -reset the bisection state). +By default, this will return your tree to the commit that was checked +out before `git bisect start`. (A new `git bisect start` will also do +that, as it cleans up the old bisection state.) + +With an optional argument, you can return to a different commit +instead: + +------------------------------------------------ +$ git bisect reset <commit> +------------------------------------------------ + +For example, `git bisect reset HEAD` will leave you on the current +bisection commit and avoid switching commits at all, while `git bisect +reset bisect/bad` will check out the first bad revision. Bisect visualize ~~~~~~~~~~~~~~~~ -During the bisection process, you can say +To see the currently remaining suspects in 'gitk', issue the following +command during the bisection process: ------------ $ git bisect visualize ------------ -to see the currently remaining suspects in `gitk`. `visualize` is a bit -too long to type and `view` is provided as a synonym. +`view` may also be used as a synonym for `visualize`. -If `DISPLAY` environment variable is not set, `git log` is used -instead. You can even give command line options such as `-p` and +If the 'DISPLAY' environment variable is not set, 'git log' is used +instead. You can also give command line options such as `-p` and `--stat`. ------------ @@ -112,73 +127,93 @@ $ git bisect view --stat Bisect log and bisect replay ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The good/bad input is logged, and +After having marked revisions as good or bad, issue the following +command to show what has been done so far: ------------ $ git bisect log ------------ -shows what you have done so far. You can truncate its output somewhere -and save it in a file, and run +If you discover that you made a mistake in specifying the status of a +revision, you can save the output of this command to a file, edit it to +remove the incorrect entries, and then issue the following commands to +return to a corrected state: ------------ +$ git bisect reset $ git bisect replay that-file ------------ -if you find later you made a mistake telling good/bad about a -revision. - -Avoiding to test a commit +Avoiding testing a commit ~~~~~~~~~~~~~~~~~~~~~~~~~ -If in a middle of bisect session, you know what the bisect suggested -to try next is not a good one to test (e.g. the change the commit +If, in the middle of a bisect session, you know that the next suggested +revision is not a good one to test (e.g. the change the commit introduces is known not to work in your environment and you know it does not have anything to do with the bug you are chasing), you may -want to find a near-by commit and try that instead. +want to find a nearby commit and try that instead. -It goes something like this: +For example: ------------ -$ git bisect good/bad # previous round was good/bad. +$ git bisect good/bad # previous round was good or bad. Bisecting: 337 revisions left to test after this $ git bisect visualize # oops, that is uninteresting. -$ git reset --hard HEAD~3 # try 3 revs before what +$ git reset --hard HEAD~3 # try 3 revisions before what # was suggested ------------ -Then compile and test the one you chose to try. After that, tell -bisect what the result was as usual. +Then compile and test the chosen revision, and afterwards mark +the revision as good or bad in the usual manner. Bisect skip ~~~~~~~~~~~~ -Instead of choosing by yourself a nearby commit, you may just want git -to do it for you using: +Instead of choosing by yourself a nearby commit, you can ask git +to do it for you by issuing the command: ------------ $ git bisect skip # Current version cannot be tested ------------ -But computing the commit to test may be slower afterwards and git may -eventually not be able to tell the first bad among a bad and one or -more "skip"ped commits. +But git may eventually be unable to tell the first bad commit among +a bad commit and one or more skipped commits. + +You can even skip a range of commits, instead of just one commit, +using the "'<commit1>'..'<commit2>'" notation. For example: + +------------ +$ git bisect skip v2.5..v2.6 +------------ + +This tells the bisect process that no commit after `v2.5`, up to and +including `v2.6`, should be tested. + +Note that if you also want to skip the first commit of the range you +would issue the command: + +------------ +$ git bisect skip v2.5 v2.5..v2.6 +------------ + +This tells the bisect process that the commits between `v2.5` included +and `v2.6` included should be skipped. + Cutting down bisection by giving more parameters to bisect start ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can further cut down the number of trials if you know what part of -the tree is involved in the problem you are tracking down, by giving -paths parameters when you say `bisect start`, like this: +You can further cut down the number of trials, if you know what part of +the tree is involved in the problem you are tracking down, by specifying +path parameters when issuing the `bisect start` command: ------------ $ git bisect start -- arch/i386 include/asm-i386 ------------ -If you know beforehand more than one good commits, you can narrow the -bisect space down without doing the whole tree checkout every time you -give good commits. You give the bad revision immediately after `start` -and then you give all the good revisions you have: +If you know beforehand more than one good commit, you can narrow the +bisect space down by specifying all of the good commits immediately after +the bad commit when issuing the `bisect start` command: ------------ $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- @@ -190,38 +225,56 @@ Bisect run ~~~~~~~~~~ If you have a script that can tell if the current source code is good -or bad, you can automatically bisect using: +or bad, you can bisect by issuing the command: ------------ -$ git bisect run my_script +$ git bisect run my_script arguments ------------ -Note that the "run" script (`my_script` in the above example) should -exit with code 0 in case the current source code is good. Exit with a +Note that the script (`my_script` in the above example) should +exit with code 0 if the current source code is good, and exit with a code between 1 and 127 (inclusive), except 125, if the current source code is bad. -Any other exit code will abort the automatic bisect process. (A -program that does "exit(-1)" leaves $? = 255, see exit(3) manual page, -the value is chopped with "& 0377".) +Any other exit code will abort the bisect process. It should be noted +that a program that terminates via "exit(-1)" leaves $? = 255, (see the +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 "run" script exits with this code, the current -revision will be skipped, see `git bisect skip` above. - -You may often find that during bisect you want to have near-constant -tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or -"revision that does not have this commit needs this patch applied to -work around other problem this bisection is not interested in") -applied to the revision being tested. - -To cope with such a situation, after the inner git-bisect finds the -next revision to test, with the "run" script, you can apply that tweak -before compiling, run the real test, and after the test decides if the -revision (possibly with the needed tweaks) passed the test, rewind the -tree to the pristine state. Finally the "run" script can exit with -the status of the real test to let "git bisect run" command loop to -know the outcome. +cannot be tested. If the script exits with this code, the current +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 +header file, or "revision that does not have this commit needs this +patch applied to work around another problem this bisection is not +interested in") applied to the revision being tested. + +To cope with such a situation, after the inner 'git bisect' finds the +next revision to test, the script can apply the patch +before compiling, run the real test, and afterwards decide if the +revision (possibly with the needed patch) passed the test and then +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 -------- @@ -233,52 +286,99 @@ $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good $ git bisect run make # "make" builds the app ------------ -* Automatically bisect a broken test suite: +* Automatically bisect a test failure between origin and HEAD: ++ +------------ +$ 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 case: + ------------ $ cat ~/test.sh #!/bin/sh -make || exit 125 # this "skip"s 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. -+ -It's safer to use a custom script outside the repo to prevent -interactions between the bisect, make and test processes and the -script. +fails, we skip the current commit. +"check_test_case.sh" should "exit 0" if the test case passes, +and "exit 1" otherwise. + -And "make test" should "exit 0", if the test suite passes, and -"exit 1" (for example) 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 "skip"s broken builds -~/check_test_case.sh # does the test case passes ? + +# 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 +------------ ++ +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 case: ++ +------------ $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 -$ git bisect run ~/test.sh +$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" ------------ + -Here "check_test_case.sh" should "exit 0", if the test case passes, -and "exit 1" (for example) otherwise. +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' + +------------ + -It's safer if both "test.sh" and "check_test_case.sh" scripts are -outside the repo to prevent interactions between the bisect, make and -test processes and the scripts. +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'. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -Documentation -------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +link:git-bisect-lk2009.html[Fighting regressions with git bisect], +linkgit:git-blame[1]. GIT --- diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 8f4fb46685..7ee923629e 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,9 +8,9 @@ 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] [--since=<date>] - [<rev> | --contents <file>] [--] <file> +'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 ----------- @@ -18,10 +18,10 @@ DESCRIPTION Annotates each line in the given file with information from the revision which last modified the line. Optionally, start annotating from the given revision. -Also it can limit the range of lines annotated. +The command can also limit the range of lines annotated. -This report doesn't tell you anything about lines which have been deleted or -replaced; you need to use a tool such as linkgit:git-diff[1] or the "pickaxe" +The report does not tell you anything about lines which have been deleted or +replaced; you need to use a tool such as 'git diff' or the "pickaxe" interface briefly mentioned in the following paragraph. Apart from supporting file annotation, git also supports searching the @@ -48,26 +48,35 @@ include::blame-options.txt[] lines between files (see `-C`) and lines moved within a file (see `-M`). The first number listed is the score. This is the number of alphanumeric characters detected - to be moved between or within files. This must be above - a certain threshold for git-blame to consider those lines + as having been moved between or within files. This must be above + a certain threshold for 'git blame' to consider those lines of code to have been moved. -f:: --show-name:: - Show filename in the original commit. By default - filename is shown if there is any line that came from a - file with different name, due to rename detection. + Show the filename in the original commit. By default + the filename is shown if there is any line that came from a + file with a different name, due to rename detection. -n:: --show-number:: - Show line number in the original commit (Default: off). + Show the line number in the original commit (Default: off). -s:: - Suppress author name and timestamp from the output. + 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 parent's version and - child's to find where the lines came from. + 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 @@ -79,46 +88,59 @@ header at the minimum has the first line which has: - 40-byte SHA-1 of the commit the line is attributed to; - the line number of the line in the original file; - the line number of the line in the final file; -- on a line that starts a group of line from a different +- on a line that starts a group of lines from a different commit than the previous one, the number of lines in this group. On subsequent lines this field is absent. This header line is followed by the following information at least once for each commit: -- author name ("author"), email ("author-mail"), time +- the author name ("author"), email ("author-mail"), time ("author-time"), and timezone ("author-tz"); similarly for committer. -- filename in the commit the line is attributed to. +- the filename in the commit that the line is attributed to. - the first line of the commit log message ("summary"). 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 git, the extent -of annotation can be limited to both line ranges and revision +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 -ll. 40-60 for file `foo`, you can use `-L` option like these +lines 40-60 for file `foo`, you can use the `-L` option like so (they mean the same thing -- both ask for 21 lines starting at line 40): git blame -L 40,60 foo git blame -L 40,+21 foo -Also you can use regular expression to specify the line range. +Also you can use a regular expression to specify the line range: git blame -L '/^sub hello {/,/^}$/' foo -would limit the annotation to the body of `hello` subroutine. +which limits the annotation to the body of the `hello` subroutine. -When you are not interested in changes older than the version +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 @@ -129,7 +151,7 @@ commit v2.6.18 or the most recent commit that is more than 3 weeks old in the above example) are blamed for that range boundary commit. -A particularly useful way is to see if an added file have lines +A particularly useful way is to see if an added file has lines created by copy-and-paste from existing files. Sometimes this indicates that the developer was being sloppy and did not refactor the code properly. You can first find the commit that @@ -138,7 +160,7 @@ introduced the file with: git log --diff-filter=A --pretty=short -- foo and then annotate the change between the commit and its -parents, using `commit{caret}!` notation: +parents, using `commit^!` notation: git blame -C -C -f $commit^! -- foo @@ -162,36 +184,38 @@ annotated. + Line numbers count from 1. -. The first time that commit shows up in the stream, it has various +. The first time that a commit shows up in the stream, it has various other information about it printed out with a one-word tag at the - beginning of each line about that "extended commit info" (author, - email, committer, dates, summary etc). + beginning of each line describing the extra commit information (author, + email, committer, dates, summary, etc.). -. Unlike Porcelain format, the filename information is always +. Unlike the Porcelain format, the filename information is always given and terminates the entry: "filename" <whitespace-quoted-filename-goes-here> + -and thus it's really quite easy to parse for some line- and word-oriented +and thus it is really quite easy to parse for some line- and word-oriented parser (which should be quite natural for most scripting languages). + [NOTE] For people who do parsing: to make it more robust, just ignore any -lines in between the first and last one ("<sha1>" and "filename" lines) -where you don't recognize the tag-words (or care about that particular +lines between the first and last one ("<sha1>" and "filename" lines) +where you do not recognize the tag words (or care about that particular one) at the beginning of the "extended information" lines. That way, if there is ever added information (like the commit encoding or extended -commit commentary), a blame viewer won't ever care. +commit commentary), a blame viewer will not care. + + +MAPPING AUTHORS +--------------- + +include::mailmap.txt[] SEE ALSO -------- linkgit:git-annotate[1] -AUTHOR ------- -Written by Junio C Hamano <junkio@cox.net> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 0fd58083eb..47235bea04 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,41 +8,49 @@ git-branch - List, create, or delete branches SYNOPSIS -------- [verse] -'git-branch' [--color | --no-color] [-r | -a] [--merged | --no-merged] - [-v [--abbrev=<length> | --no-abbrev]] - [--contains <commit>] -'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>] -'git-branch' (-m | -M) [<oldbranch>] <newbranch> -'git-branch' (-d | -D) [-r] <branchname>... +'git branch' [--color[=<when>] | --no-color] [-r | -a] + [--list] [-v [--abbrev=<length> | --no-abbrev]] + [--column[=<options>] | --no-column] + [(--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>... +'git branch' --edit-description [<branchname>] DESCRIPTION ----------- -With no arguments given a list of existing branches -will be shown, the current branch will be highlighted with an asterisk. -Option `-r` causes the remote-tracking branches to be listed, -and option `-a` shows both. -With `--contains <commit>`, shows only the branches that -contains the named commit (in other words, the branches whose -tip commits are descendant of the named commit). -With `--merged`, only branches merged into HEAD will be listed, and -with `--no-merged` only branches not merged into HEAD will be listed. - -In its second form, a new branch named <branchname> will be created. -It will start out with a head equal to the one given as <start-point>. -If no <start-point> is given, the branch will be created with a head -equal to that of the currently checked out branch. + +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. 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 branch 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 +named commit). With `--merged`, only branches merged into the named +commit (i.e. the branches whose tip commits are reachable from the named +commit) will be listed. With `--no-merged` only branches not merged into +the named commit will be listed. If the <commit> argument is missing it +defaults to 'HEAD' (i.e. the tip of the current branch). + +The command's second form creates a new branch head named <branchname> +which points to the current 'HEAD', or <start-point> if given. 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 linkgit:git-pull[1] 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>. +With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match <newbranch>, and a reflog entry is created to remember the branch renaming. If <newbranch> exists, -M must be used to force the rename @@ -52,83 +60,134 @@ With a `-d` or `-D` option, `<branchname>` will be deleted. You may specify more than one branch for deletion. If the branch currently has a reflog then the reflog will also be deleted. -Use -r together with -d to delete remote-tracking branches. Note, that it +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 remote repository or if linkgit:git-fetch[1] was configured not to fetch -them again. See also 'prune' subcommand of linkgit:git-remote[1] for way to -clean up all obsolete remote-tracking branches. +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. 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 the creation of a new branch even if it means deleting - a branch that already exists with the same name. +--force:: + Reset <branchname> to <startpoint> if <branchname> exists + 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 branchname already exists. + 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`. + +--column[=<options>]:: +--no-column:: + Display branch listing in columns. See configuration variable + column.branch for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' respectively. ++ +This option is only applicable in non-verbose mode. -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. + 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. + +-q:: +--quiet:: + Be more quiet when creating or deleting a branch, suppressing + non-error messages. --abbrev=<length>:: - Alter minimum display length for sha1 in output listing, - default value is 7. + Alter the sha1's minimum display length in the output listing. + The default value is 7 and can be overridden by the `core.abbrev` + config option. --no-abbrev:: - Display the full sha1s in output listing rather than abbreviating them. + Display the full sha1s in the output listing rather than abbreviating them. +-t:: --track:: - When creating a new branch, set up configuration so that git-pull - will automatically retrieve data from the start point, which must be - a branch. Use this if you always pull from the same upstream branch - into the new branch, and if you don't want to use "git pull - <repository> <refspec>" explicitly. This behavior is the default - when the start point is a remote 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. + When creating a new branch, set up configuration to mark the + start-point branch as "upstream" from the new branch. This + configuration will tell git to show the relationship between the + two branches in `git status` and `git branch -v`. Furthermore, + 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-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-tracking branch. --no-track:: - Ignore the branch.autosetupmerge configuration variable. + 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. + +--edit-description:: + Open an editor and edit the text to explain what the branch is + for, to be used by various other commands (e.g. `request-pull`). ---contains <commit>:: - Only list branches which contain the specified commit. +--contains [<commit>]:: + Only list branches which contain the specified commit (HEAD + if not specified). ---merged:: - Only list branches which are fully contained by HEAD. +--merged [<commit>]:: + Only list branches whose tips are reachable from the + specified commit (HEAD if not specified). ---no-merged:: - Do not list branches which are fully contained by HEAD. +--no-merged [<commit>]:: + Only list branches whose tips are not reachable from the + specified commit (HEAD if not specified). <branchname>:: The name of the branch to create or delete. @@ -137,22 +196,22 @@ OPTIONS may restrict the characters allowed in a branch name. <start-point>:: - The new branch will be created with a HEAD equal to this. It may - be given as a branch name, a commit-id, or a tag. If this option - is omitted, the current branch is assumed. + The new branch head will point to this commit. It may be + given as a branch name, a commit-id, or a tag. If this + option is omitted, the current HEAD will be used instead. <oldbranch>:: The name of an existing branch to rename. <newbranch>:: The new name for an existing branch. The same restrictions as for - <branchname> applies. + <branchname> apply. Examples -------- -Start development off of a known tag:: +Start development from a known tag:: + ------------ $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 @@ -164,7 +223,7 @@ $ git checkout my2.6.14 <1> This step and the next one could be combined into a single step with "checkout -b my2.6.14 v2.6.14". -Delete unneeded branch:: +Delete an unneeded branch:: + ------------ $ git clone git://git.kernel.org/.../git.git my.git @@ -173,21 +232,21 @@ $ git branch -d -r origin/todo origin/html origin/man <1> $ git branch -D test <2> ------------ + -<1> Delete remote-tracking branches "todo", "html", "man". Next 'fetch' or -'pull' will create them again unless you configure them not to. See -linkgit:git-fetch[1]. -<2> Delete "test" branch even if the "master" branch (or whichever branch is -currently checked out) does not have all commits from test branch. +<1> Delete the remote-tracking branches "todo", "html" and "man". The next +'fetch' or 'pull' will create them again unless you configure them not to. +See linkgit:git-fetch[1]. +<2> Delete the "test" branch even if the "master" branch (or whichever branch +is currently checked out) does not have all commits from the test branch. Notes ----- -If you are creating a branch that you want to immediately checkout, it's +If you are creating a branch that you want to checkout immediately, it is easier to use the git checkout command with its `-b` option to create a branch and check it out with a single command. -The options `--contains`, `--merged` and `--no-merged` serves three related +The options `--contains`, `--merged` and `--no-merged` serve three related but different purposes: - `--contains <commit>` is used to find all branches which will need @@ -200,13 +259,13 @@ but different purposes: - `--no-merged` is used to find branches which are candidates for merging into HEAD, since those branches are not fully contained by HEAD. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-check-ref-format[1], +linkgit:git-fetch[1], +linkgit:git-remote[1], +link:user-manual.html#what-is-a-branch[``Understanding history: What is +a branch?''] in the Git User's Manual. GIT --- diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index f6a06129ab..16a6b0aceb 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -9,23 +9,23 @@ git-bundle - Move objects and refs by archive SYNOPSIS -------- [verse] -'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' create <file> <git-rev-list-args> +'git bundle' verify <file> +'git bundle' list-heads <file> [<refname>...] +'git bundle' unbundle <file> [<refname>...] DESCRIPTION ----------- 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 so 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 +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 in an archive at the originating machine, then importing those into -another repository using linkgit:git-fetch[1] and linkgit:git-pull[1] -after moving the archive by some means (i.e., by sneakernet). As no -direct connection between repositories exists, the user must specify a +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 bundle assumes that all objects in the basis are already in the destination repository. @@ -34,140 +34,172 @@ 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 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 linkgit:git-index-pack[1] - for storage in the repository, then prints the names of all - defined references. If a reflist is given, only references - matching those in the given list are printed. This command is - really plumbing, intended to be called only by - linkgit:git-fetch[1]. - -[git-rev-list-args...]:: - A list of arguments, acceptable to git-rev-parse and - git-rev-list, that specify 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 is - acting like linkgit:git-fetch-pack[1]). + 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~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~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, master --since=10.days.ago). +specified explicitly (e.g. `^master~10`), or implicitly (e.g. +`master~10..master`, `--since=10.days.ago master`). It is very important that the basis used be held by the destination. -It is okay to err on the side of conservatism, causing the bundle file -to contain objects already in the destination as these are ignored +It is okay to err on the side of caution, causing the bundle file +to contain objects already in the destination, as these are ignored when unpacking at the destination. EXAMPLE ------- -Assume two repositories exist as R1 on machine A, and R2 on machine B. +Assume you want to transfer the history from a repository R1 on machine A +to another repository R2 on machine B. For whatever reason, direct connection between A and B is not allowed, -but we can move data from A to B via some mechanism (CD, email, etc). -We want to update R2 with developments made on branch master in R1. +but we can move data from A to B via some mechanism (CD, email, etc.). +We want to update R2 with development made on the branch master in R1. -To create the bundle you have to specify the basis. You have some options: +To bootstrap the process, you can first create a bundle that does not have +any basis. You can use a tag to remember up to what commit you last +processed, in order to make it easy to later update the other repository +with an incremental bundle: -- Without basis. -+ -This is useful when sending the whole history. +---------------- +machineA$ cd R1 +machineA$ git bundle create file.bundle master +machineA$ git tag -f lastR2bundle master +---------------- ------------- -$ git bundle create mybundle master ------------- +Then you transfer file.bundle to the target machine B. If you are creating +the repository on machine B, then you can clone from the bundle as if it +were a remote repository instead of creating an empty repository and then +pulling or fetching objects from the bundle: -- Using temporally tags. -+ -We set a tag in R1 (lastR2bundle) after the previous such transport, -and move it afterwards to help build the bundle. +---------------- +machineB$ git clone /home/me/tmp/file.bundle R2 +---------------- ------------- -$ git-bundle create mybundle master ^lastR2bundle -$ git tag -f lastR2bundle master ------------- +This will define a remote called "origin" in the resulting repository that +lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will +have an entry like this: -- Using a tag present in both repositories +------------------------ +[remote "origin"] + url = /home/me/tmp/file.bundle + fetch = refs/heads/*:refs/remotes/origin/* +------------------------ ------------- -$ git bundle create mybundle master ^v1.0.0 ------------- +To update the resulting mine.git repository, you can fetch or pull after +replacing the bundle stored at /home/me/tmp/file.bundle with incremental +updates. -- A basis based on time. +After working some more in the original repository, you can create an +incremental bundle to update the other repository: ------------- -$ git bundle create mybundle master --since=10.days.ago ------------- +---------------- +machineA$ cd R1 +machineA$ git bundle create file.bundle lastR2bundle..master +machineA$ git tag -f lastR2bundle master +---------------- -- With a limit on the number of commits +You then transfer the bundle to the other machine to replace +/home/me/tmp/file.bundle, and pull from it. ------------- -$ git bundle create mybundle master -n 10 ------------- +---------------- +machineB$ cd R2 +machineB$ git pull +---------------- -Then you move mybundle from A to B, and in R2 on B: +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 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: ------------- -$ git-bundle verify mybundle -$ git-fetch mybundle master:localRef ------------- +You can use a tag that is present in both: -With something like this in the config in R2: +---------------- +$ git bundle create mybundle v1.0.0..master +---------------- ------------------------- -[remote "bundle"] - url = /home/me/tmp/file.bdl - fetch = refs/heads/*:refs/remotes/origin/* ------------------------- +You can use a basis based on time: + +---------------- +$ git bundle create mybundle --since=10.days master +---------------- + +You can use the number of commits: + +---------------- +$ git bundle create mybundle -10 master +---------------- + +You can run `git-bundle verify` to see if you can extract from a bundle +that was created with a basis: + +---------------- +$ git bundle verify mybundle +---------------- + +This will list what commits you must have in order to extract from the +bundle and will error out if you do not have them. -You can first sneakernet the bundle file to ~/tmp/file.bdl and -then these commands on machine B: +A bundle from a recipient repository's point of view is just like a +regular repository which it fetches or pulls from. You can, for example, map +references when fetching: ------------- -$ git ls-remote bundle -$ git fetch bundle -$ git pull bundle ------------- +---------------- +$ git fetch mybundle master:localRef +---------------- -would treat it as if it is talking with a remote side over the -network. +You can also see what references it offers: -Author ------- -Written by Mark Levedahl <mdl123@verizon.net> +---------------- +$ git ls-remote mybundle +---------------- GIT --- diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index f58013ca60..2fb95bbd19 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -3,30 +3,31 @@ git-cat-file(1) NAME ---- -git-cat-file - Provide content or type/size information for repository objects +git-cat-file - Provide content or type and size information for repository objects SYNOPSIS -------- [verse] -'git-cat-file' [-t | -s | -e | -p | <type>] <object> -'git-cat-file' [--batch | --batch-check] < <list-of-objects> +'git cat-file' (-t | -s | -e | -p | <type> | --textconv ) <object> +'git cat-file' (--batch | --batch-check) < <list-of-objects> DESCRIPTION ----------- -In the first form, provides content or type of objects 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. +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, or '--textconv' is used +(which implies type "blob"). -In the second form, a list of object (separated by LFs) is provided on stdin, -and the SHA1, type, and size of each object is printed on stdout. +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. OPTIONS ------- <object>:: The name of the object to show. For a more complete list of ways to spell object names, see - "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,13 +52,18 @@ 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. --batch-check:: - Print the SHA1, type, and size of each object provided on stdin. May not be - combined with any other options or arguments. + Print the SHA1, type, and size of each object provided on stdin. May not + be combined with any other options or arguments. OUTPUT ------ @@ -81,7 +87,7 @@ object specified on stdin: ------------ If '--batch-check' is specified, output of the following form is printed for -each object specified fon stdin: +each object specified on stdin: ------------ <sha1> SP <type> SP <size> LF @@ -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 ef16b93982..5abdbaa51c 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -3,38 +3,106 @@ git-check-attr(1) NAME ---- -git-check-attr - Display gitattributes information. +git-check-attr - Display gitattributes information SYNOPSIS -------- -'git-check-attr' attr... [--] pathname... +[verse] +'git check-attr' [-a | --all | attr...] [--] pathname... +'git check-attr' --stdin [-z] [-a | --all | attr...] < <list-of-paths> DESCRIPTION ----------- -For every pathname, this command will list if each attr is 'unspecified', +For every pathname, this command will list if each attribute is 'unspecified', 'set', or 'unset' as a gitattribute on that pathname. 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. + +-z:: + Only meaningful with `--stdin`; paths are separated with a + NUL character instead of a linefeed character. + \--:: - 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. + Interpret all preceding arguments as attributes and all following + 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. -SEE ALSO +OUTPUT +------ + +The output is of the form: +<path> COLON SP <attribute> COLON SP <info> LF + +<path> is the path of a file being queried, <attribute> is an attribute +being queried and <info> can be either: + +'unspecified';; when the attribute is not defined for the path. +'unset';; when the attribute is defined as false. +'set';; when the attribute is defined as true. +<value>;; when a value has been assigned to the attribute. + +EXAMPLES -------- -linkgit:gitattributes[5]. +In the examples, the following '.gitattributes' file is used: +--------------- +*.java diff=java -crlf myAttr +NoMyAttr.java !myAttr +README caveat=unspecified +--------------- -Author ------- -Written by Junio C Hamano <junkio@cox.net> +* Listing a single attribute: +--------------- +$ git check-attr diff org/example/MyClass.java +org/example/MyClass.java: diff: java +--------------- + +* Listing multiple attributes for a file: +--------------- +$ git check-attr crlf diff myAttr -- org/example/MyClass.java +org/example/MyClass.java: crlf: unset +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 +org/example/MyClass.java: myAttr: set +org/example/NoMyAttr.java: myAttr: unspecified +--------------- -Documentation --------------- -Documentation by James Bowes. +* Not all values are equally unambiguous: +--------------- +$ git check-attr caveat README +README: caveat: unspecified +--------------- + +SEE ALSO +-------- +linkgit:gitattributes[5]. GIT --- diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index c560c0aa6d..98009d1bd5 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -3,52 +3,123 @@ git-check-ref-format(1) NAME ---- -git-check-ref-format - Make sure ref name is well formed +git-check-ref-format - Ensures that a reference name is well formed SYNOPSIS -------- -'git-check-ref-format' <refname> +[verse] +'git check-ref-format' [--normalize] + [--[no-]allow-onelevel] [--refspec-pattern] + <refname> +'git check-ref-format' --branch <branchname-shorthand> DESCRIPTION ----------- -Checks if a given 'refname' is acceptable, and exits non-zero if -it is not. +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 `$GIT_DIR/refs/heads` directory, and -a tag is stored under `$GIT_DIR/refs/tags` directory. git -imposes the following rules on how refs 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`). -. It can include slash `/` for hierarchical (directory) +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. If the `--allow-onelevel` option is used, this rule + is waived. -. It cannot have two consecutive dots `..` anywhere; +. They cannot have two consecutive dots `..` anywhere. -. It cannot have ASCII control character (i.e. bytes whose +. 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 `^`, or colon `:` anywhere. + +. They cannot have question-mark `?`, asterisk `*`, or open + bracket `[` anywhere. See the `--refspec-pattern` option below for + an exception to this rule. + +. They cannot begin or end with a slash `/` or contain multiple + consecutive slashes (see the `--normalize` option below for an + exception to this rule) -. It cannot end with a slash `/`. +. They cannot end with a dot `.`. -These rules makes it easy for shell script based tools to parse -refnames, pathname expansion by the shell when a refname is used +. They cannot contain a sequence `@{`. + +. 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 -refname expressions (see linkgit:git-rev-parse[1]). Namely: +reference name expressions (see linkgit:gitrevisions[7]): -. double-dot `..` are often used as in `ref1..ref2`, and in some - context this notation means `{caret}ref1 ref2` (i.e. not in - ref1 and in ref2). +. A double-dot `..` is often used as in `ref1..ref2`, and in some + contexts this notation means `^ref1 ref2` (i.e. not in + `ref1` and in `ref2`). -. tilde `~` and caret `{caret}` are used to introduce postfix +. A tilde `~` and caret `^` are used to introduce the postfix 'nth parent' and 'peel onion' operation. -. colon `:` is used as in `srcref:dstref` to mean "use srcref\'s +. 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 - linkgit:git-cat-file[1] "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 `--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 `*` + in place of a one full pathname component (e.g., + `foo/*/bar` but not `foo/bar*`). + +--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 +-------- + +* Print the name of the previous branch: ++ +------------ +$ git check-ref-format --branch @{-1} +------------ +* Determine the reference name to use for a new branch: ++ +------------ +$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") || +die "we do not like '$newbranch' as a branch name." +------------ GIT --- diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 676203b2eb..4d33e7be0f 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -9,11 +9,11 @@ git-checkout-index - Copy files from the index to the working tree SYNOPSIS -------- [verse] -'git-checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] +'git checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] [--stage=<number>|all] [--temp] [-z] [--stdin] - [--] [<file>]\* + [--] [<file>...] DESCRIPTION ----------- @@ -73,25 +73,25 @@ OPTIONS The order of the flags used to matter, but not anymore. -Just doing `git-checkout-index` does nothing. You probably meant -`git-checkout-index -a`. And if you want to force it, you want -`git-checkout-index -f -a`. +Just doing `git checkout-index` does nothing. You probably meant +`git checkout-index -a`. And if you want to force it, you want +`git checkout-index -f -a`. Intuitiveness is not the goal here. Repeatability is. The reason for the "no arguments means no work" behavior is that from scripts you are supposed to be able to do: ---------------- -$ find . -name '*.h' -print0 | xargs -0 git-checkout-index -f -- +$ 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 +$ find . -name '*.h' -print0 | git checkout-index -f -z --stdin ---------------- The `--` is just a good idea when you know the rest will be filenames; @@ -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 @@ -144,19 +144,19 @@ EXAMPLES To update and refresh only the files already checked out:: + ---------------- -$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh +$ 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: + ---------------- -$ git-checkout-index --prefix=git-export-dir/ -a +$ git checkout-index --prefix=git-export-dir/ -a ---------------- + -`git-checkout-index` will "export" the index into the specified +`git checkout-index` will "export" the index into the specified directory. + The final "/" is important. The exported name is literally just @@ -166,24 +166,12 @@ following example. Export files with a prefix:: + ---------------- -$ git-checkout-index --prefix=.merged- Makefile +$ 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 3ad9760a4d..63a251612a 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -8,68 +8,151 @@ git-checkout - Checkout a branch or paths to the working tree SYNOPSIS -------- [verse] -'git-checkout' [-q] [-f] [[--track | --no-track] -b <new_branch> [-l]] [-m] [<branch>] -'git-checkout' [<tree-ish>] <paths>... +'git checkout' [-q] [-f] [-m] [<branch>] +'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' [-p|--patch] [<tree-ish>] [--] [<paths>...] DESCRIPTION ----------- +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. -When <paths> are not given, this command switches branches by -updating the index and working tree to reflect the specified -branch, <branch>, and updating HEAD to be <branch> or, if -specified, <new_branch>. Using -b will cause <new_branch> to -be created; in this case you can use the --track or --no-track -options, which will be passed to `git branch`. - -When <paths> are given, this command does *not* switch -branches. It updates the named paths in the working tree from -the index file (i.e. it runs `git-checkout-index -f -u`), or -from a named commit. In -this case, the `-f` and `-b` options are meaningless and giving -either of them results in an error. <tree-ish> argument can be -used to specify a specific tree-ish (i.e. commit, tag or tree) -to update the index for the given paths before updating the -working tree. +'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 +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 re-create the original conflicted merge result. OPTIONS ------- -q:: +--quiet:: Quiet, suppress feedback messages. -f:: - Proceed even if the index or the working tree differs - from HEAD. This is used to throw away local changes. +--force:: + When switching branches, proceed even if the index or the + working tree differs from HEAD. This is used to throw away + local changes. ++ +When checking out paths from the index, do not fail upon unmerged +entries; instead, unmerged entries are ignored. + +--ours:: +--theirs:: + When checking out paths from the index, check out stage #2 + ('ours') or #3 ('theirs') for unmerged paths. -b:: Create a new branch named <new_branch> and start it at - <branch>. The new branch name must pass all checks defined - by linkgit:git-check-ref-format[1]. Some of these checks - may restrict the characters allowed in a branch name. + <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 configuration so that git-pull - will automatically retrieve data from the start point, which must be - a branch. Use this if you always pull from the same upstream branch - into the new branch, and if you don't want to use "git pull - <repository> <refspec>" explicitly. This behavior is the default - when the start point is a remote 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. + 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-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 +off of "origin/hack" (or "remotes/origin/hack", or even +"refs/remotes/origin/hack"). If the given name has no slash, or the above +guessing results in an empty name, the guessing is aborted. You can +explicitly give a name with '-b' in such a case. --no-track:: - Ignore the branch.autosetupmerge configuration variable. + Do not set up "upstream" configuration, even if the + branch.autosetupmerge configuration variable is true. -l:: - Create the new 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}". + 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:: - If you have local modifications to one or more files that +--merge:: + When switching branches, + if you have local modifications to one or more files that are different between the current branch and the branch to which you are switching, the command refuses to switch branches in order to preserve your modifications in context. @@ -81,54 +164,190 @@ When a merge conflict happens, the index entries for conflicting paths are left unmerged, and you need to resolve the conflicts and mark the resolved paths with `git add` (or `git rm` if the merge should result in deletion of the path). ++ +When checking out paths from the index, this option lets you recreate +the conflicted merge in the specified paths. + +--conflict=<style>:: + The same as --merge option above, but changes the way the + conflicting hunks are presented, overriding the + merge.conflictstyle configuration variable. Possible values are + "merge" (default) and "diff3" (in addition to what is shown by + "merge" style, shows the original contents). + +-p:: +--patch:: + Interactively select hunks in the difference between the + <tree-ish> (or the index, if unspecified) and the working + tree. The chosen hunks are then applied in reverse to the + 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. 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, + when prepended with "refs/heads/", is a valid ref), then that + branch is checked out. Otherwise, if it refers to a valid + commit, your HEAD becomes "detached" and you are no longer on + any branch (see below for details). ++ +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. -<branch>:: - Branch to checkout; may be any object ID that resolves to a - commit. Defaults to HEAD. -+ -When this parameter names a non-branch (but still a valid commit object), -your HEAD becomes 'detached'. +<start_point>:: + The name of a commit at which to start the new branch; see + linkgit:git-branch[1] for details. Defaults to HEAD. + +<tree-ish>:: + Tree to checkout from (when paths are given). If not specified, + the index will be used. -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 `-b` option, but starting from -version 1.5.0, the above command 'detaches' your HEAD from the -current branch and directly point at the commit named by the tag -(`v2.6.18` in the above example). +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 usual 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 -------- @@ -145,8 +364,8 @@ $ git checkout hello.c <3> ------------ + <1> switch branch -<2> take out a file out of other commit -<3> restore hello.c from HEAD of current branch +<2> take a file out of another commit +<3> restore hello.c from the index + If you have an unfortunate branch that is named `hello.c`, this step would be confused as an instruction to switch to that branch. @@ -156,7 +375,7 @@ You should instead write: $ git checkout -- hello.c ------------ -. After working in a wrong branch, switching to the correct +. After working in the wrong branch, switching to the correct branch would be done using: + ------------ @@ -164,12 +383,12 @@ $ git checkout mytopic ------------ + However, your "wrong" branch and correct "mytopic" branch may -differ in files that you have locally modified, in which case, +differ in files that you have modified locally, in which case 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 @@ -190,7 +409,6 @@ the `-m` option, you would see something like this: ------------ $ git checkout -m mytopic Auto-merging frotz -merge: warning: conflicts during merge ERROR: Merge conflict in frotz fatal: merge program failed ------------ @@ -205,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 5ac9cfb0ef..9f3dae631e 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -3,34 +3,62 @@ 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' --continue +'git cherry-pick' --quit +'git cherry-pick' --abort 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. +<commit>...:: + Commits to cherry-pick. For a more complete list of ways to spell commits, see - "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + 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,30 +83,125 @@ OPTIONS -n:: --no-commit:: - Usually the command automatically creates a commit with - a commit log message stating which commit was - cherry-picked. This flag applies the change necessary - to cherry-pick the named commit to your working tree, - but does not make the commit. In addition, when this - option is used, your working tree does not have to match - the HEAD commit. The cherry-pick is done against the - beginning state of your working tree. + 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. + This is useful when cherry-picking more than one commits' -effect to your working tree in a row. +effect to your index in a row. -s:: --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. + +--allow-empty:: + By default, cherry-picking an empty commit will fail, + indicating that an explicit invocation of `git commit + --allow-empty` is required. This option overrides that + behavior, allowing empty commits to be preserved automatically + in a cherry-pick. Note that when "--ff" is in effect, empty + commits that meet the "fast-forward" requirement will be kept + even without this option. Note also, that use of this option only + keeps commits that were initially empty (i.e. the commit recorded the + same tree as its parent). Commits which are made empty due to a + previous commit are dropped. To force the inclusion of those commits + use `--keep-redundant-commits`. + +--keep-redundant-commits:: + If a commit being cherry picked duplicates a commit already in the + current history, it will become empty. By default these + redundant commits are ignored. This option overrides that behavior and + creates an empty commit object. Implies `--allow-empty`. + +--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. -Author ------- -Written by Junio C Hamano <junkio@cox.net> +`git cherry-pick ..master`:: +`git cherry-pick ^HEAD master`:: -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + Apply the changes introduced by all commits that are ancestors + of master but not of HEAD to produce new commits. + +`git cherry-pick master~4 master~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 ef7caf61e1..f6c19c734d 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -7,14 +7,15 @@ git-cherry - Find commits not merged upstream SYNOPSIS -------- -'git-cherry' [-v] <upstream> [<head>] [<limit>] +[verse] +'git cherry' [-v] [<upstream> [<head> [<limit>]]] 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 linkgit:git-patch-id[1] -program. +The commits are compared with their 'patch id', obtained from +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. @@ -51,6 +52,7 @@ OPTIONS <upstream>:: Upstream branch to compare against. + Defaults to the first tracked remote branch, if available. <head>:: Working branch; defaults to HEAD. @@ -62,14 +64,6 @@ SEE ALSO -------- linkgit:git-patch-id[1] -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -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 09108d0e66..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 linkgit:git-commit[1] 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 37a82ee4b8..79fb984144 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,26 +8,33 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git-clean' [-d] [-f] [-n] [-q] [-x | -X] [--] <paths>... +'git clean' [-d] [-f] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... DESCRIPTION ----------- -Removes files unknown to git. This allows to clean the working tree -from files that are not under version control. If the '-x' option is -specified, ignored files are also removed, allowing to remove all -build products. -When optional `<paths>...` arguments are given, the paths -affected are further limited to those that match them. +Cleans the working tree by recursively removing files that are not +under version control, starting from the current directory. + +Normally, only files unknown to git are removed, but if the '-x' +option is specified, ignored files are also removed. This can, for +example, be useful to remove all build products. + +If any optional `<path>...` arguments are given, only those paths +are affected. OPTIONS ------- -d:: Remove untracked directories in addition to untracked files. + If an untracked directory is managed by a different git + repository, it is not removed by default. Use -f option twice + if you really want to remove such a directory. -f:: - If the git configuration specifies clean.requireForce as true, - git-clean will refuse to run unless given -f or -n. +--force:: + 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:: @@ -38,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 linkgit:git-reset[1]) 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 7973e6af4c..6e22522c4f 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,18 +9,22 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- [verse] -'git-clone' [--template=<template_directory>] - [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] - [-o <name>] [-u <upload-pack>] [--reference <repository>] - [--depth <depth>] [--] <repository> [<directory>] +'git clone' [--template=<template_directory>] + [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] + [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] + [--separate-git-dir <git dir>] + [--depth <depth>] [--[no-]single-branch] + [--recursive|--recurse-submodules] [--] <repository> + [<directory>] DESCRIPTION ----------- Clones a repository into a newly created directory, creates remote-tracking branches for each branch in the cloned repository -(visible using `git branch -r`), and creates and checks out an initial -branch equal to the cloned repository's currently active branch. +(visible using `git branch -r`), and creates and checks out an +initial branch that is forked from the cloned repository's +currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without @@ -28,7 +32,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. @@ -38,7 +42,7 @@ OPTIONS --local:: -l:: When the repository to clone from is on a local machine, - this flag bypasses normal "git aware" transport + this flag bypasses the normal "git aware" transport mechanism and clones the repository by making a copy of HEAD and everything under objects and refs directories. The files under `.git/objects/` directory are hardlinked @@ -59,7 +63,7 @@ OPTIONS -s:: When the repository to clone is on the local machine, instead of using hard links, automatically setup - .git/objects/info/alternates to share the objects + `.git/objects/info/alternates` to share the objects with the source repository. The resulting repository starts out without any object of its own. + @@ -68,27 +72,47 @@ it unless you understand what it does. If you clone your repository using this option and then delete branches (or use any other git command that makes any existing commit unreferenced) in the source repository, some objects may become unreferenced (or dangling). -These objects may be removed by normal git operations (such as git-commit[1]) -which automatically call git-gc[1]. If these objects are removed and -were referenced by the cloned repository, then the cloned repository -will become corrupt. - - +These objects may be removed by normal git operations (such as `git commit`) +which automatically call `git gc --auto`. (See linkgit:git-gc[1].) +If these objects are removed and were referenced by the cloned repository, +then the cloned repository will become corrupt. ++ +Note that running `git repack` without the `-l` option in a repository +cloned with `-s` will copy objects from the source repository into a pack +in the cloned repository, removing the disk space savings of `clone -s`. +It is safe, however, to run `git gc`, which uses the `-l` option by +default. ++ +If you want to break the dependency of a repository cloned with `-s` on +its source repository, you can simply run `git repack -a` to copy all +objects from the source repository into a pack in the cloned repository. --reference <repository>:: - If the reference repository is on the local machine - automatically setup .git/objects/info/alternates to + If the reference repository is on the local machine, + automatically setup `.git/objects/info/alternates` to obtain objects from the reference repository. Using an already existing repository as an alternate will require fewer objects to be copied from the repository being cloned, reducing network and local storage costs. + -*NOTE*: see NOTE to --shared option. +*NOTE*: see the NOTE for the `--shared` option. --quiet:: -q:: - Operate quietly. This flag is passed to "rsync" and - "git-fetch-pack" commands when given. + Operate quietly. Progress is not reported to the standard + error stream. This flag is also passed to the `rsync' + command when given. + +--verbose:: +-v:: + 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 + 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. --no-checkout:: -n:: @@ -106,22 +130,47 @@ will become corrupt. used, neither remote-tracking branches nor the related configuration variables are created. +--mirror:: + 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>:: - Instead of using the remote name 'origin' to keep track - of the upstream repository, use <name> instead. + Instead of using the remote name `origin` to keep track + of the upstream repository, use `<name>`. + +--branch <name>:: +-b <name>:: + Instead of pointing the newly created HEAD to the branch pointed + to by the cloned repository's HEAD, point to `<name>` branch + instead. `--branch` can also take tags and treat them like + detached HEAD. In a non-bare repository, this is the branch + that will be checked out. --upload-pack <upload-pack>:: -u <upload-pack>:: - When given, and the repository to clone from is handled - by 'git-fetch-pack', '--exec=<upload-pack>' is passed to - the command to specify non-default path for the command + When given, and the repository to clone from is accessed + via ssh, this specifies a non-default path for the command run on the other end. --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 @@ -132,6 +181,31 @@ will become corrupt. with a long history, and would want to send in fixes as patches. +--single-branch:: + Clone only the history leading to the tip of a single branch, + either specified by the `--branch` option or the primary + branch remote's `HEAD` points at. When creating a shallow + clone with the `--depth` option, this is the default, unless + `--no-single-branch` is given to fetch the histories near the + tips of all branches. + +--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 + the clone is finished. This option is ignored if the cloned + 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 @@ -140,9 +214,9 @@ will become corrupt. <directory>:: The name of a new directory to clone into. The "humanish" part of the source repository is used if no directory is - explicitly given ("repo" for "/path/to/repo.git" and "foo" - for "host.xz:foo/.git"). Cloning into an existing directory - is not allowed. + explicitly given (`repo` for `/path/to/repo.git` and `foo` + for `host.xz:foo/.git`). Cloning into an existing directory + is only allowed if the directory is empty. :git-clone: 1 include::urls.txt[] @@ -150,7 +224,7 @@ include::urls.txt[] Examples -------- -Clone from upstream:: +* Clone from upstream: + ------------ $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 @@ -159,7 +233,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 @@ -168,7 +242,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 \ @@ -178,31 +252,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-column.txt b/Documentation/git-column.txt new file mode 100644 index 0000000000..9be16eea0e --- /dev/null +++ b/Documentation/git-column.txt @@ -0,0 +1,53 @@ +git-column(1) +============= + +NAME +---- +git-column - Display data in columns + +SYNOPSIS +-------- +[verse] +'git column' [--command=<name>] [--[raw-]mode=<mode>] [--width=<width>] + [--indent=<string>] [--nl=<string>] [--pading=<n>] + +DESCRIPTION +----------- +This command formats its input into multiple columns. + +OPTIONS +------- +--command=<name>:: + Look up layout mode using configuration variable column.<name> and + column.ui. + +--mode=<mode>:: + Specify layout mode. See configuration variable column.ui for option + syntax. + +--raw-mode=<n>:: + Same as --mode but take mode encoded as a number. This is mainly used + by other commands that have already parsed layout mode. + +--width=<width>:: + Specify the terminal width. By default 'git column' will detect the + terminal width, or fall back to 80 if it is unable to do so. + +--indent=<string>:: + String to be printed at the beginning of each line. + +--nl=<N>:: + String to be printed at the end of each line, + including newline character. + +--padding=<N>:: + The number of spaces between columns. One space by default. + + +Author +------ +Written by Nguyen Thai Ngoc Duy <pclouds@gmail.com> + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 728c2fae89..eb8ee9999e 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -8,7 +8,9 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- -'git-commit-tree' <tree> [-p <parent commit>]\* < changelog +[verse] +'git commit-tree' <tree> [(-p <parent>)...] < changelog +'git commit-tree' [(-p <parent>)...] [(-m <message>)...] [(-F <file>)...] <tree> DESCRIPTION ----------- @@ -16,12 +18,13 @@ This is usually not what an end user wants to run directly. See linkgit:git-commit[1] instead. Creates a new commit object based on the provided tree object and -emits the new commit object id on stdout. If no parent is given then -it is considered to be an initial tree. +emits the new commit object id on stdout. The log message is read +from the standard input, unless `-m` or `-F` options are given. -A commit object usually has 1 parent (a commit after a change) or up -to 16 parents. More than one parent represents a merge of branches -that led to them. +A commit object may have any number of parents. With exactly one +parent, it is an ordinary commit. Having more than one parent makes +the commit a merge between several lines of history. Initial (root) +commits have no parents. While a tree represents a particular directory state of a working directory, a commit represents that state in "time", and explains how @@ -38,9 +41,17 @@ OPTIONS <tree>:: An existing tree object --p <parent commit>:: +-p <parent>:: Each '-p' indicates the id of a parent commit object. +-m <message>:: + A paragraph in the commig log message. This can be given more than + once and each <message> becomes its own paragraph. + +-F <file>:: + Read the commit log message from the given file. Use `-` to read + from the standard input. + Commit Information ------------------ @@ -67,40 +78,29 @@ 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. - -Diagnostics ------------ -You don't exist. Go away!:: - The passwd(5) gecos field couldn't be read -Your parents must have hated you!:: - The password(5) gecos field is longer than a giant static buffer. -Your sysadmin must hate you!:: - The password(5) name field is longer than a giant static buffer. +include::date-formats.txt[] 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 7e8b4ff72c..2d695f619c 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,28 +8,31 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git-commit' [-a | --interactive] [-s] [-v] [-u] [--amend] - [(-c | -C) <commit>] [-F <file> | -m <msg>] - [--allow-empty] [--no-verify] [-e] [--author=<author>] - [--cleanup=<mode>] [--] [[-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 ----------- -Use 'git commit' to store the current contents of the index in a new -commit along with a log message describing the changes you have made. +Stores the current contents of the index in a new commit along +with a log message from the user describing the changes. The content to be added can be specified in several ways: -1. by using linkgit:git-add[1] 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 linkgit:git-rm[1] 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 case the commit will ignore changes staged in the index, and instead - record the current content of the listed files; + record the current content of the listed files (which must already + be known to git); 4. by using the -a switch with the 'commit' command to automatically "add" changes from all known files (i.e. all files that are already @@ -37,17 +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 linkgit:git-status[1] command can be used to obtain a +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 you would give to -this command. +commit by giving the same set of parameters (options and paths). -If you make a commit and then found a mistake immediately after -that, you can recover from it with linkgit:git-reset[1]. +If you make a commit and then find a mistake immediately after +that, you can recover from it with 'git reset'. OPTIONS @@ -58,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 @@ -69,14 +78,53 @@ 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, 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 + linkgit:git-status[1] for details. Implies `--dry-run`. + +--porcelain:: + When doing a dry-run, give the output in a porcelain-ready + format. See linkgit:git-status[1] for details. Implies + `--dry-run`. + +-z:: + When showing `short` or `porcelain` status output, terminate + entries in the status output with NUL, instead of LF. If no + format is given, implies the `--porcelain` output format. + -F <file>:: --file=<file>:: Take the commit message from the given file. Use '-' to read the message from the standard input. --author=<author>:: - Override the author name used in the commit. Use - `A U Thor <author@example.com>` format. + 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. -m <msg>:: --message=<msg>:: @@ -84,26 +132,36 @@ OPTIONS -t <file>:: --template=<file>:: - Use the contents of the given file as the initial version - of the commit message. The editor is invoked and you can - make subsequent changes. If a message is specified using - the `-m` or `-F` options, this option has no effect. This - overrides the `commit.template` configuration variable. + When editing the commit message, start the editor with the + contents in the given file. The `commit.template` configuration + variable is often used to give this option implicitly to the + command. This mechanism can be used by projects that want to + guide participants with some hints on what to write in the message + in what order. If the user exits the editor without editing the + message, the commit is aborted. This has no effect when a message + is given by other means, e.g. with the `-m` or `-F` options. -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add Signed-off-by line by the committer at the end of the commit + log message. -n:: --no-verify:: This option bypasses the pre-commit and commit-msg hooks. - See also linkgit:githooks[5][hooks]. + See also linkgit:githooks[5]. --allow-empty:: 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. @@ -142,6 +200,10 @@ It is a rough equivalent for: ------ but can be used to amend a merge commit. -- ++ +You should understand the implications of rewriting history if you +amend a commit that has already been published. (See the "RECOVERING +FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) -i:: --include:: @@ -158,17 +220,26 @@ but can be used to amend a merge commit. 'git commit' if any paths are given on the command line, in which case this option can be omitted. If this option is specified together with '--amend', then - no paths need be specified, which can be used to amend + no paths need to be specified, which can be used to amend the last commit without committing changes that have already been staged. --u:: ---untracked-files:: - Show all untracked files, also those in uninteresting - directories, in the "Untracked files:" section of commit - message template. Without this option only its name and - a trailing slash are displayed for each untracked - directory. +-u[<mode>]:: +--untracked-files[=<mode>]:: + 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 possible options are: ++ + - 'no' - Show no untracked files + - 'normal' - Shows untracked files and directories + - 'all' - Also shows individual files in untracked directories. ++ +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. -v:: --verbose:: @@ -181,6 +252,22 @@ but can be used to amend a merge commit. --quiet:: Suppress commit summary message. +--dry-run:: + Do not create a commit, but show a list of paths that are + to be committed, paths with local changes that will be left + uncommitted and paths that are untracked. + +--status:: + Include the output of linkgit:git-status[1] in the commit + message template when using an editor to prepare the commit + message. Defaults to on, but can be used to override + configuration variable commit.status. + +--no-status:: + Do not include the output of linkgit:git-status[1] in the + commit message template when using an editor to prepare the + default commit message. + \--:: Do not interpret any more arguments as options. @@ -191,15 +278,17 @@ but can be used to amend a merge commit. these files are also staged for the next commit on top of what have been staged before. +:git-commit: 1 +include::date-formats.txt[] 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 linkgit:git-add[1]. 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 @@ -255,13 +344,13 @@ $ git commit this second commit would record the changes to `hello.c` and `hello.h` as expected. -After a merge (initiated by either linkgit:git-merge[1] or -linkgit:git-pull[1]) stops because of conflicts, cleanly merged +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 linkgit:git-status[1] +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 linkgit:git-add[1]: +stage the result as usual with 'git add': ------------ $ git status | grep unmerged @@ -302,12 +391,12 @@ ENVIRONMENT AND CONFIGURATION VARIABLES The editor used to edit the commit log message will be chosen from the GIT_EDITOR environment variable, the core.editor configuration variable, the VISUAL environment variable, or the EDITOR environment variable (in that -order). +order). See linkgit:git-var[1] for details. HOOKS ----- This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, -and `post-commit` hooks. See linkgit:githooks[5][hooks] for more +and `post-commit` hooks. See linkgit:githooks[5] for more information. @@ -319,12 +408,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 <junkio@cox.net> - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index c90421ee7f..d9463cb387 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,19 +9,20 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git-config' [<file-option>] [type] [-z|--null] name [value [value_regex]] -'git-config' [<file-option>] [type] --add name value -'git-config' [<file-option>] [type] --replace-all name [value [value_regex]] -'git-config' [<file-option>] [type] [-z|--null] --get name [value_regex] -'git-config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] -'git-config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] -'git-config' [<file-option>] --unset name [value_regex] -'git-config' [<file-option>] --unset-all name [value_regex] -'git-config' [<file-option>] --rename-section old_name new_name -'git-config' [<file-option>] --remove-section name -'git-config' [<file-option>] [-z|--null] -l | --list -'git-config' [<file-option>] --get-color name [default] -'git-config' [<file-option>] --get-colorbool name [stdout-is-tty] +'git config' [<file-option>] [type] [-z|--null] name [value [value_regex]] +'git config' [<file-option>] [type] --add name value +'git config' [<file-option>] [type] --replace-all name value [value_regex] +'git config' [<file-option>] [type] [-z|--null] --get name [value_regex] +'git config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] +'git config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] +'git config' [<file-option>] --unset name [value_regex] +'git config' [<file-option>] --unset-all name [value_regex] +'git config' [<file-option>] --rename-section old_name new_name +'git config' [<file-option>] --remove-section name +'git config' [<file-option>] [-z|--null] -l | --list +'git config' [<file-option>] --get-color name [default] +'git config' [<file-option>] --get-colorbool name [stdout-is-tty] +'git config' [<file-option>] -e | --edit DESCRIPTION ----------- @@ -36,28 +37,35 @@ existing values that match the regexp are updated or unset. If 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', which will make -'git-config' ensure that the variable(s) are of the given type and +The type specifier can be either '--int' or '--bool', to make +'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). If no type specifier is passed, -no checks or transformations are performed on the value. +a "true" or "false" string for bool), or '--path', which does some +path expansion (see '--path' below). If no type specifier is passed, no +checks or transformations are performed on the value. -The file-option can be one of '--system', '--global' or '--file' -which specify where the values will be read from or written to. -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>>). +When reading, the values are read from the system, global and +repository local configuration files by default, and options +'--system', '--global', '--local' and '--file <filename>' can be +used to tell the command to read from only that location (see <<FILES>>). -This command will fail if: +When writing, the new value is written to the repository local +configuration file by default, and options '--system', '--global', +'--file <filename>' can be used to tell the command to write to +that location (you can say '--local' but that is the default). -. 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. +This command will fail (with exit code ret) if: +. 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 ------- @@ -68,7 +76,8 @@ OPTIONS --add:: Adds a new line to the option without altering any existing - values. This is the same as providing '^$' as the value_regex. + values. This is the same as providing '^$' as the value_regex + in `--replace-all`. --get:: Get the value for a given key (optionally filtered by a regex @@ -80,8 +89,11 @@ OPTIONS is not exactly one. --get-regexp:: - Like --get-all, but interprets the name as a regular expression. - Also outputs the key names. + Like --get-all, but interprets the name as a regular expression and + writes out the key names. Regular expression matching is currently + case-sensitive and done against a canonicalized version of the key + in which section and variable names are lowercased, but subsection + names are not. --global:: For writing options: write to global ~/.gitconfig file rather than @@ -122,14 +134,25 @@ 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 + either --bool or --int, as described above. + +--path:: + 'git-config' will expand leading '{tilde}' to the value of + '$HOME', and '{tilde}user' to the home directory for the + specified user. This option has no effect when setting the + value (but you can use 'git config bla {tilde}/' from the + command line to let your shell do the expansion). + -z:: --null:: For all options that output values and/or keys, always @@ -150,24 +173,32 @@ See also <<FILES>>. When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color name default:: +--get-color name [default]:: Find the color configured for `name` (e.g. `color.diff.new`) and output it as the ANSI color escape sequence to the standard output. The optional `default` parameter is used instead, if there is no color configured for `name`. +-e:: +--edit:: + Opens an editor to modify the specified config file; either + '--system', '--global', or repository (default). + +--includes:: +--no-includes:: + Respect `include.*` directives in config files when looking up + values. Defaults to on. + [[FILES]] 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 - of course relative to the repository root, not the working - directory.) + Repository specific configuration file. ~/.gitconfig:: User-specific configuration file. Also called "global" @@ -179,23 +210,18 @@ $(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 to the global or system-wide file respectively. The GIT_CONFIG environment variable has a similar effect, but you can specify any filename you want. -The GIT_CONFIG_LOCAL environment variable on the other hand only changes -the name used instead of the repository configuration file. The global and -the system-wide configuration files will still be read. (For writing options -this will obviously result in the same behavior as using GIT_CONFIG.) - ENVIRONMENT ----------- @@ -205,10 +231,6 @@ GIT_CONFIG:: Using the "--global" option forces this to ~/.gitconfig. Using the "--system" option forces this to $(prefix)/etc/gitconfig. -GIT_CONFIG_LOCAL:: - Take the configuration from the given file instead if .git/config. - Still read the global and the system-wide configuration files, though. - See also <<FILES>>. @@ -231,7 +253,7 @@ Given a .git/config like this: ; Our diff algorithm [diff] - external = "/usr/local/bin/gnu-diff -u" + external = /usr/local/bin/diff-wrapper renames = true ; Proxy settings @@ -288,7 +310,7 @@ If you want to know all the values for a multivar, do: % git config --get-all core.gitproxy ------------ -If you like to live dangerous, you can replace *all* core.gitproxy by a +If you like to live dangerously, you can replace *all* core.gitproxy by a new one with ------------ @@ -326,15 +348,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 1ba85a259a..23c80cea64 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -7,7 +7,8 @@ git-count-objects - Count unpacked number of objects and their disk consumption SYNOPSIS -------- -'git-count-objects' [-v] +[verse] +'git count-objects' [-v] DESCRIPTION ----------- @@ -21,17 +22,9 @@ OPTIONS --verbose:: In addition to the number of loose objects and disk space consumed, it reports the number of in-pack - objects, number of packs, and number of objects that can be - removed by running `git-prune-packed`. - - -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + objects, number of packs, disk space consumed by those packs, + and number of objects that can be removed by running + `git prune-packed`. GIT --- diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt new file mode 100644 index 0000000000..11edc5a173 --- /dev/null +++ b/Documentation/git-credential-cache--daemon.txt @@ -0,0 +1,26 @@ +git-credential-cache--daemon(1) +=============================== + +NAME +---- +git-credential-cache--daemon - temporarily store user credentials in memory + +SYNOPSIS +-------- +[verse] +git credential-cache--daemon <socket> + +DESCRIPTION +----------- + +NOTE: You probably don't want to invoke this command yourself; it is +started automatically when you use linkgit:git-credential-cache[1]. + +This command listens on the Unix domain socket specified by `<socket>` +for `git-credential-cache` clients. Clients may store and retrieve +credentials. Each credential is held for a timeout specified by the +client; once no credentials are held, the daemon exits. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt new file mode 100644 index 0000000000..f3d09c5d51 --- /dev/null +++ b/Documentation/git-credential-cache.txt @@ -0,0 +1,77 @@ +git-credential-cache(1) +======================= + +NAME +---- +git-credential-cache - helper to temporarily store passwords in memory + +SYNOPSIS +-------- +----------------------------- +git config credential.helper 'cache [options]' +----------------------------- + +DESCRIPTION +----------- + +This command caches credentials in memory for use by future git +programs. The stored credentials never touch the disk, and are forgotten +after a configurable timeout. The cache is accessible over a Unix +domain socket, restricted to the current user by filesystem permissions. + +You probably don't want to invoke this command directly; it is meant to +be used as a credential helper by other parts of git. See +linkgit:gitcredentials[7] or `EXAMPLES` below. + +OPTIONS +------- + +--timeout <seconds>:: + + Number of seconds to cache credentials (default: 900). + +--socket <path>:: + + Use `<path>` to contact a running cache daemon (or start a new + cache daemon if one is not started). Defaults to + `~/.git-credential-cache/socket`. If your home directory is on a + network-mounted filesystem, you may need to change this to a + local filesystem. + +CONTROLLING THE DAEMON +---------------------- + +If you would like the daemon to exit early, forgetting all cached +credentials before their timeout, you can issue an `exit` action: + +-------------------------------------- +git credential-cache exit +-------------------------------------- + +EXAMPLES +-------- + +The point of this helper is to reduce the number of times you must type +your username or password. For example: + +------------------------------------ +$ git config credential.helper cache +$ git push http://example.com/repo.git +Username: <type your username> +Password: <type your password> + +[work for 5 more minutes] +$ git push http://example.com/repo.git +[your credentials are used automatically] +------------------------------------ + +You can provide options via the credential.helper configuration +variable (this example drops the cache time to 5 minutes): + +------------------------------------------------------- +$ git config credential.helper 'cache --timeout=300' +------------------------------------------------------- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt new file mode 100644 index 0000000000..31093467d1 --- /dev/null +++ b/Documentation/git-credential-store.txt @@ -0,0 +1,75 @@ +git-credential-store(1) +======================= + +NAME +---- +git-credential-store - helper to store credentials on disk + +SYNOPSIS +-------- +------------------- +git config credential.helper 'store [options]' +------------------- + +DESCRIPTION +----------- + +NOTE: Using this helper will store your passwords unencrypted on disk, +protected only by filesystem permissions. If this is not an acceptable +security tradeoff, try linkgit:git-credential-cache[1], or find a helper +that integrates with secure storage provided by your operating system. + +This command stores credentials indefinitely on disk for use by future +git programs. + +You probably don't want to invoke this command directly; it is meant to +be used as a credential helper by other parts of git. See +linkgit:gitcredentials[7] or `EXAMPLES` below. + +OPTIONS +------- + +--store=<path>:: + + Use `<path>` to store credentials. The file will have its + filesystem permissions set to prevent other users on the system + from reading it, but will not be encrypted or otherwise + protected. Defaults to `~/.git-credentials`. + +EXAMPLES +-------- + +The point of this helper is to reduce the number of times you must type +your username or password. For example: + +------------------------------------------ +$ git config credential.helper store +$ git push http://example.com/repo.git +Username: <type your username> +Password: <type your password> + +[several days later] +$ git push http://example.com/repo.git +[your credentials are used automatically] +------------------------------------------ + +STORAGE FORMAT +-------------- + +The `.git-credentials` file is stored in plaintext. Each credential is +stored on its own line as a URL like: + +------------------------------ +https://user:pass@example.com +------------------------------ + +When git needs authentication for a particular URL context, +credential-store will consider that context a pattern to match against +each entry in the credentials file. If the protocol, hostname, and +username (if we already have one) match, then the password is returned +to git. See the discussion of configuration in linkgit:gitcredentials[7] +for more information. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 5fa91e51ad..7f79cec3f8 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,7 +8,9 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- -'git-cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID +[verse] +'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] + [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID DESCRIPTION @@ -26,8 +28,8 @@ 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 parent -should the changeset be done against. +If the commit is a merge commit, you must tell 'git cvsexportcommit' what +parent the changeset should be done against. OPTIONS ------- @@ -62,6 +64,10 @@ OPTIONS -u:: Update affected files from CVS repository before attempting export. +-k:: + Reverse CVS keyword expansion (e.g. $Revision: 1.2.3.4$ + becomes $Revision$) in working CVS checkout before applying patch. + -w:: Specify the location of the CVS checkout to use for the export. This option does not require GIT_DIR to be set before execution if the @@ -89,14 +95,14 @@ Merge one patch into CVS:: ------------ $ export GIT_DIR=~/project/.git $ cd ~/project_cvs_checkout -$ git-cvsexportcommit -v <commit-sha1> +$ git cvsexportcommit -v <commit-sha1> $ cvs commit -F .msg <files> ------------ Merge one patch into CVS (-c and -w options). The working directory is within the Git Repo:: + ------------ - $ git-cvsexportcommit -v -c -w ~/project_cvs_checkout <commit-sha1> + $ git cvsexportcommit -v -c -w ~/project_cvs_checkout <commit-sha1> ------------ Merge pending patches into CVS automatically -- only if you really know what you are doing:: @@ -104,17 +110,9 @@ Merge pending patches into CVS automatically -- only if you really know what you ------------ $ export GIT_DIR=~/project/.git $ cd ~/project_cvs_checkout -$ git-cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git-cvsexportcommit -c -p -v +$ 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 2f9b35f622..6695ab3b4b 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate SYNOPSIS -------- [verse] -'git-cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] [-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 @@ -24,13 +24,22 @@ repository, or incrementally import into an existing one. Splitting the CVS log into patch sets is done by 'cvsps'. At least version 2.1 is required. +*WARNING:* for certain situations the import leads to incorrect results. +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 any CVS branches, yourself. It is advisable to specify a named remote via -r to separate and protect the incoming branches. +If you intend to set up a shared public repository that all developers can +read/write, or if you want to use linkgit:git-cvsserver[1], then you +probably want to make a bare clone of the imported repository, +and use the clone as the shared repository. +See linkgit:gitcvs-migration[7]. + OPTIONS ------- @@ -40,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>:: @@ -56,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 git-clone --use-separate-remote option. + 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. + @@ -136,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 -linkgit:git-cvsexportcommit[1]. +'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. @@ -158,15 +183,39 @@ If '-v' is specified, the script reports what it is doing. Otherwise, success is indicated the Unix way, i.e. by simply exiting with a zero exit status. - -Author +[[issues]] +ISSUES ------ -Written by Matthias Urlichs <smurf@smurf.noris.de>, with help from -various participants of the git-list <git@vger.kernel.org>. +Problems related to timestamps: + + * 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 + more than one vendor release) the HEAD contains the wrong content. + * If the timestamp order of different files cross the revision order + within the commit matching time window the order of commits may be + wrong. + +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. + * 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. + +Problems related to tags: + +* Multiple tags on the same revision are not imported. + +If you suspect that any of these issues may apply to the repository you +want to import consider using these alternative tools which proved to be +more stable in practice: -Documentation --------------- -Documentation by Matthias Urlichs <smurf@smurf.noris.de>. +* cvs2git (part of cvs2svn), `http://cvs2svn.tigris.org` +* parsecvs, `http://cgit.freedesktop.org/~keithp/parsecvs` GIT --- diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 3310ae25ff..88d814af0e 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -11,7 +11,7 @@ SYNOPSIS SSH: [verse] -export CVS_SERVER=git-cvsserver +export CVS_SERVER="git cvsserver" 'cvs' -d :ext:user@server/path/repo.git co <HEAD_name> pserver (/etc/inetd.conf): @@ -72,19 +72,16 @@ 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 +'git-cvsserver' maps GIT branches to CVS modules. This is very different from what most CVS users would expect since in CVS modules usually represent 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,21 +98,53 @@ 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. +environment variable, you can rename 'git-cvsserver' to `cvs`. Note: Newer CVS versions (>= 1.12.11) also support specifying CVS_SERVER directly in CVSROOT like ------ -cvs -d ":ext;CVS_SERVER=git-cvsserver:user@server/path/repo.git" co <HEAD_name> +cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name> ------ This has the advantage that it will be saved in your 'CVS/Root' files and you don't need to worry about always setting the correct environment -variable. SSH users restricted to git-shell don't need to override the default -with CVS_SERVER (and shouldn't) as git-shell understands `cvs` to mean -git-cvsserver and pretends that the other end runs the real cvs better. +variable. SSH users restricted to 'git-shell' don't need to override the default +with CVS_SERVER (and shouldn't) as 'git-shell' understands `cvs` to mean +'git-cvsserver' and pretends that the other end runs the real 'cvs' better. -- 2. For each repo that you want accessible from CVS you need to edit config in the repo and add the following section. @@ -128,11 +157,14 @@ git-cvsserver and pretends that the other end runs the real cvs better. logfile=/path/to/logfile ------ -Note: you need to ensure each user that is going to invoke git-cvsserver has +Note: you need to ensure each user that is going to invoke 'git-cvsserver' has write access to the log file and to the database (see <<dbbackend,Database Backend>>. If you want to offer write access over SSH, the users of course also need write access to the git repository itself. +You also need to ensure that each repository is "bare" (without a git index +file) for `cvs commit` to work. See linkgit:gitcvs-migration[7]. + [[configaccessmethod]] All configuration variables can also be overridden for a specific method of access. Valid method names are "ext" (for SSH access) and "pserver". The @@ -150,12 +182,12 @@ allowing access over SSH. automatically saving it in your 'CVS/Root' files, then you need to set them explicitly in your environment. CVSROOT should be set as per normal, but the directory should point at the appropriate git repo. As above, for SSH clients - _not_ restricted to git-shell, CVS_SERVER should be set to git-cvsserver. + _not_ restricted to 'git-shell', CVS_SERVER should be set to 'git-cvsserver'. + -- ------ export CVSROOT=:ext:user@server:/var/git/project.git - export CVS_SERVER=git-cvsserver + export CVS_SERVER="git cvsserver" ------ -- 4. For SSH clients that will make commits, make sure their server-side @@ -178,36 +210,47 @@ allowing access over SSH. Database Backend ---------------- -git-cvsserver uses one database per git head (i.e. CVS module) to -store information about the repository for faster access. The -database doesn't contain any persistent data and can be completely -regenerated from the git repository at any time. The database -needs to be updated (i.e. written to) after every commit. +'git-cvsserver' uses one database per git head (i.e. CVS module) to +store information about the repository to maintain consistent +CVS revision numbers. The database needs to be +updated (i.e. written to) after every commit. -If the commit is done directly by using git (as opposed to -using git-cvsserver) the update will need to happen on the -next repository access by git-cvsserver, independent of +If the commit is done directly by using `git` (as opposed to +using 'git-cvsserver') the update will need to happen on the +next repository access by 'git-cvsserver', independent of access method and requested operation. That means that even if you offer only read access (e.g. by using -the pserver method), git-cvsserver should have write access to +the pserver method), 'git-cvsserver' should have write access to the database to work reliably (otherwise you need to make sure -that the database is up-to-date any time git-cvsserver is executed). +that the database is up-to-date any time 'git-cvsserver' is executed). By default it uses SQLite databases in the git directory, named `gitcvs.<module_name>.sqlite`. Note that the SQLite backend creates temporary files in the same directory as the database file on write so it might not be enough to grant the users using -git-cvsserver write access to the database file without granting +'git-cvsserver' write access to the database file without granting 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 +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 +branch it would have picked if it had been run incrementally +pre-merge. So if you have to fully or partially (from old +backup) regenerate the database, you should be suspicious +of pre-existing CVS sandboxes. + You can configure the database backend with the following configuration variables: Configuring database backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -git-cvsserver uses the Perl DBI module. Please also read +'git-cvsserver' uses the Perl DBI module. Please also read its documentation if changing these variables, especially about `DBI->connect()`. @@ -259,10 +302,25 @@ In `dbdriver` and `dbuser` you can use the following variables: %a:: access method (one of "ext" or "pserver") %u:: - Name of the user running git-cvsserver. + Name of the user running 'git-cvsserver'. If no name can be determined, the numeric uid is used. +ENVIRONMENT +----------- + +These variables obviate the need for command-line options in some +circumstances, allowing easier restricted usage through git-shell. + +GIT_CVSSERVER_BASE_PATH takes the place of the argument to --base-path. + +GIT_CVSSERVER_ROOT specifies a single-directory whitelist. The +repository must still be configured to allow access through +git-cvsserver, as described above. + +When these environment variables are set, the corresponding +command-line arguments may not be used. + Eclipse CVS Client Notes ------------------------ @@ -280,13 +338,13 @@ 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 offer. In that case CVS_SERVER is ignored, and you will have to replace -the cvs utility on the server with git-cvsserver or manipulate your `.bashrc` -so that calling 'cvs' effectively calls git-cvsserver. +the cvs utility on the server with 'git-cvsserver' or manipulate your `.bashrc` +so that calling 'cvs' effectively calls 'git-cvsserver'. Clients known to work --------------------- @@ -308,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 @@ -328,30 +383,13 @@ is left blank. But if `gitcvs.allbinary` is set to "guess", then the correct '-k' mode will be guessed based on the contents of the file. -For best consistency with cvs, it is probably best to override the +For best consistency with 'cvs', it is probably best to override the defaults by setting `gitcvs.usecrlfattr` to true, and `gitcvs.allbinary` to "guess". 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-cvsserver' depends on DBD::SQLite. GIT --- diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 344f24ea59..31b28fc29f 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -8,15 +8,16 @@ git-daemon - A really simple server for git repositories SYNOPSIS -------- [verse] -'git-daemon' [--verbose] [--syslog] [--export-all] - [--timeout=n] [--init-timeout=n] [--strict-paths] - [--base-path=path] [--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...] +'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>...] DESCRIPTION ----------- @@ -27,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:: +--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 @@ -77,37 +78,43 @@ 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 on an a specific IP address or hostname. IP addresses can - be either an IPv4 address or an IPV6 address if supported. If IPv6 +--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:: - 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:: - Timeout for specific client sub-requests. This includes the time - it takes for the server to process the sub-request and time spent - waiting for 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>:: + Maximum number of concurrent clients, defaults to 32. Set it to + zero for no limit. --syslog:: Log to syslog instead of stderr. Note that this option does not imply --verbose, thus by default only error conditions will be logged. --user-path:: ---user-path=path:: - Allow ~user notation to be used in requests. When +--user-path=<path>:: + Allow {tilde}user notation to be used in requests. When specified with no parameter, requests to - git://host/~alice/foo is taken as a request to access + git://host/{tilde}alice/foo is taken as a request to access 'foo' repository in the home directory of user `alice`. If `--user-path=path` is specified, the same request is taken as a request to access `path/foo` repository in @@ -124,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 @@ -138,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 an configuration + 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 @@ -164,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 @@ -199,28 +216,28 @@ $ 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: + ------------------------------------------------ - git stream tcp nowait nobody /usr/bin/git-daemon - git-daemon --inetd --verbose --export-all + git stream tcp nowait nobody /usr/bin/git + git daemon --inetd --verbose --export-all /pub/foo /pub/bar ------------------------------------------------ -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: + ------------------------------------------------ - git stream tcp nowait nobody /usr/bin/git-daemon - git-daemon --inetd --verbose --export-all + git stream tcp nowait nobody /usr/bin/git + git daemon --inetd --verbose --export-all --interpolated-path=/pub/%H%D /pub/www.example.org/software /pub/www.example.com/software @@ -235,13 +252,13 @@ 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: + ------------------------------------------------ - git-daemon --verbose --export-all + git daemon --verbose --export-all --interpolated-path=/pub/%IP/%D /pub/192.168.1.200/software /pub/10.10.220.23/software @@ -253,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'). @@ -265,14 +282,12 @@ selectively enable/disable services per repository:: ---------------------------------------------------------------- -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>. +ENVIRONMENT +----------- +'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. GIT --- diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 9f6f483186..039cce2e98 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -8,7 +8,9 @@ git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS -------- -'git-describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>... +[verse] +'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>... +'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] DESCRIPTION ----------- @@ -18,19 +20,29 @@ shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the abbreviated object name of the most recent commit. +By default (without --all or --tags) `git describe` only shows +annotated tags. For more information about creating annotated tags +see the -a and -s options to linkgit:git-tag[1]. OPTIONS ------- -<committish>:: - The object name of the committish. +<committish>...:: + Committish object names to describe. + +--dirty[=<mark>]:: + Describe the working tree. + It means describe HEAD and appends <mark> (`-dirty` by + default) if the working tree is dirty. --all:: Instead of using only the annotated tags, use any ref - found in `.git/refs/`. + found in `.git/refs/`. This option enables matching + any known branch, remote-tracking branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. + found in `.git/refs/tags`. This option enables matching + a lightweight (non-annotated) tag. --contains:: Instead of finding the tag that predates the commit, find @@ -38,8 +50,10 @@ OPTIONS Automatically implies --tags. --abbrev=<n>:: - Instead of using the default 8 hexadecimal digits as the - abbreviated object name, use <n> digits. + Instead of using the default 7 hexadecimal digits as the + abbreviated object name, use <n> digits, or as many digits + as needed to form a unique object name. An <n> of 0 + will suppress long format, only showing the closest tag. --candidates=<n>:: Instead of considering only the 10 most recent tags as @@ -63,8 +77,8 @@ OPTIONS This is useful when you want to see parts of the commit object name in "describe" output, even when the commit in question happens to be a tagged version. Instead of just emitting the tag name, it will - describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2 - that points at object deadbeef....). + describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 + that points at object deadbee....). --match <pattern>:: Only consider tags matching the given pattern (can be used to avoid @@ -78,11 +92,11 @@ EXAMPLES With something like git.git current tree, I get: - [torvalds@g5 git]$ git-describe parent + [torvalds@g5 git]$ git describe parent v1.0.4-14-g2414721 i.e. the current head of my "parent" branch is based on v1.0.4, -but since it has a handful commits on top of that, +but since it has a few commits on top of that, describe has added the number of additional commits ("14") and an abbreviated object name for the commit itself ("2414721") at the end. @@ -91,10 +105,13 @@ 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 + [torvalds@g5 git]$ git describe v1.0.4 v1.0.4 With --all, the command can use branch heads as references, so @@ -103,7 +120,7 @@ the output shows the reference path as well: [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 tags/v1.0.0-21-g975b - [torvalds@g5 git]$ git describe --all HEAD^ + [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^ heads/lt/describe-7-g975b With --abbrev set to 0, the command can be used to find the @@ -112,16 +129,23 @@ closest tagname without any suffix: [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2 tags/v1.0.0 +Note that the suffix you get if you type these commands today may be +longer than what Linus saw above when he ran these commands, as your +git repository may have new commits whose object names begin with +975b that did not exist back then, and "-g975b" suffix alone may not +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. @@ -129,20 +153,9 @@ abbreviation of the input committish's SHA1. If multiple tags were found during the walk then the tag which has the fewest commits different from the input committish will be selected and output. Here fewest commits different is defined as -the number of commits which would be shown by "git log tag..input" +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 <junkio@cox.net>. 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 8a64869d27..906774f0f7 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -8,20 +8,24 @@ git-diff-files - Compares files in the working tree and the index SYNOPSIS -------- -'git-diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] +[verse] +'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] 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 "git-diff-index" and "git-diff-tree". +same as for 'git diff-index' and 'git diff-tree'. OPTIONS ------- include::diff-options.txt[] --1 -2 -3 or --base --ours --theirs, and -0:: +-1 --base:: +-2 --ours:: +-3 --theirs:: +-0:: Diff against the "base" version, "our branch" or "their branch" respectively. With these options, diffs for merged entries are not shown. @@ -40,18 +44,8 @@ omit diff output for unmerged entries and just show "Unmerged". -q:: Remain silent even on nonexistent files -Output format -------------- -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>. +include::diff-format.txt[] GIT --- diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index f6e844fe61..c0b7c581ad 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -8,7 +8,8 @@ git-diff-index - Compares content and mode of blobs between the index and reposi SYNOPSIS -------- -'git-diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] +[verse] +'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] DESCRIPTION ----------- @@ -31,11 +32,9 @@ 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. -Output format -------------- include::diff-format.txt[] Operating Modes @@ -50,31 +49,31 @@ 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 with a "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 *what* you are going to commit, without having to write a new tree object and compare it that way, and to do that, you just do - git-diff-index --cached HEAD + git diff-index --cached HEAD Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had -done an "git-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: +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: - torvalds@ppc970:~/git> git-diff-index --cached HEAD + torvalds@ppc970:~/git> git diff-index --cached HEAD -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c 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 +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 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". @@ -82,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 @@ -118,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 56caeb2d26..1439486e40 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -9,7 +9,7 @@ git-diff-tree - Compares the content and mode of blobs found via two tree object SYNOPSIS -------- [verse] -'git-diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] +'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] [-t] [-r] [-c | --cc] [--root] [<common diff options>] <tree-ish> [<tree-ish>] [<path>...] @@ -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 ------- @@ -43,40 +43,49 @@ include::diff-options.txt[] show tree entry itself as well as subtrees. Implies -r. --root:: - When '--root' is specified the initial commit will be showed as a big + When '--root' is specified the initial commit will be shown as a big creation event. This is equivalent to a diff against the NULL tree. --stdin:: When '--stdin' is specified, the command does not take <tree-ish> arguments from the command line. Instead, it - reads either one <commit> or a pair of <tree-ish> - separated with a single space from its standard input. + reads lines containing either two <tree>, one <commit>, or a + list of <commit> from its standard input. (Use a single space + as separator.) + -When a single commit is given on one line of such input, it compares -the commit with its parents. The following flags further affects its -behavior. This does not apply to the case where two <tree-ish> -separated with a single space are given. +When two trees are given, it compares the first tree with the second. +When a single commit is given, it compares the commit with its +parents. The remaining commits, when given, are used as if they are +parents of the first commit. ++ +When comparing two trees, the ID of both trees (separated by a space +and terminated by a newline) is printed before the difference. When +comparing commits, the ID of the first (or only) commit, followed by a +newline, is printed. ++ +The following flags further 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:: @@ -93,11 +102,11 @@ include::pretty-options.txt[] This flag changes the way a merge commit patch is displayed, in a similar way to the '-c' option. It implies the '-c' and '-p' options and further compresses the patch output - by omitting hunks that show differences from only one - parent, or show the same change from all but one parent - for an Octopus merge. When this optimization makes all - hunks disappear, the commit itself and the commit log - message is not shown, just like in any other "empty diff" case. + by omitting uninteresting hunks whose the contents in the parents + have only two variants and the merge result picks one of them + without modification. When all hunks are uninteresting, the commit + itself and the commit log message is not shown, just like in any other + "empty diff" case. --always:: Show the commit itself and the commit log message even @@ -112,13 +121,13 @@ Limiting Output If you're only interested in differences in a subset of files, for example some architecture-specific files, you might do: - git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 + git diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 and it will only show you what changed in those two directories. Or if you are searching for what changed in just `kernel/sched.c`, just do - git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c + git diff-tree -r <tree-ish> <tree-ish> kernel/sched.c and it will ignore all differences to other files. @@ -129,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: @@ -150,18 +159,8 @@ HEAD commits it finds, which is even more interesting. in case you care). -Output format -------------- -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>. +include::diff-format.txt[] GIT --- diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 7acd428964..f8d0819113 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,14 +8,19 @@ 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>...]:: +'git diff' [--options] [--] [<path>...]:: This form is to view the changes you made relative to the index (staging area for the next commit). In other @@ -23,18 +28,21 @@ 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>...]:: +'git diff' [--options] --cached [<commit>] [--] [<path>...]:: This form is to view the changes you staged for the next 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>...]:: +'git diff' [--options] <commit> [--] [<path>...]:: This form is to view the changes you have in your working tree relative to the named <commit>. You can @@ -42,36 +50,37 @@ forced by --no-index. branch name to compare with the tip of a different branch. -'git-diff' [--options] <commit> <commit> [--] [<path>...]:: +'git diff' [--options] <commit> <commit> [--] [<path>...]:: This is to view the changes between two arbitrary <commit>. -'git-diff' [--options] <commit>..<commit> [--] [<path>...]:: +'git diff' [--options] <commit>..<commit> [--] [<path>...]:: This is synonymous to the previous form. If <commit> on one side is omitted, it will have the same effect as using HEAD instead. -'git-diff' [--options] <commit>\...<commit> [--] [<path>...]:: +'git diff' [--options] <commit>\...<commit> [--] [<path>...]:: This form is to view the changes on the branch containing and up to the second <commit>, starting at a common ancestor - of both <commit>. "git-diff A\...B" is equivalent to - "git-diff $(git-merge-base A B) B". You can omit any one + of both <commit>. "git diff A\...B" is equivalent to + "git diff $(git-merge-base A B) B". You can omit any one of <commit>, which has the same effect as using HEAD instead. 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 ------- @@ -83,8 +92,7 @@ include::diff-options.txt[] the diff to the named paths (you can give directory names and get diff for all files under them). -Output format -------------- + include::diff-format.txt[] EXAMPLES @@ -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 new file mode 100644 index 0000000000..31fc2e3aed --- /dev/null +++ b/Documentation/git-difftool.txt @@ -0,0 +1,123 @@ +git-difftool(1) +=============== + +NAME +---- +git-difftool - Show changes using common diff tools + +SYNOPSIS +-------- +[verse] +'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...] + +DESCRIPTION +----------- +'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. See +linkgit:git-diff[1]. + +OPTIONS +------- +-d:: +--dir-diff:: + Copy the modified files to a temporary location and perform + a directory diff on them. This mode never prompts before + launching the diff tool. + +-y:: +--no-prompt:: + Do not prompt before launching a diff tool. + +--prompt:: + Prompt before each invocation of the diff tool. + This is the default behaviour; the option is provided to + override any configuration settings. + +-t <tool>:: +--tool=<tool>:: + Use the diff tool specified by <tool>. Valid values include + emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help` + for the list of valid <tool> settings. ++ +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' +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 +tool is available in PATH. ++ +Instead of running one of the known diff tools, +'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 +`-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. `$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`. + +--tool-help:: + Print a list of diff tools that may be used with `--tool`. + +-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 +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. + +difftool.<tool>.cmd:: + Specify the command to invoke the specified diff tool. ++ +See the `--tool=<tool>` option above for more details. + +difftool.prompt:: + Prompt before each invocation of the diff tool. + +SEE ALSO +-------- +linkgit:git-diff[1]:: + Show changes between commits, commit and working tree, etc + +linkgit:git-mergetool[1]:: + Run merge conflict resolution tools to resolve merge conflicts + +linkgit:git-config[1]:: + Get and set repository or global options + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 277a547a02..d6487e1ce0 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -8,23 +8,24 @@ git-fast-export - Git data exporter SYNOPSIS -------- -'git-fast-export [options]' | 'git-fast-import' +[verse] +'git fast-export [options]' | 'git fast-import' DESCRIPTION ----------- This program dumps the given revisions in a form suitable to be piped -into linkgit:git-fast-import[1]. +into 'git fast-import'. -You can use it as a human readable bundle replacement (see +You can use it as a human-readable bundle replacement (see linkgit:git-bundle[1]), or as a kind of an interactive -linkgit:git-filter-branch[1]. +'git filter-branch'. OPTIONS ------- --progress=<n>:: Insert 'progress' statements every <n> objects, to be shown by - linkgit:git-fast-import[1] during import. + 'git fast-import' during import. --signed-tags=(verbatim|warn|strip|abort):: Specify how to handle signed tags. Since any transformation @@ -36,6 +37,26 @@ when encountering a signed tag. With 'strip', the tags will be made 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 object is filtered out. + Since revisions and files to export can be limited by path, + tagged objects may be filtered completely. ++ +When asking to 'abort' (which is the default), this program will die +when encountering such a tag. With 'drop' it will omit such tags from +the output. With 'rewrite', if the tagged object is a commit, it will +rewrite the tag to tag an ancestor commit (via parent rewriting; see +linkgit:git-rev-list[1]) + +-M:: +-C:: + Perform move and/or copy detection, as described in the + linkgit:git-diff[1] manual page, and use it to generate + rename and copy commands in the output dump. ++ +Note that earlier versions of this command did not complain and +produced incorrect results if you gave these options. + --export-marks=<file>:: Dumps the internal marks table to <file> when complete. Marks are written one per line as `:markid SHA-1`. Only marks @@ -56,6 +77,36 @@ If the backend uses a similar \--import-marks file, this allows for incremental bidirectional exporting of the repository by keeping the marks the same across runs. +--fake-missing-tagger:: + Some old repositories have tags without a tagger. The + fast-import protocol was pretty strict about that, and did not + allow that. So fake a tagger to be able to fast-import the + output. + +--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 + directory structure or history of a repository without + touching the contents of individual files. Note that the + resulting stream can only be used by a repository which + already contains the necessary objects. + +--full-tree:: + This option will cause fast-export to issue a "deleteall" + directive for each commit followed by a full list of all files + in the commit (as opposed to just listing the files which are + different from the commit's first parent). + +[<git-rev-list-args>...]:: + A list of arguments, acceptable to 'git rev-parse' and + 'git rev-list', that specifies the specific objects and references + to export. For example, `master~10..master` causes the + current master reference to be exported along with all objects + added since its 10th ancestor commit. EXAMPLES -------- @@ -85,19 +136,10 @@ referenced by that revision range contains the string Limitations ----------- -Since linkgit:git-fast-import[1] 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 395c055f95..2620d28b4b 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -8,14 +8,15 @@ git-fast-import - Backend for fast Git data importers SYNOPSIS -------- -frontend | 'git-fast-import' [options] +[verse] +frontend | 'git fast-import' [options] 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 linkgit:git-init[1]) 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,6 +79,36 @@ 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 + 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 + to the .git/info/fast-import directory. However, other + importers may use a different location. + +--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= + options. + +--cat-blob-fd=<fd>:: + Write responses to `cat-blob` and `ls` queries to the + file descriptor <fd> instead of `stdout`. Allows `progress` + output intended for the end-user to be separated from other + output. + +--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 @@ -82,11 +116,11 @@ 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 linkgit:git-pack-objects[1]. + to 'git pack-objects'. --quiet:: Disable all non-fatal output, making fast-import silent when it - is successful. This option disables the output shown by + is successful. This option disables the output shown by \--stats. --stats:: @@ -124,9 +158,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. @@ -138,7 +172,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. @@ -170,7 +204,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 @@ -220,7 +255,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 linkgit:git-am[1] 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 @@ -253,10 +288,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 -linkgit:git-update-index[1]. +'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 @@ -303,6 +338,30 @@ 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. + +`option`:: + Specify any of the options listed under OPTIONS that do not + change stream semantic to suit the frontend's needs. This + command is optional and is not needed to perform an import. + `commit` ~~~~~~~~ Create or update a branch with a new commit, recording one logical @@ -311,12 +370,12 @@ change to the project. .... 'commit' SP <ref> LF mark? - ('author' SP <name> SP LT <email> GT SP <when> LF)? - 'committer' SP <name> SP LT <email> GT SP <when> LF + ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? + 'committer' (SP <name>)? SP LT <email> GT SP <when> LF data ('from' SP <committish> LF)? ('merge' SP <committish> LF)? - (filemodify | filedelete | filecopy | filerename | filedeleteall)* + (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)* LF? .... @@ -339,14 +398,13 @@ commit message use a 0 length data. Commit messages are free-form and are not interpreted by Git. Currently they must be encoded in UTF-8, as fast-import does not permit other encodings to be specified. -Zero or more `filemodify`, `filedelete`, `filecopy`, `filerename` -and `filedeleteall` commands +Zero or more `filemodify`, `filedelete`, `filecopy`, `filerename`, +`filedeleteall` and `notemodify` commands may be included to update the contents of the branch prior to creating the commit. These commands may be supplied in any order. However it is recommended that a `filedeleteall` command precede -all `filemodify`, `filecopy` and `filerename` commands in the same -commit, as `filedeleteall` -wipes the branch clean (see below). +all `filemodify`, `filecopy`, `filerename` and `notemodify` commands in +the same commit, as `filedeleteall` wipes the branch clean (see below). The `LF` after the command is optional (it used to be required). @@ -368,8 +426,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. @@ -398,7 +456,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. @@ -414,16 +472,16 @@ 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: ---- from refs/heads/branch^0 ---- -The `{caret}0` suffix is necessary as fast-import does not permit a branch to +The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the -`from` command is even read from the input. Adding `{caret}0` will force +`from` command is even read from the input. Adding `^0` will force fast-import to resolve the commit through Git's revision parsing library, rather than its internal branch table, thereby loading in the existing value of the branch. @@ -457,9 +515,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. @@ -481,6 +541,11 @@ in octal. Git only supports the following modes: what you want. * `100755` or `755`: A normal, but executable, file. * `120000`: A symlink, the content of the file will be the link target. +* `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). @@ -500,6 +565,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` @@ -592,6 +659,45 @@ more memory per active branch (less than 1 MiB for even most large projects); so frontends that can easily obtain only the affected paths for a commit are encouraged to do so. +`notemodify` +^^^^^^^^^^^^ +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 + `blob` command. The frontend just needs to connect it to the + commit that is to be annotated. ++ +.... + 'N' SP <dataref> SP <committish> LF +.... ++ +Here `<dataref>` can 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. + +Inline data format:: + The data content for the note has not been supplied yet. + The frontend wants to supply it as part of this modify + command. ++ +.... + 'N' SP 'inline' SP <committish> LF + data +.... ++ +See below for a detailed description of the `data` command. + +In both formats `<committish>` is any of the commit specification +expressions also accepted by `from` (see above). + `mark` ~~~~~~ Arranges for fast-import to save a reference to the current object, allowing @@ -621,7 +727,7 @@ lightweight (non-annotated) tags see the `reset` command below. .... 'tag' SP <name> LF 'from' SP <committish> LF - 'tagger' SP <name> SP LT <email> GT SP <when> LF + 'tagger' (SP <name>)? SP LT <email> GT SP <when> LF data .... @@ -654,7 +760,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 linkgit:git-tag[1] process. +with the standard 'git tag' process. `reset` ~~~~~~~ @@ -700,7 +806,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` @@ -803,13 +909,212 @@ Callers may wish to process the output through a tool such as sed to remove the leading part of the line, for example: ==== - frontend | git-fast-import | sed 's/^progress //' + frontend | git fast-import | sed 's/^progress //' ==== 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. +`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. + +.... + 'cat-blob' SP <dataref> LF +.... + +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. + +Output uses the same format as `git cat-file --batch`: + +==== + <sha1> SP 'blob' SP <size> LF + <contents> LF +==== + +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. + +See ``Responses To Commands'' below for details about how to read +this output safely. + +`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 +.... + +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> -- <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 +==== + +See ``Responses To Commands'' below for details about how to read +this output safely. + +`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` +~~~~~~~~ +Processes the specified option so that git fast-import behaves in a +way that suits the frontend's needs. +Note that options specified by the frontend are overridden by any +options the user may specify to git fast-import itself. + +.... + 'option' SP <option> LF +.... + +The `<option>` part of the command may contain any of the options +listed in the OPTIONS section that do not change import semantics, +without the leading '--' and is treated in the same way. + +Option commands must be the first commands on the input (not counting +feature commands), to give an option command after any non-option +command is an error. + +The following commandline options change import semantics and may therefore +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. + +Responses To Commands +--------------------- +New objects written by fast-import are not available immediately. +Most fast-import commands have no visible effect until the next +checkpoint (or completion). The frontend can send commands to +fill fast-import's input pipe without worrying about how quickly +they will take effect, which improves performance by simplifying +scheduling. + +For some frontends, though, it is useful to be able to read back +data from the current repository as it is being updated (for +example when the source material describes objects in terms of +patches to be applied to previously imported objects). This can +be accomplished by connecting the frontend and fast-import via +bidirectional pipes: + +==== + mkfifo fast-import-output + frontend <fast-import-output | + git fast-import >fast-import-output +==== + +A frontend set up this way can use `progress`, `ls`, and `cat-blob` +commands to read information from the import in progress. + +To avoid deadlock, such frontends must completely consume any +pending output from `progress`, `ls`, and `cat-blob` before +performing writes to fast-import that might block. + Crash Reports ------------- If fast-import is supplied invalid input it will terminate with a @@ -851,7 +1156,7 @@ An example crash: M 777 inline bob END_OF_INPUT - $ git-fast-import <in + $ git fast-import <in fatal: Corrupt mode: M 777 inline bob fast-import: dumping crash report to .git/fast_import_crash_8434 @@ -955,7 +1260,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 linkgit:git-blame[1] to track +Doing so will allow tools such as 'git blame' to track through the real commit history and properly annotate the source files. @@ -984,7 +1289,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 linkgit:git-repack[1]. +\--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. @@ -1108,14 +1413,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 282fcaf17f..474fa307a0 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 -------- -'git-fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...] +[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 linkgit:git-fetch[1] which is a -higher level wrapper of this command instead. +Usually you would want to use 'git fetch', which is a +higher level wrapper of this command, instead. -Invokes 'git-upload-pack' on a potentially remote repository, +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 @@ -31,21 +32,31 @@ OPTIONS --all:: Fetch all remote refs. +--stdin:: + Take the list of refs from stdin, one per line. If there + are refs specified on the command line in addition to this + option, then the refs from stdin are processed after those + on the command line. ++ +If '--stateless-rpc' is specified together with this option then +the list of refs must be in packet format (pkt-line). Each ref must +be in a separate packet, and the list must end with a flush packet. + -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 +101,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 489b2b17e6..b41d7c1de1 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -8,19 +8,23 @@ git-fetch - Download objects and refs from another repository SYNOPSIS -------- -'git-fetch' <options> <repository> <refspec>... +[verse] +'git fetch' [<options>] [<repository> [<refspec>...]] +'git fetch' [<options>] <group> +'git fetch' --multiple [<options>] [(<repository> | <group>)...] +'git fetch' --all [<options>] DESCRIPTION ----------- -Fetches named heads or tags from another repository, along with -the objects necessary to complete them. +Fetches named heads or tags from one or more other repositories, +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 @@ -28,6 +32,10 @@ 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 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]). OPTIONS ------- @@ -37,19 +45,47 @@ include::pull-fetch-param.txt[] include::urls-remotes.txt[] -SEE ALSO --------- -linkgit:git-pull[1] +EXAMPLES +-------- -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net> +* Update the remote-tracking branches: ++ +------------------------------------------------ +$ git fetch origin +------------------------------------------------ ++ +The above command copies all branches from the remote refs/heads/ +namespace and stores them to the local refs/remotes/origin/ namespace, +unless the branch.<name>.fetch option is used to specify a non-default +refspec. + +* Using refspecs explicitly: ++ +------------------------------------------------ +$ git fetch origin +pu:pu maint:tmp +------------------------------------------------ ++ +This updates (or creates, as necessary) branches `pu` and `tmp` in +the local repository by fetching from the branches (respectively) +`pu` and `maint` from the remote repository. ++ +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. -Documentation -------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-pull[1] GIT --- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index ea77f1fce5..81f58234a7 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -8,12 +8,13 @@ git-filter-branch - Rewrite branches SYNOPSIS -------- [verse] -'git-filter-branch' [--env-filter <command>] [--tree-filter <command>] +'git filter-branch' [--env-filter <command>] [--tree-filter <command>] [--index-filter <command>] [--parent-filter <command>] [--msg-filter <command>] [--commit-filter <command>] [--tag-name-filter <command>] [--subdirectory-filter <directory>] + [--prune-empty] [--original <namespace>] [-d <directory>] [-f | --force] - [<rev-list options>...] + [--] [<rev-list options>...] DESCRIPTION ----------- @@ -31,12 +32,18 @@ changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. +*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +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 be able to easily push and distribute the rewritten branch on top of the original branch. Please do not use this command if you do not know the full implications, and avoid using it anyway, if a simple single commit -would suffice to fix your problem. +would suffice to fix your problem. (See the "RECOVERING FROM UPSTREAM +REBASE" section in linkgit:git-rebase[1] for further information about +rewriting published history.) Always verify that the rewritten version is correct: The original refs, if different from the rewritten ones, will be stored in the namespace @@ -75,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>:: @@ -89,13 +96,15 @@ OPTIONS --index-filter <command>:: This is the filter for rewriting the index. It is similar to the tree filter but does not check out the tree, which makes it much - faster. For hairy cases, see linkgit:git-update-index[1]. + faster. Frequently used with `git rm --cached + --ignore-unmatch ...`, see EXAMPLES below. For hairy + cases, see linkgit:git-update-index[1]. --parent-filter <command>:: This is the filter for rewriting the commit's parent list. It will receive the parent string on stdin and shall output the new parent string on stdout. The parent string is in - a format accepted by linkgit:git-commit-tree[1]: empty for + the format described in linkgit:git-commit-tree[1]: empty for the initial commit, "-p parent" for a normal commit and "-p parent1 -p parent2 -p parent3 ..." for a merge commit. @@ -108,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 - linkgit:git-commit-tree[1] 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 @@ -119,7 +128,11 @@ 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 linkgit:git-rebase[1] 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 +and that makes no change to the tree. --tag-name-filter <command>:: This is the filter for rewriting tag names. When passed, @@ -147,7 +160,17 @@ 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. + project root. Implies <<Remap_to_ancestor>>. + +--prune-empty:: + Some kind of filters will generate empty commits, that left the tree + untouched. This switch allow git-filter-branch to ignore such + commits. Though, this switch only applies for commits that have one + and only one parent, it will hence keep merges points. Also, this + option is not compatible with the use of '--commit-filter'. Though you + just need to use the function 'git_commit_non_empty_tree "$@"' instead + of the `git commit-tree "$@"` idiom in your commit filter to make that + happen. --original <namespace>:: Use this option to set the namespace where the original commits @@ -163,15 +186,26 @@ to other tags will be rewritten to point to the underlying commit. -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>:: - When options are given after the new branch name, they will - be passed to linkgit:git-rev-list[1]. Only commits in the resulting - output will be filtered, although the filtered commits can still - reference parents which are outside of that set. +<rev-list options>...:: + 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. 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 @@ -188,14 +222,29 @@ 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. -A significantly faster version: +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 +history, so we also add `--ignore-unmatch`: -------------------------------------------------------------------------- -git filter-branch --index-filter 'git update-index --remove filename' HEAD +git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD -------------------------------------------------------------------------- Now, you will get the rewritten history saved in HEAD. +To rewrite the repository to look as if `foodir/` had been its project +root, and discard all other history: + +------------------------------------------------------- +git filter-branch --subdirectory-filter foodir -- --all +------------------------------------------------------- + +Thus you can, e.g., turn a library subdirectory into a repository of +its own. Note the `--` that separates 'filter-branch' options from +revision options, and the `--all` to rewrite all branches and tags. + To set a commit (which typically is at the tip of another history) to be the parent of the current initial commit, in order to paste the other history behind the current history: @@ -255,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: ------------------------------------------------------- @@ -269,10 +318,20 @@ range in addition to the new branch name. The new branch name will point to the top-most revision that a 'git rev-list' of this range will print. +If you need to add 'Acked-by' lines to, say, the last 10 commits (none +of which is a merge), use this command: + +-------------------------------------------------------- +git filter-branch --msg-filter ' + cat && + echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>" +' HEAD~10..HEAD +-------------------------------------------------------- + *NOTE* the changes introduced by the commits, and which are not reverted by subsequent commits, will still be in the rewritten branch. If you want to throw out _changes_ together with the commits, you should use the -interactive mode of linkgit:git-rebase[1]. +interactive mode of 'git rebase'. Consider this history: @@ -300,21 +359,52 @@ 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 --------------------------------------------------------------- -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. +Checklist for Shrinking a Repository +------------------------------------ + +git-filter-branch is often used to get rid of a subset of files, +usually with some combination of `--index-filter` and +`--subdirectory-filter`. People expect the resulting repository to +be smaller than the original, but you need a few more steps to +actually make it smaller, because git tries hard not to lose your +objects until you tell it to. First make sure that: + +* You really removed all variants of a filename, if a blob was moved + over its lifetime. `git log --name-only --follow --all -- filename` + can help you find renames. + +* You really filtered all refs: use `--tag-name-filter cat -- --all` + when calling git-filter-branch. + +Then there are two ways to get a smaller repository. A safer way is +to clone, that keeps your original intact. + +* Clone it with `git clone file:///path/to/repo`. The clone + will not have the removed objects. See linkgit:git-clone[1]. (Note + that cloning with a plain path just hardlinks everything!) + +If you really don't want to clone it, for whatever reasons, check the +following points instead (in this order). This is a very destructive +approach, so *make a backup* or go back to cloning it. You have been +warned. + +* Remove the original refs backed up by git-filter-branch: say `git + for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git + update-ref -d`. + +* Expire all reflogs with `git reflog expire --expire=now --all`. + +* Garbage collect all unreferenced objects with `git gc --prune=now` + (or if your git-gc is not new enough to support arguments to + `--prune`, use `git repack -ad; git prune` instead). GIT --- diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 2a7cfb980b..3a0f55ec8e 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,25 +9,27 @@ 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 script is intended mostly for internal use by scripts -automatically invoking `git-merge`. +This command is intended mostly for internal use by scripts +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 @@ -46,9 +53,16 @@ OPTIONS CONFIGURATION ------------- +merge.branchdesc:: + In addition to branch names, populate the log message with + the branch description text associated with them. Defaults + to false. + 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 +72,6 @@ SEE ALSO -------- linkgit:git-merge[1] - -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -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 b347bfbb14..c872b883ba 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -8,15 +8,15 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- [verse] -'git-for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] - [--sort=<key>]\* [--format=<format>] [<pattern>...] +'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] + [(--sort=<key>)...] [--format=<format>] [<pattern>...] DESCRIPTION ----------- Iterate over all refs that match `<pattern>` and show them according to the given `<format>`, after sorting them according -to the given set of `<key>`. If `<max>` is given, stop after +to the given set of `<key>`. If `<count>` is given, stop after showing that many refs. The interpolated values in `<format>` can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. @@ -47,9 +47,9 @@ OPTIONS `xx`; for example `%00` interpolates to `\0` (NUL), `%09` to `\t` (TAB) and `%0a` to `\n` (LF). -<pattern>:: +<pattern>...:: If one or more patterns are given, only refs are shown that - match againt at least one pattern, either using fnmatch(3) or + match against at least one pattern, either using fnmatch(3) or literally, in the latter case matching completely or from the beginning up to a slash. @@ -74,15 +74,24 @@ For all objects, the following names can be used: refname:: The name of the ref (the part after $GIT_DIR/). + For a non-ambiguous short name of the ref append `:short`. + The option core.warnAmbiguousRefs is used to select the strict + abbreviation mode. 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'' + from the displayed ref. Respects `:short` in the same way as + `refname` above. In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can @@ -92,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`). @@ -114,12 +124,12 @@ EXAMPLES -------- An example directly producing formatted text. Show the most recent -3 tagged commits:: +3 tagged commits: ------------ #!/bin/sh -git-for-each-ref --count=3 --sort='-*authordate' \ +git for-each-ref --count=3 --sort='-*authordate' \ --format='From: %(*authorname) %(*authoremail) Subject: %(*subject) Date: %(*authordate) @@ -131,11 +141,11 @@ 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 -git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \ +git for-each-ref --shell --format="ref=%(refname)" refs/heads | \ while read entry do eval "$entry" @@ -145,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 @@ -189,9 +199,21 @@ Its message reads as: fi ' -eval=`git-for-each-ref --shell --format="$fmt" \ +eval=`git for-each-ref --shell --format="$fmt" \ --sort='*objecttype' \ --sort=-taggerdate \ 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 4dafa39a92..04c7346e3e 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -9,16 +9,19 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git-format-patch' [-k] [-o <dir> | --stdout] [--thread] - [--attach[=<boundary>] | --inline[=<boundary>]] - [-s | --signoff] [<common diff options>] +'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout] + [--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> ] DESCRIPTION @@ -27,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 linkgit:git-am[1]. +for use with 'git am'. There are two ways to specify which commits to operate on. @@ -36,34 +39,33 @@ 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. -A single commit, when interpreted as a <revision range> -expression, means "everything that leads to that commit", but -if you write 'git format-patch <commit>', the previous rule -applies to that command line and you do not get "everything -since the beginning of the time". If you want to format -everything since project inception to one commit, say "git -format-patch \--root <commit>" to make it clear that it is the -latter case. +The first rule takes precedence in the case of a single <commit>. To +apply the second rule, i.e., format everything since the beginning of +history up until <commit>, use the '\--root' option: `git format-patch +--root <commit>`. If you want to format only <commit> itself, you +can do this with `git format-patch -1 <commit>`. By default, each output file is numbered sequentially from 1, and uses the first line of the commit message (massaged for pathname safety) as -the filename. With the --numbered-files option, the output file names +the filename. With the `--numbered-files` option, the output file names will only be numbers, without the first line of the commit appended. The names of the output files are printed to standard -output, unless the --stdout option is specified. +output, unless the `--stdout` option is specified. -If -o is specified, output files are created in <dir>. Otherwise +If `-o` is specified, output files are created in <dir>. Otherwise they are created in the current working directory. -If -n is specified, instead of "[PATCH] Subject", the first line -is formatted as "[PATCH n/m] Subject". +By default, the subject of a single patch is "[PATCH] First Line" and +the subject when multiple patches are output is "[PATCH n/m] First +Line". To force 1/1 to be added for a single patch, use `-n`. To omit +patch numbers from the subject, use `-N`. -If given --thread, git-format-patch will generate In-Reply-To and -References headers to make the second and subsequent patch mails appear -as replies to the first mail; this also generates a Message-Id header to +If given `--thread`, `git-format-patch` will generate `In-Reply-To` and +`References` headers to make the second and subsequent patch mails appear +as replies to the first mail; this also generates a `Message-Id` header to reference. OPTIONS @@ -72,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>:: @@ -81,7 +83,7 @@ include::diff-options.txt[] -n:: --numbered:: - Name output in '[PATCH n/m]' format. + Name output in '[PATCH n/m]' format, even with a single patch. -N:: --no-numbered:: @@ -93,7 +95,6 @@ include::diff-options.txt[] --numbered-files:: Output file names will be a simple number sequence without the default first line of the commit appended. - Mutually exclusive with the --stdout option. -k:: --keep-subject:: @@ -112,20 +113,40 @@ include::diff-options.txt[] --attach[=<boundary>]:: Create multipart/mixed attachment, the first part of which is the commit message and the patch itself in the - second part, with "Content-Disposition: attachment". + second part, with `Content-Disposition: attachment`. + +--no-attach:: + Disable the creation of an attachment, overriding the + configuration setting. --inline[=<boundary>]:: Create multipart/mixed attachment, the first part of which is the commit message and the patch itself in the - second part, with "Content-Disposition: inline". - ---thread:: - Add In-Reply-To and References headers to make the second and - subsequent mails appear as replies to the first. Also generates - the Message-Id header to reference. + second part, with `Content-Disposition: inline`. + +--thread[=<style>]:: +--no-thread:: + Controls addition of `In-Reply-To` and `References` headers to + make the second and subsequent mails appear as replies to the + first. Also controls generation of the `Message-Id` header to + reference. ++ +The optional <style> argument can be either `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 +`--in-reply-to`, and the first patch mail, in this order. 'deep' +threading makes every mail a reply to the previous one. ++ +The default is `--no-thread`, unless the 'format.thread' configuration +is set. If `--thread` is specified without a style, it defaults to the +style specified by 'format.thread' if any, or else `shallow`. ++ +Beware that the default for 'git send-email' is to thread emails +itself. If you want `git format-patch` to take care of threading, you +will want to ensure that threading is disabled for `git send-email`. --in-reply-to=Message-Id:: - Make the first mail (or all the mails with --no-thread) appear as a + 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. @@ -140,57 +161,319 @@ include::diff-options.txt[] Instead of the standard '[PATCH]' prefix in the subject line, instead use '[<Subject-Prefix>]'. This allows for useful naming of a patch series, and can be - combined with the --numbered option. + 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 + 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"`. + The negated form `--no-add-header` discards *all* (`To:`, + `Cc:`, and custom) headers added so far from config or command + line. --cover-letter:: - Generate a cover letter template. You still have to fill in - a description, but the shortlog and the diffstat will be - generated for you. + 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 - `--suffix=.txt`. + `--suffix=.txt`. Leaving this empty will remove the `.patch` + suffix. + -Note that you would need to include the leading dot `.` if you -want a filename like `0001-description-of-my-change.patch`, and -the first letter does not have to be a dot. Leaving it empty would -not add any suffix. +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:: - Don't output contents of changes in binary files, just take note - that they differ. Note that this disable the patch to be properly - applied. By default the contents of changes in those files are - encoded in the patch. + Do not output contents of changes in binary files, instead + display a notice that those files changed. Patches generated + using this option cannot be applied properly, but they are + still useful for code review. + +--root:: + Treat the revision argument as a <revision range>, even if it + is just a single commit (that would normally be treated as a + <since>). Note that root commits included in the specified + range are always formatted as creation patches, independently + of this flag. CONFIGURATION ------------- -You can specify extra mail header lines to be added to each message -in the repository configuration, new defaults for the subject prefix -and file suffix, and number patches when outputting more than one. +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 "To" or "Cc:" headers, configure +attachments, and sign off patches with configuration variables. ------------ [format] - headers = "Organization: git-foo\n" - subjectprefix = CHANGE - suffix = .txt - numbered = auto + headers = "Organization: git-foo\n" + 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 +$ git format-patch -k --stdout R1..R2 | git am -3 -k ------------ * Extract all commits which are in the current branch but not in the @@ -206,7 +489,7 @@ For each commit a separate file is created in the current directory. project: + ------------ -$ git format-patch \--root origin +$ git format-patch --root origin ------------ * The same as the previous one: @@ -217,8 +500,8 @@ $ git format-patch -M -B origin + Additionally, it detects and handles renames and complete rewrites intelligently to produce a renaming patch. A renaming patch reduces -the amount of text output, and generally makes it easier to review it. -Note that the "patch" program does not understand renaming patches, so +the amount of text output, and generally makes it easier to review. +Note that non-git "patch" programs won't understand renaming patches, so use it only when you know the recipient uses git to apply your patch. * Extract three topmost commits from the current branch and format them @@ -232,15 +515,6 @@ SEE ALSO -------- linkgit:git-am[1], linkgit:git-send-email[1] - -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -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 6e9f717642..eec4bdb600 100644 --- a/Documentation/git-fsck-objects.txt +++ b/Documentation/git-fsck-objects.txt @@ -8,10 +8,15 @@ git-fsck-objects - Verifies the connectivity and validity of the objects in the SYNOPSIS -------- -'git-fsck-objects' ... +[verse] +'git fsck-objects' ... 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 9846c859cf..bbb25da2dd 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -9,8 +9,9 @@ git-fsck - Verifies the connectivity and validity of the objects in the database SYNOPSIS -------- [verse] -'git-fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] - [--full] [--strict] [--verbose] [--lost-found] [<object>*] +'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] + [--[no-]full] [--strict] [--verbose] [--lost-found] + [--[no-]dangling] [--[no-]progress] [<object>*] DESCRIPTION ----------- @@ -21,14 +22,19 @@ 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. +--dangling:: +--no-dangling:: + Print objects that exist but that are never 'directly' used (default). + `--no-dangling` can be used to omit this information from the output. + --root:: Report root nodes. @@ -52,7 +58,8 @@ index file, all SHA1 references in .git/refs/*, and all reflogs (unless or $GIT_DIR/objects/info/alternates, and in packed git archives found in $GIT_DIR/objects/pack and corresponding pack subdirectories in alternate - object pools. + object pools. This is now default; you can turn it off + with --no-full. --strict:: Enable more strict checking, namely to catch a file mode @@ -71,29 +78,28 @@ index file, all SHA1 references in .git/refs/*, and all reflogs (unless a blob, the contents are written into the file, rather than its object name. -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. - -So for example +--progress:: +--no-progress:: + Progress status is reported on the standard error stream by + default when it is attached to a terminal, unless + --no-progress or --verbose is specified. --progress forces + progress status even if the standard error stream is not + directed to a terminal. - git-fsck --unreachable HEAD $(cat .git/refs/heads/*) +DISCUSSION +---------- -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 -do have a valid tree. +git-fsck 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 reachable from any of the specified head nodes (or the default +set, as mentioned above). Any corrupt objects you will have to find in backups or other archives -(i.e., you can just remove them and do an "rsync" with some other site in +(i.e., you can just remove them and do an 'rsync' with some other site in the hopes that somebody else has the object you have corrupted). -Of course, "valid tree" doesn't mean that it wasn't generated by some -evil person, and the end result might be crap. git is a revision -tracking system, not a quality assurance system ;) - Extracted Diagnostics --------------------- @@ -121,9 +127,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. @@ -141,14 +144,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 6ace615d80..b370b025b8 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -8,20 +8,21 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- -'git-gc' [--aggressive] [--auto] [--quiet] +[verse] +'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] 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 linkgit:git-add[1]. +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,15 +51,23 @@ 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>:: + Prune loose objects older than date (default is 2 weeks ago, + overridable by the config variable `gc.pruneExpire`). This + option is on by default. + +--no-prune:: + Do not prune any loose objects. + --quiet:: Suppress all progress reports. @@ -75,11 +84,21 @@ The optional configuration variable 'gc.reflogExpireUnreachable' can be set to indicate how long historical reflog entries which are not part of the current branch should remain available in this repository. These types of entries are generally created as -a result of using `git commit \--amend` or `git rebase` and are the +a result of using `git commit --amend` or `git rebase` and are the 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. @@ -89,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. @@ -98,7 +117,7 @@ much time is spent optimizing the delta compression of the objects in the repository when the --aggressive option is specified. The larger the value, the more time is spent optimizing the delta compression. See the documentation for the --window' option in linkgit:git-repack[1] for -more details. This defaults to 10. +more details. This defaults to 250. The optional configuration variable 'gc.pruneExpire' controls how old the unreferenced loose objects have to be before they are pruned. The @@ -108,17 +127,24 @@ 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 linkgit:git-filter-branch[1] in -refs/original/, or reflogs (which may references commits in branches +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). 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] @@ -126,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 c13bf98697..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 -------- -'git-get-tar-commit-id' < <tarfile> +[verse] +'git get-tar-commit-id' < <tarfile> DESCRIPTION ----------- Acts as a filter, extracting the commit ID stored in archives created by -linkgit:git-archive[1]. 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 1b646b73f0..3bec036883 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -9,29 +9,64 @@ 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] - [-c | --count] [--all-match] + [(-O | --open-files-in-pager) [<pager>]] + [-z | --null] + [-c | --count] [--all-match] [-q | --quiet] + [--max-depth <depth>] + [--color[=<when>] | --no-color] + [--break] [--heading] [-p | --show-function] [-A <post-context>] [-B <pre-context>] [-C <context>] + [-W | --function-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. Patterns +are lists of one or more search expressions separated by newline +characters. An empty string as search expression matches all lines. + + +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:: @@ -45,6 +80,13 @@ OPTIONS -I:: Don't match the pattern in binary files. +--max-depth <depth>:: + For each <pathspec> given on command line, descend at most <depth> + levels of directories. A negative value means no limit. + This option is ignored if <pathspec> contains active wildcards. + In other words if "a*" matches a directory named "a*", + "*" is matched literally so --max-depth is still effective. + -w:: --word-regexp:: Match the pattern only at word boundary (either begin at the @@ -76,12 +118,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:: @@ -91,29 +139,79 @@ 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:: + Output \0 instead of the character that normally follows a + file name. -c:: --count:: Instead of showing every matched line, show the number of lines that match. --[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. +--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`. + +--break:: + Print an empty line between matches from different files. + +--heading:: + Show the filename above the matches in that file instead of + at the start of each shown line. + +-p:: +--show-function:: + Show the preceding line that contains the function name of + the match, unless the matching line is a function name itself. + The name is determined in the same way as 'git diff' works out + patch hunk headers (see 'Defining a custom hunk-header' in + linkgit:gitattributes[5]). -<num>:: - A shortcut for specifying -C<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'. @@ -131,35 +229,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 'time_t' -- '*.[ch]'`:: + 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 '#define' --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 105397f2bd..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 linkgit:gitk[1], 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. +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'. -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 @@ -34,22 +35,22 @@ blame:: browser:: Start a tree browser showing all files in the specified - commit (or 'HEAD' by default). Files selected through the + commit (or 'HEAD' by default). Files selected through the 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,22 +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 + 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 citool:: +`git gui blame --line=100 Makefile`:: + + Loads annotations as described above and automatically + scrolls the view to center on line '100'. + +`git gui citool`:: Make one commit and return to the shell when it is complete. + This command returns a non-zero exit code if the window was + closed in any way other than by making a commit. + +`git gui citool --amend`:: + + Automatically enter the 'Amend Last Commit' mode of + the interface. -git citool:: +`git gui citool --nocommit`:: - Same as 'git gui citool' (above). + 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 gui browser maint:: +`git citool`:: + + Same as `git gui citool` (above). + +`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 @@ -84,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 @@ -102,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 cf3dce8a4a..4b0a502e8e 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -8,7 +8,9 @@ git-hash-object - Compute object ID and optionally creates a blob from a file SYNOPSIS -------- -'git-hash-object' [-t <type>] [-w] [--stdin | --stdin-paths] [--] <file>... +[verse] +'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>... +'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] < <list-of-paths> DESCRIPTION ----------- @@ -16,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". @@ -35,13 +37,21 @@ OPTIONS --stdin-paths:: Read file names from stdin instead of from the command-line. -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +--path:: + Hash object as it were located at the given path. The location of + file does not directly influence on the hash value, but path is + used to determine what git filters should be applied to the object + before it can be placed to the object database, and, as result of + applying filters, the actual blob put into the object database may + differ from the given file. This option is mainly useful for hashing + temporary files located outside of the working directory or files + read from stdin. + +--no-filters:: + Hash the contents as is, ignoring any input filter that would + 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. GIT --- diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index faecd6bb90..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 @@ -23,7 +24,7 @@ If a git command is named, a manual page for that command is brought up. The 'man' program is used by default for this purpose, but this can be overridden by other options or configuration variables. -Note that 'git --help ...' is identical as 'git help ...' because the +Note that `git --help ...` is identical to `git help ...` because the former is internally converted into the latter. OPTIONS @@ -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 ~~~~~~~~~~ @@ -112,7 +113,9 @@ For example, this configuration: will try to use konqueror first. But this may fail (for example if DISPLAY is not set) and in that case emacs' woman mode will be tried. -If everything fails the 'man' program will be tried anyway. +If everything fails, or if no viewer is configured, the viewer specified +in the GIT_MAN_VIEWER environment variable will be tried. If that +fails too, the 'man' program will be tried anyway. man.<tool>.path ~~~~~~~~~~~~~~~ @@ -169,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 new file mode 100644 index 0000000000..f4e0741c11 --- /dev/null +++ b/Documentation/git-http-backend.txt @@ -0,0 +1,196 @@ +git-http-backend(1) +=================== + +NAME +---- +git-http-backend - Server side implementation of Git over HTTP + +SYNOPSIS +-------- +[verse] +'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 protocol +and the backwards-compatible dumb HTTP protocol, as well as clients +pushing using the smart HTTP protocol. + +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 +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'. + +SERVICES +-------- +These services can be enabled/disabled using the per-repository +configuration file: + +http.getanyfile:: + 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. + It is enabled by default, but a repository can disable it + by setting this configuration item to `false`. + +http.uploadpack:: + 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 + 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 + users, including anonymous users, by setting it to `true`. + +URL TRANSLATION +--------------- +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 +automatically by the web server. + +EXAMPLES +-------- +All of the following examples map 'http://$hostname/git/foo/bar.git' +to '/var/www/git/foo/bar.git'. + +Apache 2.x:: + Ensure mod_cgi, mod_alias, and mod_env are enabled, set + GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and + create a ScriptAlias to the CGI: ++ +---------------------------------------------------------------- +SetEnv GIT_PROJECT_ROOT /var/www/git +SetEnv GIT_HTTP_EXPORT_ALL +ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ +---------------------------------------------------------------- ++ +To enable anonymous read access but authenticated write access, +require authorization with a LocationMatch directive: ++ +---------------------------------------------------------------- +<LocationMatch "^/git/.*/git-receive-pack$"> + AuthType Basic + AuthName "Git Access" + Require group committers + ... +</LocationMatch> +---------------------------------------------------------------- ++ +To require authentication for both reads and writes, use a Location +directive around the repository, or one of its parent directories: ++ +---------------------------------------------------------------- +<Location /git/private> + AuthType Basic + AuthName "Private Git Access" + Require group committers + ... +</Location> +---------------------------------------------------------------- ++ +To serve gitweb at the same url, use a ScriptAliasMatch to only +those URLs that 'git http-backend' can handle, and forward the +rest to gitweb: ++ +---------------------------------------------------------------- +ScriptAliasMatch \ + "(?x)^/git/(.*/(HEAD | \ + info/refs | \ + objects/(info/[^/]+ | \ + [0-9a-f]{2}/[0-9a-f]{38} | \ + pack/pack-[0-9a-f]{40}\.(pack|idx)) | \ + git-(upload|receive)-pack))$" \ + /usr/libexec/git-core/git-http-backend/$1 + +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 + files that are stored on disk. On many systems this may + be more efficient as Apache can ask the kernel to copy the + file contents from the file system directly to the network: ++ +---------------------------------------------------------------- +SetEnv GIT_PROJECT_ROOT /var/www/git + +AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/www/git/$1 +AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1 +ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ +---------------------------------------------------------------- ++ +This can be combined with the gitweb configuration: ++ +---------------------------------------------------------------- +SetEnv GIT_PROJECT_ROOT /var/www/git + +AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/www/git/$1 +AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1 +ScriptAliasMatch \ + "(?x)^/git/(.*/(HEAD | \ + info/refs | \ + objects/info/[^/]+ | \ + git-(upload|receive)-pack))$" \ + /usr/libexec/git-core/git-http-backend/$1 +ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ +---------------------------------------------------------------- + + +ENVIRONMENT +----------- +'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) +* REMOTE_USER +* REMOTE_ADDR +* CONTENT_TYPE +* QUERY_STRING +* REQUEST_METHOD + +The GIT_HTTP_EXPORT_ALL environmental variable may be passed to +'git-http-backend' to bypass the check for the "git-daemon-export-ok" +file in each repository before allowing export of that repository. + +The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and +GIT_COMMITTER_EMAIL to '$\{REMOTE_USER}@http.$\{REMOTE_ADDR\}', +ensuring that any reflogs created by 'git-receive-pack' contain some +identifying information of the remote user who performed the push. + +All CGI environment variables are available to each of the hooks +invoked by the 'git-receive-pack'. + +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-http-fetch.txt b/Documentation/git-http-fetch.txt index 70fb635291..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 -------- -'git-http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url> +[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 d69b20549b..2e67362bd4 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -8,7 +8,8 @@ git-http-push - Push objects over HTTP/DAV to another repository SYNOPSIS -------- -'git-http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] +[verse] +'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] DESCRIPTION ----------- @@ -82,24 +83,15 @@ destination side. Without '--force', the <src> ref is stored at the remote only if <dst> does not exist, or <dst> is a proper subset (i.e. an -ancestor) of <src>. This check, known as "fast forward check", +ancestor) of <src>. This check, known as "fast-forward check", is performed in order to avoid accidentally overwriting the remote ref and lose other peoples' commits from there. -With '--force', the fast forward check is disabled for all refs. +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 f4fdc24283..875d2831a5 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -3,59 +3,156 @@ git-imap-send(1) NAME ---- -git-imap-send - Dump a mailbox from stdin into an imap folder +git-imap-send - Send a collection of patches from stdin to an IMAP folder SYNOPSIS -------- -'git-imap-send' +[verse] +'git imap-send' DESCRIPTION ----------- -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 sent with mail clients that cannot read mailbox -files directly. +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. 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: -git-format-patch --signoff --stdout --attach origin | git-imap-send +git format-patch --signoff --stdout --attach origin | git imap-send CONFIGURATION ------------- -git-imap-send requires the following values in the repository -configuration file (shown with examples): +To use the tool, imap.folder and either imap.tunnel or imap.host must be set +to appropriate values. + +Variables +~~~~~~~~~ + +imap.folder:: + The folder to drop the mails into, which is typically the Drafts + folder. For example: "INBOX.Drafts", "INBOX/Drafts" or + "[Gmail]/Drafts". Required to use imap-send. + +imap.tunnel:: + Command used to setup a tunnel to the IMAP server through which + commands will be piped instead of using a direct network connection + to the server. Required when imap.host is not set to use imap-send. + +imap.host:: + A URL identifying the server. Use a `imap://` prefix for non-secure + connections and a `imaps://` prefix for secure connections. + Ignored when imap.tunnel is set, but required to use imap-send + otherwise. + +imap.user:: + The username to use when logging in to the server. + +imap.pass:: + The password to use when logging in to the server. + +imap.port:: + An integer port number to connect to on the server. + Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. + Ignored when imap.tunnel is set. + +imap.sslverify:: + A boolean to enable/disable verification of the server certificate + used by the SSL/TLS connection. Default is `true`. Ignored when + imap.tunnel is set. + +imap.preformattedHTML:: + A boolean to enable/disable the use of html encoding when sending + a patch. An html encoded patch will be bracketed with <pre> + and have a content type of text/html. Ironically, enabling this + 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 +~~~~~~~~ + +Using tunnel mode: .......................... [imap] - Folder = "INBOX.Drafts" + folder = "INBOX.Drafts" + tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null" +.......................... -[imap] - Tunnel = "ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null" +Using direct mode: +......................... [imap] - Host = imap.server.com - User = bob - Pass = pwd - Port = 143 + folder = "INBOX.Drafts" + host = imap://imap.example.com + user = bob + pass = p4ssw0rd .......................... +Using direct mode with SSL: -BUGS ----- -Doesn't handle lines starting with "From " in the message body. +......................... +[imap] + folder = "INBOX.Drafts" + host = imaps://imap.example.com + user = bob + pass = p4ssw0rd + port = 123 + sslverify = false +.......................... -Author ------- -Derived from isync 1.0.1 by Mike McCormack. +EXAMPLE +------- +To submit patches using GMail's IMAP interface, first, edit your ~/.gitconfig +to specify your account settings: -Documentation --------------- -Documentation by Mike McCormack +--------- +[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 +sent by your email program meets the standards of your project. +Many projects do not like patches to be attached. Some mail +agents will transform patches (e.g. wrap lines, send them as +format=flowed) in ways that make them fail. You will get angry +flames ridiculing you if you don't check this. + +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 + +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 6409363ae5..39e6d0ddd8 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -9,8 +9,8 @@ git-index-pack - Build pack index file for an existing packed archive SYNOPSIS -------- [verse] -'git-index-pack' [-v] [-o <index-file>] <pack-file> -'git-index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>] +'git index-pack' [-v] [-o <index-file>] <pack-file> +'git index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>] [<pack-file>] @@ -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 - linkgit:git-repack[1]. + 'git repack'. --fix-thin:: - It is possible for linkgit:git-pack-objects[1] 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 linkgit:git-repack[1] 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. @@ -78,6 +74,16 @@ OPTIONS --strict:: Die, if the pack contains broken objects or links. +--threads=<n>:: + Specifies the number of threads to spawn when resolving + deltas. This requires that index-pack be compiled with + pthreads otherwise this option is ignored with a warning. + This is meant to reduce packing time on multiprocessor + machines. The required amount of memory for the delta search + window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and use maximum 3 threads. + Note ---- @@ -86,18 +92,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 linkgit:git-repack[1] +.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 439cabb737..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] [--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 792643c809..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>]] +[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 @@ -54,49 +81,51 @@ is given: - 'group' (or 'true'): Make the repository group-writable, (and g+sx, since the git group may be not the primary group of all users). + This is used to loosen the permissions of an otherwise safe umask(2) value. + Note that the umask still applies to the other permission bits (e.g. if + umask is '0022', using 'group' will not remove read privileges from other + (non-group) users). See '0xxx' for how to exactly specify the repository + permissions. - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository readable by all users. - - '0xxx': '0xxx' is an octal number and each file will have mode '0xxx' - Any option except 'umask' can be set using this option. '0xxx' will - override users umask(2) value, and thus, users with a safe umask (0077) - can use this option. '0640' will create a repository which is group-readable - but not writable. '0660' is equivalent to 'group'. + - '0xxx': '0xxx' is an octal number and each file will have mode '0xxx'. + '0xxx' will override users' umask(2) value (and not only loosen permissions + as 'group' and 'all' does). '0640' will create a repository which is + group-readable, but not group-writable or accessible to others. '0660' will + create a repo that is readable and writable to the current user and group, + but inaccessible to others. By default, the configuration flag receive.denyNonFastForwards is enabled in shared repositories, so that you cannot force a non fast-forwarding push into it. +If you name a (possibly non-existent) directory at the end of the command +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. -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 template directory used will (in order): -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 argument given with the `--template` option. -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 contents of the `$GIT_TEMPLATE_DIR` environment variable. + - 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 -------- @@ -105,22 +134,13 @@ Start a new git repository for an existing code base:: + ---------------- $ cd /path/to/my/codebase -$ git-init <1> -$ git-add . <2> +$ git init <1> +$ 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 7da5b8d9a9..f3eef510f2 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -8,13 +8,13 @@ git-instaweb - Instantly browse your working repository in gitweb SYNOPSIS -------- [verse] -'git-instaweb' [--local] [--httpd=<httpd>] [--port=<port>] +'git instaweb' [--local] [--httpd=<httpd>] [--port=<port>] [--browser=<browser>] -'git-instaweb' [--start] [--stop] [--restart] +'git instaweb' [--start] [--stop] [--restart] DESCRIPTION ----------- -A simple script to setup gitweb and a web server for browsing the local +A simple script to set up `gitweb` and a web server for browsing the local repository. OPTIONS @@ -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 lighttpd, apache2 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 db61bc96c7..1f906208f9 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -8,47 +8,58 @@ git-log - Show commit logs SYNOPSIS -------- -'git-log' <option>... +[verse] +'git log' [<options>] [<since>..<until>] [[\--] <path>...] DESCRIPTION ----------- Shows the commit logs. -The command takes options applicable to the linkgit:git-rev-list[1] +The command takes options applicable to the 'git rev-list' command to control what is shown and how, and options applicable to -the linkgit:git-diff-tree[1] 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]. + +--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 + full ref name (including prefix) will be printed. The default option + is 'short'. ---decorate:: - Print out the ref names of any commits that are shown. +--source:: + Print out the ref name given on the command line by which each + commit was reached. --full-diff:: - Without this flag, "git log -p <paths>..." shows commits that + Without this flag, "git log -p <path>..." shows commits that touch the specified paths, and diffs about the same specified paths. With this, the full diff is shown for commits that touch - the specified paths; this means that "<paths>..." limits only + 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 @@ -57,58 +68,123 @@ include::diff-options.txt[] Note that only message is considered, if also a diff is shown its size is not included. -<paths>...:: - Show only commits that affect the specified paths. - +[\--] <path>...:: + 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 4dc475e0de..c406a11001 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -7,7 +7,8 @@ git-lost-found - Recover lost refs that luckily have not yet been pruned SYNOPSIS -------- -'git-lost-found' +[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 560594e25f..4b28292811 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -9,15 +9,15 @@ git-ls-files - Show information about files in the index and the working tree SYNOPSIS -------- [verse] -'git-ls-files' [-z] [-t] [-v] - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\* - (-[c|d|o|i|s|u|k|m])\* +'git ls-files' [-z] [-t] [-v] + (--[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 ----------- @@ -44,16 +44,18 @@ OPTIONS -o:: --others:: - Show other files in the output + Show other (i.e. untracked) files in the output -i:: --ignored:: - Show ignored files in the output. - Note that this also reverses any exclude list present. + Show only ignored files in the output. When showing files in the + index, print only those matched by an exclude pattern. When + showing "other" files, show only those matched by an exclude + pattern. -s:: --stage:: - Show stage files in the output + Show staged contents' object name, mode bits and stage number in the output. --directory:: If a whole directory is classified as "other", show just its @@ -77,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:: @@ -104,9 +107,18 @@ 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 R:: removed/deleted C:: modified/changed @@ -126,9 +138,15 @@ OPTIONS --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only handful hexdigits prefix. + lines, show only a partial prefix. Non default number of digits can be specified with --abbrev=<n>. +--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. @@ -138,19 +156,19 @@ 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, the index records up to three such pairs; one from tree O in stage 1, A in stage 2, and B in stage 3. This information can be used by the user (or the porcelain) to see what should eventually be recorded at the -path. (see git-read-tree for more information on state) +path. (see linkgit:git-read-tree[1] for more information on state) When `-z` option is not used, TAB, LF, and backslash characters in pathnames are represented as `\t`, `\n`, and `\\`, @@ -160,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. @@ -175,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. @@ -191,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 f92f3ca186..7a9b86a58a 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -9,8 +9,8 @@ git-ls-remote - List references in a remote repository SYNOPSIS -------- [verse] -'git-ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] - <repository> <refs>... +'git ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] + [--exit-code] <repository> [<refs>...] DESCRIPTION ----------- @@ -31,11 +31,17 @@ OPTIONS -u <exec>:: --upload-pack=<exec>:: - Specify the full path of linkgit:git-upload-pack[1] on the remote + Specify the full path of 'git-upload-pack' on the remote host. This allows listing references from repositories accessed via 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 <junkio@cox.net> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index d9881fbbbe..16e87fd6dd 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -9,17 +9,29 @@ git-ls-tree - List the contents of a tree object SYNOPSIS -------- [verse] -'git-ls-tree' [-d] [-r] [-t] [-l] [-z] - [--name-only] [--name-status] [--full-name] [--abbrev=[<n>]] - <tree-ish> [paths...] +'git ls-tree' [-d] [-r] [-t] [-l] [-z] + [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]] + <tree-ish> [<path>...] DESCRIPTION ----------- Lists the contents of a given tree object, like what "/bin/ls -a" does -in the current working directory. Note that the usage is subtly different, -though - 'paths' denote 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. +in the current working directory. Note that: + + - the behaviour is slightly different from that of "/bin/ls" in that the + '<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 '<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 + 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. OPTIONS ------- @@ -49,14 +61,18 @@ OPTIONS --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only handful hexdigits prefix. + lines, show only a partial prefix. Non default number of digits can be specified with --abbrev=<n>. --full-name:: Instead of showing the path names relative to the current working directory, show the full path names. -paths:: +--full-tree:: + Do not limit the listing to the current working directory. + Implies --full-name. + +[<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. @@ -66,8 +82,10 @@ Output Format ------------- <mode> SP <type> SP <object> TAB <file> -When the `-z` option is not used, TAB, LF, and backslash characters +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 +'git update-index' expects. When the `-l` option is used, format changes to @@ -77,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 <junkio@cox.net>, -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 183dc1dd75..97e7a8e9e7 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -8,15 +8,16 @@ git-mailinfo - Extracts patch and authorship from a single e-mail message SYNOPSIS -------- -'git-mailinfo' [-k] [-u | --encoding=<encoding>] <msg> <patch> +[verse] +'git mailinfo' [-k|-b] [-u | --encoding=<encoding> | -n] [--scissors] <msg> <patch> DESCRIPTION ----------- -Reading a single e-mail message from the standard input, and +Reads a single e-mail message from the standard input, and writes the commit log message in <msg> file, and the patches in <patch> file. The author name, e-mail and e-mail subject are -written out to the standard output to be used by git-am +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. @@ -24,27 +25,65 @@ command directly. See linkgit:git-am[1] instead. OPTIONS ------- -k:: - Usually the program 'cleans up' the Subject: header line - to extract the title line for the commit log message, - among which (1) remove 'Re:' or 're:', (2) leading - 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. + Usually the program removes email cruft from the Subject: + header line to extract the title line for the commit log + message. This option prevents this munging, and is most + useful when used to read back 'git format-patch -k' output. ++ +Specifically, the following are removed until none of them remain: ++ +-- +* Leading and trailing whitespace. + +* Leading `Re:`, `re:`, and `:`. + +* Leading bracketed strings (between `[` and `]`, usually + `[PATCH]`). +-- ++ +Finally, runs of whitespace are normalized to a single ASCII space +character. + +-b:: + When -k is not in effect, all leading strings bracketed with '[' + and ']' pairs are stripped. This option limits the stripping to + only the pairs whose bracketed string contains the word "PATCH". -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. + +--scissors:: + Remove everything in body before a scissors line. A line that + mainly consists of scissors (either ">8" or "8<") and perforation + (dash "-") marks is called a scissors line, and is used to request + the reader to cut the message at that line. If such a line + appears in the body of the message before the patch, everything + before it (including the scissors line itself) is ignored when + this option is used. ++ +This is useful if you want to begin your message in a discussion thread +with comments and suggestions on the message you are responding to, and to +conclude it with a patch submission, separating the discussion and the +beginning of the proposed commit log message with a scissors line. ++ +This can enabled by default with the configuration option mailinfo.scissors. + +--no-scissors:: + Ignore scissors lines. Useful for overriding mailinfo.scissors settings. <msg>:: The commit log message extracted from e-mail, usually @@ -53,17 +92,6 @@ conversion, even with this flag. <patch>:: The patch extracted from e-mail. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net> - - -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 9a2aedd480..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 <junkio@cox.net> - - -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 bbe8512397..b295bf8330 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -8,34 +8,113 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- -'git-merge-base' [--all] <commit> <commit> +[verse] +'git merge-base' [-a|--all] <commit> <commit>... +'git merge-base' [-a|--all] --octopus <commit>... +'git merge-base' --independent <commit>... DESCRIPTION ----------- -"git-merge-base" finds as good a common ancestor as possible between -the two commits. That is, given two commits A and B 'git-merge-base A -B' will output a commit which is reachable from both A and B through -the parent relationship. +'git merge-base' finds best common ancestor(s) between two commits to use +in a three-way merge. One common ancestor is 'better' than another common +ancestor if the latter is an ancestor of the former. A common ancestor +that does not have any better common ancestor 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. -Given a selection of equally good common ancestors it should not be -relied on to decide in any particular way. +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. -The "git-merge-base" algorithm is still in flux - use the source... +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:: --all:: - Output all common ancestors for the two commits instead of - just one. + Output all merge bases for the commits, instead of just one. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> +DISCUSSION +---------- -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +Given two commits 'A' and 'B', `git merge-base A B` will output a commit +which is reachable from both 'A' and 'B' through the parent relationship. + +For example, with this topology: + + o---o---o---B + / + ---o---1---o---o---o---A + +the merge base between 'A' and 'B' is '1'. + +Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the +merge base between 'A' and a hypothetical commit 'M', which is a merge +between 'B' and 'C'. For example, with this topology: + + o---o---o---o---C + / + / o---o---o---B + / / + ---2---1---o---o---o---A + +the result of `git merge-base A B C` is '1'. This is because the +equivalent topology with a merge commit 'M' between 'B' and 'C' is: + + + o---o---o---o---o + / \ + / o---o---o---o---M + / / + ---2---1---o---o---o---A + +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: + + ---1---o---A + \ / + X + / \ + ---2---o---o---B + +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. + +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 149f131051..d7db2a3737 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -9,23 +9,24 @@ git-merge-file - Run a three-way file merge SYNOPSIS -------- [verse] -'git-merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]] - [-p|--stdout] [-q|--quiet] <current-file> <base-file> <other-file> +'git merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]] + [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>] + <current-file> <base-file> <other-file> DESCRIPTION ----------- -git-file-merge incorporates all changes that lead from the `<base-file>` +'git merge-file' incorporates all changes that lead from the `<base-file>` to `<other-file>` into `<current-file>`. The result ordinarily goes into -`<current-file>`. git-merge-file is useful for combining separate changes +`<current-file>`. 'git merge-file' is useful for combining separate changes to an original. Suppose `<base-file>` is the original, and both -`<current-file>` and `<other-file>` are modifications of `<base-file>`. -Then git-merge-file combines both changes. +`<current-file>` and `<other-file>` are modifications of `<base-file>`, +then 'git merge-file' combines both changes. A conflict occurs if both `<current-file>` and `<other-file>` have changes -in a common segment of lines. If a conflict is found, git-merge-file -normally outputs a warning and brackets the conflict with <<<<<<< and ->>>>>>> lines. A typical conflict will look like this: +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: <<<<<<< A lines in file A @@ -34,13 +35,16 @@ normally outputs a warning and brackets the conflict with <<<<<<< and >>>>>>> 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 -implements all of RCS merge's functionality which is needed by +'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]. @@ -51,7 +55,7 @@ OPTIONS This option may be given up to three times, and specifies labels to be used in place of the corresponding file names in conflict reports. That is, - `git-merge-file -L x -L y -L z a b c` generates output that + `git merge-file -L x -L y -L z a b c` generates output that looks like it came from files x, y and z instead of from files a, b and c. @@ -60,33 +64,28 @@ OPTIONS `<current-file>`. -q:: - Quiet; do not warn about conflicts. + 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 a0ead2bbf3..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 ----------- @@ -29,31 +30,31 @@ OPTIONS Instead of stopping at the first failed merge, do all of them in one shot - continue with merging even when previous merges returned errors, and only return the error code after all the - merges are over. + merges. -q:: - Do not complain about failed merge program (the merge program - failure usually indicates conflicts during merge). This is for + Do not complain about a failed merge program (a merge program + failure usually indicates conflicts during the merge). This is for porcelains which might want to emit custom messages. -If "git-merge-index" is called with multiple <file>s (or -a) then it +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. +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 -RCS "merge" program merge object order. In the above ordering, the +RCS 'merge' program merge object order. In the above ordering, the original is first. But the argument order to the 3-way merge program -"merge" is to have the original in the middle. Don't ask me why. +'merge' is to have the original in the middle. Don't ask me why. Examples: - torvalds@ppc970:~/merge-test> git-merge-index cat MM + torvalds@ppc970:~/merge-test> git merge-index cat MM This is MM from the original tree. # original This is modified MM in the branch A. # merge1 This is modified MM in the branch B. # merge2 @@ -61,26 +62,17 @@ Examples: or - torvalds@ppc970:~/merge-test> git-merge-index cat AA MM + torvalds@ppc970:~/merge-test> git merge-index cat AA MM cat: : No such file or directory This is added AA in the branch A. This is added AA in the branch B. 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 -merge once anything has returned an error (i.e., "cat" returned an error +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 5c9ce641ec..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 <junkio@cox.net> 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 b785e0f6e0..c5f84b6495 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -8,28 +8,21 @@ git-merge-tree - Show three-way merge without touching index SYNOPSIS -------- -'git-merge-tree' <base-tree> <branch1> <branch2> +[verse] +'git merge-tree' <base-tree> <branch1> <branch2> DESCRIPTION ----------- Reads three treeish, and output trivial merge results and conflicting stages to the standard output. This is similar to -what three-way read-tree -m does, but instead of storing the +what three-way 'git read-tree -m' does, but instead of storing the results in the index, the command outputs the entries to the standard output. This is meant to be used by higher level scripts to compute -merge results outside index, and stuff the results back into the +merge results outside of the index, and stuff the results back into the index. For this reason, the output from the command omits -entries that match <branch1> tree. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +entries that match the <branch1> tree. GIT --- diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 55bc367479..3ceefb8a1f 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -9,18 +9,56 @@ git-merge - Join two or more development histories together SYNOPSIS -------- [verse] -'git-merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... - [-m <msg>] <remote> <remote>... -'git-merge' <msg> HEAD <remote>... +'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] + [-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. - -The second syntax (<msg> `HEAD` <remote>) is supported for +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. + +Assume the following history exists and the current branch is +"`master`": + +------------ + A---B---C topic + / + D---E---F---G master +------------ + +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. + +------------ + A---B---C topic + / \ + D---E---F---G---H master +------------ + +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> <remote>`. +new scripts. It is the same as `git merge -m <msg> <commit>...`. + +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. OPTIONS @@ -28,143 +66,256 @@ OPTIONS include::merge-options.txt[] -m <msg>:: - The commit message to be used for the merge commit (in case - it is created). The `git-fmt-merge-msg` script can be used - to give a good default for automated `git-merge` invocations. + 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. + +<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. +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 `<<<` `===` `>>>`. +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`. -<remote>:: - Other branch head merged into our branch. You need at - least one <remote>. Specifying more than one <remote> - obviously means you are trying an Octopus. +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 +--------------------------- + +During a merge, the working tree files are updated to reflect the result +of the merge. Among the changes made to the common ancestor's version, +non-overlapping ones (that is, you changed an area of the file while the +other side left that area intact, or vice versa) are incorporated in the +final result verbatim. When both sides made changes to the same area, +however, git cannot randomly pick one side over the other, and asks you to +resolve it by leaving what both sides did to that area. + +By default, git uses the same style as that is used by "merge" program +from the RCS suite to present such a conflicted hunk, like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed. +<<<<<<< yours:sample.txt +Conflict resolution is hard; +let's go shopping. +======= +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +The area where a pair of conflicting changes happened is marked with markers +`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` +is typically your side, and the part afterwards is typically their side. + +The default format does not show what the original said in the conflicting +area. You cannot tell how many lines are deleted and replaced with +Barbie's remark on your side. The only thing you can tell is that your +side wants to say it is hard and you'd prefer to go shopping, while the +other side wants to claim it is easy. + +An alternative style can be used by setting the "merge.conflictstyle" +configuration variable to "diff3". In "diff3" style, the above conflict +may look like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed. +<<<<<<< yours:sample.txt +Conflict resolution is hard; +let's go shopping. +||||||| +Conflict resolution is hard. +======= +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses +another `|||||||` marker that is followed by the original text. You can +tell that the original just stated a fact, and your side simply gave in to +that statement and gave up, while the other side tried to have a more +positive attitude. You can sometimes come up with a better resolution by +viewing the original. + + +HOW TO RESOLVE CONFLICTS +------------------------ -include::merge-strategies.txt[] +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 merge --abort` + can be used for this. -If you tried a merge which resulted in a complex conflicts and -would want to start over, you can recover with -linkgit:git-reset[1]. + * 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. -CONFIGURATION -------------- -include::merge-config.txt[] +You can work through the conflict with a number of tools: -branch.<name>.mergeoptions:: - Sets default options for merging into branch <name>. The syntax and - supported options are equal to that of git-merge, but option values - containing whitespace characters are currently not supported. - -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 -exactly match the -tree of `HEAD` commit (i.e. the contents of the last commit) when -it happens. In other words, `git-diff --cached HEAD` must -report no changes. - -[NOTE] -This is a bit of a lie. In certain special cases, your index is -allowed to be different from the tree of the `HEAD` commit. The most -notable case is when your `HEAD` commit is already ahead of what -is being merged, in which case your index can have arbitrary -differences from your `HEAD` commit. Also, your index entries -may have differences from your `HEAD` commit that match -the result of a trivial merge (e.g. you received the same patch -from an external source to produce the same result as what you are -merging). For example, if a path did not exist in the common -ancestor and your head commit but exists in the tree you are -merging into your repository, and if you already happen to have -that path exactly in your index, the merge does not have to -fail. - -Otherwise, merge will refuse to do any harm to your repository -(that is, it may fetch the objects from remote, and it may even -update the local branch used to keep track of the remote branch -with `git pull remote rbranch:lbranch`, but your working tree, -`.git/HEAD` pointer and index file are left intact). - -You may have local modifications in the working tree files. In -other words, `git-diff` is allowed to report changes. -However, the merge uses your working tree as the working area, -and in order to prevent the merge operation from losing such -changes, it makes sure that they do not interfere with the -merge. Those complex tables in read-tree documentation define -what it means for a path to "interfere with the merge". And if -your local modifications interfere with the merge, again, it -stops before touching anything. - -So in the above two "failed merge" case, you do not have to -worry about loss of data --- you simply were not ready to do -a merge, so no merge happened at all. You may want to finish -whatever you were in the middle of doing, and retry the same -pull after you are done and ready. - -When things cleanly merge, these things happen: - -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 to match exactly the current `HEAD` commit; otherwise we -will write out your local changes already registered in your -index file along with the merge result, which is not good. -Because 1. involves only the paths different between your -branch and the remote branch you are pulling from during the -merge (which is typically a fraction of the whole tree), you can -have local modifications in your working tree as long as they do -not overlap with what the merge updates. - -When there are conflicts, these things happen: - -1. `HEAD` stays the same. - -2. Cleanly merged paths are updated both in the index file and - in your working tree. + * Use a mergetool. `git mergetool` to launch a graphical + mergetool which will work you through the merge. -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 - can inspect the stages with `git-ls-files -u`). The working - tree files have the result of "merge" program; i.e. 3-way - merge result with familiar conflict markers `<<< === >>>`. + * Look at the diffs. `git diff` will show a three-way diff, + highlighting changes from both the `HEAD` and `MERGE_HEAD` + versions. -4. No other changes are done. 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`. + * 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. -After seeing a conflict, you can do two things: + * 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. - * Decide not to merge. The only clean-up 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` can - be used for this. - * Resolve the conflicts. `git-diff` would report only the - conflicting paths because of the above 2. and 3.. Edit the - working tree files into a desirable shape, `git-add` or `git-rm` - them, to make the index file contain what the merge result - should be, and run `git-commit` to commit the result. +EXAMPLES +-------- +* Merge branches `fixes` and `enhancements` on top of + the current branch, making an octopus merge: ++ +------------------------------------------------ +$ git merge fixes enhancements +------------------------------------------------ + +* Merge branch `obsolete` into the current branch, using `ours` + merge strategy: ++ +------------------------------------------------ +$ git merge -s ours obsolete +------------------------------------------------ + +* Merge branch `maint` into the current branch, but do not make + a new commit automatically: ++ +------------------------------------------------ +$ git merge --no-commit maint +------------------------------------------------ ++ +This can be used when you want to include further changes to the +merge, or want to write your own merge commit message. ++ +You should refrain from abusing this option to sneak substantial +changes into a merge commit. Small fixups like bumping +release/version name would be acceptable. -SEE ALSO --------- -linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], -linkgit:gitattributes[5] +include::merge-strategies.txt[] -Author ------- -Written by Junio C Hamano <junkio@cox.net> +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. -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], +linkgit:gitattributes[5], +linkgit:git-reset[1], +linkgit:git-diff[1], linkgit:git-ls-files[1], +linkgit:git-add[1], linkgit:git-rm[1], +linkgit:git-mergetool[1] GIT --- diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt new file mode 100644 index 0000000000..f98a41b87c --- /dev/null +++ b/Documentation/git-mergetool--lib.txt @@ -0,0 +1,47 @@ +git-mergetool{litdd}lib(1) +========================== + +NAME +---- +git-mergetool--lib - Common git merge tool shell scriptlets + +SYNOPSIS +-------- +[verse] +'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool{litdd}lib"' + +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-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{litdd}lib', your script must set `TOOL_MODE` +to define the operation mode for the functions listed below. +'diff' and 'merge' are valid values. + +FUNCTIONS +--------- +get_merge_tool:: + returns a merge tool. + +get_merge_tool_cmd:: + returns the custom command for a merge tool. + +get_merge_tool_path:: + returns the custom path for a merge tool. + +run_merge_tool:: + launches a merge tool given the tool name and a true/false + flag to indicate whether a merge base is present. + '$MERGED', '$LOCAL', '$REMOTE', and '$BASE' must be defined + for use by the merge tool. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 83525609c6..2a49de7cfe 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -7,43 +7,47 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts SYNOPSIS -------- -'git-mergetool' [--tool=<tool>] [<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 linkgit:git-merge[1]. +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 ------- --t or --tool=<tool>:: +-t <tool>:: +--tool=<tool>:: Use the merge resolution program specified by <tool>. Valid merge tools are: - kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, and opendiff + 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 -by specifying the command line to invoke in a configration +Instead of running one of the known merge tool programs, +'git mergetool' can be customized to run an alternative program +by specifying the command line to invoke in a configuration variable `mergetool.<tool>.cmd`. + -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 @@ -55,18 +59,30 @@ of the file to which the merge tool should write the result of the merge resolution. + If the custom merge tool correctly indicates the success of a -merge resolution with its exit code then the configuration +merge resolution with its exit code, then the configuration variable `mergetool.<tool>.trustExitCode` can be set to `true`. -Otherwise, `git mergetool` will prompt the user to indicate the +Otherwise, 'git mergetool' will prompt the user to indicate the success of the resolution after the custom tool has exited. -Author ------- -Written by Theodore Y Ts'o <tytso@mit.edu> +-y:: +--no-prompt:: + Don't prompt before each invocation of the merge resolution + program. -Documentation --------------- -Documentation by Theodore Y Ts'o. +--prompt:: + Prompt before each invocation of the merge resolution program. + This is the default behaviour; the option is provided to + override any configuration settings. + +TEMPORARY FILES +--------------- +`git mergetool` creates `*.orig` backup files while resolving merges. +These are safe to remove once a file has been merged and its +`git mergetool` session has completed. + +Setting the `mergetool.keepBackup` configuration variable to `false` +causes `git mergetool` to automatically remove the backup as files +are successfully merged. GIT --- diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 232bc1a338..65e167a5c5 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -8,7 +8,8 @@ git-mktag - Creates a tag object SYNOPSIS -------- -'git-mktag' < signature_file +[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 1ddbf00afc..5c6ebdfad9 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -8,12 +8,14 @@ git-mktree - Build a tree-object from ls-tree formatted text SYNOPSIS -------- -'git-mktree' [-z] +[verse] +'git mktree' [-z] [--missing] [--batch] DESCRIPTION ----------- -Reads standard input in non-recursive `ls-tree` output format, -and creates a tree object. The object name of the tree object +Reads standard input in non-recursive `ls-tree` output format, and creates +a tree object. The order of the tree entries is normalised by mktree so +pre-sorting the input is not required. The object name of the tree object built is written to the standard output. OPTIONS @@ -21,13 +23,17 @@ OPTIONS -z:: Read the NUL-terminated `ls-tree -z` output instead. -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +--missing:: + Allow missing objects. The default behaviour (without this option) + is to verify that each tree entry's sha1 identifies an existing + object. This option has no effect on the treatment of gitlink entries + (aka "submodules") which are always allowed to be missing. + +--batch:: + Allow building of more than one tree object before exiting. Each + tree is separated by as single blank line. The final new-line is + optional. Note - if the '-z' option is used, lines are terminated + with NUL. GIT --- diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 339190600a..e3c8448614 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -8,14 +8,15 @@ git-mv - Move or rename a file, a directory, or a symlink SYNOPSIS -------- -'git-mv' <options>... <args>... +[verse] +'git mv' <options>... <args>... DESCRIPTION ----------- This script is used to move or rename a file, directory or symlink. - git-mv [-f] [-n] <source> <destination> - git-mv [-f] [-n] [-k] <source> ... <destination directory> + git mv [-v] [-f] [-n] [-k] <source> <destination> + git mv [-v] [-f] [-n] [-k] <source> ... <destination directory> In the first form, it renames <source>, which must exist and be either a file, symlink or directory, to <destination>. @@ -28,6 +29,7 @@ committed. OPTIONS ------- -f:: +--force:: Force renaming or moving of a file even if the target exists -k:: Skip move or rename actions which would lead to an error @@ -38,16 +40,9 @@ 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>. +-v:: +--verbose:: + Report the names of files as they are moved. GIT --- diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index ffac3f8f56..ad1d1468c9 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -9,13 +9,13 @@ git-name-rev - Find symbolic names for given revs SYNOPSIS -------- [verse] -'git-name-rev' [--tags] [--refs=<pattern>] +'git name-rev' [--tags] [--refs=<pattern>] ( --all | --stdin | <committish>... ) 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 @@ -38,8 +38,7 @@ OPTIONS Instead of printing both the SHA-1 and the name, print only the name. If given with --tags the usual tag prefix of "tags/" is also omitted from the name, matching the output - of linkgit:git-describe[1] more closely. This option - cannot be combined with --stdin. + of `git-describe` more closely. --no-undefined:: Die with error code != 0 when a reference is undefined, @@ -56,11 +55,11 @@ 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 -33db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0.99^0~940 +33db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0.99~940 ------------ Now you are wiser, because you know that it happened 940 revisions before v0.99. @@ -71,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 new file mode 100644 index 0000000000..b95aafae2d --- /dev/null +++ b/Documentation/git-notes.txt @@ -0,0 +1,386 @@ +git-notes(1) +============ + +NAME +---- +git-notes - Add or inspect object notes + +SYNOPSIS +-------- +[verse] +'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 +----------- +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]. + +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 object (defaults to HEAD). + +show:: + 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` 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. + 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> and +Johan Herland <johan@herland.net> + +Documentation +------------- +Documentation by Johannes Schindelin and Johan Herland + +GIT +--- +Part of the linkgit:git[7] suite diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt new file mode 100644 index 0000000000..fe1f49bc6f --- /dev/null +++ b/Documentation/git-p4.txt @@ -0,0 +1,531 @@ +git-p4(1) +========= + +NAME +---- +git-p4 - Import from and submit to Perforce repositories + + +SYNOPSIS +-------- +[verse] +'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... +'git p4 sync' [<sync options>] [<p4 depot path>...] +'git p4 rebase' +'git p4 submit' [<submit options>] [<master branch name>] + + +DESCRIPTION +----------- +This command provides a way to interact with p4 repositories +using git. + +Create a new git repository from an existing p4 repository using +'git p4 clone', giving it one or more p4 depot paths. Incorporate +new commits from p4 changes with 'git p4 sync'. The 'sync' command +is also used to include new branches from other p4 depot paths. +Submit git changes back to p4 using 'git p4 submit'. The command +'git p4 rebase' does a sync plus rebases the current branch onto +the updated p4 remote branch. + + +EXAMPLE +------- +* Clone a repository: ++ +------------ +$ git p4 clone //depot/path/project +------------ + +* Do some work in the newly created git repository: ++ +------------ +$ cd project +$ vi foo.h +$ git commit -a -m "edited foo.h" +------------ + +* Update the git repository with recent changes from p4, rebasing your + work on top: ++ +------------ +$ git p4 rebase +------------ + +* Submit your commits back to p4: ++ +------------ +$ git p4 submit +------------ + + +COMMANDS +-------- + +Clone +~~~~~ +Generally, 'git p4 clone' is used to create a new git directory +from an existing p4 repository: +------------ +$ git p4 clone //depot/path/project +------------ +This: + +1. Creates an empty git repository in a subdirectory called 'project'. ++ +2. Imports the full contents of the head revision from the given p4 +depot path into a single commit in the git branch 'refs/remotes/p4/master'. ++ +3. Creates a local branch, 'master' from this remote and checks it out. + +To reproduce the entire p4 history in git, use the '@all' modifier on +the depot path: +------------ +$ git p4 clone //depot/path/project@all +------------ + + +Sync +~~~~ +As development continues in the p4 repository, those changes can +be included in the git repository using: +------------ +$ git p4 sync +------------ +This command finds new changes in p4 and imports them as git commits. + +P4 repositories can be added to an existing git repository using +'git p4 sync' too: +------------ +$ mkdir repo-git +$ cd repo-git +$ git init +$ git p4 sync //path/in/your/perforce/depot +------------ +This imports the specified depot into +'refs/remotes/p4/master' in an existing git repository. The +'--branch' option can be used to specify a different branch to +be used for the p4 content. + +If a git repository includes branches 'refs/remotes/origin/p4', these +will be fetched and consulted first during a 'git p4 sync'. Since +importing directly from p4 is considerably slower than pulling changes +from a git remote, this can be useful in a multi-developer environment. + + +Rebase +~~~~~~ +A common working pattern is to fetch the latest changes from the p4 depot +and merge them with local uncommitted changes. Often, the p4 repository +is the ultimate location for all code, thus a rebase workflow makes +sense. This command does 'git p4 sync' followed by 'git rebase' to move +local commits on top of updated p4 changes. +------------ +$ git p4 rebase +------------ + + +Submit +~~~~~~ +Submitting changes from a git repository back to the p4 repository +requires a separate p4 client workspace. This should be specified +using the 'P4CLIENT' environment variable or the git configuration +variable 'git-p4.client'. The p4 client must exist, but the client root +will be created and populated if it does not already exist. + +To submit all changes that are in the current git branch but not in +the 'p4/master' branch, use: +------------ +$ git p4 submit +------------ + +To specify a branch other than the current one, use: +------------ +$ git p4 submit topicbranch +------------ + +The upstream reference is generally 'refs/remotes/p4/master', but can +be overridden using the '--origin=' command-line option. + +The p4 changes will be created as the user invoking 'git p4 submit'. The +'--preserve-user' option will cause ownership to be modified +according to the author of the git commit. This option requires admin +privileges in p4, which can be granted using 'p4 protect'. + + +OPTIONS +------- + +General options +~~~~~~~~~~~~~~~ +All commands except clone accept these options. + +--git-dir <dir>:: + Set the 'GIT_DIR' environment variable. See linkgit:git[1]. + +--verbose:: + Provide more progress information. + +Sync options +~~~~~~~~~~~~ +These options can be used in the initial 'clone' as well as in +subsequent 'sync' operations. + +--branch <branch>:: + Import changes into given branch. If the branch starts with + 'refs/', it will be used as is, otherwise the path 'refs/heads/' + will be prepended. The default branch is 'master'. If used + with an initial clone, no HEAD will be checked out. ++ +This example imports a new remote "p4/proj2" into an existing +git repository: ++ +---- + $ git init + $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 +---- + +--detect-branches:: + Use the branch detection algorithm to find new paths in p4. It is + documented below in "BRANCH DETECTION". + +--changesfile <file>:: + Import exactly the p4 change numbers listed in 'file', one per + line. Normally, 'git p4' inspects the current p4 repository + state and detects the changes it should import. + +--silent:: + Do not print any progress information. + +--detect-labels:: + Query p4 for labels associated with the depot paths, and add + them as tags in git. Limited usefulness as only imports labels + associated with new changelists. Deprecated. + +--import-labels:: + Import labels from p4 into git. + +--import-local:: + By default, p4 branches are stored in 'refs/remotes/p4/', + where they will be treated as remote-tracking branches by + linkgit:git-branch[1] and other commands. This option instead + puts p4 branches in 'refs/heads/p4/'. Note that future + sync operations must specify '--import-local' as well so that + they can find the p4 branches in refs/heads. + +--max-changes <n>:: + Limit the number of imported changes to 'n'. Useful to + limit the amount of history when using the '@all' p4 revision + specifier. + +--keep-path:: + The mapping of file names from the p4 depot path to git, by + default, involves removing the entire depot path. With this + option, the full p4 depot path is retained in git. For example, + path '//depot/main/foo/bar.c', when imported from + '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the + git path is instead 'depot/main/foo/bar.c'. + +--use-client-spec:: + Use a client spec to find the list of interesting files in p4. + See the "CLIENT SPEC" section below. + +Clone options +~~~~~~~~~~~~~ +These options can be used in an initial 'clone', along with the 'sync' +options described above. + +--destination <directory>:: + Where to create the git repository. If not provided, the last + component in the p4 depot path is used to create a new + directory. + +--bare:: + Perform a bare clone. See linkgit:git-clone[1]. + +-/ <path>:: + Exclude selected depot paths when cloning. + +Submit options +~~~~~~~~~~~~~~ +These options can be used to modify 'git p4 submit' behavior. + +--origin <commit>:: + Upstream location from which commits are identified to submit to + p4. By default, this is the most recent p4 commit reachable + from 'HEAD'. + +-M[<n>]:: + Detect renames. See linkgit:git-diff[1]. Renames will be + represented in p4 using explicit 'move' operations. There + is no corresponding option to detect copies, but there are + variables for both moves and copies. + +--preserve-user:: + Re-author p4 changes before submitting to p4. This option + requires p4 admin privileges. + +--export-labels:: + Export tags from git as p4 labels. Tags found in git are applied + to the perforce working directory. + +Rebase options +~~~~~~~~~~~~~~ +These options can be used to modify 'git p4 rebase' behavior. + +--import-labels:: + Import p4 labels. + +DEPOT PATH SYNTAX +----------------- +The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can +be one or more space-separated p4 depot paths, with an optional +p4 revision specifier on the end: + +"//depot/my/project":: + Import one commit with all files in the '#head' change under that tree. + +"//depot/my/project@all":: + Import one commit for each change in the history of that depot path. + +"//depot/my/project@1,6":: + Import only changes 1 through 6. + +"//depot/proj1@all //depot/proj2@all":: + Import all changes from both named depot paths into a single + repository. Only files below these directories are included. + There is not a subdirectory in git for each "proj1" and "proj2". + You must use the '--destination' option when specifying more + than one depot path. The revision specifier must be specified + identically on each depot path. If there are files in the + depot paths with the same name, the path with the most recently + updated version of the file is the one that appears in git. + +See 'p4 help revisions' for the full syntax of p4 revision specifiers. + + +CLIENT SPEC +----------- +The p4 client specification is maintained with the 'p4 client' command +and contains among other fields, a View that specifies how the depot +is mapped into the client repository. The 'clone' and 'sync' commands +can consult the client spec when given the '--use-client-spec' option or +when the useClientSpec variable is true. After 'git p4 clone', the +useClientSpec variable is automatically set in the repository +configuration file. This allows future 'git p4 submit' commands to +work properly; the submit command looks only at the variable and does +not have a command-line option. + +The full syntax for a p4 view is documented in 'p4 help views'. 'Git p4' +knows only a subset of the view syntax. It understands multi-line +mappings, overlays with '+', exclusions with '-' and double-quotes +around whitespace. Of the possible wildcards, 'git p4' only handles +'...', and only when it is at the end of the path. 'Git p4' will complain +if it encounters an unhandled wildcard. + +Bugs in the implementation of overlap mappings exist. If multiple depot +paths map through overlays to the same location in the repository, +'git p4' can choose the wrong one. This is hard to solve without +dedicating a client spec just for 'git p4'. + +The name of the client can be given to 'git p4' in multiple ways. The +variable 'git-p4.client' takes precedence if it exists. Otherwise, +normal p4 mechanisms of determining the client are used: environment +variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. + + +BRANCH DETECTION +---------------- +P4 does not have the same concept of a branch as git. Instead, +p4 organizes its content as a directory tree, where by convention +different logical branches are in different locations in the tree. +The 'p4 branch' command is used to maintain mappings between +different areas in the tree, and indicate related content. 'git p4' +can use these mappings to determine branch relationships. + +If you have a repository where all the branches of interest exist as +subdirectories of a single depot path, you can use '--detect-branches' +when cloning or syncing to have 'git p4' automatically find +subdirectories in p4, and to generate these as branches in git. + +For example, if the P4 repository structure is: +---- +//depot/main/... +//depot/branch1/... +---- + +And "p4 branch -o branch1" shows a View line that looks like: +---- +//depot/main/... //depot/branch1/... +---- + +Then this 'git p4 clone' command: +---- +git p4 clone --detect-branches //depot@all +---- +produces a separate branch in 'refs/remotes/p4/' for //depot/main, +called 'master', and one for //depot/branch1 called 'depot/branch1'. + +However, it is not necessary to create branches in p4 to be able to use +them like branches. Because it is difficult to infer branch +relationships automatically, a git configuration setting +'git-p4.branchList' can be used to explicitly identify branch +relationships. It is a list of "source:destination" pairs, like a +simple p4 branch specification, where the "source" and "destination" are +the path elements in the p4 repository. The example above relied on the +presence of the p4 branch. Without p4 branches, the same result will +occur with: +---- +git config git-p4.branchList main:branch1 +git p4 clone --detect-branches //depot@all +---- + + +PERFORMANCE +----------- +The fast-import mechanism used by 'git p4' creates one pack file for +each invocation of 'git p4 sync'. Normally, git garbage compression +(linkgit:git-gc[1]) automatically compresses these to fewer pack files, +but explicit invocation of 'git repack -adf' may improve performance. + + +CONFIGURATION VARIABLES +----------------------- +The following config settings can be used to modify 'git p4' behavior. +They all are in the 'git-p4' section. + +General variables +~~~~~~~~~~~~~~~~~ +git-p4.user:: + User specified as an option to all p4 commands, with '-u <user>'. + The environment variable 'P4USER' can be used instead. + +git-p4.password:: + Password specified as an option to all p4 commands, with + '-P <password>'. + The environment variable 'P4PASS' can be used instead. + +git-p4.port:: + Port specified as an option to all p4 commands, with + '-p <port>'. + The environment variable 'P4PORT' can be used instead. + +git-p4.host:: + Host specified as an option to all p4 commands, with + '-h <host>'. + The environment variable 'P4HOST' can be used instead. + +git-p4.client:: + Client specified as an option to all p4 commands, with + '-c <client>', including the client spec. + +Clone and sync variables +~~~~~~~~~~~~~~~~~~~~~~~~ +git-p4.syncFromOrigin:: + Because importing commits from other git repositories is much faster + than importing them from p4, a mechanism exists to find p4 changes + first in git remotes. If branches exist under 'refs/remote/origin/p4', + those will be fetched and used when syncing from p4. This + variable can be set to 'false' to disable this behavior. + +git-p4.branchUser:: + One phase in branch detection involves looking at p4 branches + to find new ones to import. By default, all branches are + inspected. This option limits the search to just those owned + by the single user named in the variable. + +git-p4.branchList:: + List of branches to be imported when branch detection is + enabled. Each entry should be a pair of branch names separated + by a colon (:). This example declares that both branchA and + branchB were created from main: ++ +------------- +git config git-p4.branchList main:branchA +git config --add git-p4.branchList main:branchB +------------- + +git-p4.ignoredP4Labels:: + List of p4 labels to ignore. This is built automatically as + unimportable labels are discovered. + +git-p4.importLabels:: + Import p4 labels into git, as per --import-labels. + +git-p4.labelImportRegexp:: + Only p4 labels matching this regular expression will be imported. The + default value is '[a-zA-Z0-9_\-.]+$'. + +git-p4.useClientSpec:: + Specify that the p4 client spec should be used to identify p4 + depot paths of interest. This is equivalent to specifying the + option '--use-client-spec'. See the "CLIENT SPEC" section above. + This variable is a boolean, not the name of a p4 client. + +Submit variables +~~~~~~~~~~~~~~~~ +git-p4.detectRenames:: + Detect renames. See linkgit:git-diff[1]. + +git-p4.detectCopies:: + Detect copies. See linkgit:git-diff[1]. + +git-p4.detectCopiesHarder:: + Detect copies harder. See linkgit:git-diff[1]. + +git-p4.preserveUser:: + On submit, re-author changes to reflect the git author, + regardless of who invokes 'git p4 submit'. + +git-p4.allowMissingP4Users:: + When 'preserveUser' is true, 'git p4' normally dies if it + cannot find an author in the p4 user map. This setting + submits the change regardless. + +git-p4.skipSubmitEdit:: + The submit process invokes the editor before each p4 change + is submitted. If this setting is true, though, the editing + step is skipped. + +git-p4.skipSubmitEditCheck:: + After editing the p4 change message, 'git p4' makes sure that + the description really was changed by looking at the file + modification time. This option disables that test. + +git-p4.allowSubmit:: + By default, any branch can be used as the source for a 'git p4 + submit' operation. This configuration variable, if set, permits only + the named branches to be used as submit sources. Branch names + must be the short names (no "refs/heads/"), and should be + separated by commas (","), with no spaces. + +git-p4.skipUserNameCheck:: + If the user running 'git p4 submit' does not exist in the p4 + user map, 'git p4' exits. This option can be used to force + submission regardless. + +git-p4.attemptRCSCleanup:: + If enabled, 'git p4 submit' will attempt to cleanup RCS keywords + ($Header$, etc). These would otherwise cause merge conflicts and prevent + the submit going ahead. This option should be considered experimental at + present. + +git-p4.exportLabels:: + Export git tags to p4 labels, as per --export-labels. + +git-p4.labelExportRegexp:: + Only p4 labels matching this regular expression will be exported. The + default value is '[a-zA-Z0-9_\-.]+$'. + +IMPLEMENTATION DETAILS +---------------------- +* Changesets from p4 are imported using git fast-import. +* Cloning or syncing does not require a p4 client; file contents are + collected using 'p4 print'. +* Submitting requires a p4 client, which is not in the same location + as the git repository. Patches are applied, one at a time, to + this p4 client and submitted from there. +* Each commit imported by 'git p4' has a line at the end of the log + message indicating the p4 depot location and change number. This + line is used by later 'git p4 sync' operations to know which p4 + changes are new. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index f4d8d68e34..20c8551d6a 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -9,9 +9,11 @@ git-pack-objects - Create a packed archive of objects SYNOPSIS -------- [verse] -'git-pack-objects' [-q] [--no-reuse-delta] [--delta-base-offset] [--non-empty] - [--local] [--incremental] [--window=N] [--depth=N] [--all-progress] - [--revs [--unpacked | --all]*] [--stdout | base-name] < object-list +'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] + [--keep-true-parents] < object-list DESCRIPTION @@ -19,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. -'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 ------- @@ -59,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 linkgit:git-rev-list[1] with `--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. @@ -71,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:: @@ -79,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 @@ -92,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 @@ -104,20 +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 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 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 @@ -131,7 +139,7 @@ base-name:: --all-progress:: When --stdout is specified then progress report is - displayed during the object count and deltification phases + displayed during the object count and compression phases but inhibited during the write-out phase. The reason is that in some cases the output stream is directly linked to another command which may wish to display progress @@ -140,6 +148,11 @@ base-name:: report for the write-out phase as well even if --stdout is used. +--all-progress-implied:: + This is used to imply --all-progress whenever progress display + is activated. Unlike --all-progress this flag doesn't actually + force any progress display by itself. + -q:: This flag makes the command not to report its progress on the standard error stream. @@ -158,24 +171,39 @@ 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, and defaults to -1, the zlib default, if neither is set. - Add \--no-reuse-object if you want to force a uniform compression + 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 @@ -192,14 +220,9 @@ base-name:: to force the version for the generated pack index, and to force 64-bit index entries on objects located above the given offset. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation -------------- -Documentation by Junio C Hamano +--keep-true-parents:: + With this option, parents that are hidden by grafts are packed + nevertheless. SEE ALSO -------- diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index 6737326f0b..f2869da572 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -8,21 +8,22 @@ git-pack-redundant - Find redundant pack files SYNOPSIS -------- -'git-pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > +[verse] +'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > DESCRIPTION ----------- 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. +`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. -git-fsck --full --unreachable | cut -d ' ' -f3 | \ -git-pack-redundant --all | xargs rm +git fsck --full --unreachable | cut -d ' ' -f3 | \ +git pack-redundant --all | xargs rm OPTIONS ------- @@ -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 c0718468d5..10afd4edfe 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -7,7 +7,8 @@ git-pack-refs - Pack heads and tags for efficient repository access SYNOPSIS -------- -'git-pack-refs' [--all] [--no-prune] +[verse] +'git pack-refs' [--all] [--no-prune] DESCRIPTION ----------- @@ -26,16 +27,16 @@ problem by stashing the refs in a single file, traditional `$GIT_DIR/refs` hierarchy, it is looked up in this file and used if found. -Subsequent updates to branches always creates new file under +Subsequent updates to branches always create new files under `$GIT_DIR/refs` hierarchy. A recommended practice to deal with a repository with too many refs is to pack its refs with `--all --prune` once, and -occasionally run `git-pack-refs \--prune`. Tags are by +occasionally run `git pack-refs --prune`. Tags are by definition stationary and are not expected to change. Branch heads will be packed with the initial `pack-refs --all`, but only the currently active branch heads will become unpacked, -and next `pack-refs` (without `--all`) will leave them +and the next `pack-refs` (without `--all`) will leave them unpacked. @@ -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 951dbd6c83..a45ea1ece8 100644 --- a/Documentation/git-parse-remote.txt +++ b/Documentation/git-parse-remote.txt @@ -8,7 +8,8 @@ git-parse-remote - Routines to help parsing remote repository access parameters SYNOPSIS -------- -'. git-parse-remote' +[verse] +'. "$(git --exec-path)/git-parse-remote"' DESCRIPTION ----------- @@ -17,34 +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. -The primary entry points are: - -get_remote_refs_for_fetch:: - Given the list of user-supplied `<repo> <refspec>...`, - return the list of refs to fetch after canonicalizing - them into `$GIT_DIR` relative paths - (e.g. `refs/heads/foo`). When `<refspec>...` is empty - the returned list of refs consists of the defaults - for the given `<repo>`, if specified in - `$GIT_DIR/remotes/`, `$GIT_DIR/branches/`, or `remote.*.fetch` - configuration. - -get_remote_refs_for_push:: - Given the list of user-supplied `<repo> <refspec>...`, - return the list of refs to push in a form suitable to be - fed to the `git-send-pack` command. When `<refspec>...` - is empty the returned list of refs consists of the - defaults for the given `<repo>`, if specified in - `$GIT_DIR/remotes/`. - -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 bb8a079254..90268f02e7 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -7,7 +7,8 @@ git-patch-id - Compute unique ID for a patch SYNOPSIS -------- -'git-patch-id' < <patch> +[verse] +'git patch-id' < <patch> DESCRIPTION ----------- @@ -18,9 +19,9 @@ 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 string. The first +commit, and outputs two 40-byte hexadecimal strings. The first string is the patch ID, and the second string is the commit ID. This can be used to make a mapping from patch ID to 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 ffbf93a799..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 -------- -'git-peek-remote' [--upload-pack=<git-upload-pack>] [<host>:]<directory> +[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 <junkio@cox.net> - -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 f330b8a5b9..80dc022ede 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -8,7 +8,8 @@ git-prune-packed - Remove extra objects that are already in pack files SYNOPSIS -------- -'git-prune-packed' [-n] [-q] +[verse] +'git prune-packed' [-n|--dry-run] [-q|--quiet] DESCRIPTION @@ -28,20 +29,14 @@ disk storage, etc. OPTIONS ------- -n:: +--dry-run:: Don't actually remove any objects, only show those that would have been removed. -q:: +--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 ec335d6fab..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] [--expire <expire>] [--] [<head>...] +[verse] +'git prune' [-n] [-v] [--expire <expire>] [--] [<head>...] DESCRIPTION ----------- -NOTE: In most cases, users should run linkgit:git-gc[1], 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,9 +32,14 @@ OPTIONS ------- -n:: +--dry-run:: Do not remove anything; just report what it would remove. +-v:: +--verbose:: + Report all removed objects. + \--:: Do not interpret any more arguments as options. @@ -53,18 +59,18 @@ borrows from your repository via its `.git/objects/info/alternates`: ------------ -$ git prune $(cd ../another && $(git-rev-parse --all)) +$ 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 linkgit:git-gc[1], 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 -------- @@ -73,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 d0f1595f7e..defb544ed0 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -8,35 +8,109 @@ 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + 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 `pull.rebase`, `branch.<name>.rebase` and `branch.autosetuprebase` in +linkgit:git-config[1] if you want to make `git pull` always use +`--rebase` instead of merging. + [NOTE] This is a potentially _dangerous_ mode of operation. @@ -47,6 +121,9 @@ unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: Override earlier --rebase. +Options related to fetching +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + include::fetch-options.txt[] include::pull-fetch-param.txt[] @@ -70,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>` @@ -83,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 @@ -131,77 +208,32 @@ $ git pull origin next ------------------------------------------------ + This leaves a copy of `next` temporarily in FETCH_HEAD, but -does not update any remote-tracking branches. - -* Bundle local branch `fixes` and `enhancements` on top of - the current branch, making an Octopus merge: +does not update any remote-tracking branches. Using remote-tracking +branches, the same can be done by invoking fetch and merge: + ------------------------------------------------ -$ git pull . fixes enhancements +$ git fetch origin +$ git merge origin/next ------------------------------------------------ -+ -This `git pull .` syntax is equivalent to `git merge`. - -* Merge local branch `obsolete` into the current branch, using `ours` - merge strategy: -+ ------------------------------------------------- -$ git pull -s ours . obsolete ------------------------------------------------- - -* Merge local branch `maint` into the current branch, but do not make - a commit automatically: -+ ------------------------------------------------- -$ git pull --no-commit . maint ------------------------------------------------- -+ -This can be used when you want to include further changes to the -merge, or want to write your own merge commit message. -+ -You should refrain from abusing this option to sneak substantial -changes into a merge commit. Small fixups like bumping -release/version name would be acceptable. - -* Command line pull of multiple branches from one repository: -+ ------------------------------------------------- -$ git checkout master -$ git fetch origin +pu:pu maint:tmp -$ git pull . tmp ------------------------------------------------- -+ -This updates (or creates, as necessary) branches `pu` and `tmp` in -the local repository by fetching from the branches (respectively) -`pu` and `maint` from the remote repository. -+ -The `pu` branch will be updated even if it is does not fast-forward; -the others will not be. -+ -The final command then merges the newly fetched `tmp` into master. If you tried a pull which resulted in a complex conflicts and -would want to start over, you can recover with -linkgit:git-reset[1]. +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 <junkio@cox.net> - -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 89e0049bce..cb97cc1c3b 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -9,8 +9,9 @@ git-push - Update remote refs along with associated objects SYNOPSIS -------- [verse] -'git-push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] - [--repo=all] [-f | --force] [-v | --verbose] [<repository> <refspec>...] +'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] + [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] + [<repository> [<refspec>...]] DESCRIPTION ----------- @@ -23,51 +24,65 @@ every time you push into it, by setting up 'hooks' there. See documentation for linkgit:git-receive-pack[1]. -OPTIONS -------- +OPTIONS[[OPTIONS]] +------------------ <repository>:: The "remote" repository that is destination of a push - operation. See the section <<URLS,GIT URLS>> below. - -<refspec>:: - The canonical format of a <refspec> parameter is - `+?<src>:<dst>`; that is, an optional plus `+`, followed - by the source ref, followed by a colon `:`, followed by - the destination ref. + operation. This parameter can be either a URL + (see the section <<URLS,GIT URLS>> below) or the name + of a remote (see the section <<REMOTES,REMOTES>> below). + +<refspec>...:: + The format of a <refspec> parameter is an optional plus + `+`, followed by the source ref <src>, followed + by a colon `:`, followed by the destination ref <dst>. + It is used to specify with what <src> object the <dst> ref + in the remote repository is to be updated. + -The <src> side represents the source branch (or arbitrary -"SHA1 expression", such as `master~4` (four parents before the -tip of `master` branch); see linkgit:git-rev-parse[1]) that you -want to push. The <dst> side represents the destination location. +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:gitrevisions[7]). + -The local ref that matches <src> is used -to fast forward the remote ref that matches <dst> (or, if no <dst> was -specified, the same ref that <src> referred to locally). If -the optional leading plus `+` is used, the remote ref is updated -even if it does not result in a fast forward update. +The <dst> tells which ref on the remote side is updated with this +push. Arbitrary expressions cannot be used here, an actual ref must +be named. If `:`<dst> is omitted, the same ref as <src> will be +updated. + -`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. +The object referenced by <src> is used to update the <dst> reference +on the remote side, but by default this is only allowed if the +update can fast-forward <dst>. By having the optional leading `+`, +you can tell git to update the <dst> ref even when the update is not a +fast-forward. This does *not* attempt to merge <src> into <dst>. See +EXAMPLES below for details. + -A parameter <ref> without a colon pushes the <ref> from the source -repository to the destination repository under the same name. +`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. + Pushing an empty <src> allows you to delete the <dst> ref from the remote repository. + -The special refspec `:` (or `+:` to allow non-fast forward updates) -directs git to push "matching" heads: for every head that exists on -the local side, the remote side is updated if a head of the same name +The special refspec `:` (or `+:` to allow non-fast-forward updates) +directs git to push "matching" branches: for every branch that exists on +the local side, the remote side is updated if a branch of the same name already exists on the remote side. This is the default operation mode if no explicit refspec is found (that is neither on the command line nor in any Push line of the corresponding remotes file---see below). --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. + +--prune:: + Remove remote branches that don't have a local counterpart. For example + a remote branch `tmp` will be removed if a local branch with the same + name doesn't exist any more. This also respects refspecs, e.g. + `git push --prune remote refs/heads/*:refs/tmp/*` would + make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo` + doesn't exist. --mirror:: Instead of naming each ref to push, specifies that all - refs under `$GIT_DIR/refs/heads/` and `$GIT_DIR/refs/tags/` + 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 will be force updated on the remote end, and deleted refs @@ -75,23 +90,31 @@ nor in any Push line of the corresponding remotes file---see below). if the configuration option `remote.<remote>.mirror` is set. +-n:: --dry-run:: Do everything except actually send the updates. +--porcelain:: + Produce machine-readable output. The output status line for each ref + will be tab-separated and sent to stdout instead of stderr. The full + symbolic names of the refs will be given. + +--delete:: + All listed refs are deleted from the remote repository. This is + 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. --receive-pack=<git-receive-pack>:: +--exec=<git-receive-pack>:: Path to the 'git-receive-pack' program on the remote end. Sometimes useful when pushing to a remote repository over ssh, and you do not have the program in a directory on the default $PATH. ---exec=<git-receive-pack>:: - Same as \--receive-pack=<git-receive-pack>. - -f:: --force:: Usually, the command refuses to update a remote ref that is @@ -99,20 +122,66 @@ nor in any Push line of the corresponding remotes file---see below). This flag disables the check. This can cause the remote repository to lose commits; use it with care. ---repo=<repo>:: - When no repository is specified the command defaults to - "origin"; this overrides it. +--repo=<repository>:: + This option is only relevant if no <repository> argument is + 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 + can be used to override the name "origin". In other words, + the difference between these two commands ++ +-------------------------- +git push public #1 +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'. + +-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. +--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|on-demand:: + Make sure all submodule commits used by the revisions to be + pushed are available on a remote tracking branch. If 'check' is + used git will verify that all submodule commits that changed in + the revisions to be pushed are available on at least one remote + of the submodule. If any commits are missing the push will be + aborted and exit with non-zero status. If 'on-demand' is used + all submodules that changed in the revisions to be pushed will + be pushed. If on-demand was not able to push all necessary + revisions it will also be aborted and exit with non-zero status. + + include::urls-remotes.txt[] OUTPUT @@ -129,27 +198,51 @@ representing the status of a single ref. Each line is of the form: <flag> <summary> <from> -> <to> (<reason>) ------------------------------- +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; +`+`;; 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 @@ -165,41 +258,173 @@ reason:: refs, no explanation is needed. For a failed ref, the reason for failure is described. +Note about fast-forwards +------------------------ + +When an update changes a branch (or more in general, a ref) that used to +point at commit A to point at another commit B, it is called a +fast-forward update if and only if B is a descendant of A. + +In a fast-forward update from A to B, the set of commits that the original +commit A built on top of is a subset of the commits the new commit B +builds on top of. Hence, it does not lose any history. + +In contrast, a non-fast-forward update will lose history. For example, +suppose you and somebody else started at the same commit X, and you built +a history leading to commit B while the other person built a history +leading to commit A. The history looks like this: + +---------------- + + B + / + ---X---A + +---------------- + +Further suppose that the other person already pushed changes leading to A +back to the original repository you two obtained the original commit X. + +The push done by the other person updated the branch that used to point at +commit X to point at commit A. It is a fast-forward. + +But if you try to push, you will attempt to update the branch (that +now points at A) with commit B. This does _not_ fast-forward. If you did +so, the changes introduced by commit A will be lost, because everybody +will now start building on top of B. + +The command by default does not allow an update that is not a fast-forward +to prevent such loss of history. + +If you do not want to lose your work (history from X to B) nor the work by +the other person (history from X to A), you would need to first fetch the +history from the repository, create a history that contains changes done +by both parties, and push the result back. + +You can perform "git pull", resolve potential conflicts, and "git push" +the result. A "git pull" will create a merge commit C between commits A +and B. + +---------------- + + B---C + / / + ---X---A + +---------------- + +Updating A with the resulting merge commit will fast-forward and your +push will be accepted. + +Alternatively, you can rebase your change between X and B on top of A, +with "git pull --rebase", and push the result back. The rebase will +create a new commit D that builds the change between X and B on top of +A. + +---------------- + + B D + / / + ---X---A + +---------------- + +Again, updating A with this commit will fast-forward and your push will be +accepted. + +There is another common situation where you may encounter non-fast-forward +rejection when you try to push, and it is possible even when you are +pushing into a repository nobody else pushes into. After you push commit +A yourself (in the first picture in this section), replace it with "git +commit --amend" to produce commit B, and you try to push it out, because +forgot that you have pushed A out already. In such a case, and only if +you are certain that nobody in the meantime fetched your earlier commit A +(and started building on top of it), you can run "git push --force" to +overwrite it. In other words, "git push --force" is a method reserved for +a case where you do mean to lose history. + + Examples -------- -git push origin master:: +`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`:: + Without additional configuration, works like + `git push origin :`. ++ +The default behavior of this command when no <refspec> is given can be +configured by setting the `push` option of the remote. ++ +For example, to default to pushing only the current branch to `origin` +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 :`:: + Push "matching" branches to `origin`. See + <refspec> in the <<OPTIONS,OPTIONS>> section above for a + description of "matching" branches. + +`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 :experimental:: - Find a ref that matches `experimental` in the `origin` repository - (e.g. `refs/heads/experimental`), and delete it. +`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:: - Find a ref that matches `master` in the source repository - (most likely, it would find `refs/heads/master`), and update - the ref that matches `satellite/master` (most likely, it would - be `refs/remotes/satellite/master`) in `origin` repository with it. +`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 master:refs/heads/experimental:: +`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`:: 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. -Author ------- -Written by Junio C Hamano <junkio@cox.net>, later rewritten in C -by Linus Torvalds <torvalds@osdl.org> +`git push origin :experimental`:: + Find a ref that matches `experimental` in the `origin` repository + (e.g. `refs/heads/experimental`), and delete it. -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +`git push origin +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 + following situation, where a fast-forward is not possible: ++ +---- + o---o---o---A---B origin/master + \ + X---Y---Z dev +---- ++ +The above command would change the origin repository to ++ +---- + A---B (unnamed branch) + / + o---o---o---X---Y---Z master +---- ++ +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. GIT --- diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index 0600379394..7f112f3dcd 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -9,7 +9,7 @@ git-quiltimport - Applies a quilt patchset onto the current branch SYNOPSIS -------- [verse] -'git-quiltimport' [--dry-run] [--author <author>] [--patches <dir>] +'git quiltimport' [--dry-run | -n] [--author <author>] [--patches <dir>] DESCRIPTION @@ -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 58fb906ef6..c4bde6509e 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,11 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' (<tree-ish> | [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +[verse] +'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] + [-u [--exclude-per-directory=<gitignore>] | -i]] + [--index-output=<file>] [--no-sparse-checkout] + (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -22,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 ------- @@ -43,42 +47,46 @@ 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 - original index file cannot have anything at the path - `<prefix>` itself, and have nothing in `<prefix>/` - directory. Note that the `<prefix>/` value must end - with a slash. + of the named tree-ish under the directory at `<prefix>`. + The command will refuse to overwrite entries that already + existed in the original index file. Note that the `<prefix>/` + value must end with a slash. --exclude-per-directory=<gitignore>:: When running the command with `-u` and `-m` options, the @@ -107,13 +115,21 @@ OPTIONS directories the index file and index output file are located in. +--no-sparse-checkout:: + 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. @@ -121,63 +137,68 @@ 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 +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 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 ~~~~~~~~~~~~~~ -Typically, this is invoked as `git-read-tree -m $H $M`, where $H +Typically, this is invoked as `git read-tree -m $H $M`, where $H 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). +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 +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 + 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 + 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 @@ -192,34 +213,40 @@ 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 -`git-diff-index --cached $M`. Note that this does not -necessarily match `git-diff-index --cached $H` would have +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 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 +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. +merge, but it would not show in `git diff-index --cached $M` +output after the two-tree merge. +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 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 ~~~~~~~~~~~ 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 ---------------- -$ git-read-tree -m <tree1> <tree2> <tree3> +$ git read-tree -m <tree1> <tree2> <tree3> ---------------- and you will end up with an index with all of the <tree1> entries in @@ -229,7 +256,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": @@ -245,7 +272,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. @@ -261,7 +288,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 @@ -285,8 +312,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. @@ -304,17 +331,17 @@ commit. To illustrate, suppose you start from what has been committed last to your repository: ---------------- -$ JC=`git-rev-parse --verify "HEAD^0"` -$ git-checkout-index -f -u -a $JC +$ 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: ---------------- -$ git-fetch git://.... linus -$ LT=`cat .git/FETCH_HEAD` +$ git fetch git://.... linus +$ LT=`git rev-parse FETCH_HEAD` ---------------- Your work tree is still based on your HEAD ($JC), but you have @@ -323,10 +350,10 @@ added or modified index entries since $JC, and if you haven't, then does the right thing. So with the following sequence: ---------------- -$ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT -$ git-merge-index git-merge-one-file -a +$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT +$ git merge-index git-merge-one-file -a $ echo "Merge with Linus" | \ - git-commit-tree `git-write-tree` -p $JC -p $LT + git commit-tree `git write-tree` -p $JC -p $LT ---------------- what you would commit is a pure merge between $JC and $LT without @@ -334,34 +361,71 @@ 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 have finished your work-in-progress), attempt the merge again. +Sparse checkout +--------------- + +"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 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 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 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 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 the file `unwanted`: + +---------------- +/* +!unwanted +---------------- + +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 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 +turn `core.sparseCheckout` on in order to have sparse checkout +support. + + 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 7166414355..147fa1a8e0 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,25 +8,33 @@ git-rebase - Forward-port local commits to the updated upstream head SYNOPSIS -------- [verse] -'git-rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] - [-s <strategy> | --strategy=<strategy>] - [-C<n>] [ --whitespace=<option>] [-p | --preserve-merges] - [--onto <newbase>] <upstream> [<branch>] -'git-rebase' --continue | --skip | --abort +'git rebase' [-i | --interactive] [options] [--onto <newbase>] + [<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`. +of commits that would be shown by `git log <upstream>..HEAD` (or +`git log HEAD`, if --root is specified). The current branch is reset to <upstream>, or <newbase> if the --onto option was supplied. This has the exact same effect as -`git reset --hard <upstream>` (or <newbase>). +`git reset --hard <upstream>` (or <newbase>). ORIG_HEAD is set +to point at the tip of the branch before the reset. The commits that were previously saved into the temporary area are then reapplied to the current branch, one by one, in order. Note that @@ -37,9 +45,9 @@ 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 -original <branch> and remove the .dotest working files, use the command -`git rebase --abort` instead. +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. Assume the following history exists and the current branch is "topic": @@ -52,8 +60,8 @@ Assume the following history exists and the current branch is "topic": From this point, the result of either of the following commands: - git-rebase master - git-rebase master topic + git rebase master + git rebase master topic would be: @@ -63,12 +71,13 @@ 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 -will be skipped. For example, running `git-rebase master` on the +will be skipped. For example, running `git rebase master` on the following history (in which A' and A introduce the same set of changes, but have different committer information): @@ -91,7 +100,7 @@ branch to another, to pretend that you forked the topic branch from the latter branch, using `rebase --onto`. First let's assume your 'topic' is based on branch 'next'. -For example feature developed in 'topic' depends on some +For example, a feature developed in 'topic' depends on some functionality which is found in 'next'. ------------ @@ -102,9 +111,9 @@ functionality which is found in 'next'. o---o---o topic ------------ -We would want to make 'topic' forked from branch 'master', -for example because the functionality 'topic' branch depend on -got merged into more stable 'master' branch, like this: +We want to make 'topic' forked from branch 'master'; for example, +because the functionality on which 'topic' depends was merged into the +more stable 'master' branch. We want our tree to look like this: ------------ o---o---o---o---o master @@ -116,7 +125,7 @@ got merged into more stable 'master' branch, like this: We can get this using the following command: - git-rebase --onto master next topic + git rebase --onto master next topic Another example of --onto option is to rebase part of a @@ -132,7 +141,7 @@ branch. If we have the following situation: then the command - git-rebase --onto master topicA topicB + git rebase --onto master topicA topicB would result in: @@ -155,7 +164,7 @@ the following situation: then the command - git-rebase --onto topicA~5 topicA~3 topicA + git rebase --onto topicA~5 topicA~3 topicA would result in the removal of commits F and G: @@ -167,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 @@ -184,11 +193,21 @@ 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 +CONFIGURATION +------------- + +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>:: @@ -196,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. @@ -208,7 +232,15 @@ 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. + +--keep-empty:: + Keep the commits that do not change anything from its + parents in the result. --skip:: Restart the rebasing process by skipping the current patch. @@ -218,18 +250,53 @@ OPTIONS Use merging strategies to rebase. When the recursive (default) merge strategy is used, this allows rebase to be aware of renames on the upstream side. ++ +Note that a rebase merge works by replaying each commit from the working +branch on top of the <upstream> branch. Because of this, when a merge +conflict happens, the side reported as 'ours' is the so-far rebased +series, starting with <upstream>, and 'theirs' is the working branch. In +other words, the sides are swapped. -s <strategy>:: --strategy=<strategy>:: - 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). This implies --merge. + Use the given merge strategy. + 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 +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. -v:: --verbose:: - Display a diffstat of what changed upstream since the last rebase. + Be verbose. Implies --stat. + +--stat:: + Show a diffstat of what changed upstream since the last rebase. The + diffstat is also controlled by the configuration option rebase.stat. + +-n:: +--no-stat:: + Do not show a diffstat as part of the rebase process. + +--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 @@ -237,9 +304,31 @@ OPTIONS context exist they all must match. By default no context is ever ignored. ---whitespace=<nowarn|warn|error|error-all|strip>:: - This flag is passed to the `git-apply` program +-f:: +--force-rebase:: + Force the rebase even if the current branch is a descendant + 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 (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 + of the rebased commits (see linkgit:git-am[1]). + Incompatible with the --interactive option. -i:: --interactive:: @@ -249,20 +338,59 @@ OPTIONS -p:: --preserve-merges:: - Instead of ignoring merges, try to recreate them. This option - only works in interactive mode. + 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 + limiting them with an <upstream>. This allows you to rebase + the root commit(s) on a branch. Must be used with --onto, and + will skip changes already contained in <newbase> (instead of + <upstream>). When used together with --preserve-merges, 'all' + root commits will be rewritten to have <newbase> as parent + instead. + +--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 ----- -When you rebase a branch, you are changing its history in a way that -will cause problems for anyone who already has a copy of the branch -in their repository and tries to pull updates from you. You should -understand the implications of using 'git rebase' on a repository that -you share. -When the git rebase command is run, it will first execute a "pre-rebase" +You should understand the implications of using 'git rebase' on a +repository that you share. See also RECOVERING FROM UPSTREAM REBASE +below. + +When the git-rebase command is run, it will first execute a "pre-rebase" hook if one exists. You can use this hook to do sanity checks and reject the rebase if it isn't appropriate. Please see the template pre-rebase hook script for an example. @@ -285,10 +413,13 @@ The interactive mode is meant for this type of workflow: where point 2. consists of several instances of -a. regular use +a) regular use + 1. finish something worthy of a commit 2. commit -b. independent fixup + +b) independent fixup + 1. realize that something does not work 2. fix that 3. commit it @@ -314,27 +445,33 @@ 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. +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. +"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. -In both cases, or when a "pick" does not succeed (because of merge -errors), the loop will stop to let you fix things, and you can continue -the loop with `git rebase --continue`. +'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 @@ -359,6 +496,30 @@ sure that the current HEAD is "B", and call $ git rebase -i -p --onto Q O ----------------------------- +Reordering and editing commits usually creates untested intermediate +steps. You may want to check that your history editing did not break +anything by running a test, or at least recompiling at intermediate +points in history by using the "exec" command (shortcut "x"). You may +do so by creating a todo list like this one: + +------------------------------------------- +pick deadbee Implement feature XXX +fixup f1a5c00 Fix to feature XXX +exec make +pick c0ffeee The oneline of the next commit +edit deadbab The oneline of the commit after +exec cd subdir; make test +... +------------------------------------------- + +The interactive rebase will stop when a command fails (i.e. exits with +non-0 status) to give you an opportunity to fix the problem. You can +continue with `git rebase --continue`. + +The "exec" command launches the command in a shell (the one specified +in `$SHELL`, or the default shell if `$SHELL` is not set), so you can +use shell features (like "cd", ">", ";" ...). The command is run from +the root of the working tree. SPLITTING COMMITS ----------------- @@ -368,41 +529,174 @@ 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: -- Start an interactive rebase with 'git rebase -i <commit>^', where +- Start an interactive rebase with `git rebase -i <commit>^`, where <commit> is the commit you want to split. In fact, any commit range will do, as long as it contains that commit. - Mark the commit you want to split with the action "edit". -- When it comes to editing that commit, execute 'git reset HEAD^'. The +- When it comes to editing that commit, execute `git reset HEAD^`. The effect is that the HEAD is rewound by one, and the index follows suit. However, the working tree stays the same. - Now add the changes to the index that you want to have in the first - commit. You can use linkgit:git-add[1] (possibly interactively) and/or - linkgit:git-gui[1] to do that. + commit. You can use `git add` (possibly interactively) or + 'git gui' (or both) to do that. - Commit the now-current index with whatever commit message is appropriate now. - Repeat the last two steps until your working tree is clean. -- Continue the rebase with 'git rebase --continue'. +- Continue the rebase with `git rebase --continue`. If you are not absolutely sure that the intermediate revisions are consistent (they compile, pass the testsuite, etc.) you should use -linkgit:git-stash[1] 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. -Authors ------- -Written by Junio C Hamano <junkio@cox.net> and -Johannes E. Schindelin <johannes.schindelin@gmx.de> +RECOVERING FROM UPSTREAM REBASE +------------------------------- + +Rebasing (or any other form of rewriting) a branch that others have +based work on is a bad idea: anyone downstream of it is forced to +manually fix their history. This section explains how to do the fix +from the downstream's point of view. The real fix, however, would be +to avoid rebasing the upstream in the first place. + +To illustrate, suppose you are in a situation where someone develops a +'subsystem' branch, and you are working on a 'topic' that is dependent +on this 'subsystem'. You might end up with a history like the +following: + +------------ + o---o---o---o---o---o---o---o---o master + \ + o---o---o---o---o subsystem + \ + *---*---* topic +------------ + +If 'subsystem' is rebased against 'master', the following happens: + +------------ + o---o---o---o---o---o---o---o master + \ \ + o---o---o---o---o o'--o'--o'--o'--o' subsystem + \ + *---*---* topic +------------ + +If you now continue development as usual, and eventually merge 'topic' +to 'subsystem', the commits from 'subsystem' will remain duplicated forever: + +------------ + o---o---o---o---o---o---o---o master + \ \ + o---o---o---o---o o'--o'--o'--o'--o'--M subsystem + \ / + *---*---*-..........-*--* topic +------------ -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +Such duplicates are generally frowned upon because they clutter up +history, making it harder to follow. To clean things up, you need to +transplant the commits on 'topic' to the new 'subsystem' tip, i.e., +rebase 'topic'. This becomes a ripple effect: anyone downstream from +'topic' is forced to rebase too, and so on! + +There are two kinds of fixes, discussed in the following subsections: + +Easy case: The changes are literally the same.:: + + This happens if the 'subsystem' rebase was a simple rebase and + had no conflicts. + +Hard case: The changes are not the same.:: + + This happens if the 'subsystem' rebase had conflicts, or used + `--interactive` to omit, edit, squash, or fixup commits; or + if the upstream used one of `commit --amend`, `reset`, or + `filter-branch`. + + +The easy case +~~~~~~~~~~~~~ + +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 +changes that are already present in the new upstream. So if you say +(assuming you're on 'topic') +------------ + $ git rebase subsystem +------------ +you will end up with the fixed history +------------ + o---o---o---o---o---o---o---o master + \ + o'--o'--o'--o'--o' subsystem + \ + *---*---* topic +------------ + + +The hard case +~~~~~~~~~~~~~ + +Things get more complicated if the 'subsystem' changes do not exactly +correspond to the ones before the rebase. + +NOTE: While an "easy case recovery" sometimes appears to be successful + even in the hard case, it may have unintended consequences. For + 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' +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 + 'subsystem' is at `subsystem@{1}`. Subsequent fetches will + increase the number. (See linkgit:git-reflog[1].) + +* Relative to the tip of 'topic': knowing that your 'topic' has three + commits, the old tip of 'subsystem' must be `topic~3`. + +You can then transplant the old `subsystem..topic` to the new tip by +saying (for the reflog case, and assuming you are on 'topic' already): +------------ + $ git rebase --onto subsystem subsystem@{1} +------------ + +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. + +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 a70c7168f6..b1f7dc643a 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -8,27 +8,28 @@ git-receive-pack - Receive what is pushed into the repository SYNOPSIS -------- +[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 'git-fetch-pack'. +repository. For pull operations, see linkgit:git-fetch-pack[1]. -The command allows for creation and fast forwarding of sha1 refs +The command allows for creation and fast-forwarding of sha1 refs (heads/tags) on the remote end (strictly speaking, it is the -local end receive-pack runs, but to the user who is sitting at +local end 'git-receive-pack' runs, but to the user who is sitting at the send-pack end, it is updating the remote. Confused?) There are other real-world examples of using update and post-update hooks found in the Documentation/howto directory. -git-receive-pack honours the receive.denyNonFastForwards config +'git-receive-pack' honours the receive.denyNonFastForwards config option, which tells it if updates to a ref should be denied if they are not fast-forwards. @@ -86,7 +87,7 @@ post-receive Hook ----------------- After all refs were updated (or attempted to be updated), if any ref update was successful, and if $GIT_DIR/hooks/post-receive -file exists and is executable, it will be invoke once with no +file exists and is executable, it will be invoked once with no parameters. The standard input of the hook will be one line for each successfully updated ref: @@ -111,10 +112,10 @@ ref listing the commits pushed to the repository: if expr "$oval" : '0*$' >/dev/null then echo "Created a new ref, with the following commits:" - git-rev-list --pretty "$nval" + git rev-list --pretty "$nval" else echo "New commits:" - git-rev-list --pretty "$nval" "^$oval" + git rev-list --pretty "$nval" "^$oval" fi | mail -s "Changes to ref $ref" commit-list@mydomain done @@ -125,7 +126,7 @@ non-zero exit code will generate an error message. Note that it is possible for refname to not have sha1-new when this hook runs. This can easily occur if another user modifies the ref -after it was updated by receive-pack, but before the hook was able +after it was updated by 'git-receive-pack', but before the hook was able to evaluate it. It is recommended that hooks rely on sha1-new rather than the current value of refname. @@ -133,32 +134,23 @@ post-update Hook ---------------- After all other processing, if at least one ref was updated, and if $GIT_DIR/hooks/post-update file exists and is executable, then -post-update will called with the list of refs that have been updated. +post-update will be called with the list of refs that have been updated. This can be used to implement any repository wide cleanup tasks. The exit code from this hook invocation is ignored; the only thing -left for git-receive-pack to do at that point is to exit itself +left for 'git-receive-pack' to do at that point is to exit itself anyway. -This hook can be used, for example, to run "git-update-server-info" +This hook can be used, for example, to run `git update-server-info` if the repository is packed and is served via a dumb transport. #!/bin/sh - exec git-update-server-info + exec git update-server-info 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 8492aeacf1..7fe2d2247b 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 @@ -16,19 +17,17 @@ The command takes various subcommands, and different options depending on the subcommand: [verse] -git reflog expire [--dry-run] [--stale-fix] [--verbose] +'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>] +'git reflog delete' ref@\{specifier\}... +'git reflog' ['show'] [log-options] [<ref>] Reflog is a mechanism to record when the tip of branches are updated. This command is to manage the information recorded in it. The subcommand "expire" is used to prune older reflog entries. Entries older than `expire` time, or entries older than -`expire-unreachable` time and are not reachable from the current +`expire-unreachable` time and not reachable from the current tip, are removed from the reflog. This is typically not used directly by the end users -- instead, see linkgit:git-gc[1]. @@ -36,17 +35,17 @@ The subcommand "show" (which is also the default, in the absence of any subcommands) will take all the normal log options, and show the log of the reference provided in the command-line (or `HEAD`, by default). The reflog will cover all recent actions (HEAD reflog records branch switching -as well). It is an alias for 'git log -g --abbrev-commit --pretty=oneline'; +as well). It is an alias for `git log -g --abbrev-commit --pretty=oneline`; 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 +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:gitrevisions[7] for more details. To delete single entries from the reflog, use the subcommand "delete" -and specify the _exact_ entry (e.g. ``git reflog delete master@\{2\}''). +and specify the _exact_ entry (e.g. "`git reflog delete master@{2}`"). OPTIONS @@ -71,7 +70,7 @@ them. which in turn defaults to 90 days. --expire-unreachable=<time>:: - Entries older than this time and are not reachable from + Entries older than this time and not reachable from the current tip of the branch are pruned. Without the option it is taken from configuration `gc.reflogExpireUnreachable`, which in turn defaults to @@ -92,14 +91,6 @@ them. --verbose:: Print extra information on screen. -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -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 f6dafd4495..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 new file mode 100644 index 0000000000..f5836e46d0 --- /dev/null +++ b/Documentation/git-remote-helpers.txt @@ -0,0 +1,369 @@ +git-remote-helpers(1) +===================== + +NAME +---- +git-remote-helpers - Helper programs to interact with remote repositories + +SYNOPSIS +-------- +[verse] +'git remote-<transport>' <repository> [<URL>] + +DESCRIPTION +----------- + +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/*:refs/svn/origin/branches/*` +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 *:*`. + +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/*:refs/svn/origin/branches/*` +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 *:*`. + +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 +-------- + +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 preceded with '*', + which marks them mandatory for git version using the remote + helper to understand (unknown mandatory capability is fatal + error). + +'list':: + Lists the refs, one per line, in the format "<value> <name> + [<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. 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>:: + 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 valid + for it). Options should be set before other commands, + 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, 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. ++ +Optionally may output a 'lock <file>' line indicating a file under +GIT_DIR/objects/pack which is keeping a pack until refs can be +suitably updated. ++ +Supported if the helper has the "fetch" capability. + +'push' +<src>:<dst>:: + 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 + (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. ++ +When the push is complete, outputs one or more 'ok <dst>' or +'error <dst> <why>?' lines to indicate success or failure of +each pushed ref. The status report output is terminated by +a blank line. The option field <why> may be quoted in a C +style string if it contains an LF. ++ +Supported if the helper has the "push" capability. + +'import' <name>:: + Produces a fast-import stream which imports the current value + of the named ref. It may additionally import other refs as + needed to construct the history efficiently. The script writes + to a helper-specific private namespace. The value of the named + ref should be written to a location in this namespace derived + 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>:: + Connects to given service. Standard input and standard output + of helper are connected to specified service (git prefix is + included in service name so e.g. fetching uses 'git-upload-pack' + as service) on remote side. Valid replies to this command are + empty line (connection established), 'fallback' (no smart + transport support, fall back to dumb transports) and just + exiting with error message printed (can't connect, don't + bother trying to fall back). After line feed terminating the + positive (empty) response, the output of service starts. After + the connection ends, the remote helper exits. ++ +Supported if the helper has the "connect" capability. + +If a fatal error occurs, the program writes the error message to +stderr and exits. The caller should expect that a suitable error +message has been printed if the child closes the connection without +completing a valid response for the current command. + +Additional commands may be supported, as may be determined from +capabilities reported by the helper. + +REF LIST ATTRIBUTES +------------------- + +'for-push':: + The caller wants to use the ref list to prepare push + commands. A helper might chose to acquire the ref list by + opening a different type of connection to the destination. + +'unchanged':: + This ref is unchanged since the last import or fetch, although + the helper cannot necessarily determine what value that produced. + +OPTIONS +------- +'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'\}:: + Enables (or disables) progress messages displayed by the + transport helper during a command. + +'option depth' <depth>:: + Deepens the history of a shallow repository. + +'option followtags' \{'true'|'false'\}:: + If enabled the helper should automatically fetch annotated + tag objects if the object the tag points at was transferred + during the fetch command. If the tag is not fetched by + the helper a second fetch command will usually be sent to + ask for the tag specifically. Some helpers may be able to + use this option to avoid a second network connection. + +'option dry-run' \{'true'|'false'\}: + If true, pretend the operation completed successfully, + but don't actually change any repository data. For most + helpers this only applies to the 'push', if supported. + +'option servpath <c-style-quoted-path>':: + 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. + +SEE ALSO +-------- +linkgit:git-remote[1] + +linkgit:git-remote-testgit[1] + +GIT +--- +Part of the linkgit:git[1] suite 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 345943a264..a308f4c79f 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -9,12 +9,18 @@ git-remote - manage set of tracked repositories SYNOPSIS -------- [verse] -'git-remote' [-v | --verbose] -'git-remote' add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url> -'git-remote' rm <name> -'git-remote' show [-n] <name> -'git-remote' prune [-n | --dry-run] <name> -'git-remote' update [group] +'git remote' [-v | --verbose] +'git remote add' [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror=<fetch|push>] <name> <url> +'git remote rename' <old> <new> +'git remote rm' <name> +'git remote set-head' <name> (-a | -d | <branch>) +'git remote set-branches' [--add] <name> <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>)...] DESCRIPTION ----------- @@ -28,6 +34,7 @@ OPTIONS -v:: --verbose:: Be a little more verbose and show remote url after name. + NOTE: This must be placed between `remote` and `subcommand`. COMMANDS @@ -45,27 +52,95 @@ 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 -up to point at remote's `<master>` branch instead of whatever -branch the `HEAD` at the remote repository actually points at. +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 +configuration settings for the remote are updated. ++ +In case <old> and <new> are the same, and <old> is a file under +`$GIT_DIR/remotes` or `$GIT_DIR/branches`, the remote is converted to +the configuration file format. '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 (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`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted. ++ +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 +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 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 +regex <oldurl> (first URL if no <oldurl> is given) to <newurl>. If +<oldurl> doesn't match any URL, error occurs and nothing is changed. ++ +With '--push', push URLs are manipulated instead of fetch URLs. ++ +With '--add', instead of changing some URL, new URL is added. ++ +With '--delete', instead of changing some URL, all URLs matching +regex <url> are deleted. Trying to delete all non-push URLs is an +error. + 'show':: Gives some information about the remote <name>. @@ -75,22 +150,24 @@ 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>". + -With `--dry-run` option, report what branches will be pruned, but do no +With `--dry-run` option, report what branches will be pruned, but do not actually prune them. 'update':: Fetch updates for a named set of remotes in the repository as defined by remotes.<group>. If a named group is not specified on the command line, -the configuration parameter remotes.default will get used; if +the configuration parameter remotes.default will be used; if remotes.default is not defined, all remotes which do not have the configuration parameter remote.<name>.skipDefaultUpdate set to true will be updated. (See linkgit:git-config[1]). ++ +With `--prune` option, prune all the remotes that are updated. DISCUSSION @@ -141,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 04d6f1fbc4..4c1aff65e6 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 ----------- @@ -31,50 +32,57 @@ OPTIONS Instead of incrementally packing the unpacked objects, pack everything referenced into a single pack. Especially useful when packing a repository that is used - for private development and there is no need to worry - about people fetching via dumb protocols from it. Use + for private development. Use with '-d'. This will clean up the objects that `git prune` - leaves behind, but `git fsck --full` shows as + leaves behind, but `git fsck --full --dangling` shows as dangling. ++ +Note that users fetching over dumb protocols will have to fetch the +whole new pack in order to get any contained object, no matter how many +other objects in that pack they already have locally. -A:: - Same as `-a`, but any unreachable objects in a previous - pack become loose, unpacked objects, instead of being - left in the old pack. Unreachable objects are never - intentionally added to a pack, even when repacking. - When used with '-d', this option - prevents unreachable objects from being immediately + Same as `-a`, unless '-d' is used. Then any unreachable + objects in a previous pack become loose, unpacked objects, + instead of being left in the old pack. Unreachable objects + are never intentionally added to a pack, even when repacking. + This option prevents unreachable objects from being immediately deleted by way of being left in the old pack and then removed. Instead, the loose unreachable objects will be pruned according to normal expiry rules - with the next 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 runs linkgit:git-prune-packed[1]. + 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 + 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 gitlink:git-update-server-info[1]. + 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 @@ -84,10 +92,10 @@ OPTIONS 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 @@ -96,32 +104,25 @@ OPTIONS 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 new file mode 100644 index 0000000000..17df525275 --- /dev/null +++ b/Documentation/git-replace.txt @@ -0,0 +1,85 @@ +git-replace(1) +============== + +NAME +---- +git-replace - Create, list, delete refs to replace objects + +SYNOPSIS +-------- +[verse] +'git replace' [-f] <object> <replacement> +'git replace' -d <object>... +'git replace' -l [<pattern>] + +DESCRIPTION +----------- +Adds a 'replace' reference in `.git/refs/replace/` + +The name of the 'replace' reference is the SHA1 of the object that is +replaced. The content of the 'replace' reference is the SHA1 of the +replacement object. + +Unless `-f` is given, the 'replace' reference must not yet exist in +`.git/refs/replace/` directory. + +Replacement references will be used by default by all git commands +except those doing reachability traversal (prune, pack transfer and +fsck). + +It is possible to disable use of replacement references for any +command using the `--no-replace-objects` option just after 'git'. + +For example if commit 'foo' has been replaced by commit 'bar': + +------------------------------------------------ +$ git --no-replace-objects cat-file commit foo +------------------------------------------------ + +shows information about commit 'foo', while: + +------------------------------------------------ +$ git cat-file commit foo +------------------------------------------------ + +shows information about commit 'bar'. + +The 'GIT_NO_REPLACE_OBJECTS' environment variable can be set to +achieve the same effect as the `--no-replace-objects` option. + +OPTIONS +------- +-f:: + If an existing replace ref for the same object exists, it will + be overwritten (instead of failing). + +-d:: + Delete existing replace refs for the given objects. + +-l <pattern>:: + List replace refs for objects that match the given pattern (or + all if no pattern is given). + Typing "git replace" without arguments, also lists all replace + refs. + +BUGS +---- +Comparing blobs or trees that have been replaced with those that +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. + +There may be other problems when using 'git rev-list' related to +pending objects. And of course things may break if an object of one +type is replaced by an object of another type (for example a blob +replaced by a commit). + +SEE ALSO +-------- +linkgit:git-tag[1] +linkgit:git-branch[1] +linkgit:git[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index 2ca39946b7..9ec115b9e0 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -8,7 +8,8 @@ git-repo-config - Get and set repository or global options SYNOPSIS -------- -'git-repo-config' ... +[verse] +'git repo-config' ... DESCRIPTION @@ -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 c71d86985e..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 <junkio@cox.net> - -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 8030ec4d01..a62227f84e 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -7,65 +7,76 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- -'git-rerere' [clear|diff|status|gc] +[verse] +'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc'] DESCRIPTION ----------- -In a workflow that employs relatively long lived topic branches, -the developer sometimes needs to resolve the same conflict over +In a workflow employing relatively long lived topic branches, +the developer sometimes needs to resolve the same conflicts over and over again until the topic branches are done (either merged to the "release" branch, or sent out and accepted upstream). -This command helps this process by recording conflicted -automerge results and corresponding hand-resolve results on the -initial manual merge, and later by noticing the same automerge -results and applying the previously recorded hand resolution. +This command assists the developer in this process by recording +conflicted automerge results and corresponding hand resolve results +on the initial manual merge, and applying previously recorded +hand resolutions to their corresponding automerge results. [NOTE] -You need to set the configuration variable rerere.enabled to +You need to set the configuration variable rerere.enabled in order to 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 -is aborted. Calling linkgit:git-am[1] --skip or linkgit:git-rebase[1] -[--skip|--abort] will automatically invoke this command. +Reset the metadata used by rerere if a merge resolution is to be +aborted. Calling 'git am [--skip|--abort]' or 'git rebase [--skip|--abort]' +will automatically invoke this command. + +'forget' <pathspec>:: + +Reset 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 +Display diffs for the current state of the resolution. It is useful for tracking what has changed while the user is resolving conflicts. Additional arguments are passed directly to the system -diff(1) command installed in PATH. +'diff' command installed in PATH. 'status':: -Like diff, but this only prints the filenames that will be tracked -for resolutions. +Print paths with conflicts whose merge resolution rerere will record. + +'remaining':: + +Print paths with conflicts that have not been autoresolved by rerere. +This includes paths whose resolutions cannot be tracked by rerere, +such as conflicting submodules. 'gc':: -This command is used to prune records of conflicted merge that -occurred long time ago. By default, conflicts older than 15 -days that you have not recorded their resolution, and conflicts -older than 60 days, are pruned. These are controlled with +Prune records of conflicted merges that +occurred a long time ago. By default, unresolved conflicts older +than 15 days and resolved conflicts older than 60 +days are pruned. These defaults are controlled via the `gc.rerereunresolved` and `gc.rerereresolved` configuration -variables. +variables respectively. DISCUSSION ---------- -When your topic branch modifies overlapping area that your +When your topic branch modifies an overlapping area that your master branch (or upstream) touched since your topic branch forked from it, you may want to test it with the latest master, even before your topic branch is ready to be pushed upstream: @@ -140,46 +151,45 @@ top of the tip before the test merge: This would leave only one merge commit when your topic branch is finally ready and merged into the master branch. This merge would require you to resolve the conflict, introduced by the -commits marked with `*`. However, often this conflict is 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` command helps you to resolve this final +blew away. 'git rerere' helps you resolve this final conflicted merge using the information from your earlier hand resolve. -Running `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 records 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, running `git-rerere` after seeing a conflicted -automerge, if the conflict is the same as the earlier one -recorded, it is noticed and a three-way merge between the +Next time, after seeing the same conflicted automerge, +running 'git rerere' will perform a three-way merge between the earlier conflicted automerge, the earlier manual resolution, and -the current conflicted automerge is performed by the command. +the current conflicted automerge. If this three-way merge resolves cleanly, the result is written -out to your working tree file, so you would not have to manually -resolve it. Note that `git-rerere` leaves the index file alone, +out to your working tree file, so you do not have to manually +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` when it exits with a failed automerge, which -records it if it is a new conflict, or reuses the earlier hand -resolve when it is not. `git-commit` also invokes `git-rerere` -when recording a merge result. What this means is that you do -not have to do anything special yourself (Note: you still have -to set the config variable rerere.enabled to enable this command). +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' +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). -In our example, when you did the test merge, the manual +In our example, when you do the test merge, the manual resolution is recorded, and it will be reused when you do the -actual merge later with updated master and topic branch, as long -as the earlier resolution is still applicable. +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: ------------ @@ -194,18 +204,13 @@ development on the topic branch: o---o---o---*---o---o---o---o master ------------ -you could run `git rebase master topic`, to keep yourself -up-to-date even before your topic is ready to be sent upstream. -This would result in falling back to three-way merge, and it -would conflict the same way the test merge you resolved earlier. -`git-rerere` is run by `git rebase` to help you resolve this +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 conflict. - -Author ------- -Written by Junio C Hamano <junkio@cox.net> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 12ea9b23c5..117e3743a6 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,52 +8,119 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git reset' [--mixed | --soft | --hard] [-q] [<commit>] 'git reset' [-q] [<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. +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. -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. +'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. -The second form with 'paths' is used to revert selected paths in -the index from a given commit, without moving HEAD. +'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 linkgit:git-status[1] 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 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. ++ +In other words, --merge does something like a 'git read-tree -u -m <commit>', +but carries forward unmerged index entries. + +--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. +-- + +If you want to undo a commit other than the latest on a branch, +linkgit:git-revert[1] is your friend. + + +OPTIONS +------- -q:: +--quiet:: Be quiet, only report errors. -<commit>:: - Commit to make the current HEAD. If not given defaults to HEAD. -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:: + ------------ @@ -73,17 +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. - Undo a commit, making it a topic branch:: + ------------ @@ -99,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:: + @@ -128,11 +174,11 @@ Undo a merge or pull:: $ git pull <1> Auto-merging nitfol CONFLICT (content): Merge conflict in nitfol -Automatic merge failed/prevented; fix up by hand +Automatic merge failed; fix conflicts and then commit the result. $ git reset --hard <2> $ git pull . topic/branch <3> Updating from 41223... to 13134... -Fast forward +Fast-forward $ git reset --hard ORIG_HEAD <4> ------------ + @@ -143,13 +189,35 @@ right now, so you decide to do that later. which is a synonym for "git reset --hard HEAD" clears the mess from the index file and the working tree. <3> Merge a topic branch into the current branch, which resulted -in a fast forward. +in a fast-forward. <4> But you decided that the topic branch is not ready for public consumption yet. "pull" or "merge" always leaves the original 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 working tree:: ++ +------------ +$ git pull <1> +Auto-merging nitfol +Merge made by recursive. + nitfol | 20 +++++---- + ... +$ git reset --merge ORIG_HEAD <2> +------------ ++ +<1> Even if you may have local modifications in your +working tree, you can safely say "git pull" when you know +that the change in the other branch does not overlap with +them. +<2> After inspecting the result of the merge, you may find +that the change in the other branch is unsatisfactory. Running +"git reset --hard ORIG_HEAD" will let you go back to where you +were, but it will discard your local changes, which you do not +want. "git reset --merge" keeps your local changes. + + Interrupted workflow:: + Suppose you are interrupted by an urgent fix request while you @@ -175,6 +243,8 @@ $ git reset <3> <3> At this point the index file still has all the WIP changes you committed as 'snapshot WIP'. This updates the index to show your WIP files as uncommitted. ++ +See also linkgit:git-stash[1]. Reset a single file in the index:: + @@ -193,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 <junkio@cox.net> 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) + + 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) -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +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 c9b0950321..38fafcaa6b 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -9,33 +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} ] + [ \--regexp-ignore-case | -i ] + [ \--extended-regexp | -E ] + [ \--fixed-strings | -F ] + [ \--date=(local|relative|default|iso|rfc|short) ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] [ \--bisect ] @@ -50,28 +60,34 @@ SYNOPSIS DESCRIPTION ----------- -Lists commit objects in reverse chronological order starting at the -given commit(s), taking ancestry relationship into account. This is -useful to produce human-readable log output. +List commits that are reachable by following the `parent` links from the +given commit(s), but exclude commits that are reachable from the one(s) +given with a '{caret}' in front of them. The output is given in reverse +chronological order by default. -Commits which are stated with a preceding '{caret}' cause listing to -stop at that point. Their parents are implied. Thus the following -command: +You can think of this as a set operation. Commits given on the command +line form a set of commits that are reachable from any of them, and then +commits reachable from any of the ones given with '{caret}' in front are +subtracted from that set. The remaining commits are what comes out in the +command's output. Various other options and paths parameters can be used +to further limit the result. + +Thus, the following command: ----------------------------------------------------------------------- - $ git-rev-list foo bar ^baz + $ git rev-list foo bar ^baz ----------------------------------------------------------------------- -means "list all the commits which are included in 'foo' and 'bar', but -not in 'baz'". +means "list all the commits which are reachable from 'foo' or 'bar', but +not from 'baz'". A special notation "'<commit1>'..'<commit2>'" can be used as a short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of the following may be used interchangeably: ----------------------------------------------------------------------- - $ git-rev-list origin..HEAD - $ git-rev-list HEAD ^origin + $ git rev-list origin..HEAD + $ git rev-list HEAD ^origin ----------------------------------------------------------------------- Another special notation is "'<commit1>'...'<commit2>'" which is useful @@ -79,15 +95,15 @@ for merges. The resulting set of commits is the symmetric difference between the two operands. The following two commands are equivalent: ----------------------------------------------------------------------- - $ git-rev-list A B --not $(git-merge-base --all A B) - $ git-rev-list A...B + $ git rev-list A B --not $(git merge-base --all A B) + $ git rev-list A...B ----------------------------------------------------------------------- -linkgit:git-rev-list[1] is a very essential git program, since it +'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 linkgit:git-bisect[1] and -linkgit:git-repack[1]. +used by commands as different as 'git bisect' and +'git repack'. OPTIONS ------- @@ -97,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 9e273bc5a6..4cc3e9586f 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -8,35 +8,46 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- -'git-rev-parse' [ --option ] <args>... +[verse] +'git rev-parse' [ --option ] <args>... DESCRIPTION ----------- Many git porcelainish commands take mixture of flags (i.e. parameters that begin with a dash '-') and parameters -meant for underlying `git-rev-list` command they use internally -and flags and parameters for other commands they use as the -downstream of `git-rev-list`. This command is used to +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 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-dash-dash:: +--keep-dashdash:: Only meaningful in `--parseopt` mode. Tells the option parser to echo out the first `--` met instead of skipping it. +--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 themselves. + +--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. @@ -64,7 +75,8 @@ 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-\*`). + 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, + the command input is still interpreted as usual. --not:: When showing object names, prefix them with '{caret}' and @@ -84,17 +96,34 @@ OPTIONS unfortunately named tag "master"), and show them as full refnames (e.g. "refs/heads/master"). ---all:: - Show all refs found in `$GIT_DIR/refs`. +--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. ---branches:: - Show branch refs found in `$GIT_DIR/refs/heads`. +--all:: + 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 (`?`, +`*`, or `[`), it is turned into a prefix match by appending `/*`. ---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 (`?`, `*`, or `[`), it is turned into a prefix + match by appending `/*`. ---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 @@ -107,7 +136,13 @@ 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. The path shown, when relative, is + relative to the current working 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 @@ -120,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 @@ -128,207 +169,43 @@ OPTIONS --since=datestring:: --after=datestring:: - Parses the date string, and outputs corresponding - --max-age= parameter for git-rev-list command. + Parse the date string, and output the corresponding + --max-age= parameter for 'git rev-list'. --until=datestring:: --before=datestring:: - Parses the date string, and outputs corresponding - --min-age= parameter for git-rev-list command. + Parse the date string, and output the corresponding + --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, 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` 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. - -* 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>). - -* 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\}'. - -* 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. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is -the difference of two sets (subtract the set of commits -reachable from `r1` from the set of commits reachable from -`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 exists. `r1{caret}@` notation means all -parents of `r1`. `r1{caret}!` includes commit `r1` but excludes -its all 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. @@ -381,7 +258,34 @@ 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 +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` +option. + +Example +~~~~~~~ + +------------ +$ cat >your-git-script.sh <<\EOF +#!/bin/sh +args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments +command="git frotz -n24 $args" # and use it inside a handcrafted + # command line +eval "$command" +EOF + +$ sh your-git-script.sh "a b'c" ------------ EXAMPLES @@ -409,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 <junkio@cox.net> 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 5b49b81386..70152e8b1e 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -3,28 +3,46 @@ 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' --continue +'git revert' --quit +'git revert' --abort 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). + +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 +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. @@ -35,37 +53,69 @@ OPTIONS option specifies the parent number (starting from 1) of the mainline and allows revert to reverse the change relative to the specified parent. ++ +Reverting a merge commit declares that you will never want the tree changes +brought in by the merge. As a result, later merges will only bring in tree +changes introduced by commits that are not ancestors of the previously +reverted merge. This may or may not be what you want. ++ +See the link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for +more details. --no-edit:: - With this option, `git-revert` will not start the commit + 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, but does not make the - commit. In addition, when this option is used, your - working tree does not have to match the HEAD commit. - The revert is done against the beginning state of your - working tree. + 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. + This is useful when reverting more than one commits' -effect to your working tree in a row. +effect to your index in a row. -s:: --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. -Author ------- -Written by Junio C Hamano <junkio@cox.net> +SEQUENCER SUBCOMMANDS +--------------------- +include::sequencer.txt[] -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +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. + +`git revert -n master~5..master~2`:: + + 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 d88554bedc..5d31860eb1 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -7,18 +7,19 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- -'git-rm' [-f] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... +[verse] +'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... DESCRIPTION ----------- Remove files from the index, or from the working tree and the index. `git rm` will not remove a file from just your working directory. -(There is no option to remove a file only from the work tree +(There is no option to remove a file only from the working tree and yet keep it in the index; use `/bin/rm` if you want to do that.) The files being removed have to be identical to the tip of the branch, and no updates to their contents can be staged in the index, though that default behavior can be overridden with the `-f` option. -When '--cached' is given, the staged content has to +When `--cached` is given, the staged content has to match either the tip of the branch or the file on disk, allowing the file to be removed from just the index. @@ -36,6 +37,7 @@ OPTIONS but this requires the `-r` option to be explicitly given. -f:: +--force:: Override the up-to-date check. -n:: @@ -63,7 +65,7 @@ OPTIONS -q:: --quiet:: - git-rm normally outputs one line (in the form of an "rm" command) + `git rm` normally outputs one line (in the form of an `rm` command) for each file removed. This option suppresses that output. @@ -77,20 +79,72 @@ 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 'd*'` and `git rm 'd/*'`, as the former will also remove all of directory `d2`. +REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM +-------------------------------------------------------- +There is no option for `git rm` to remove from the index only +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'' +~~~~~~~~~~~~~~~~~~~~~~~ +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` +(as opposed to `git rm`), use `git commit -a`, as it will +automatically notice and record all removals. You can also have a +similar effect without committing by using `git add -u`. + +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. + +Typically you would first remove all tracked files from the working +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. + +After that, the easiest way to record all removals, additions, and +modifications in the working tree is: + +---------------- +git add -A +---------------- + +See linkgit:git-add[1]. + +Other ways +~~~~~~~~~~ +If all you really want to do is to remove from the index the files +that are no longer present in the working tree (perhaps because +your working tree is dirty so that you cannot use `git commit -a`), +use the following command: + +---------------- +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`. @@ -99,14 +153,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 251d661afd..324117072d 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -8,82 +8,162 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- -'git-send-email' [options] <file|directory> [... file|directory] - +[verse] +'git send-email' [options] <file|directory|rev-list options>... DESCRIPTION ----------- Takes the patches given on the command line and emails them out. +Patches can be specified as files, directories (which will send all +files in the directory), or directly as a revision list. In the +last case, any format accepted by linkgit:git-format-patch[1] can +be passed to git send-email. The header of the email is configurable by command line options. If not specified on the command line, the user will be prompted with a ReadLine enabled interface to provide the necessary information. +There are two formats accepted for patch files: + +1. mbox format files ++ +This is what linkgit:git-format-patch[1] generates. Most headers and MIME +formatting are ignored. + +2. The original format used by Greg Kroah-Hartman's 'send_lots_of_email.pl' +script ++ +This format expects the first line of the file to contain the "Cc:" value +and the "Subject:" of the message as the second line. + + OPTIONS ------- -The options available are: ---bcc:: - Specify a "Bcc:" value for each email. +Composing +~~~~~~~~~ + +--annotate:: + Review and edit each patch you're about to send. See the + CONFIGURATION section for 'sendemail.multiedit'. + +--bcc=<address>:: + Specify a "Bcc:" value for each email. Default is the value of + 'sendemail.bcc'. + The --bcc option must be repeated for each user you want on the bcc list. ---cc:: +--cc=<address>:: Specify a starting "Cc:" value for each email. + Default is the value of 'sendemail.cc'. + The --cc option must be repeated for each user you want on the cc list. ---cc-cmd:: - Specify a command to execute once per patch file which - should generate patch file specific "Cc:" entries. - Output of this command must be single email address per line. - Default is the value of 'sendemail.cccmd' configuration value. - ---chain-reply-to:: ---no-chain-reply-to:: - If this is set, each email will be sent as a reply to the previous - email sent. If disabled with "--no-chain-reply-to", all emails after - the first will be sent as replies to the first email sent. When using - this, it is recommended that the first file given be an overview of the - entire patch series. - Default is the value of the 'sendemail.chainreplyto' configuration - value; if that is unspecified, default to --chain-reply-to. - --compose:: - Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an - introductory message for the patch series. - ---from:: - Specify the sender of the emails. This will default to - the value GIT_COMMITTER_IDENT, as returned by "git-var -l". - The user will still be prompted to confirm this entry. - ---in-reply-to:: - 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 (the default) + Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) + to edit an introductory message for the patch series. ++ +When '--compose' is used, git send-email will use the From, Subject, and +In-Reply-To headers specified in the message. If the body of the message +(what you type after the headers and a blank line) only contains blank +(or GIT: prefixed) lines the summary won't be sent, but From, Subject, +and In-Reply-To headers will be used unless they are removed. ++ +Missing From or In-Reply-To headers will be prompted for. ++ +See the CONFIGURATION section for 'sendemail.multiedit'. + +--from=<address>:: + Specify the sender of the emails. If not specified on the command line, + the value of the 'sendemail.from' configuration option is used. If + neither the command line option nor 'sendemail.from' are set, then the + user will be prompted for the value. The default for the prompt will be + the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not + set, as returned by "git var -l". + +--in-reply-to=<identifier>:: + 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. Only necessary if --compose is also set. If --compose is not set, this will be prompted for. ---signed-off-by-cc:: ---no-signed-off-by-cc:: - If this is set, add emails found in Signed-off-by: or Cc: lines to the - cc list. - Default is the value of 'sendemail.signedoffcc' configuration value; - if that is unspecified, default to --signed-off-by-cc. +--to=<address>:: + 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, + 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. ---quiet:: - Make git-send-email less verbose. One line per email should be - all that is output. +--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. ---identity:: - A configuration identity. When given, causes values in the - 'sendemail.<identity>' subsection to take precedence over - values in the 'sendemail' section. The default identity is - the value of 'sendemail.identity'. ---smtp-server:: +Sending +~~~~~~~ + +--envelope-sender=<address>:: + Specify the envelope sender used to send the emails. + This is useful if your default address is not the address that is + subscribed to a list. In order to use the 'From' address, set the + value to "auto". If you use the sendmail binary, you must have + suitable privileges for the -f parameter. Default is the value of the + 'sendemail.envelopesender' configuration variable; if that is + unspecified, choosing the envelope sender is left to your MTA. + +--smtp-encryption=<encryption>:: + Specify the encryption to use, either 'ssl' or 'tls'. Any other + 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 + the password. Default is the value of 'sendemail.smtppass', + however '--smtp-pass' always overrides this value. ++ +Furthermore, passwords need not be specified in configuration files +or on the command line. If a username has been specified (with +'--smtp-user' or a 'sendemail.smtpuser'), but no password has been +specified (with '--smtp-pass' or 'sendemail.smtppass'), then the +user is prompted for a password while the input is masked for privacy. + +--smtp-server=<host>:: If set, specifies the outgoing SMTP server to use (e.g. `smtp.example.com` or a raw IP address). Alternatively it can specify a full pathname of a sendmail-like program instead; @@ -93,108 +173,166 @@ The --cc option must be repeated for each user you want on the cc list. `/usr/lib/sendmail` if such program is available, or `localhost` otherwise. ---smtp-server-port:: +--smtp-server-port=<port>:: Specifies a port different from the default port (SMTP - servers typically listen to smtp port 25 and ssmtp port - 465). + servers typically listen to smtp port 25, but may also listen to + submission port 587, or the common SSL smtp port 465); + symbolic port names (e.g. "submission" instead of 587) + 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-user:: - Username for SMTP-AUTH. In place of this option, the following - configuration variables can be specified: +--smtp-ssl:: + Legacy alias for '--smtp-encryption ssl'. + +--smtp-user=<user>:: + Username for SMTP-AUTH. Default is the value of 'sendemail.smtpuser'; + if a username is not specified (with '--smtp-user' or 'sendemail.smtpuser'), + then authentication is not attempted. + +--smtp-debug=0|1:: + Enable (1) or disable (0) debug output. If enabled, SMTP + commands and replies will be printed. Useful to debug TLS + connection and authentication problems. + +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. + Output of this command must be single email address per line. + Default is the value of 'sendemail.cccmd' configuration value. + +--[no-]chain-reply-to:: + If this is set, each email will be sent as a reply to the previous + email sent. If disabled with "--no-chain-reply-to", all emails after + the first will be sent as replies to the first email sent. When using + this, it is recommended that the first file given be an overview of the + entire patch series. Disabled by default, but the 'sendemail.chainreplyto' + configuration variable can be used to enable it. + +--identity=<identity>:: + A configuration identity. When given, causes values in the + 'sendemail.<identity>' subsection to take precedence over + values in the 'sendemail' section. The default identity is + the value of 'sendemail.identity'. + +--[no-]signed-off-by-cc:: + If this is set, add emails found in Signed-off-by: or Cc: lines to the + cc list. Default is the value of 'sendemail.signedoffbycc' configuration + value; if that is unspecified, default to --signed-off-by-cc. + +--suppress-cc=<category>:: + Specify an additional category of recipients to suppress the + auto-cc of: + -- - * sendemail.smtpuser - * sendemail.<identity>.smtpuser (see sendemail.identity). +- 'author' will avoid including the patch author +- 'self' will avoid including the sender +- 'cc' will avoid including anyone mentioned in Cc lines in the patch header + except for self (use 'self' for that). +- 'bodycc' will avoid including anyone mentioned in Cc lines in the + patch body (commit message) except for self (use 'self' for that). +- 'sob' will avoid including anyone mentioned in Signed-off-by lines except + for self (use 'self' for that). +- 'cccmd' will avoid running the --cc-cmd. +- 'body' is equivalent to 'sob' + 'bodycc' +- 'all' will suppress all auto cc values. -- + -However, --smtp-user always overrides these variables. +Default is the value of 'sendemail.suppresscc' configuration value; if +that is unspecified, default to 'self' if --suppress-from is +specified, as well as 'body' if --no-signed-off-cc is specified. + +--[no-]suppress-from:: + If this is set, do not add the From: address to the cc: list. + Default is the value of 'sendemail.suppressfrom' configuration + value; if that is unspecified, default to --no-suppress-from. + +--[no-]thread:: + If this is set, the In-Reply-To and References headers will be + added to each email sent. Whether each mail refers to the + previous email (`deep` threading per 'git format-patch' + wording) or to the first email (`shallow` threading) is + governed by "--[no-]chain-reply-to". + -If a username is not specified (with --smtp-user or a -configuration variable), then authentication is not attempted. - ---smtp-pass:: - Password for SMTP-AUTH. The argument is optional: If no - argument is specified, then the empty string is used as - the password. +If disabled with "--no-thread", those headers will not be added +(unless specified with --in-reply-to). Default is the value of the +'sendemail.thread' configuration value; if that is unspecified, +default to --thread. + -In place of this option, the following configuration variables -can be specified: +It is up to the user to ensure that no In-Reply-To header already +exists when 'git send-email' is asked to add it (especially note that +'git format-patch' can be configured to do the threading itself). +Failure to do so may not produce the expected result in the +recipient's MUA. + + +Administering +~~~~~~~~~~~~~ + +--confirm=<mode>:: + Confirm just before sending: + -- - * sendemail.smtppass - * sendemail.<identity>.smtppass (see sendemail.identity). +- 'always' will always confirm before sending +- 'never' will never confirm before sending +- 'cc' will confirm before sending when send-email has automatically + added addresses from the patch to the Cc list +- 'compose' will confirm before sending the first message when using --compose. +- 'auto' is equivalent to 'cc' + 'compose' -- + -However, --smtp-pass always overrides these variables. -+ -Furthermore, passwords need not be specified in configuration files -or on the command line. If a username has been specified (with ---smtp-user or a configuration variable), but no password has been -specified (with --smtp-pass or a configuration variable), then the -user is prompted for a password while the input is masked for privacy. - ---smtp-ssl:: - If set, connects to the SMTP server using SSL. - Default is the value of the 'sendemail.smtpssl' configuration value; - if that is unspecified, does not use SSL. - ---subject:: - Specify the initial subject of the email thread. - Only necessary if --compose is also set. If --compose - is not set, this will be prompted for. - ---suppress-from:: ---no-suppress-from:: - If this is set, do not add the From: address to the cc: list. - Default is the value of 'sendemail.suppressfrom' configuration value; - if that is unspecified, default to --no-suppress-from. - ---suppress-cc:: - Specify an additional category of recipients to suppress the - auto-cc of. 'self' will avoid including the sender, 'author' will - avoid including the patch author, 'cc' will avoid including anyone - mentioned in Cc lines in the patch, 'sob' will avoid including - anyone mentioned in Signed-off-by lines, and 'cccmd' will avoid - running the --cc-cmd. 'all' will suppress all auto cc values. - Default is the value of 'sendemail.suppresscc' configuration value; - if that is unspecified, default to 'self' if --suppress-from is - specified, as well as 'sob' if --no-signed-off-cc is specified. - ---thread:: ---no-thread:: - If this is set, the In-Reply-To header will be set on each email sent. - If disabled with "--no-thread", no emails will have the In-Reply-To - header set. - Default is the value of the 'sendemail.thread' configuration value; - if that is unspecified, default to --thread. +Default is the value of 'sendemail.confirm' configuration value; if that +is unspecified, default to 'auto' unless any of the suppress options +have been specified, in which case default to 'compose'. --dry-run:: Do everything except actually send the emails. ---envelope-sender:: - Specify the envelope sender used to send the emails. - This is useful if your default address is not the address that is - subscribed to a list. If you use the sendmail binary, you must have - suitable privileges for the -f parameter. +--[no-]format-patch:: + When an argument may be understood either as a reference or as a file name, + choose to understand it as a format-patch argument ('--format-patch') + or as a file name ('--no-format-patch'). By default, when such a conflict + occurs, git send-email will fail. ---to:: - 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. +--quiet:: + Make git-send-email less verbose. One line per email should be + all that is output. + +--[no-]validate:: + Perform sanity checks on patches. + Currently, validation means the following: + -The --to option must be repeated for each user you want on the to list. +-- + * Warn of patches that contain lines longer than 998 characters; this + is due to SMTP limits as described by http://www.ietf.org/rfc/rfc2821.txt. +-- ++ +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 ------------- -sendemail.identity:: - The default configuration identity. When specified, - 'sendemail.<identity>.<item>' will have higher precedence than - 'sendemail.<item>'. This is useful to declare multiple SMTP - identities and to hoist sensitive authentication information - out of the repository and into the global configuration file. sendemail.aliasesfile:: To avoid typing long email addresses, point this to one or more @@ -202,46 +340,45 @@ sendemail.aliasesfile:: sendemail.aliasfiletype:: Format of the file(s) specified in sendemail.aliasesfile. Must be - one of 'mutt', 'mailrc', 'pine', or 'gnus'. + one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus'. -sendemail.to:: - Email address (or alias) to always send to. +sendemail.multiedit:: + If true (default), a single editor instance will be spawned to edit + files you have to edit (patches when '--annotate' is used, and the + summary when '--compose' is used). If false, files will be edited one + after the other, spawning a new editor each time. -sendemail.cccmd:: - Command to execute to generate per patch file specific "Cc:"s. +sendemail.confirm:: + Sets the default for whether to confirm before sending. Must be + one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm' + in the previous section for the meaning of these values. -sendemail.bcc:: - Email address (or alias) to always bcc. - -sendemail.chainreplyto:: - Boolean value specifying the default to the '--chain_reply_to' - parameter. - -sendemail.smtpserver:: - Default SMTP server to use. - -sendemail.smtpserverport:: - Default SMTP server port to use. - -sendemail.smtpuser:: - Default SMTP-AUTH username. +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: -sendemail.smtppass:: - Default SMTP-AUTH password. + [sendemail] + smtpencryption = tls + smtpserver = smtp.gmail.com + smtpuser = yourname@gmail.com + smtpserverport = 587 -sendemail.smtpssl:: - Boolean value specifying the default to the '--smtp-ssl' parameter. +Once your commits are ready to be sent to the mailing list, run the +following commands: -Author ------- -Written by Ryan Anderson <ryan@michonline.com> + $ git format-patch --cover-letter -M origin/master -o outgoing/ + $ edit outgoing/0000-* + $ git send-email outgoing/* -git-send-email is originally based upon -send_lots_of_email.pl by Greg Kroah-Hartman. +Note: the following perl modules are required + Net::SMTP::SSL, MIME::Base64 and Authen::SASL -Documentation --------------- -Documentation by Ryan Anderson +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 ba2fdaec08..bd3eaa69bf 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -8,12 +8,13 @@ git-send-pack - Push objects over git protocol to another repository SYNOPSIS -------- -'git-send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] +[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 linkgit:git-push[1] which is a -higher level wrapper of this command instead. +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 updates it from the current repository, sending named refs. @@ -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,8 +87,8 @@ 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 linkgit:git-rev-parse[1] to resolve a symbolic ref -name. +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 local refs. @@ -105,24 +106,15 @@ name. Without '--force', the <src> ref is stored at the remote only if <dst> does not exist, or <dst> is a proper subset (i.e. an -ancestor) of <src>. This check, known as "fast forward check", +ancestor) of <src>. This check, known as "fast-forward check", is performed in order to avoid accidentally overwriting the remote ref and lose other peoples' commits from there. -With '--force', the fast forward check is disabled for all refs. +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..2ffaf9392e --- /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 `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 c543170342..5e5f1c8964 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -7,7 +7,8 @@ git-sh-setup - Common git shell script setup code SYNOPSIS -------- -'git-sh-setup' +[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,29 @@ 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. + +require_clean_work_tree <action> [<hint>]:: + checks that the working tree and index associated with the + repository have no uncommitted changes to tracked files. + Otherwise it emits an error message of the form `Cannot + <action>: <reason>. <hint>`, and dies. Example: ++ +---------------- +require_clean_work_tree rebase "Please commit or stash them." +---------------- 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 bd09196acc..9b9250600f 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -3,31 +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-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 the `git-receive-pack` and `git-upload-pack` commands -are permitted to be called, with a single required argument. - -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 daa64d4d81..01d8417316 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,8 +8,8 @@ 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 log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] +'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] <commit>... DESCRIPTION ----------- @@ -19,6 +19,11 @@ 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,33 +44,29 @@ 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 '* [%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 and subsequent lines are indented by `indent2` spaces. `width`, `indent1`, and `indent2` default to 76, 6 and 9 respectively. -FILES ------ - -If the file `.mailmap` exists, it will be used for mapping author -email addresses to a real author name. One mapping per line, first -the author name followed by the email address enclosed by -'<' and '>'. Use hash '#' for comments. Example: ------------- -# Keep alphabetized -Adam Morrow <adam@localhost.localdomain> -Eve Jones <eve@laptop.(none)> ------------- +MAPPING AUTHORS +--------------- -Author ------- -Written by Jeff Garzik <jgarzik@pobox.com> +The `.mailmap` feature is used to coalesce together commits by the same +person in the shortlog, where their name and/or email address was +spelled differently. -Documentation --------------- -Documentation by Junio C Hamano. +include::mailmap.txt[] GIT --- diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index de9e8f885f..a8e77b5350 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -8,17 +8,19 @@ git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -'git-show-branch' [--all] [--remotes] [--topo-order] [--current] +'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order] + [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] - [--no-name | --sha1-name] [--topics] [<rev> | <glob>]... -'git-show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] + [--no-name | --sha1-name] [--topics] + [(<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. @@ -29,13 +31,13 @@ no <rev> nor <glob> is given on the command line. OPTIONS ------- <rev>:: - Arbitrary extended SHA1 expression (see `git-rev-parse`) - that typically names a branch HEAD or a tag. + 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:: @@ -57,6 +59,11 @@ OPTIONS appear in topological order (i.e., descendant commits are shown before their parents). +--date-order:: + This option is similar to '--topo-order' in the sense that no + parent comes before all of its children, but otherwise commits + are ordered according to their commit date. + --sparse:: By default, the output omits merges that are reachable from only one tip being shown. This option makes them @@ -74,9 +81,11 @@ OPTIONS Synonym to `--more=-1` --merge-base:: - Instead of showing the commit list, just act like the - 'git-merge-base -a' command, except that it can accept - more than two heads. + Instead of showing the commit list, determine possible + merge bases for the specified commits. All merge bases + will be contained in all specified commits. This is + different from how linkgit:git-merge-base[1] handles + the case of three or more commits. --independent:: Among the <reference>s given, display only the ones that @@ -99,14 +108,24 @@ OPTIONS will show the revisions given by "git rev-list {caret}master topic1 topic2" +-g:: --reflog[=<n>[,<base>]] [<ref>]:: Shows <n> most recent ref-log entries for the given ref. If <base> is given, <n> entries going back from that entry. <base> can be specified as count or date. - `-g` can be used as a short-hand for this option. When - no explicit <ref> parameter is given, it defaults to the + When no explicit <ref> parameter is given, it defaults to the current branch (or `HEAD` if it is detached). +--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. @@ -148,16 +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'. "fixes" branch -adds one commit 'Introduce "reset type"'. "mhf" branch has 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: ------------ @@ -172,24 +192,13 @@ only the primary branches. In addition, if you happen to be on your topic branch, it is shown as well. ------------ -$ git show-branch --reflog='10,1 hour ago' --list master +$ git show-branch --reflog="10,1 hour ago" --list master ------------ shows 10 reflog entries going back from the tip as of 1 hour ago. Without `--list`, the output also shows how these tips are topologically related with each other. - -Author ------- -Written by Junio C Hamano <junkio@cox.net> - - -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 891f0eff27..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 -------- -'git-show-index' < idx-file +[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 6b99529b6b..5dbcd47fec 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -8,9 +8,10 @@ git-show-ref - List references in a local repository SYNOPSIS -------- [verse] -'git-show-ref' [-q|--quiet] [--verify] [-h|--head] [-d|--dereference] - [-s|--hash] [--abbrev] [--tags] [--heads] [--] <pattern>... -'git-show-ref' --exclude-existing[=pattern] +'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference] + [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] + [--heads] [--] [<pattern>...] +'git show-ref' --exclude-existing[=<pattern>] < ref-list DESCRIPTION ----------- @@ -24,12 +25,11 @@ The --exclude-existing form is a filter that does the inverse, it shows the refs from stdin that don't exist in the local repository. Use of this utility is encouraged in favor of directly accessing files under -in the `.git` directory. +the `.git` directory. OPTIONS ------- --h:: --head:: Show the HEAD reference. @@ -44,13 +44,13 @@ OPTIONS -d:: --dereference:: - Dereference tags into object IDs as well. They will be shown with "^{}" + Dereference tags into object IDs as well. They will be shown with "{caret}{}" appended. -s:: ---hash:: +--hash[=<n>]:: - Only show the SHA1 hash, not the reference name. When also using + Only show the SHA1 hash, not the reference name. When combined with --dereference the dereferenced tag will still be shown after the SHA1. --verify:: @@ -59,11 +59,10 @@ OPTIONS Aside from returning an error code of 1, it will also print an error message if '--quiet' was not specified. ---abbrev:: ---abbrev=len:: +--abbrev[=<n>]:: Abbreviate the object name. When using `--hash`, you do - not have to say `--hash --abbrev`; `--hash=len` would do. + not have to say `--hash --abbrev`; `--hash=n` would do. -q:: --quiet:: @@ -71,22 +70,25 @@ OPTIONS Do not print any results to stdout. When combined with '--verify' this can be used to silently check if a reference exists. ---exclude-existing:: ---exclude-existing=pattern:: +--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: - (1) strip "^{}" at the end of line if any; + 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: + (1) strip "{caret}{}" 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; (4) ignore if refname is a ref that exists in the local repository; (5) otherwise output the line. -<pattern>:: +<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 ------ @@ -137,14 +139,14 @@ When using the '--verify' flag, the command requires an exact path: will only match the exact branch called "master". -If nothing matches, linkgit:git-show-ref[1] 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 allows you to do things like ----------------------------------------------------------------------------- - git-show-ref --quiet --verify -- "refs/heads/$headname" || + git show-ref --quiet --verify -- "refs/heads/$headname" || echo "$headname is not a valid branch" ----------------------------------------------------------------------------- @@ -165,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 baaf2bc8fe..ae4edcccfb 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -8,7 +8,8 @@ git-show - Show various types of objects SYNOPSIS -------- -'git-show' [options] <object>... +[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 linkgit:git-ls-tree[1] +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 linkgit:git-diff-tree[1] 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. @@ -33,10 +34,10 @@ This manual page describes only the most frequently used options. OPTIONS ------- -<object>:: - The name of the object to show. +<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 <junkio@cox.net>. 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 new file mode 100644 index 0000000000..ba3fe0d7f5 --- /dev/null +++ b/Documentation/git-stage.txt @@ -0,0 +1,23 @@ +git-stage(1) +============== + +NAME +---- +git-stage - Add file contents to the staging area + + +SYNOPSIS +-------- +[verse] +'git stage' args... + + +DESCRIPTION +----------- + +This is a synonym for linkgit:git-add[1]. Please refer to the +documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index baa4f55b48..0aa4e20eae 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -8,45 +8,73 @@ git-stash - Stash the changes in a dirty working directory away SYNOPSIS -------- [verse] -'git-stash' (list | show [<stash>] | apply [<stash>] | clear | drop [<stash>] | pop [<stash>]) -'git-stash' [save [<message>]] +'git stash' list [<options>] +'git stash' show [<stash>] +'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] + [-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. The modifications stashed away by this command can be listed with -`git-stash list`, inspected with `git-stash show`, and restored -(potentially on top of a different commit) with `git-stash apply`. -Calling git-stash without any arguments is equivalent to `git-stash -save`. A stash is by default listed as "WIP on 'branchname' ...", but +`git stash list`, inspected with `git stash show`, and restored +(potentially on top of a different commit) with `git stash apply`. +Calling `git stash` without any arguments is equivalent to `git stash save`. +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}` +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}` is also possible). OPTIONS ------- -save [<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. This is the default action when no - subcommand is given. The <message> part is optional and gives - the description along with the stashed state. + Save your local modifications to a new 'stash', and run `git reset + --hard` to revert them. The <message> part is optional and gives + the description along with the stashed state. For quickly making + a snapshot, you can omit _both_ "save" and <message>, but giving + only <message> does not trigger this action to prevent a misspelled + subcommand from making an unwanted stash. ++ +If the `--keep-index` option is used, all changes already added to the +index are left intact. ++ +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. 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. list [<options>]:: List the stashes that you currently have. Each 'stash' is listed - with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is + with its name (e.g. `stash@{0}` is the latest stash, `stash@{1}` is the one before, etc.), the name of the branch that was current when the stash was made, and a short description of the commit the stash was based on. @@ -56,45 +84,73 @@ 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 linkgit:git-log[1] -command to control what is shown and how. +The command takes options applicable to the 'git log' +command to control what is shown and how. See linkgit:git-log[1]. 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 - -p stash@\{1}` to view the second most recent stash in patch form). + 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). -apply [--index] [<stash>]:: +pop [--index] [-q|--quiet] [<stash>]:: - Restore the changes recorded in the stash on top of the current - working tree state. When no `<stash>` is given, applies the latest - one. The working directory must match the index. + Remove a single stashed state from the stash list and apply it + on top of the current working tree state, i.e., do the inverse + operation of `git stash save`. The working directory must + match the index. + -This operation can fail with conflicts; you need to resolve them -by hand in the working tree. +Applying the state can fail with conflicts; in this case, it is not +removed from the stash list. You need to resolve the conflicts by hand +and call `git stash drop` manually afterwards. + If the `--index` option is used, then tries to reinstate not only the working 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, 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. 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. + 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 +changed enough that `git stash apply` fails due to conflicts. Since +the stash is applied on top of the commit that was HEAD at the time +`git stash` was run, it restores the originally stashed state with +no conflicts. clear:: Remove all the stashed states. Note that those states will then - be subject to pruning, and may be difficult or impossible to recover. + be subject to pruning, and may be impossible to recover (see + 'Examples' below for a possible strategy). -drop [<stash>]:: +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>}`. -pop [<stash>]:: +create:: - Remove a single stashed state from the stash list and apply on top - of the current working tree state. When no `<stash>` is given, - `stash@\{0}` is assumed. See also `apply`. + Create a stash (which is a regular commit object) and return its + object name, without storing it anywhere in the ref namespace. DISCUSSION @@ -132,11 +188,11 @@ perform a pull, and then unstash, like this: + ---------------------------------------------------------------- $ git pull -... + ... file foobar not up to date, cannot merge. $ git stash $ git pull -$ git stash apply +$ git stash pop ---------------------------------------------------------------- Interrupted workflow:: @@ -147,7 +203,7 @@ make a commit to a temporary branch to store your changes away, and return to your original branch to make the emergency fix, like this: + ---------------------------------------------------------------- -... hack hack hack ... +# ... hack hack hack ... $ git checkout -b my_wip $ git commit -a -m "WIP" $ git checkout master @@ -155,19 +211,51 @@ $ edit emergency fix $ git commit -a -m "Fix in a hurry" $ git checkout my_wip $ git reset --soft HEAD^ -... continue hacking ... +# ... 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 ... +# ... hack hack hack ... $ git stash $ edit emergency fix $ git commit -a -m "Fix in a hurry" -$ git stash apply -... continue hacking ... +$ git stash pop +# ... continue hacking ... +---------------------------------------------------------------- + +Testing partial commits:: + +You can use `git stash save --keep-index` when you want to make two or +more commits out of the changes in the work tree, and you want to test +each change before committing: ++ ---------------------------------------------------------------- +# ... hack hack hack ... +$ git add --patch foo # add just first part to the index +$ git stash save --keep-index # save all other changes to the stash +$ edit/build/test first part +$ git commit -m 'First part' # commit fully tested change +$ git stash pop # prepare to work on all other changes +# ... repeat above five steps until one commit remains ... +$ edit/build/test remaining parts +$ git commit foo -m 'Remaining parts' +---------------------------------------------------------------- + +Recovering stashes that were cleared/dropped erroneously:: + +If you mistakenly drop or clear stashes, they cannot be recovered +through the normal safety mechanisms. However, you can try the +following incantation to get a list of stashes that are still in your +repository, but not reachable any more: ++ +---------------------------------------------------------------- +git fsck --unreachable | +grep commit | cut -d\ -f3 | +xargs git log --merges --no-walk --grep=WIP +---------------------------------------------------------------- + SEE ALSO -------- @@ -176,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 fef62b16df..67e5f53a9e 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -8,7 +8,8 @@ git-status - Show the working tree status SYNOPSIS -------- -'git-status' <options>... +[verse] +'git status' [<options>...] [--] [<pathspec>...] DESCRIPTION ----------- @@ -17,28 +18,173 @@ 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`. -The command takes the same set of options as `git-commit`; it -shows what would be committed if the same options are given to -`git-commit`. - -If there is no path that is different between the index file and -the current HEAD commit (i.e., there is nothing to commit by running -`git-commit`), the command exits with non-zero status. +OPTIONS +------- + +-s:: +--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 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. ++ +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. ++ +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 + the `--porcelain` output format if no other format is given. + +--column[=<options>]:: +--no-column:: + Display untracked files in columns. See configuration variable + column.status for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' + respectively. 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. 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. +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 the " `-> PATH2`" part is +shown only when `PATH1` corresponds to a different path in the +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 [ M] deleted from index + R [ MD] renamed in index + C [ MD] copied in index + [MARC] index and work tree matches + [ MARC] M work tree changed since index + [ MARC] D deleted in work tree + ------------------------------------------------- + D D unmerged, both deleted + A U unmerged, added by us + U D unmerged, deleted by them + U A unmerged, added by them + D U unmerged, deleted by us + A A unmerged, both added + 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. CONFIGURATION ------------- @@ -53,23 +199,14 @@ paths shown are relative to the repository root, not to the current directory. If `status.submodulesummary` 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]). +to -1 or an unlimited number), the submodule summary will be enabled for +the long format and a summary of commits for modified submodules will be +shown (see --summary-limit option of linkgit:git-submodule[1]). SEE ALSO -------- linkgit:gitignore[5] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net>. - -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 8421a39f26..a80d94650d 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -3,33 +3,83 @@ git-stripspace(1) NAME ---- -git-stripspace - Filter out empty lines +git-stripspace - Remove unnecessary whitespace SYNOPSIS -------- -'git-stripspace' [-s | --strip-comments] < <stream> +[verse] +'git stripspace' [-s | --strip-comments] < input DESCRIPTION ----------- -Remove multiple empty lines, and empty lines at beginning and end. + +Clean the input in the manner used by 'git' for text such as commit +messages, notes, tags and branch descriptions. + +With no arguments, this will: + +- remove trailing whitespace from all lines +- collapse multiple consecutive empty lines into one empty line +- remove empty lines from the beginning and end of the input +- add a missing '\n' to the last line if necessary. + +In the case where the input consists entirely of whitespace characters, no +output will be produced. + +*NOTE*: This is intended for cleaning metadata, prefer the `--whitespace=fix` +mode of linkgit:git-apply[1] for correcting whitespace of patches or files in +the repository. OPTIONS ------- -s:: --strip-comments:: - In addition to empty lines, also strip lines starting with '#'. + Skip and remove all lines starting with '#'. -<stream>:: - Byte stream to act on. +EXAMPLES +-------- -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> +Given the following noisy input with '$' indicating the end of a line: -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +-------- +|A brief introduction $ +| $ +|$ +|A new paragraph$ +|# with a commented-out line $ +|explaining lots of stuff.$ +|$ +|# An old paragraph, also commented-out. $ +| $ +|The end.$ +| $ +--------- + +Use 'git stripspace' with no arguments to obtain: + +-------- +|A brief introduction$ +|$ +|A new paragraph$ +|# with a commented-out line$ +|explaining lots of stuff.$ +|$ +|# An old paragraph, also commented-out.$ +|$ +|The end.$ +--------- + +Use 'git stripspace --strip-comments' to obtain: + +-------- +|A brief introduction$ +|$ +|A new paragraph$ +|explaining lots of stuff.$ +|$ +|The end.$ +--------- GIT --- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 441ae1483b..9e488c0aad 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,55 +9,191 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git-submodule' [--quiet] add [-b branch] [--] <repository> [<path>] -'git-submodule' [--quiet] status [--cached] [--] [<path>...] -'git-submodule' [--quiet] init [--] [<path>...] -'git-submodule' [--quiet] update [--init] [--] [<path>...] -'git-submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] +'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] [(-n|--summary-limit) <n>] + [commit] [--] [<path>...] +'git submodule' [--quiet] foreach [--recursive] <command> +'git submodule' [--quiet] sync [--] [<path>...] + + +DESCRIPTION +----------- +Submodules allow foreign repositories to be embedded within +a dedicated subdirectory of the source tree, always pointed +at a particular commit. + +They are not to be confused with remotes, which are meant mainly +for branches of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. + +Submodules are composed from a so-called `gitlink` tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the +root of the source tree assigns a logical name to the submodule and +describes the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see 'submodule init'). + +This command will manage the tree entries and contents of the +gitmodules file for you, as well as inspect the status of your +submodules and update them. +When adding a new submodule to the tree, the 'add' subcommand +is to be used. However, when pulling a tree containing submodules, +these will not be checked out by default; +the 'init' and 'update' subcommands will maintain submodules +checked out and at appropriate revision in your working tree. +You can briefly inspect the up-to-date status of your submodules +using the 'status' subcommand and get a detailed overview of the +difference between the index and checkouts using the 'summary' +subcommand. COMMANDS -------- add:: Add the given repository as a submodule at the given path - to the changeset to be committed next. If path is a valid - repository within the project, it is added as is. Otherwise, - repository is cloned at the specified path. path is added to the - changeset and registered in .gitmodules. If no path is - specified, the path is deduced from the repository specification. - If the repository url begins with ./ or ../, it is stored as - given but resolved as a relative path from the main project's - url when cloning. + to the changeset to be committed next to the current + project: the current project is termed the "superproject". ++ +This requires at least one argument: <repository>. The optional +argument <path> is the relative location for the cloned submodule +to exist in the superproject. If <path> is not given, the +"humanish" part of the source repository is used ("repo" for +"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). ++ +<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 (Please note that to specify a repository 'foo.git' +which is located right next to a superproject 'bar.git', you'll +have to use '../foo.git' instead of './foo.git' - as one might expect +when following the rules for relative URLs - because the evaluation +of relative URLs in Git is identical to that of relative directories). +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 +submodule is created by cloning from the named URL. If <path> does +exist and is already a valid git repository, then this is added +to the changeset without cloning. This second form is provided +to ease creating a new submodule from scratch, and presumes +the user will later push the submodule to the given URL. ++ +In either case, the given URL is recorded into .gitmodules for +use by subsequent users cloning the superproject. If the URL is +given relative to the superproject's repository, the presumption +is the superproject and submodule repositories will be kept +together in the same relative location, and only the +superproject's URL needs to be provided: git-submodule will correctly +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 linkgit:git-describe[1] 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 +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 in .git/config each submodule - name and url found in .gitmodules. The key used in .git/config is - `submodule.$name.url`. This command does not alter existing information - in .git/config. + 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 + 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. + 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`. `none` can be overriden by specifying + `--checkout`. + 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 +registered submodules, and update any nested submodules within. 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. + 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 + 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, $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, $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 + of each submodule before evaluating the command. + 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 '|| :' + to the end of the command. ++ +As an example, +git submodule foreach \'echo $path {backtick}git +rev-parse HEAD{backtick}'+ will show the path and currently checked out +commit for each submodule. + +sync:: + Synchronizes submodules' remote URL configuration setting + to the value specified in .gitmodules. It will only affect those + submodules which already have a 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. OPTIONS ------- @@ -69,11 +205,23 @@ 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 with this option, the commit stored in the index is used instead. +--files:: + This option is only valid for the summary command. This command + compares the commit in the index with that in the submodule HEAD + when this option is used. + -n:: --summary-limit:: This option is only valid for the summary command. @@ -82,9 +230,53 @@ OPTIONS (the default). This limit only applies to modified submodules. The size is always limited to 1 for added/deleted/typechanged submodules. -<path>:: - Path to submodule(s). When specified this will restrict the command +-N:: +--no-fetch:: + This option is only valid for the update command. + Don't fetch new objects from the remote site. + +--merge:: + This option is only valid for the update command. + Merge the commit recorded in the superproject into the current branch + of the submodule. If this option is given, the submodule's HEAD will + not be detached. If a merge failure prevents this process, you will + have to resolve the resulting conflicts within the submodule with the + usual conflict resolution tools. + If the key `submodule.$name.update` is set to `merge`, this option is + implicit. + +--rebase:: + 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 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. + +--recursive:: + This option is only valid for foreach, update and status commands. + Traverse submodules recursively. The operation is performed not + only in the submodules of the current repo, but also + in any nested submodules inside those submodules (and so on). + +<path>...:: + Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. + (This argument is required with add). FILES ----- @@ -94,11 +286,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 f4cbd2f212..cfe8d2b5df 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -3,35 +3,34 @@ git-svn(1) NAME ---- -git-svn - Bidirectional operation between a single Subversion branch and git +git-svn - Bidirectional operation between a Subversion repository and git SYNOPSIS -------- -'git-svn' <command> [options] [arguments] +[verse] +'git svn' <command> [options] [arguments] DESCRIPTION ----------- -git-svn is a simple conduit for changesets between Subversion and git. -It is not to be confused with linkgit:git-svnimport[1], which is -read-only. +'git svn' is a simple conduit for changesets between Subversion and git. +It provides a bidirectional flow of changes between a Subversion and a git +repository. -git-svn was originally designed for an individual developer who wants a -bidirectional flow of changesets between a single branch in Subversion -and an arbitrary number of branches in git. Since its inception, -git-svn has gained the ability to track multiple branches in a manner -similar to git-svnimport. +'git svn' can track a standard Subversion repository, +following the common "trunk/branches/tags" layout, with the --stdlayout option. +It can also follow branches and tags in any layout with the -T/-t/-b options +(see options to 'init' below, and also the 'clone' command). -git-svn is especially useful when it comes to tracking repositories -not organized in the way Subversion developers recommend (trunk, -branches, tags directories). +Once tracking a Subversion repository (with any of the above methods), the git +repository can be updated from Subversion by the 'fetch' command and +Subversion updated from git by the 'dcommit' command. COMMANDS -------- --- 'init':: Initializes an empty git repository with additional - metadata directories for git-svn. The Subversion URL + metadata directories for 'git svn'. The Subversion URL may be specified as a command-line argument, or as full URL arguments to -T/-t/-b. Optionally, the target directory to operate on can be specified as a second @@ -48,30 +47,27 @@ COMMANDS --stdlayout;; These are optional command-line options for init. Each of these flags can point to a relative repository path - (--tags=project/tags') or a full url - (--tags=https://foo.org/project/tags). The option --stdlayout is + (--tags=project/tags) or a full url + (--tags=https://foo.org/project/tags). + You can specify more than one --tags and/or --branches options, in case + your Subversion repository places tags or branches under multiple paths. + The option --stdlayout is a shorthand way of setting trunk,tags,branches as the relative paths, which is the Subversion default. If any of the other options are given 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. ---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. ---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 @@ -85,6 +81,21 @@ COMMANDS specified, the prefix must include a trailing slash. Setting a prefix is useful if you wish to track multiple projects that share a common repository. +--ignore-paths=<regex>;; + When passed to 'init' or 'clone' this regular expression will + be preserved as a config key. See 'fetch' for a description + of '--ignore-paths'. +--no-minimize-url;; + When tracking multiple directories (using --stdlayout, + --branches, or --tags options), git svn will attempt to connect + to the root (or highest allowed level) of the Subversion + repository. This default allows better tracking of history if + entire projects are moved within a repository, but may cause + issues on repositories where read access restrictions are in + place. Passing '--no-minimize-url' will allow git svn to + accept URLs as-is without attempting to connect to a higher + level directory. This option is off by default when only + one URL/branch is tracked (it would do little good). 'fetch':: Fetch unfetched revisions from the Subversion remote we are @@ -92,53 +103,185 @@ COMMANDS .git/config file may be specified as an optional command-line argument. +--localtime;; + Store Git commit times in the local timezone instead of UTC. This + makes 'git log' (even without --date=local) show the same times + that `svn log` would in the local timezone. ++ +This doesn't interfere with interoperating with the Subversion +repository you cloned from, but if you wish for your local Git +repository to be able to interoperate with someone else's local Git +repository, either don't use this option or you should both use it in +the same local timezone. + +--parent;; + Fetch only from the SVN parent of the current HEAD. + +--ignore-paths=<regex>;; + This allows one to specify a Perl regular expression that will + cause skipping of all matching paths from checkout from SVN. + The '--ignore-paths' option should match for every 'fetch' + (including automatic fetches due to 'clone', 'dcommit', + 'rebase', etc) on a given repository. ++ +[verse] +config key: svn-remote.<name>.ignore-paths ++ +If the ignore-paths config key is set and the command line option is +also given, both regular expressions will be used. ++ +Examples: ++ +-- +Skip "doc*" directory for every fetch;; ++ +------------------------------------------------------------------------ +--ignore-paths="^doc" +------------------------------------------------------------------------ + +Skip "branches" and "tags" of first level directories;; ++ +------------------------------------------------------------------------ +--ignore-paths="^[^/]+/(?:branches|tags)" +------------------------------------------------------------------------ +-- + 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; or if a second argument is passed; it will create a directory and work within that. It accepts all arguments that the 'init' and 'fetch' commands accept; with the exception of - '--fetch-all'. After a repository is cloned, the 'fetch' - command will be able to update revisions without affecting - the working tree; and the 'rebase' command will be able - to update the working tree with the latest changes. + '--fetch-all' and '--parent'. After a repository is cloned, + the 'fetch' command will be able to update revisions without + 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. - -This works similarly to 'svn update' or 'git-pull' except that -it preserves linear history with 'git-rebase' instead of -'git-merge' for ease of dcommiting with git-svn. - -This accepts all options that 'git-svn fetch' and 'git-rebase' -accepts. However '--fetch-all' only fetches from the current ++ +This works similarly to `svn update` or 'git pull' except that +it preserves linear history with 'git rebase' instead of +'git merge' for ease of dcommitting with 'git svn'. ++ +This accepts all options that 'git svn fetch' and 'git rebase' +accept. However, '--fetch-all' only fetches from the current [svn-remote], and not all [svn-remote] definitions. - -Like 'git-rebase'; this requires that the working tree be clean ++ +Like 'git rebase'; this requires that the working tree be clean and have no uncommitted changes. -l;; --local;; - Do not fetch remotely; only run 'git-rebase' against the + Do not fetch remotely; only run 'git rebase' against the last fetched commit from the upstream SVN. 'dcommit':: - Commit each diff from a specified head directly to the SVN + Commit each diff from the current branch directly to the SVN repository, and then rebase or reset (depending on whether or not there is a diff between SVN and head). This will create a revision in SVN for each commit in git. - It is recommended that you run git-svn fetch and rebase (not - pull or merge) your commits against the latest changes in the - SVN repository. - An optional command-line argument may be specified as an - alternative to HEAD. - This is advantageous over 'set-tree' (below) because it produces - cleaner, more linear history. ++ +When an optional git branch name (or a git commit object name) +is specified as an argument, the subcommand works on the specified +branch, not on the current branch. ++ +Use of 'dcommit' is preferred to 'set-tree' (below). + --no-rebase;; After committing, do not rebase or reset. --- +--commit-url <URL>;; + Commit to this SVN URL (the full path). This is intended to + allow existing 'git svn' repositories created with one transport + method (e.g. `svn://` or `http://` for anonymous read) to be + reused if a user is later given access to an alternate transport + method (e.g. `svn+ssh://` or `https://`) for commit. ++ +[verse] +config key: svn-remote.<name>.commiturl +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. + +-m;; +--message;; + Allows to specify the commit message. + +-t;; +--tag;; + Create a tag by using the tags_subdir instead of the branches_subdir + specified during git svn init. + +-d;; +--destination;; + If more than one --branches (or --tags) option was given to the 'init' + or 'clone' command, you must provide the location of the branch (or + tag) you wish to create in the SVN repository. The value of this + option must match one of the paths specified by a --branches (or + --tags) option. You can see these paths with the commands ++ + git config --get-all svn-remote.<name>.branches + git config --get-all svn-remote.<name>.tags ++ +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'. 'log':: This should make it easy to look up svn log messages when svn @@ -147,10 +290,12 @@ and have no uncommitted changes. The following features from `svn log' are supported: + -- +-r <n>[:<n>];; --revision=<n>[:<n>];; is supported, non-numeric args are not: HEAD, NEXT, BASE, PREV, etc ... --v/--verbose;; +-v;; +--verbose;; it's not completely compatible with the --verbose output in svn log, but reasonably close. --limit=<n>;; @@ -173,23 +318,22 @@ NOTE: SVN itself only stores times in UTC and nothing else. The regular svn client converts the UTC time to the local time (or based on the TZ= environment). This command has the same behaviour. + -Any other arguments are passed directly to `git log' +Any other arguments are passed directly to 'git log' 'blame':: 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. + arguments are passed directly to 'git blame'. + --git-format;; - Produce output in the same format as `git blame', but with + Produce output in the same format as 'git blame', but with SVN revision numbers instead of git commit hashes. In this mode, changes that haven't been committed to SVN (including local working-copy edits) are shown as revision 0. --- 'find-rev':: When given an SVN revision number of the form 'rN', returns the corresponding git commit hash (this can optionally be followed by a @@ -203,28 +347,36 @@ Any other arguments are passed directly to `git log' absolutely no attempts to do patching when committing to SVN, it simply overwrites files with those specified in the tree or commit. All merging is assumed to have taken place - independently of git-svn functions. + independently of 'git svn' functions. 'create-ignore':: Recursively finds the svn:ignore property on directories and creates matching .gitignore files. The resulting files are staged to be committed, but are not committed. Use -r/--revision to refer to a - specfic revision. + specific revision. 'show-ignore':: Recursively finds and lists the svn:ignore property on directories. The output is suitable for appending to the $GIT_DIR/info/exclude file. +'mkdirs':: + Attempts to recreate empty directories that core git cannot track + based on information in $GIT_DIR/svn/<refname>/unhandled.log files. + 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 - command-line. This command is intended for interoperability with - git-svnimport and does not rely on being inside an git-svn - init-ed repository. This command takes three arguments, (a) the + command-line. This command does not rely on being inside an `git svn + init`-ed repository. This command takes three arguments, (a) the original tree to diff against, (b) the new tree result, (c) the URL of the target Subversion repository. The final argument - (URL) may be omitted if you are working from a git-svn-aware - repository (that has been init-ed with git-svn). + (URL) may be omitted if you are working from a 'git svn'-aware + repository (that has been `init`-ed with 'git svn'). The -r<revision> option is required for this. 'info':: @@ -246,108 +398,170 @@ Any other arguments are passed directly to `git log' Shows the Subversion externals. Use -r/--revision to specify a specific revision. --- +'gc':: + Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn + and remove $GIT_DIR/svn/<refname>index files in .git/svn. + +'reset':: + Undoes the effects of 'fetch' back to the specified revision. + This allows you to re-'fetch' an SVN revision. Normally the + contents of an SVN revision should never change and 'reset' + should not be necessary. However, if SVN permissions change, + or if you alter your --ignore-paths option, a 'fetch' may fail + with "not found in commit" (file not previously visible) or + "checksum mismatch" (missed a modification). If the problem + file cannot be ignored forever (with --ignore-paths) the only + way to repair the repo is to use 'reset'. ++ +Only the rev_map and refs/remotes/git-svn are changed. Follow 'reset' +with a 'fetch' and then 'git reset' or 'git rebase' to move local +branches onto the new tree. + +-r <n>;; +--revision=<n>;; + Specify the most recent revision to keep. All later revisions + are discarded. +-p;; +--parent;; + Discard the specified revision as well, keeping the nearest + parent instead. +Example:;; +Assume you have local changes in "master", but you need to refetch "r2". ++ +------------ + r1---r2---r3 remotes/git-svn + \ + A---B master +------------ ++ +Fix the ignore-paths or SVN permissions problem that caused "r2" to +be incomplete in the first place. Then: ++ +[verse] +git svn reset -r2 -p +git svn fetch ++ +------------ + r1---r2'--r3' remotes/git-svn + \ + r2---r3---A---B master +------------ ++ +Then fixup "master" with 'git rebase'. +Do NOT use 'git merge' or your history will not be compatible with a +future 'dcommit'! ++ +[verse] +git rebase --onto remotes/git-svn A^ master ++ +------------ + r1---r2'--r3' remotes/git-svn + \ + A'--B' 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 linkgit:git-init[1]. - --r <ARG>:: ---revision <ARG>:: - -Used with the 'fetch' command. + These are passed directly to 'git init'. +-r <arg>:: +--revision <arg>:: + Used with the 'fetch' command. ++ This allows revision ranges for partial/cauterized history to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), $NUMBER:HEAD, and BASE:$NUMBER are all supported. - ++ This can allow you to make partial mirrors when running fetch; but is generally not recommended because history will be skipped and lost. -:: --stdin:: - -Only used with the 'set-tree' command. - + Only used with the 'set-tree' command. ++ Read a list of commits from stdin and commit them in reverse order. Only the leading sha1 is read from each line, so -git-rev-list --pretty=oneline output can be used. +'git rev-list --pretty=oneline' output can be used. --rmdir:: - -Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. - + Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. ++ Remove directories from the SVN tree if there are no files left behind. SVN can version empty directories, and they are not removed by default if there are no files left in them. git cannot version empty directories. Enabling this flag will make the commit to SVN act like git. - ++ +[verse] config key: svn.rmdir -e:: --edit:: - -Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. - + Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. ++ Edit the commit message before committing to SVN. This is off by default for objects that are commits, and forced on when committing tree objects. - ++ +[verse] config key: svn.edit -l<num>:: --find-copies-harder:: - -Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. - -They are both passed directly to git-diff-tree see + Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. ++ +They are both passed directly to 'git diff-tree'; see linkgit:git-diff-tree[1] for more information. - ++ [verse] config key: svn.l config key: svn.findcopiesharder -A<filename>:: --authors-file=<filename>:: - -Syntax is compatible with the files used by git-svnimport and -git-cvsimport: - + Syntax is compatible with the file used by 'git cvsimport': ++ ------------------------------------------------------------------------ loginname = Joe User <user@example.com> ------------------------------------------------------------------------ - -If this option is specified and git-svn encounters an SVN -committer name that does not exist in the authors-file, git-svn ++ +If this option is specified and 'git svn' encounters an SVN +committer name that does not exist in the authors-file, 'git svn' will abort operation. The user will then have to add the -appropriate entry. Re-running the previous git-svn command +appropriate entry. Re-running the previous 'git svn' command after the authors-file is modified should continue operation. - ++ +[verse] config key: svn.authorsfile +--authors-prog=<filename>:: + If this option is specified, for each SVN committer name that + does not exist in the authors file, the given file is executed + with the committer name as the first argument. The program is + expected to return a single line of the form "Name <email>", + which will be treated as if included in the authors file. + -q:: --quiet:: - Make git-svn less verbose. + Make 'git svn' less verbose. Specify a second time to make it + even less verbose. --repack[=<n>]:: --repack-flags=<flags>:: - -These should help keep disk usage sane for large fetches -with many revisions. - + These should help keep disk usage sane for large fetches with + many revisions. ++ --repack takes an optional argument for the number of revisions to fetch before repacking. This defaults to repacking every 1000 commits fetched if no argument is specified. - ---repack-flags are passed directly to linkgit:git-repack[1]. - ++ +--repack-flags are passed directly to 'git repack'. ++ [verse] config key: svn.repack config key: svn.repackflags @@ -356,37 +570,49 @@ config key: svn.repackflags --merge:: -s<strategy>:: --strategy=<strategy>:: - -These are only used with the 'dcommit' and 'rebase' commands. - -Passed directly to git-rebase when using 'dcommit' if a -'git-reset' cannot be used (see dcommit). +-p:: +--preserve-merges:: + These are only used with the 'dcommit' and 'rebase' commands. ++ +Passed directly to 'git rebase' when using 'dcommit' if a +'git reset' cannot be used (see 'dcommit'). -n:: --dry-run:: - -This can be used with the 'dcommit' and 'rebase' commands. - + This can be used with the 'dcommit', 'rebase', 'branch' and + 'tag' commands. ++ For 'dcommit', print out the series of git arguments that would show which diffs would be committed to SVN. - ++ For 'rebase', display the local branch associated with the upstream svn repository associated with the current branch and the URL of svn 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 ---------------- --- -i<GIT_SVN_ID>:: --id <GIT_SVN_ID>:: - -This sets GIT_SVN_ID (instead of using the environment). This -allows the user to override the default refname to fetch from -when tracking a single URL. The 'log' and 'dcommit' commands -no longer require this switch as an argument. + This sets GIT_SVN_ID (instead of using the environment). This + allows the user to override the default refname to fetch from + when tracking a single URL. The 'log' and 'dcommit' commands + no longer require this switch as an argument. -R<remote name>:: --svn-remote <remote name>:: @@ -400,33 +626,39 @@ no longer require this switch as an argument. started tracking a branch and never tracked the trunk it was descended from. This feature is enabled by default, use --no-follow-parent to disable it. - ++ +[verse] config key: svn.followparent --- CONFIG FILE-ONLY OPTIONS ------------------------ --- 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. - -The 'git-svn log' command will not work on repositories using + This gets rid of the 'git-svn-id:' lines at the end of every commit. ++ +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:: - -This allows git-svn to re-map repository URLs and UUIDs from -mirrors created using SVN::Mirror (or svk) for metadata. - + This allows 'git svn' to re-map repository URLs and UUIDs from + mirrors created using SVN::Mirror (or svk) for metadata. ++ If an SVN revision has a property, "svm:headrev", it is likely that the revision was created by SVN::Mirror (also used by SVK). The property contains a repository UUID and a revision. We want @@ -443,20 +675,59 @@ svn-remote.<name>.useSvnsyncprops:: svn-remote.<name>.rewriteRoot:: This allows users to create repositories from alternate - URLs. For example, an administrator could run git-svn on the + URLs. For example, an administrator could run 'git svn' on the server locally (accessing via file://) but wish to distribute the repository with a public http:// or svn:// URL in the metadata so users of it will see the public URL. -Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps -options all affect the metadata generated and used by git-svn; they +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 + option to "false" if you track a SVN repository with many + empty blobs that are not symlinks. This option may be changed + while 'git svn' is running and take effect on the next + revision fetched. If unset, 'git svn' assumes this option to + be "true". + +svn.pathnameencoding:: + This instructs git svn to recode pathnames to a given encoding. + It can be used by windows users and by those who work in non-utf8 + locales to avoid corrupted file names with non-ASCII characters. + Valid encodings are the ones supported by Perl's Encode module. + +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 -------------- @@ -465,21 +736,21 @@ Tracking and contributing to the trunk of a Subversion-managed project: ------------------------------------------------------------------------ # Clone a repo (like git clone): - git-svn clone http://svn.foo.org/project/trunk + git svn clone http://svn.example.com/project/trunk # Enter the newly cloned directory: cd trunk -# You should be on master branch, double-check with git-branch +# You should be on master branch, double-check with 'git branch' git branch # Do some work and commit locally to git: git commit ... # Something is committed to SVN, rebase your local changes against the # latest changes in SVN: - git-svn rebase + git svn rebase # Now commit your changes (that were committed previously using git) to SVN, # as well as automatically updating your working HEAD: - git-svn dcommit + git svn dcommit # Append svn:ignore settings to the default git exclude file: - git-svn show-ignore >> .git/info/exclude + git svn show-ignore >> .git/info/exclude ------------------------------------------------------------------------ Tracking and contributing to an entire Subversion-managed project @@ -487,9 +758,11 @@ Tracking and contributing to an entire Subversion-managed project ------------------------------------------------------------------------ # Clone a repo (like git clone): - git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags + git svn clone http://svn.example.com/project -T trunk -b branches -t tags # View all branches and tags you have cloned: git branch -r +# Create a new branch in SVN + git svn branch waldo # Reset your master to trunk (or any other branch, replacing 'trunk' # with the appropriate name): git reset --hard remotes/trunk @@ -497,48 +770,53 @@ Tracking and contributing to an entire Subversion-managed project # of dcommit/rebase/show-ignore should be the same as above. ------------------------------------------------------------------------ -The initial 'git-svn clone' can be quite time-consuming +The initial 'git svn clone' can be quite time-consuming (especially for large Subversion repositories). If multiple people (or one person with multiple machines) want to use -git-svn to interact with the same Subversion repository, you can -do the initial 'git-svn clone' to a repository on a server and +'git svn' to interact with the same Subversion repository, you can +do the initial 'git svn clone' to a repository on a server and have each person clone that repository with 'git clone': ------------------------------------------------------------------------ # Do the initial import on a server - ssh server "cd /pub && git-svn clone http://svn.foo.org/project + ssh server "cd /pub && git svn clone http://svn.example.com/project # Clone locally - make sure the refs/remotes/ space matches the server mkdir project cd project - git-init + 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 -# Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) - git-svn init http://svn.foo.org/project +# 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) + git svn init http://svn.example.com/project # Pull the latest changes from Subversion - git-svn rebase + git svn rebase ------------------------------------------------------------------------ REBASE VS. PULL/MERGE --------------------- - -Originally, git-svn recommended that the remotes/git-svn branch be -pulled or merged from. This is because the author favored -'git-svn set-tree B' to commit a single head rather than the -'git-svn set-tree A..B' notation to commit multiple commits. - -If you use 'git-svn set-tree A..B' to commit several diffs and you do -not have the latest remotes/git-svn merged into my-branch, you should -use 'git-svn rebase' to update your work branch instead of 'git pull' or -'git merge'. 'pull/merge' can cause non-linear history to be flattened -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 +Prefer to use 'git svn rebase' or 'git rebase', rather than +'git pull' or 'git merge' to synchronize unintegrated commits with a 'git svn' +branch. Doing so will keep the history of unintegrated commits linear with +respect to the upstream SVN repository and allow the use of the preferred +'git svn dcommit' subcommand to push unintegrated commits back into SVN. + +Originally, 'git svn' recommended that developers pulled or merged from +the 'git svn' branch. This was because the author favored +`git svn set-tree B` to commit a single head rather than the +`git svn set-tree A..B` notation to commit multiple commits. Use of +'git pull' or 'git merge' with `git svn set-tree A..B` will cause non-linear +history to be flattened when committing into SVN and this can lead to merge +commits unexpectedly reversing previous commits in SVN. + +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 @@ -548,35 +826,54 @@ 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 -directly from the SVN server, and avoid all git-clone/pull/merge/push +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 dcommiting to the SVN repository. +'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 +Running 'git merge' or 'git pull' is NOT recommended on a branch you +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 +that is a mirror of an SVN branch, 'dcommit' may commit to the wrong branch. -'git-clone' does not clone branches under the refs/remotes/ hierarchy or -any git-svn metadata, or config. So repositories created and managed with -using git-svn should use rsync(1) for cloning, if cloning is to be done +If you do merge, note the following rule: 'git svn dcommit' will +attempt to commit on top of the SVN commit named in +------------------------------------------------------------------------ +git log --grep=^git-svn-id: --first-parent -1 +------------------------------------------------------------------------ +You 'must' therefore ensure that the most recent commit of the branch +you want to dcommit to is the 'first' parent of the merge. Chaos will +ensue otherwise, especially if the first parent is an older commit on +the same SVN branch. + +'git clone' does not clone branches under the refs/remotes/ hierarchy or +any 'git svn' metadata, or config. So repositories created and managed with +using 'git svn' should use 'rsync' for cloning, if cloning is to be done at all. -Since 'dcommit' uses rebase internally, any git branches you git-push to -before dcommit on will require forcing an overwrite of the existing ref +Since 'dcommit' uses rebase internally, any git branches you 'git push' to +before 'dcommit' on will require forcing an overwrite of the existing ref on the remote repository. This is generally considered bad practice, -see the git-push(1) documentation for details. +see the linkgit:git-push[1] documentation for details. -Do not use the --amend option of git-commit(1) on a change you've +Do not use the --amend option of linkgit:git-commit[1] on a change you've already dcommitted. It is considered bad practice to --amend commits you've already pushed to a remote repository for other users, and dcommit with SVN is analogous to that. +When using multiple --branches or --tags, 'git svn' does not automatically +handle name collisions (for example, if two branches from different paths have +the same name, or if a branch and a tag have the same name). In these cases, +use 'init' to set up your git repository then, before your first 'fetch', edit +the .git/config file so that the branches and tags are associated with +different name spaces. For example: + + branches = stable/*:refs/remotes/svn/stable/* + branches = debug/*:refs/remotes/svn/debug/* + BUGS ---- @@ -587,13 +884,13 @@ 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 ------------- -git-svn stores [svn-remote] configuration information in the +'git svn' stores [svn-remote] configuration information in the repository .git/config file. It is similar the core git [remote] sections except 'fetch' keys do not accept glob arguments; but they are instead handled by the 'branches' @@ -604,27 +901,38 @@ listed below are allowed: ------------------------------------------------------------------------ [svn-remote "project-a"] url = http://server.org/svn + fetch = trunk/project-a:refs/remotes/project-a/trunk branches = branches/*/project-a:refs/remotes/project-a/branches/* tags = tags/*/project-a:refs/remotes/project-a/tags/* - trunk = trunk/project-a:refs/remotes/project-a/trunk ------------------------------------------------------------------------ -Keep in mind that the '*' (asterisk) wildcard of the local ref +Keep in mind that the '\*' (asterisk) wildcard of the local ref (right of the ':') *must* be the farthest right path component; -however the remote wildcard may be anywhere as long as it's own +however the remote wildcard may be anywhere as long as it's an 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 -linkgit:git-config[1] +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 3d3a059c5e..981d3a8fc1 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -7,16 +7,18 @@ git-symbolic-ref - Read and modify symbolic refs SYNOPSIS -------- -'git-symbolic-ref' [-q] [-m <reason>] <name> [<ref>] +[verse] +'git symbolic-ref' [-m <reason>] <name> <ref> +'git symbolic-ref' [-q] [--short] <name> DESCRIPTION ----------- Given one argument, reads which branch head the given symbolic ref refers to and outputs its path, relative to the `.git/` directory. Typically you would give `HEAD` as the <name> -argument to see on which branch your working tree is on. +argument to see which branch your working tree is on. -Give two arguments, create or update a symbolic ref <name> to +Given two arguments, creates or updates a symbolic ref <name> to point at the given branch <ref>. A symbolic ref is a regular file that stores a string that @@ -32,6 +34,10 @@ OPTIONS symbolic ref but a detached HEAD; instead exit with non-zero status silently. +--short:: + When showing the value of <name> as a symbolic ref, try to shorten the + value, e.g. from `refs/heads/master` to `master`. + -m:: Update the reflog for <name> with <reason>. This is valid only when creating or updating a symbolic ref. @@ -42,21 +48,14 @@ In the past, `.git/HEAD` was a symbolic link pointing at `refs/heads/master`. When we wanted to switch to another branch, we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we wanted to find out which branch we are on, we did `readlink .git/HEAD`. -This was fine, and internally that is what still happens by -default, but on platforms that do not have working symlinks, -or that do not have the `readlink(1)` command, this was a bit -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 +But symbolic links are not entirely portable, so they are now +deprecated and symbolic refs (as described above) are used by +default. + +'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 <junkio@cox.net> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 8f40f4bf0d..e36a7c3d1e 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -9,52 +9,65 @@ git-tag - Create, list, delete or verify a tag object signed with GPG SYNOPSIS -------- [verse] -'git-tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <name> [<head>] -'git-tag' -d <name>... -'git-tag' [-n[<num>]] -l [<pattern>] -'git-tag' -v <name>... +'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>] [--points-at <object>] + [--column[=<options>] | --no-column] [<pattern>...] + [<pattern>...] +'git tag' -v <tagname>... DESCRIPTION ----------- -Adds a 'tag' reference in `.git/refs/tags/` -Unless `-f` is given, the tag must not yet exist in +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 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 committer identity for the current user is used to find the -GnuPG key for signing. +GnuPG key for signing. The configuration variable `gpg.program` +is used to specify custom GnuPG binary. + OPTIONS ------- -a:: +--annotate:: Make an unsigned, annotated tag object -s:: - Make a GPG-signed tag, using the default e-mail address's key +--sign:: + Make a GPG-signed tag, using the default e-mail address's key. -u <key-id>:: - Make a GPG-signed tag, using the given key +--local-user=<key-id>:: + Make a GPG-signed tag, using the given key. -f:: +--force:: 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>:: @@ -62,27 +75,61 @@ OPTIONS are printed when using -l. The default is not to print any annotation lines. If no number is given to `-n`, only the first line is printed. + 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. + +--column[=<options>]:: +--no-column:: + Display tag listing in columns. See configuration variable + column.tag for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' respectively. ++ +This option is only applicable when listing tags without annotation lines. + +--contains <commit>:: + Only list tags which contain the specified commit. + +--points-at <object>:: + Only list tags of the given object. -m <msg>:: +--message=<msg>:: Use the given tag message (instead of prompting). - If multiple `-m` options are given, there values are + If multiple `-m` options are given, their values are concatenated as separate paragraphs. Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. -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>` is given. +--cleanup=<mode>:: + This option sets how the tag message is cleaned up. + The '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'. The + 'strip' mode is default. The 'verbatim' mode does not change message at + all, 'whitespace' removes just leading/trailing whitespace lines and + 'strip' removes both whitespace and commentary. + +<tagname>:: + The name of the tag to create, delete, or describe. + The new tag name must pass all checks defined by + linkgit:git-check-ref-format[1]. Some of these checks + may restrict the characters allowed in a tag name. + 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: @@ -118,12 +165,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 +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 one. If somebody got a release tag from you, you cannot just change @@ -151,20 +198,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. @@ -175,9 +221,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 "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 @@ -193,20 +240,20 @@ 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. A one-shot pull is a sign that a commit history is now crossing the boundary between one circle of people (e.g. "people who are -primarily interested in networking part of the kernel") who may +primarily interested in the networking part of the kernel") who may have their own set of tags (e.g. "this is the third release candidate from the networking group to be proposed for general consumption with 2.6.21 release") to another circle of people @@ -218,8 +265,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. @@ -228,30 +275,25 @@ 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[] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, -Junio C Hamano <junkio@cox.net> and Chris Wright <chrisw@osdl.org>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-check-ref-format[1]. GIT --- diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 74ed06525e..f7362dc2d1 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 -------- -'git-tar-tree' [--remote=<repo>] <tree-ish> [ <base> ] +[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^{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 d0552b2c74..e9f148a00d 100644 --- a/Documentation/git-unpack-file.txt +++ b/Documentation/git-unpack-file.txt @@ -9,7 +9,8 @@ git-unpack-file - Creates a temporary file with a blob's contents SYNOPSIS -------- -'git-unpack-file' <blob> +[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 b9c4279a88..ff23494e70 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -8,7 +8,8 @@ git-unpack-objects - Unpack objects from a packed archive SYNOPSIS -------- -'git-unpack-objects' [-n] [-q] [-r] [--strict] <pack-file +[verse] +'git unpack-objects' [-n] [-q] [-r] [--strict] <pack-file DESCRIPTION @@ -21,7 +22,7 @@ Objects that already exist in the repository will *not* be unpacked from the pack-file. Therefore, nothing will be unpacked if you use this command on a pack-file that exists within the target repository. -Please see the `git-repack` documentation for options to generate +See linkgit:git-repack[1] for options to generate new packs and replace existing ones. OPTIONS @@ -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 bbb0a6ad57..9d0b1515c5 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -9,18 +9,19 @@ git-update-index - Register file contents in the working tree to the index SYNOPSIS -------- [verse] -'git-update-index' +'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] [--ignore-submodules] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] - [-z] [--stdin] + [-z] [--stdin] [--index-version <n>] [--verbose] - [--] [<file>]\* + [--] [<file>...] DESCRIPTION ----------- @@ -31,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 @@ -53,15 +54,15 @@ 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: +--ignore-submodules:: Do not try to update submodules. This option is only respected when passed before --refresh. --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:: @@ -78,9 +79,9 @@ OPTIONS --assume-unchanged:: --no-assume-unchanged:: - When these flags are specified, the object name recorded + When these flags are specified, the object names recorded for the paths are not updated. Instead, these options - sets and unsets the "assume unchanged" bit for the + set and unset the "assume unchanged" bit for the paths. When the "assume unchanged" bit is on, git stops checking the working tree files for possible modifications, so you need to manually unset the bit to @@ -88,10 +89,29 @@ OPTIONS sometimes helpful when working with a big project on a filesystem that has very slow lstat(2) system call (e.g. cifs). ++ +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). +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, +you will need to handle the situation manually. + +--really-refresh:: + Like '--refresh', but checks stat information unconditionally, + without regard to the "assume unchanged" setting. + +--skip-worktree:: +--no-skip-worktree:: + When one of these flags is specified, the object name recorded + for the paths are not updated. Instead, these options + set and unset the "skip-worktree" bit for the paths. See + section "Skip-worktree bit" below for more information. -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:: @@ -109,10 +129,10 @@ OPTIONS --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 conflicts with the entry being added are + that conflict with the entry being added are automatically removed with warning messages. --stdin:: @@ -123,9 +143,13 @@ OPTIONS --verbose:: Report what is being added and removed from index. +--index-version <n>:: + Write the resulting index out in the named on-disk format version. + The current default version is 2. + -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. @@ -145,7 +169,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 @@ -157,7 +181,7 @@ merging. To pretend you have a file with mode and sha1 at path, say: ---------------- -$ git-update-index --cacheinfo mode sha1 path +$ git update-index --cacheinfo mode sha1 path ---------------- '--info-only' is used to register files without placing them in the object @@ -186,13 +210,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 @@ -244,16 +268,18 @@ 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 +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 +`git update-index --refresh` finds the working tree file matches +the index (use `git update-index --really-refresh` if you want to mark them as "assume unchanged"). @@ -262,7 +288,7 @@ Examples To update and refresh only the files already checked out: ---------------- -$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh +$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh ---------------- On an inefficient filesystem with `core.ignorestat` set:: @@ -294,16 +320,37 @@ M foo.c <9> now it checks with lstat(2) and finds it has been changed. +Skip-worktree bit +----------------- + +Skip-worktree bit can be defined in one (long) sentence: When reading +an entry, if it is marked as skip-worktree, then Git pretends its +working directory version is up to date and read the index version +instead. + +To elaborate, "reading" means checking for file existence, reading +file attributes or file content. The working directory version may be +present or absent. If present, its content may match against the index +version or not. Writing is not affected by this bit, content safety +is still first priority. Note that Git _can_ update working directory +file, that is marked skip-worktree, if it is safe to do so (i.e. +working directory version matches index version) + +Although this bit looks similar to assume-unchanged bit, its goal is +different from assume-unchanged bit's. Skip-worktree also takes +precedence over assume-unchanged bit when both are set. + + Configuration ------------- The command honors `core.filemode` configuration variable. If -your repository is on an filesystem whose executable bits are +your repository is on a filesystem whose executable bits are 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 @@ -313,20 +360,17 @@ from symbolic link to regular file. The command looks at `core.ignorestat` configuration variable. See 'Using "assume unchanged" bit' section above. +The command also looks at `core.trustctime` configuration variable. +It can be useful when the inode change time is regularly modified by +something outside Git (file system crawlers and backup systems use +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 7f7e3d197b..d377a35243 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -7,18 +7,19 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- -'git-update-ref' [-m <reason>] (-d <ref> <oldvalue> | [--no-deref] <ref> <newvalue> [<oldvalue>]) +[verse] +'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>]) DESCRIPTION ----------- Given two arguments, stores the <newvalue> in the <ref>, possibly -dereferencing the symbolic refs. E.g. `git-update-ref HEAD +dereferencing the symbolic refs. E.g. `git update-ref HEAD <newvalue>` updates the current branch head to the new object. Given three arguments, stores the <newvalue> in the <ref>, possibly dereferencing the symbolic refs, after verifying that the current value of the <ref> matches <oldvalue>. -E.g. `git-update-ref refs/heads/master <newvalue> <oldvalue>` +E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>` updates the master branch head to <newvalue> only if its current value is <oldvalue>. You can specify 40 "0" or an empty string as <oldvalue> to make sure that the ref you are creating does @@ -41,7 +42,7 @@ the result of following the symbolic pointers. In general, using - git-update-ref HEAD "$head" + git update-ref HEAD "$head" should be a _lot_ safer than doing @@ -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 d21be41d06..bd0e36492f 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -8,7 +8,8 @@ git-update-server-info - Update auxiliary info file to help dumb servers SYNOPSIS -------- -'git-update-server-info' [--force] +[verse] +'git update-server-info' [--force] DESCRIPTION ----------- @@ -31,28 +32,13 @@ OUTPUT ------ Currently the command updates the following files. Please see -linkgit:gitrepository-layout[5][repository-layout] for description of +linkgit:gitrepository-layout[5] for description of what they are for: * objects/info/packs * info/refs - -BUGS ----- -When you remove an existing ref, the command fails to update -info/refs file unless `--force` flag is given. - - -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -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 e49f68f68e..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 -------- -'git-upload-archive' <directory> +[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 bac465e13f..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 -------- +[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 67e8e1f93a..67edf58689 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,11 +21,11 @@ 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 -------- - $ git-var GIT_AUTHOR_IDENT + $ git var GIT_AUTHOR_IDENT Eric W. Biederman <ebiederm@lnxi.com> 1121223278 -0600 @@ -36,14 +37,27 @@ GIT_AUTHOR_IDENT:: GIT_COMMITTER_IDENT:: The person who put a piece of code into git. -Diagnostics ------------ -You don't exist. Go away!:: - The passwd(5) gecos field couldn't be read -Your parents must have hated you!:: - The password(5) gecos field is longer than a giant static buffer. -Your sysadmin must hate you!:: - The password(5) name field is longer than a giant static buffer. +GIT_EDITOR:: + Text editor for use by git commands. The value is meant to be + interpreted by the shell when it is used. Examples: `~/bin/vi`, + `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe" + --nofork`. The order of preference is the `$GIT_EDITOR` + environment variable, then `core.editor` configuration, then + `$VISUAL`, then `$EDITOR`, and then the default chosen at compile + time, which is usually 'vi'. +ifdef::git-default-editor[] + The build you are using chose '{git-default-editor}' as the default. +endif::git-default-editor[] + +GIT_PAGER:: + Text viewer for use by git commands (e.g., 'less'). The value + is meant to be interpreted by the shell. The order of preference + is the `$GIT_PAGER` environment variable, then `core.pager` + configuration, then `$PAGER`, and then the default chosen at + compile time (usually 'less'). +ifdef::git-default-pager[] + The build you are using chose '{git-default-pager}' as the default. +endif::git-default-pager[] SEE ALSO -------- @@ -51,14 +65,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 478f236996..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] [--] <pack>.idx ... +[verse] +'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... DESCRIPTION ----------- -Reads given idx file for packed git archive created with -git-pack-objects command and verifies idx file and the +Reads given idx file for packed git archive created with the +'git pack-objects' command and verifies idx file and the corresponding pack file. OPTIONS @@ -23,8 +24,15 @@ OPTIONS The idx files to verify. -v:: +--verbose:: After verifying the pack, show list of objects contained - in the pack. + in the pack and a histogram of delta chain length. + +-s:: +--stat-only:: + Do not verify the pack contents; only show the histogram of delta + chain length. With `--verbose`, list of objects is also shown. + \--:: Do not interpret any more arguments as options. @@ -40,14 +48,6 @@ for objects that are not deltified in the pack, and for objects that are deltified. -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -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 dffba8906a..5ff76e892a 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -7,24 +7,21 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- -'git-verify-tag' <tag>... +[verse] +'git verify-tag' <tag>... DESCRIPTION ----------- -Validates the gpg signature created by git-tag. +Validates the gpg signature created by 'git tag'. OPTIONS ------- -<tag>:: - SHA1 identifier of a git tag object. +-v:: +--verbose:: + Print the contents of the tag object before validating it. -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>. +<tag>...:: + SHA1 identifiers of git tag objects. GIT --- diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index e80a7c1cc4..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,30 +21,37 @@ 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 * open (this is the default under Mac OS X GUI) +* start (this is the default under MinGW) 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 ----------------------- @@ -61,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 @@ -70,14 +78,14 @@ 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. Note about konqueror -------------------- -When 'konqueror' is specified by the a command line option or a +When 'konqueror' is specified by a command line option or a configuration variable, we launch 'kfmclient' to try to open the HTML man page on an already opened konqueror in a new tab if possible. @@ -96,7 +104,7 @@ the following: cmd = A_PATH_TO/konqueror ------------------------------------------------ -Note about git config --global +Note about git-config --global ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that these configuration variables should probably be set using @@ -109,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 f5d39c7870..6c8f510c3f 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 -------- -'git-whatchanged' <option>... +[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 <junkio@cox.net> - - -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 8744f6535d..f22041a9dc 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -8,25 +8,27 @@ git-write-tree - Create a tree object from the current index SYNOPSIS -------- -'git-write-tree' [--missing-ok] [--prefix=<prefix>/] +[verse] +'git write-tree' [--missing-ok] [--prefix=<prefix>/] DESCRIPTION ----------- -Creates a tree object using the current index. +Creates a tree object using the current index. The name of the new +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. @@ -35,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 7414238fe5..55e405d644 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]] - [-p|--paginate|--no-pager] - [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] - [--help] COMMAND [ARGS] +'git' [--version] [--help] [-c <name>=<value>] + [--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>] + <command> [<args>] DESCRIPTION ----------- @@ -20,14 +21,14 @@ Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals. -See this linkgit:gittutorial[7][tutorial] to get started, then see +See linkgit:gittutorial[7] to get started, then see link:everyday.html[Everyday Git] for a useful minimum set of commands, and "man git-commandname" for documentation of each command. CVS users may -also want to read linkgit:gitcvs-migration[7][CVS migration]. See -link:user-manual.html[Git User's Manual] for a more in-depth +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,74 +44,269 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.5.6/git.html[documentation for release 1.5.6] +* link:v1.7.10.4/git.html[documentation for release 1.7.10.4] * release notes for - link:RelNotes-1.5.6.txt[1.5.6], + link:RelNotes/1.7.10.4.txt[1.7.10.4], + link:RelNotes/1.7.10.3.txt[1.7.10.3], + link:RelNotes/1.7.10.2.txt[1.7.10.2], + link:RelNotes/1.7.10.1.txt[1.7.10.1], + link:RelNotes/1.7.10.txt[1.7.10]. -* link:v1.5.5/git.html[documentation for release 1.5.5] +* link:v1.7.9.7/git.html[documentation for release 1.7.9.7] * release notes for - 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.7.9.7.txt[1.7.9.7], + link:RelNotes/1.7.9.6.txt[1.7.9.6], + link:RelNotes/1.7.9.5.txt[1.7.9.5], + link:RelNotes/1.7.9.4.txt[1.7.9.4], + link:RelNotes/1.7.9.3.txt[1.7.9.3], + link:RelNotes/1.7.9.2.txt[1.7.9.2], + link:RelNotes/1.7.9.1.txt[1.7.9.1], + link:RelNotes/1.7.9.txt[1.7.9]. -* link:v1.5.5.4/git.html[documentation for release 1.5.5.4] +* link:v1.7.8.6/git.html[documentation for release 1.7.8.6] -* link:v1.5.4.5/git.html[documentation for release 1.5.4.5] +* release notes for + link:RelNotes/1.7.8.6.txt[1.7.8.6], + link:RelNotes/1.7.8.5.txt[1.7.8.5], + link:RelNotes/1.7.8.4.txt[1.7.8.4], + link:RelNotes/1.7.8.3.txt[1.7.8.3], + link:RelNotes/1.7.8.2.txt[1.7.8.2], + link:RelNotes/1.7.8.1.txt[1.7.8.1], + link:RelNotes/1.7.8.txt[1.7.8]. + +* link:v1.7.7.7/git.html[documentation for release 1.7.7.7] + +* release notes for + link:RelNotes/1.7.7.7.txt[1.7.7.7], + link:RelNotes/1.7.7.6.txt[1.7.7.6], + link:RelNotes/1.7.7.5.txt[1.7.7.5], + link:RelNotes/1.7.7.4.txt[1.7.7.4], + link:RelNotes/1.7.7.3.txt[1.7.7.3], + link:RelNotes/1.7.7.2.txt[1.7.7.2], + link:RelNotes/1.7.7.1.txt[1.7.7.1], + link:RelNotes/1.7.7.txt[1.7.7]. + +* link:v1.7.6.6/git.html[documentation for release 1.7.6.6] + +* release notes for + link:RelNotes/1.7.6.6.txt[1.7.6.6], + link:RelNotes/1.7.6.5.txt[1.7.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.7.5.4/git.html[documentation for release 1.7.5.4] + +* release notes for + 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.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.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:v1.6.1.3/git.html[documentation for release 1.6.1.3] + +* release notes for + link:RelNotes/1.6.1.3.txt[1.6.1.3], + link:RelNotes/1.6.1.2.txt[1.6.1.2], + link:RelNotes/1.6.1.1.txt[1.6.1.1], + link:RelNotes/1.6.1.txt[1.6.1]. + +* link:v1.6.0.6/git.html[documentation for release 1.6.0.6] + +* release notes for + link:RelNotes/1.6.0.6.txt[1.6.0.6], + link:RelNotes/1.6.0.5.txt[1.6.0.5], + link:RelNotes/1.6.0.4.txt[1.6.0.4], + link:RelNotes/1.6.0.3.txt[1.6.0.3], + link:RelNotes/1.6.0.2.txt[1.6.0.2], + link:RelNotes/1.6.0.1.txt[1.6.0.1], + link:RelNotes/1.6.0.txt[1.6.0]. + +* link:v1.5.6.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:v1.5.5.6/git.html[documentation for release 1.5.5.6] + +* release notes for + link:RelNotes/1.5.5.6.txt[1.5.5.6], + link:RelNotes/1.5.5.5.txt[1.5.5.5], + link:RelNotes/1.5.5.4.txt[1.5.5.4], + link:RelNotes/1.5.5.3.txt[1.5.5.3], + link:RelNotes/1.5.5.2.txt[1.5.5.2], + link:RelNotes/1.5.5.1.txt[1.5.5.1], + link:RelNotes/1.5.5.txt[1.5.5]. + +* link:v1.5.4.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: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], @@ -134,18 +330,39 @@ OPTIONS + Other options are available to control how the manual page is displayed. See linkgit:git-help[1] for more information, -because 'git --help ...' is converted internally into 'git -help ...'. +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 + environment variable. If no path is given, 'git' will print the current setting and then exit. +--html-path:: + 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. @@ -156,23 +373,27 @@ 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 environment is not set, it is set to the current working directory. +--no-replace-objects:: + Do not use replacement refs to replace git objects. See + linkgit:git-replace[1] for more information. + FURTHER DOCUMENTATION --------------------- @@ -181,13 +402,16 @@ See the references above to get started using git. The following is probably more detail than necessary for a first-time user. The link:user-manual.html#git-concepts[git concepts chapter of the -user-manual] and the linkgit:gitcore-tutorial[7][Core tutorial] both provide +user-manual] and linkgit:gitcore-tutorial[7] both provide introductions to the underlying git architecture. +See linkgit:gitworkflows[7] for an overview of recommended workflows. + See also the link:howto-index.html[howto] documents for some useful examples. -The internals are documented link:technical/api-index.html[here]. +The internals are documented in the +link:technical/api-index.html[GIT API documentation]. GIT COMMANDS ------------ @@ -269,7 +493,7 @@ Synching repositories include::cmds-synchingrepositories.txt[] -The following are helper programs used by the above; end users +The following are helper commands used by the above; end users typically do not use them directly. include::cmds-synchelpers.txt[] @@ -310,7 +534,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 @@ -353,28 +578,26 @@ 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 ------------------------ -Please see the linkgit:gitrepository-layout[5][repository layout] -document. +Please see the linkgit:gitrepository-layout[5] document. -Read linkgit:githooks[5][hooks] for more details about each hook. +Read linkgit:githooks[5] for more details about each hook. Higher level SCMs may provide and manage additional information in the `$GIT_DIR`. @@ -382,7 +605,7 @@ Higher level SCMs may provide and manage additional information in the Terminology ----------- -Please see the linkgit:gitglossary[7][glossary] document. +Please see linkgit:gitglossary[7]. Environment Variables @@ -409,9 +632,9 @@ git so take care if using Cogito etc. 'GIT_ALTERNATE_OBJECT_DIRECTORIES':: Due to the immutable nature of git objects, old objects can be archived into shared, read-only directories. This variable - specifies a ":" separated list of git object directories which - can be used to search for git objects. New objects will not be - written to these directories. + specifies a ":" separated (on Windows ";" separated) list + of git object directories which can be used to search for git + objects. New objects will not be written to these directories. 'GIT_DIR':: If the 'GIT_DIR' environment variable is set then it @@ -425,6 +648,28 @@ 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 + up into while looking for a repository directory. + It will not exclude the current working directory or + 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':: @@ -458,7 +703,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` @@ -479,13 +723,20 @@ other 'GIT_PAGER':: This environment variable overrides `$PAGER`. If it is set to an empty string or to the value "cat", git will not launch - a pager. + a pager. See also the `core.pager` option in + linkgit:git-config[1]. + +'GIT_EDITOR':: + This environment variable overrides `$EDITOR` and `$VISUAL`. + It is used by several git comands when, on interactive mode, + an editor is to be launched. See also linkgit:git-var[1] + and the `core.editor` option in linkgit:git-config[1]. 'GIT_SSH':: - If this environment variable is set then linkgit:git-fetch[1] - and linkgit:git-push[1] 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: + 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 shell command to execute on that remote system. + @@ -497,10 +748,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, - git-whatchanged, etc., 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 @@ -526,7 +784,7 @@ Discussion[[Discussion]] More detail on the following is available from the link:user-manual.html#git-concepts[git concepts chapter of the -user-manual] and the linkgit:gitcore-tutorial[7][Core tutorial]. +user-manual] and linkgit:gitcore-tutorial[7]. A git project normally consists of a working directory with a ".git" subdirectory at the top level. The .git directory contains, among other @@ -576,23 +834,27 @@ 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 -------- linkgit:gittutorial[7], linkgit:gittutorial-2[7], -linkgit:giteveryday[7], linkgit:gitcvs-migration[7], +link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7], linkgit:gitglossary[7], linkgit:gitcore-tutorial[7], -link:user-manual.html[The Git User's Manual] +linkgit:gitcli[7], link:user-manual.html[The Git User's Manual], +linkgit:gitworkflows[7] GIT --- diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 471754eb12..80120ea14f 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -7,7 +7,7 @@ gitattributes - defining attributes per path SYNOPSIS -------- -$GIT_DIR/info/attributes, gitattributes +$GIT_DIR/info/attributes, .gitattributes DESCRIPTION @@ -18,10 +18,10 @@ A `gitattributes` file is a simple text file that gives Each line in `gitattributes` file is of form: - glob attr1 attr2 ... + pattern attr1 attr2 ... -That is, a glob pattern followed by an attributes list, -separated by whitespaces. When the glob pattern matches the +That is, a pattern followed by an attributes list, +separated by whitespaces. When the pattern matches the path in question, the attributes listed on the line are given to the path. @@ -48,30 +48,38 @@ Set to a value:: Unspecified:: - No glob pattern matches the path, and nothing says if + No pattern matches the path, and nothing says if the path has or does not have the attribute, the attribute for the path is said to be Unspecified. -When more than one glob pattern matches the path, a later line +When more than one pattern matches the path, a later line overrides an earlier line. This overriding is done per -attribute. +attribute. The rules how the pattern matches paths are the +same as in `.gitignore` files; see linkgit:gitignore[5]. When deciding what attributes are assigned to a path, git 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 (the further the -directory that contains `.gitattributes` is from the path in -question, the lower its precedence). +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). 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 `!`. @@ -87,58 +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 is meant to - mark the path as a "binary" file. The path never goes - through line endings conversion upon checkin/checkout. + 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 the configuration variable `core.autocrlf` is false, no -conversion is done. +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. -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. +------------------------ +* 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'. + +------------------------ +manual.pdf -text +------------------------ -When `core.autocrlf` is set to "input", line endings are -converted to LF upon checkin, but there is no conversion done -upon checkout. +Conversely, text files that git does not detect can have normalization +enabled manually. + +------------------------ +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,24 +256,24 @@ 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. `ident` ^^^^^^^ -When the attribute `ident` is set to a path, git replaces -`$Id$` in the blob object with `$Id:`, followed by +When the attribute `ident` is set for a path, git replaces +`$Id$` in the blob object with `$Id:`, followed by the 40-character hexadecimal blob object name, followed by a dollar sign `$` upon checkout. Any byte sequence that begins with `$Id:` and ends with `$` in the worktree file is replaced @@ -186,16 +294,77 @@ output is used to update the worktree file. Similarly, the `clean` command is used to convert the contents of worktree file upon checkin. -A missing filter driver definition in the config is not an error -but makes the filter a no-op passthru. +One use of the content filtering is to massage the content into a shape +that is more convenient for the platform, filesystem, and the user to use. +For this mode of operation, the key phrase here is "more convenient" and +not "turning something unusable into usable". In other words, the intent +is that if someone unsets the filter driver definition, or does not have +the appropriate filter program, the project should still be usable. -The content filtering is done to massage the content into a -shape that is more convenient for the platform, filesystem, and -the user to use. The key phrase here is "more convenient" and not -"turning something unusable into usable". In other words, the -intent is that if someone unsets the filter driver definition, -or does not have the appropriate filter program, the project -should still be usable. +Another use of the content filtering is to store the content that cannot +be directly used in the repository (e.g. a UUID that refers to the true +content stored outside git, or an encrypted content) and turn it into a +usable form upon checkout (e.g. download the external content, or decrypt +the encrypted content). + +These two filters behave differently, and by default, a filter is taken as +the former, massaging the contents into more convenient shape. A missing +filter driver definition in the config, or a filter driver that exits with +a non-zero status, is not an error but makes the filter a no-op passthru. + +You can declare that a filter turns a content that by itself is unusable +into a usable content by setting the filter.<driver>.required configuration +variable to `true`. + +For example, in .gitattributes, you would assign the `filter` +attribute for paths. + +------------------------ +*.c filter=indent +------------------------ + +Then you would define a "filter.indent.clean" and "filter.indent.smudge" +configuration in your .git/config to specify a pair of commands to +modify the contents of C programs when the source files are checked +in ("clean" is run) and checked out (no change is made because the +command is "cat"). + +------------------------ +[filter "indent"] + clean = indent + 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. + +If a filter _must_ succeed in order to make the stored contents usable, +you can declare that the filter is `required`, in the configuration: + +------------------------ +[filter "crypt"] + clean = openssl enc ... + smudge = openssl enc -d ... + required +------------------------ + +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 @@ -204,20 +373,48 @@ 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 ~~~~~~~~~~~~~~~~~~~~ -The attribute `diff` affects if `git diff` generates textual -patch for the path or just says `Binary files differ`. It also -can affect what line is shown on the hunk header `@@ -k,l +n,m @@` -line. +`diff` +^^^^^^ + +The attribute `diff` affects how 'git' generates diffs for particular +files. It can tell git whether to generate a textual patch for the path +or to treat the path as a binary file. It can also affect what line is +shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an +external command to generate the diff, or ask git to convert binary +files to a text format before generating the diff. Set:: @@ -228,7 +425,8 @@ Set:: Unset:: A path to which the `diff` attribute is unset will - generate `Binary files differ`. + generate `Binary files differ` (or a binary patch, if + binary patches are enabled). Unspecified:: @@ -239,21 +437,21 @@ Unspecified:: String:: - Diff is shown using the specified custom diff driver. - The driver program is given its input using the same - calling convention as used for GIT_EXTERNAL_DIFF - program. This name is also used for custom hunk header - selection. + Diff is shown using the specified diff driver. Each driver may + specify one or more options, as described in the following + section. The options for the diff driver "foo" are defined + by the configuration variables in the "diff.foo" section of the + git config file. -Defining a custom diff driver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Defining an external diff driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The definition of a diff driver is done in `gitconfig`, not `gitattributes` file, so strictly speaking this manual page is a wrong place to talk about it. However... -To define a custom diff driver `jcdiff`, add a section to your +To define an external diff driver `jcdiff`, add a section to your `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: ---------------------------------------------------------------- @@ -271,31 +469,32 @@ See linkgit:git[1] for details. Defining a custom hunk-header ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Each group of changes (called "hunk") in the textual diff output +Each group of changes (called a "hunk") in the textual diff output is prefixed with a line of the form: @@ -k,l +n,m @@ TEXT -The text is called 'hunk header', and by default a line that -begins with an alphabet, an underscore or a dollar sign is used, -which matches what GNU `diff -p` output uses. This default -selection however is not suited for some contents, and you can -use customized pattern to make a selection. +This is called a 'hunk header'. The "TEXT" portion is by default a line +that begins with an alphabet, an underscore or a dollar sign; this +matches what GNU 'diff -p' output uses. This default selection however +is not suited for some contents, and you can use a customized pattern +to make a selection. -First in .gitattributes, you would assign the `diff` attribute +First, in .gitattributes, you would assign the `diff` attribute for paths. ------------------------ *.tex diff=tex ------------------------ -Then, you would define "diff.tex.funcname" configuration to +Then, you would define a "diff.tex.xfuncname" configuration to specify a regular expression that matches a line that you would -want to appear as the hunk header, like this: +want to appear as the hunk header "TEXT". Add a section to your +`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: ------------------------ [diff "tex"] - funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$" + xfuncname = "^(\\\\(sub)*section\\{.*)$" ------------------------ Note. A single level of backslashes are eaten by the @@ -307,37 +506,209 @@ backslash, and zero or more occurrences of `sub` followed by There are a few built-in patterns to make this easier, and `tex` is one of them, so you do not have to write the above in your configuration file (you still need to enable this with the -attribute mechanism, via `.gitattributes`). Another built-in -pattern is defined for `java` that defines a pattern suitable -for program text in Java language. +attribute mechanism, via `.gitattributes`). The following built in +patterns are available: + +- `bibtex` suitable for files with BibTeX coded references. + +- `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. + +- `matlab` suitable for source code in the MATLAB language. + +- `objc` suitable for source code in the Objective-C language. + +- `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. + +- `ruby` suitable for source code in the Ruby language. + +- `tex` suitable for source code for LaTeX documents. + + +Customizing word diff +^^^^^^^^^^^^^^^^^^^^^ + +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 +several such commands can be run together without intervening +whitespace. To separate them, use a regular expression in your +`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: + +------------------------ +[diff "tex"] + wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" +------------------------ + +A built-in pattern is provided for all languages listed in the +previous section. + + +Performing text diffs of binary files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sometimes it is desirable to see the diff of a text-converted +version of some binary files. For example, a word processor +document can be converted to an ASCII text representation, and +the diff of the text shown. Even though this conversion loses +some information, the resulting diff is useful for human +viewing (but cannot be applied directly). + +The `textconv` config option is used to define a program for +performing such a conversion. The program should take a single +argument, the name of a file to convert, and produce the +resulting text on stdout. + +For example, to show the diff of the exif information of a +file instead of the binary information (assuming you have the +exif tool installed), add the following section to your +`$GIT_DIR/config` file (or `$HOME/.gitconfig` file): + +------------------------ +[diff "jpg"] + textconv = exif +------------------------ + +NOTE: The text conversion is generally a one-way conversion; +in this example, we lose the actual image contents and focus +just on the text data. This means that diffs generated by +textconv are _not_ suitable for applying. For this reason, +only `git diff` and the `git log` family of commands (i.e., +log, whatchanged, show) will perform text conversion. `git +format-patch` will never generate this output. If you want to +send somebody a text-converted diff of a binary file (e.g., +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The attribute `merge` affects how three versions of a file is +`merge` +^^^^^^^ + +The attribute `merge` affects how three versions of a file are merged when a file-level merge is necessary during `git merge`, -and other programs such as `git revert` and `git cherry-pick`. +and other commands such as `git revert` and `git cherry-pick`. Set:: Built-in 3-way merge driver is used to merge the - contents in a way similar to `merge` command of `RCS` + contents in a way similar to 'merge' command of `RCS` suite. This is suitable for ordinary text files. 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:: @@ -405,7 +776,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 @@ -419,6 +791,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -426,13 +815,15 @@ Checking whitespace errors ^^^^^^^^^^^^ The `core.whitespace` configuration variable allows you to define what -`diff` and `apply` should consider whitespace errors for all paths in +'diff' and 'apply' should consider whitespace errors for all paths in the project (See linkgit:git-config[1]). This attribute gives you finer 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:: @@ -440,16 +831,104 @@ 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. +Creating an archive +~~~~~~~~~~~~~~~~~~~ + +`export-ignore` +^^^^^^^^^^^^^^^ + +Files and directories with the attribute `export-ignore` won't be added to +archive files. + +`export-subst` +^^^^^^^^^^^^^^ + +If the attribute `export-subst` is set for a file then git will expand +several placeholders when adding this file to an archive. The +expansion depends on the availability of a commit ID, i.e., if +linkgit:git-archive[1] has been given a tree instead of a commit or a +tag then no replacement will be done. The placeholders are the same +as those for the option `--pretty=format:` of linkgit:git-log[1], +except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` +in the file. E.g. the string `$Format:%H$` will be replaced by the +commit hash. + + +Packing objects +~~~~~~~~~~~~~~~ + +`delta` +^^^^^^^ + +Delta compression will not be attempted for blobs for paths with the +attribute `delta` set to false. + + +Viewing files in GUI tools +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`encoding` +^^^^^^^^^^ + +The value of this attribute specifies the character encoding that should +be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to +display the contents of the relevant file. Note that due to performance +considerations linkgit:gitk[1] does not use this attribute unless you +manually enable per-file encodings in its options. + +If this attribute is not set or has an invalid value, the value of the +`gui.encoding` configuration variable is used instead +(See linkgit:git-config[1]). + + +USING 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 -text -diff +------------ + +but that may become cumbersome, when you have many attributes. Using +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 +------------ + +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 MACRO ATTRIBUTES +------------------------- + +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 -text +------------ + + EXAMPLE ------- @@ -499,22 +978,9 @@ frotz unspecified ---------------------------------------------------------------- -Creating an archive -~~~~~~~~~~~~~~~~~~~ - -`export-subst` -^^^^^^^^^^^^^^ - -If the attribute `export-subst` is set for a file then git will expand -several placeholders when adding this file to an archive. The -expansion depends on the availability of a commit ID, i.e. if -linkgit:git-archive[1] has been given a tree instead of a commit or a -tag then no replacement will be done. The placeholders are the same -as those for the option `--pretty=format:` of linkgit:git-log[1], -except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` -in the file. E.g. the string `$Format:%H$` will be replaced by the -commit hash. - +SEE ALSO +-------- +linkgit:git-check-attr[1]. GIT --- diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 8fb5d889e5..ea17f7a53b 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -13,29 +13,58 @@ gitcli DESCRIPTION ----------- -This manual describes best practice in how to use git CLI. Here are -the rules that you should follow when you are scripting git: +This manual describes the convention used throughout git CLI. + +Many commands take revisions (most often "commits", but sometimes +"tree-ish", depending on the context and command) and paths as their +arguments. Here are the rules: + + * Revisions come first and then paths. + E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`, + `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86` + are paths. + + * When an argument can be misunderstood as either a revision or a path, + they can be disambiguated by placing `--` between them. + E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work + tree. Please show changes between the version I staged in the index + and what I have in the work tree for that file". not "show difference + between the HEAD commit and the work tree as a whole". You can say + `git diff HEAD --` to ask for the latter. + + * Without disambiguating `--`, git makes a reasonable guess, but errors + out and asking you to disambiguate when ambiguous. E.g. if you have a + file called HEAD in your work tree, `git diff HEAD` is ambiguous, and + you have to say either `git diff HEAD --` or `git diff -- HEAD` to + disambiguate. + +When writing a script that is expected to handle random user-input, it is +a good practice to make it explicit which arguments are which by placing +disambiguating `--` at appropriate places. + +Here are the rules regarding the "flags" that you should follow when you are +scripting git: * it's preferred to use the non dashed form of git commands, which means that - you should prefer `"git foo"` to `"git-foo"`. + you should prefer `git foo` to `git-foo`. - * splitting short options to separate words (prefer `"git foo -a -b"` - to `"git foo -ab"`, the latter may not even work). + * splitting short options to separate words (prefer `git foo -a -b` + to `git foo -ab`, the latter may not even work). * when a command line option takes an argument, use the 'sticked' form. In - other words, write `"git foo -oArg"` instead of `"git foo -o Arg"` for short - options, and `"git foo --long-opt=Arg"` instead of `"git foo --long-opt Arg"` + other words, write `git foo -oArg` instead of `git foo -o Arg` for short + options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` for long options. An option that takes optional option-argument must be written in the 'sticked' form. * when you give a revision parameter to a command, make sure the parameter is not ambiguous with a name of a file in the work tree. E.g. do not write - `"git log -1 HEAD"` but write `"git log -1 HEAD --"`; the former will not work + `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. -ENHANCED CLI ------------- +ENHANCED OPTION PARSER +---------------------- From the git 1.5.4 series and further, many git commands (not all of them at the time of the writing though) come with an enhanced option parser. @@ -52,7 +81,7 @@ couple of magic command line options: + --------------------------------------------- $ git describe -h -usage: git-describe [options] <committish>* +usage: git describe [options] <committish>* --contains find the tag that comes after the commit --debug debug search strategy on stderr @@ -70,17 +99,17 @@ usage: git-describe [options] <committish>* Negating options ~~~~~~~~~~~~~~~~ -Options with long option names can be negated by prefixing `"--no-"`. For -example, `"git branch"` has the option `"--track"` which is 'on' by default. You -can use `"--no-track"` to override that behaviour. The same goes for `"--color"` -and `"--no-color"`. +Options with long option names can be negated by prefixing `--no-`. For +example, `git branch` has the option `--track` which is 'on' by default. You +can use `--no-track` to override that behaviour. The same goes for `--color` +and `--no-color`. Aggregating short options ~~~~~~~~~~~~~~~~~~~~~~~~~ Commands that support the enhanced option parser allow you to aggregate short -options. This means that you can for example use `"git rm -rf"` or -`"git clean -fdx"`. +options. This means that you can for example use `git rm -rf` or +`git clean -fdx`. Separating argument from the option @@ -104,9 +133,41 @@ $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT ---------------------------- -Documentation -------------- -Documentation by Pierre Habouzit. +NOTES ON FREQUENTLY CONFUSED OPTIONS +------------------------------------ + +Many commands that can work on files in the working tree +and/or in the index can take `--cached` and/or `--index` +options. Sometimes people incorrectly think that, because +the index was originally called cache, these two are +synonyms. They are *not* -- these two options mean very +different things. + + * The `--cached` option is used to ask a command that + usually works on files in the working tree to *only* work + with the index. For example, `git grep`, when used + without a commit to specify from which commit to look for + strings in, usually works on files in the working tree, + but with the `--cached` option, it looks for strings in + the index. + + * The `--index` option is used to ask a command that + usually works on files in the working tree to *also* + affect the index. For example, `git stash apply` usually + merges changes recorded in a stash to the working tree, + but with the `--index` option, it also merges changes to + the index as well. + +`git apply` command can be used with `--cached` and +`--index` (but not at the same time). Usually the command +only affects the files in the working tree, but with +`--index`, it patches both the files and their index +entries, and with `--cached`, it modifies only the index +entries. + +See also http://marc.info/?l=git&m=116563135620359 and +http://marc.info/?l=git&m=119150393620273 for further +information. GIT --- diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index cb4ec40440..9d893369a0 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -12,12 +12,12 @@ git * DESCRIPTION ----------- -This tutorial explains how to use the "core" git programs to set up and +This tutorial explains how to use the "core" git commands to set up and work with a git repository. If you just need to use git as a revision control system you may prefer -to start with linkgit:gittutorial[7][a tutorial introduction to git] or -link:user-manual.html[the git user manual]. +to start with "A Tutorial Introduction to GIT" (linkgit:gittutorial[7]) or +link:user-manual.html[the GIT User Manual]. However, an understanding of these low-level tools can be helpful if you want to understand git's internals. @@ -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. @@ -42,14 +50,14 @@ one for a totally new project, or an existing working tree that you want 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`. +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 $ cd git-tutorial -$ git-init +$ git init ------------------------------------------------ to which git will reply @@ -61,7 +69,7 @@ Initialized empty Git repository in .git/ which is just git's way of saying that you haven't been doing anything strange, and that it will have created a local `.git` directory setup for your new project. You will now have a `.git` directory, and you can -inspect that with `ls`. For your new empty project, it should show you +inspect that with 'ls'. For your new empty project, it should show you three entries, among other things: - a file called `HEAD`, that has `ref: refs/heads/master` in it. @@ -102,14 +110,13 @@ 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. [NOTE] -An advanced user may want to take a look at the -linkgit:gitrepository-layout[5][repository layout] document +An advanced user may want to take a look at linkgit:gitrepository-layout[5] after finishing this tutorial. You have now created your first git repository. Of course, since it's @@ -140,17 +147,17 @@ 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 -adding a new entry with the `\--add` flag (or removing an entry with the -`\--remove`) flag. +adding a new entry with the `--add` flag (or removing an entry with the +`--remove`) flag. So to populate the index with the two files you just created, you can do ------------------------------------------------ -$ git-update-index --add hello example +$ git update-index --add hello example ------------------------------------------------ and you have now told git to track those two files. @@ -174,19 +181,19 @@ 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 +$ 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 ---------------- -$ git-cat-file "blob" 557db03 +$ git cat-file blob 557db03 ---------------- which will print out "Hello World". The object `557db03` is nothing @@ -206,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. @@ -229,22 +236,22 @@ $ 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 +$ git diff-files ------------ Oops. That wasn't very readable. It just spit out its own internal -version of a `diff`, but that internal version really just tells you +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: ------------ -$ git-diff-files -p +$ git diff-files -p diff --git a/hello b/hello index 557db03..263414f 100644 --- a/hello @@ -256,11 +263,11 @@ 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. -A common shorthand for `git-diff-files -p` is to just write `git +A common shorthand for `git diff-files -p` is to just write `git diff`, which will do the same thing. ------------ @@ -284,15 +291,15 @@ 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`. -There are no options or other input: git-write-tree will take the +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 filenames with their contents (and their permissions), and we're creating the equivalent of a git "directory" object: ------------------------------------------------ -$ git-write-tree +$ git write-tree ------------------------------------------------ and this will just output the name of the resulting tree, in this case @@ -303,34 +310,34 @@ 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 +`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: ------------------------------------------------ -$ tree=$(git-write-tree) -$ commit=$(echo 'Initial commit' | git-commit-tree $tree) -$ git-update-ref HEAD $commit +$ tree=$(git write-tree) +$ commit=$(echo 'Initial commit' | git commit-tree $tree) +$ git update-ref HEAD $commit ------------------------------------------------ In this case this creates a totally new commit that is not related to @@ -346,37 +353,37 @@ 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 state in the working tree, and how they don't have to match, even when we commit things. -As before, if we do `git-diff-files -p` in our git-tutorial project, +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. But now we can do ---------------- -$ git-diff-index -p HEAD +$ 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 @@ -391,20 +398,20 @@ $ git diff HEAD which ends up doing the above for you. -In other words, `git-diff-index` normally compares a tree against the -working tree, but when given the `\--cached` flag, it is told to +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 -file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return +file to HEAD, doing `git diff-index --cached -p HEAD` should thus return 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, -regardless of whether the `\--cached` flag is used or not. The `\--cached` +regardless of whether the `--cached` flag is used or not. The `--cached` flag really only determines whether the file *contents* to be compared come from the working tree or not. @@ -423,17 +430,17 @@ work through the index file, so the first thing we need to do is to update the index cache: ------------------------------------------------ -$ git-update-index hello +$ git update-index hello ------------------------------------------------ -(note how we didn't need the `\--add` flag this time, since git knew +(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 -differences, but `git-diff-index -p HEAD` still *does* show that the +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 @@ -461,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 @@ -469,16 +476,16 @@ 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 the same diff that we've already seen several times, we can now do ---------------- -$ git-diff-tree -p HEAD +$ git diff-tree -p HEAD ---------------- (again, `-p` means to show the difference as a human-readable patch), @@ -487,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 +----+ @@ -519,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. @@ -543,7 +550,7 @@ with the associated patches use the more complex (and much more powerful) ---------------- -$ git-whatchanged -p +$ git whatchanged -p ---------------- and you will see exactly what has changed in the repository over its @@ -553,15 +560,15 @@ short history. 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. +can still show it for each command just adding the `--root` option, +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'. @@ -596,14 +603,14 @@ 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> ---------------- which will sign the current `HEAD` (but you can also give it another -argument that specifies the thing to tag, i.e., you could have tagged the +argument that specifies the thing to tag, e.g., you could have tagged the current `mybranch` point by using `git tag <tagname> mybranch`). You normally only do signed tags for major releases or things @@ -643,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`. @@ -654,31 +661,31 @@ information for the files involved) will likely need to be refreshed. So after you do a `cp -a` to create a new copy, you'll want to do + ---------------- -$ git-update-index --refresh +$ git update-index --refresh ---------------- + in the new repository to make sure that the index file is up-to-date. Note that the second point is true even across machines. You can duplicate a remote git repository with *any* regular copy mechanism, be it -`scp`, `rsync` or `wget`. +'scp', 'rsync' or 'wget'. 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 -$ git-update-index --refresh +$ git read-tree --reset HEAD +$ 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 +working tree, `git update-index --refresh` notices them and tells you they need to be updated. The above can also be written as simply @@ -690,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 @@ -714,7 +721,7 @@ $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git followed by ---------------- -$ git-read-tree HEAD +$ git read-tree HEAD ---------------- to populate the index. However, now you have populated the index, and @@ -723,14 +730,14 @@ actually have any of the working tree files to work on. To get those, you'd check them out with ---------------- -$ git-checkout-index -u -a +$ git checkout-index -u -a ---------------- 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 @@ -777,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 ------------ @@ -820,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. @@ -840,7 +847,7 @@ $ git commit -m "Some work." -i hello ------------------------------------------------ Here, we just added another line to `hello`, and we used a shorthand for -doing both `git-update-index hello` and `git commit` by just giving the +doing both `git update-index hello` and `git commit` by just giving the filename directly to `git commit`, with an `-i` flag (it tells git to 'include' that file in addition to what you have done to the index file so far when making the commit). The `-m` flag is to give the @@ -874,15 +881,15 @@ helps you view what's going on: $ gitk --all ---------------- -will show you graphically both of your branches (that's what the `\--all` +will show you graphically both of your branches (that's what the `--all` means: normally it will just show you your current `HEAD`) and their histories. You can also see exactly how they came to be from a common source. -Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want +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: ------------ @@ -900,7 +907,7 @@ file, which had no differences in the `mybranch` branch), and say: ---------------- Auto-merging hello CONFLICT (content): Merge conflict in hello - Automatic merge failed; fix up by hand + Automatic merge failed; fix conflicts and then commit the result. ---------------- It tells you that it did an "Automatic merge", which @@ -926,9 +933,9 @@ $ 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 +After you're done, start up `gitk --all` to see graphically what the history looks like. Notice that `mybranch` still exists, and you can switch to it, and continue to work with it if you want to. The `mybranch` branch will not contain the merge, but next time you merge it @@ -939,7 +946,7 @@ Another useful tool, especially if you do not always work in X-Window environment, is `git show-branch`. ------------------------------------------------ -$ git-show-branch --topo-order --more=1 master mybranch +$ git show-branch --topo-order --more=1 master mybranch * [master] Merge work in mybranch ! [mybranch] Some work. -- @@ -951,7 +958,7 @@ $ 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 `*` 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. @@ -964,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 'git-rev-parse' documentation if you +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 'git-show-branch' -documentation for details. +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 @@ -994,20 +1001,20 @@ would be different) ---------------- Updating from ae3a2da... to a80b4aa.... -Fast forward - example | 1 + - hello | 1 + - 2 files changed, 2 insertions(+), 0 deletions(-) +Fast-forward (no commit created; -m option ignored) + example | 1 + + hello | 1 + + 2 files changed, 2 insertions(+) ---------------- -Because your branch did not contain anything more than what are -already merged into the `master` branch, the merge operation did +Because your branch did not contain anything more than what had +already been merged into the `master` branch, the merge operation did not actually do a merge. Instead, it just updated the top of the tree of your branch to that of the `master` branch. This is -often called 'fast forward' merge. +often called 'fast-forward' merge. -You can run `gitk \--all` again to see how the commit ancestry -looks like, or run `show-branch`, which tells you this. +You can run `gitk --all` again to see how the commit ancestry +looks like, or run 'show-branch', which tells you this. ------------------------------------------------ $ git show-branch master mybranch @@ -1024,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> @@ -1067,9 +1074,9 @@ most efficient way to exchange git objects between repositories. Local directory:: `/path/to/repo.git/` + -This transport is the same as SSH transport but uses `sh` to run +This transport is the same as SSH transport but uses 'sh' to run both ends on the local machine instead of running other end on -the remote machine via `ssh`. +the remote machine via 'ssh'. git Native:: `git://remote.machine/path/to/repo.git/` @@ -1085,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 @@ -1096,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 @@ -1116,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 @@ -1133,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. @@ -1169,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. @@ -1187,29 +1194,29 @@ $ git show-branch * [master] Some fun. ! [mybranch] Some work. -- - + [mybranch] Some work. * [master] Some fun. -*+ [mybranch^] New day. + + [mybranch] Some work. +*+ [master^] Initial commit ------------ 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) +$ mb=$(git merge-base HEAD mybranch) ------------ The command writes the commit object name of the common ancestor to the standard output, so we captured its output to a variable, because we will be using it in the next step. By the way, the common -ancestor commit is the "New day." commit in this case. You can +ancestor commit is the "Initial commit" commit in this case. You can tell it by: ------------ -$ git-name-rev $mb +$ git name-rev --name-only --tags $mb my-first-tag ------------ @@ -1217,10 +1224,10 @@ After finding out a common ancestor commit, the second step is this: ------------ -$ git-read-tree -m -u $mb HEAD mybranch +$ 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, @@ -1236,64 +1243,63 @@ trees are left in non-zero stages. At this point, you can inspect the index file with this command: ------------ -$ git-ls-files --stage +$ git ls-files --stage 100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example -100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello -100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello +100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello ------------ In our example of only two files, we did not have unchanged -files so only 'example' resulted in collapsing, but in real-life -large projects, only small number of files change in one commit, -and this 'collapsing' tends to trivially merge most of the paths -fairly quickly, leaving only a handful the real changes in non-zero +files so only 'example' resulted in collapsing. But in real-life +large projects, when only a small number of files change in one commit, +this 'collapsing' tends to trivially merge most of the paths +fairly quickly, leaving only a handful of real changes in non-zero stages. -To look at only non-zero stages, use `\--unmerged` flag: +To look at only non-zero stages, use `--unmerged` flag: ------------ -$ git-ls-files --unmerged -100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello -100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +$ git ls-files --unmerged +100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello +100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello ------------ 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 -Auto-merging hello. -merge: warning: conflicts during merge -ERROR: Merge conflict in hello. +$ git merge-index git-merge-one-file hello +Auto-merging hello +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 -eventually calls `merge` program from RCS suite to perform a -file-level 3-way merge. In this case, `merge` detects +eventually calls 'merge' program from RCS suite to perform a +file-level 3-way merge. In this case, 'merge' detects conflicts, and the merge result with conflict marks is left in the working tree.. This can be seen if you run `ls-files --stage` again at this point: ------------ -$ git-ls-files --stage +$ git ls-files --stage 100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example -100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello -100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello +100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello ------------ 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). @@ -1321,7 +1327,7 @@ how git repositories at `kernel.org` are managed. Publishing the changes from your local (private) repository to your remote (public) repository requires a write privilege on the remote machine. You need to have an SSH account there to -run a single command, `git-receive-pack`. +run a single command, 'git-receive-pack'. First, you need to create an empty repository on the remote machine that will house your public repository. This empty @@ -1330,8 +1336,8 @@ into it later. Obviously, this repository creation needs to be done only once. [NOTE] -`git push` uses a pair of programs, -`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. @@ -1346,30 +1352,31 @@ $ 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: ------------ -$ GIT_DIR=my-git.git git-init +$ GIT_DIR=my-git.git git init ------------ Make sure this directory is available for others you want your -changes to be pulled by via the transport of your choice. Also -you need to make sure that you have the `git-receive-pack` +changes to be pulled via the transport of your choice. Also +you need to make sure that you have the 'git-receive-pack' program on the `$PATH`. [NOTE] Many installations of sshd do not invoke your shell as the login shell when you directly run programs; what this means is that if -your login shell is `bash`, only `.bashrc` is read and not +your login shell is 'bash', only `.bashrc` is read and not `.bash_profile`. As a workaround, make sure `.bashrc` sets up -`$PATH` so that you can run `git-receive-pack` program. +`$PATH` so that you can run 'git-receive-pack' program. [NOTE] If you plan to publish this repository to be accessed over http, -you should do `chmod +x my-git.git/hooks/post-update` at this -point. This makes sure that every time you push into this -repository, `git-update-server-info` is run. +you should do `mv my-git.git/hooks/post-update.sample +my-git.git/hooks/post-update` at this point. +This makes sure that every time you push into this +repository, `git update-server-info` is run. Your "public repository" is now ready to accept your changes. Come back to the machine you have your private repository. From @@ -1408,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-*.pack` and `pack-*.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 @@ -1421,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 ;-). @@ -1447,7 +1454,7 @@ public repository you might want to repack & prune often, or never. If you run `git repack` again at this point, it will say -"Nothing to pack". Once you continue your development and +"Nothing new to pack.". Once you continue your development and accumulate the changes, running `git repack` again will create a new pack, that contains objects created since you packed your repository the last time. We recommend that you pack your project @@ -1487,18 +1494,18 @@ A recommended workflow for a "project lead" goes like this: 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` copied from the standard templates -would contain a call to `git-update-server-info` but the -`post-update` hook itself is disabled by default -- enable it -with `chmod +x post-update`. This makes sure `git-update-server-info` -keeps the necessary files up-to-date. +`$GIT_DIR/hooks/post-update.sample` copied from the standard templates +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. 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. @@ -1512,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. @@ -1534,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. @@ -1551,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. @@ -1559,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 @@ -1589,7 +1596,7 @@ suggested in the previous section may be new to you. You do not have to worry. git supports "shared public repository" style of cooperation you are probably more familiar with as well. -See linkgit:gitcvs-migration[7][git for CVS users] for the details. +See linkgit:gitcvs-migration[7] for the details. Bundling your work together --------------------------- @@ -1656,7 +1663,7 @@ branch before these two merges by resetting it to 'master~2': $ git reset --hard master~2 ------------ -You can make sure 'git show-branch' matches the state before +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 branch heads (this is known as 'making an Octopus'): @@ -1690,8 +1697,11 @@ to follow, not easier. SEE ALSO -------- -linkgit:gittutorial[7], linkgit:gittutorial-2[7], -linkgit:giteveryday[7], linkgit:gitcvs-migration[7], +linkgit:gittutorial[7], +linkgit:gittutorial-2[7], +linkgit:gitcvs-migration[7], +linkgit:git-help[1], +link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] GIT diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt new file mode 100644 index 0000000000..7dfffc0046 --- /dev/null +++ b/Documentation/gitcredentials.txt @@ -0,0 +1,183 @@ +gitcredentials(7) +================= + +NAME +---- +gitcredentials - providing usernames and passwords to git + +SYNOPSIS +-------- +------------------ +git config credential.https://example.com.username myusername +git config credential.helper "$helper $options" +------------------ + +DESCRIPTION +----------- + +Git will sometimes need credentials from the user in order to perform +operations; for example, it may need to ask for a username and password +in order to access a remote repository over HTTP. This manual describes +the mechanisms git uses to request these credentials, as well as some +features to avoid inputting these credentials repeatedly. + +REQUESTING CREDENTIALS +---------------------- + +Without any credential helpers defined, git will try the following +strategies to ask the user for usernames and passwords: + +1. If the `GIT_ASKPASS` environment variable is set, the program + specified by the variable is invoked. A suitable prompt is provided + to the program on the command line, and the user's input is read + from its standard output. + +2. Otherwise, if the `core.askpass` configuration variable is set, its + value is used as above. + +3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its + value is used as above. + +4. Otherwise, the user is prompted on the terminal. + +AVOIDING REPETITION +------------------- + +It can be cumbersome to input the same credentials over and over. Git +provides two methods to reduce this annoyance: + +1. Static configuration of usernames for a given authentication context. + +2. Credential helpers to cache or store passwords, or to interact with + a system password wallet or keychain. + +The first is simple and appropriate if you do not have secure storage available +for a password. It is generally configured by adding this to your config: + +--------------------------------------- +[credential "https://example.com"] + username = me +--------------------------------------- + +Credential helpers, on the other hand, are external programs from which git can +request both usernames and passwords; they typically interface with secure +storage provided by the OS or other programs. + +To use a helper, you must first select one to use. Git currently +includes the following helpers: + +cache:: + + Cache credentials in memory for a short period of time. See + linkgit:git-credential-cache[1] for details. + +store:: + + Store credentials indefinitely on disk. See + linkgit:git-credential-store[1] for details. + +You may also have third-party helpers installed; search for +`credential-*` in the output of `git help -a`, and consult the +documentation of individual helpers. Once you have selected a helper, +you can tell git to use it by putting its name into the +credential.helper variable. + +1. Find a helper. ++ +------------------------------------------- +$ git help -a | grep credential- +credential-foo +------------------------------------------- + +2. Read its description. ++ +------------------------------------------- +$ git help credential-foo +------------------------------------------- + +3. Tell git to use it. ++ +------------------------------------------- +$ git config --global credential.helper foo +------------------------------------------- + +If there are multiple instances of the `credential.helper` configuration +variable, each helper will be tried in turn, and may provide a username, +password, or nothing. Once git has acquired both a username and a +password, no more helpers will be tried. + + +CREDENTIAL CONTEXTS +------------------- + +Git considers each credential to have a context defined by a URL. This context +is used to look up context-specific configuration, and is passed to any +helpers, which may use it as an index into secure storage. + +For instance, imagine we are accessing `https://example.com/foo.git`. When git +looks into a config file to see if a section matches this context, it will +consider the two a match if the context is a more-specific subset of the +pattern in the config file. For example, if you have this in your config file: + +-------------------------------------- +[credential "https://example.com"] + username = foo +-------------------------------------- + +then we will match: both protocols are the same, both hosts are the same, and +the "pattern" URL does not care about the path component at all. However, this +context would not match: + +-------------------------------------- +[credential "https://kernel.org"] + username = foo +-------------------------------------- + +because the hostnames differ. Nor would it match `foo.example.com`; git +compares hostnames exactly, without considering whether two hosts are part of +the same domain. Likewise, a config entry for `http://example.com` would not +match: git compares the protocols exactly. + + +CONFIGURATION OPTIONS +--------------------- + +Options for a credential context can be configured either in +`credential.*` (which applies to all credentials), or +`credential.<url>.*`, where <url> matches the context as described +above. + +The following options are available in either location: + +helper:: + + The name of an external credential helper, and any associated options. + If the helper name is not an absolute path, then the string `git + credential-` is prepended. The resulting string is executed by the + shell (so, for example, setting this to `foo --option=bar` will execute + `git credential-foo --option=bar` via the shell. See the manual of + specific helpers for examples of their use. + +username:: + + A default username, if one is not provided in the URL. + +useHttpPath:: + + By default, git does not consider the "path" component of an http URL + to be worth matching via external helpers. This means that a credential + stored for `https://example.com/foo.git` will also be used for + `https://example.com/bar.git`. If you do want to distinguish these + cases, set this option to `true`. + + +CUSTOM HELPERS +-------------- + +You can write your own custom helpers to interface with any system in +which you keep credentials. See the documentation for git's +link:technical/api-credentials.html[credentials API] for details. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt index 1db3f52945..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 ----------- @@ -18,9 +19,9 @@ important than any other. However, you can emulate the CVS model by designating a single shared repository which people can synchronize with; this document explains how to do that. -Some basic familiarity with git is required. This -linkgit:gittutorial[7][tutorial introduction to git] and the -linkgit:gitglossary[7][git glossary] should be sufficient. +Some basic familiarity with git is required. Having gone through +linkgit:gittutorial[7] and +linkgit:gitglossary[7] should be sufficient. Developing against a shared repository -------------------------------------- @@ -34,7 +35,7 @@ $ git clone foo.com:/pub/repo.git/ my-project $ cd my-project ------------------------------------------------ -and hack away. The equivalent of `cvs update` is +and hack away. The equivalent of 'cvs update' is ------------------------------------------------ $ git pull origin @@ -46,28 +47,28 @@ 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` +The 'pull' command knows where to get updates from because of certain +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 linkgit:git-push[1] 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: +in the local repository. So the last 'push' can be done with either of: ------------ $ git push origin @@ -81,8 +82,8 @@ Setting Up a Shared Repository ------------------------------ We assume you have already created a git repository for your project, -possibly created from scratch or from a tarball (see the -linkgit:gittutorial[7][tutorial]), or imported from an already existing CVS +possibly created from scratch or from a tarball (see +linkgit:gittutorial[7]), or imported from an already existing CVS repository (see the next section). Assume your existing repo is at /home/alice/myproject. Create a new "bare" @@ -143,12 +144,17 @@ work, you must not modify the imported branches; instead, create new branches for your own changes, and merge in the imported branches as necessary. +If you want a shared repository, you will need to make a bare clone +of the imported directory, as described above. Then treat the imported +directory as another development clone for purposes of merging +incremental imports. + Advanced Shared Repository Management ------------------------------------- Git allows you to specify scripts called "hooks" to be run at certain points. You can use these, for example, to send all commits to the shared -repository to a mailing list. See linkgit:githooks[5][Hooks used by git]. +repository to a mailing list. See linkgit:githooks[5]. You can enforce finer grained permissions using update hooks. See link:howto/update-hook-example.txt[Controlling access to branches using diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 4d56c85260..daf1782a31 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -3,44 +3,59 @@ gitdiffcore(7) NAME ---- -gitdiffcore - Tweaking diff output (June 2005) +gitdiffcore - Tweaking diff output SYNOPSIS -------- -git diff * +[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(1) output. The manipulation +unconventional ways before showing 'diff' output. The manipulation is collectively called "diffcore transformation". This short note -describes what they are and how to use them to produce diff outputs -that are easier to understand than the conventional kind. +describes what they are and how to use them to produce 'diff' output +that is easier to understand than the conventional kind. The chain of operation ---------------------- -The git-diff-* 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 compare -corresponding paths in the two sets of files. The result of -comparison is passed from these commands to what is internally -called "diffcore", in a format similar to what is output when -the -p option is not used. E.g. +In all of these cases, the commands themselves first optionally limit +the two sets of files by any pathspecs given on their command-lines, +and compare corresponding paths in the two resulting sets of files. + +The pathspecs are used to limit the world diff operates in. They remove +the filepairs outside the specified sets of pathnames. E.g. If the +input set of filepairs included: + +------------------------------------------------ +:100644 100644 bcd1234... 0123456... M junkfile +------------------------------------------------ + +but the command invocation was `git diff-files myfile`, then the +junkfile entry would be removed from the list because only "myfile" +is under consideration. + +The result of comparison is passed from these commands to what is +internally called "diffcore", in a format similar to what is output +when the -p option is not used. E.g. ------------------------------------------------ in-place edit :100644 100644 bcd1234... 0123456... M file0 @@ -52,53 +67,28 @@ unmerged :000000 000000 0000000... 0000000... U file6 The diffcore mechanism is fed a list of such comparison results (each of which is called "filepair", although at this point each of them talks about a single file), and transforms such a list -into another list. There are currently 6 such transformations: +into another list. There are currently 5 such transformations: -- diffcore-pathspec - diffcore-break - diffcore-rename - diffcore-merge-broken - diffcore-pickaxe - diffcore-order -These are applied in sequence. The set of filepairs git-diff-\* -commands find are used as the input to diffcore-pathspec, and -the output from diffcore-pathspec is used as the input to the +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-\* commands) or +format sections of the manual for 'git diff-{asterisk}' commands) or diff-patch format. -diffcore-pathspec: For Ignoring Files Outside Our Consideration ---------------------------------------------------------------- - -The first transformation in the chain is diffcore-pathspec, and -is controlled by giving the pathname parameters to the -git-diff-* commands on the command line. The pathspec is used -to limit the world diff operates in. It removes the filepairs -outside the specified set of pathnames. E.g. If the input set -of filepairs included: - ------------------------------------------------- -:100644 100644 bcd1234... 0123456... M junkfile ------------------------------------------------- - -but the command invocation was "git-diff-files myfile", then the -junkfile entry would be removed from the list because only "myfile" -is under consideration. - -Implementation note. For performance reasons, git-diff-tree -uses the pathname parameters on the command line to cull set of -filepairs it feeds the diffcore mechanism itself, and does not -use diffcore-pathspec, but the end result is the same. - - 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-* 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: @@ -134,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-* commands. If the +(to detect copies as well) to the 'git diff-{asterisk}' commands. If the input contained these filepairs: ------------------------------------------------ @@ -178,12 +168,12 @@ a similarity score different from the default of 50% by giving a 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-\* commands feed unmodified filepairs to +Note. When the "-C" option is used with `--find-copies-harder` +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-\* commands can detect copies only if the file that was +the expense of making it slower. Without `--find-copies-harder`, +'git diff-{asterisk}' commands can detect copies only if the file that was copied happened to have been modified in the same changeset. @@ -234,18 +224,18 @@ 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-* +-S option and the `--pickaxe-all` option to the 'git diff-*' 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 +When `--pickaxe-all` is not in effect, diffcore-pickaxe leaves only such filepairs that touch the specified string in its -output. When `\--pickaxe-all` is used, diffcore-pickaxe leaves all +output. When `--pickaxe-all` is used, diffcore-pickaxe leaves all filepairs intact if there is such a filepair, or makes the output empty otherwise. The latter behaviour is designed to make reviewing of the changes in the context of the whole @@ -257,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-* 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/gitglossary.txt b/Documentation/gitglossary.txt index 5c5c31d31c..d77a45aed6 100644 --- a/Documentation/gitglossary.txt +++ b/Documentation/gitglossary.txt @@ -16,8 +16,10 @@ include::glossary-content.txt[] SEE ALSO -------- -linkgit:gittutorial[7], linkgit:gittutorial-2[7], -linkgit:giteveryday[7], linkgit:gitcvs-migration[7], +linkgit:gittutorial[7], +linkgit:gittutorial-2[7], +linkgit:gitcvs-migration[7], +link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] GIT diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 4f06ae0ed4..b9003fed24 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -15,19 +15,27 @@ DESCRIPTION Hooks are little scripts you can place in `$GIT_DIR/hooks` directory to trigger action at certain points. When -`git-init` is run, a handful example hooks are copied in the +'git init' is run, a handful of example hooks are copied into the `hooks` directory of the new repository, but by default they are -all disabled. To enable a hook, make it executable with `chmod +x`. +all disabled. To enable a hook, rename it by removing its `.sample` +suffix. + +NOTE: It is also a requirement for a given hook to be executable. +However - in a freshly initialized repository - the `.sample` files are +executable by default. This document describes the currently defined hooks. +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 @@ -38,9 +46,9 @@ The default 'applypatch-msg' hook, when enabled, runs the 'commit-msg' hook, if the latter is enabled. 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 @@ -53,50 +61,50 @@ The default 'pre-applypatch' hook, when enabled, runs the 'pre-commit' hook, if the latter is enabled. 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 -with `\--no-verify` option. It takes no parameter, and is +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 -that the commit log message. The second is the source of the commit -message, and can be: `message` (if a `\-m` or `\-F` option was -given); `template` (if a `\-t` option was given or the +that contains the commit log message. The second is the source of the commit +message, and can be: `message` (if a `-m` or `-F` option was +given); `template` (if a `-t` option was given or the configuration option `commit.template` is set); `merge` (if the 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). +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 +it is not suppressed by the `--no-verify` option. A non-zero exit means a failure of the hook and aborts the commit. It should not be used as replacement for pre-commit hook. @@ -104,12 +112,12 @@ The sample `prepare-commit-msg` hook that comes with git comments out the `Conflicts:` part of a merge's commit message. commit-msg ----------- +~~~~~~~~~~ -This hook is invoked by `git-commit`, and can be bypassed -with `\--no-verify` option. It takes a single parameter, the +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 @@ -121,35 +129,46 @@ The default 'commit-msg' hook, when enabled, detects duplicate "Signed-off-by" lines, and aborts the commit if one is found. 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 +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 +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. This hook can be used to perform repository validity checks, auto-display differences from the previous HEAD if different, or set working dir metadata 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 @@ -159,10 +178,10 @@ for an example of how to do this. [[pre-receive]] 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. +This hook is invoked by 'git-receive-pack' on the remote 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. @@ -183,15 +202,15 @@ 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]] 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. +This hook is invoked by 'git-receive-pack' on the remote 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. @@ -204,13 +223,13 @@ three parameters: - and the new objectname to be stored in the ref. A zero exit from the update hook allows the ref to be updated. -Exiting with a non-zero status prevents `git-receive-pack` +Exiting with a non-zero status prevents 'git-receive-pack' from updating that ref. This hook can be used to prevent 'forced' update on certain refs by making sure that the object name is a commit object that is a descendant of the commit object named by the old object name. -That is, to enforce a "fast forward only" policy. +That is, to enforce a "fast-forward only" policy. It could also be used to log the old..new status. However, it does not know the entire set of branches, so it would end up @@ -222,19 +241,19 @@ 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 -`hooks.allowunannotated` config option turned on--prevents +`hooks.allowunannotated` config option unset or set to false--prevents unannotated tags to be pushed. [[post-receive]] 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. +This hook is invoked by 'git-receive-pack' on the remote 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. @@ -243,7 +262,7 @@ arguments, but gets the same information as the <<pre-receive,'pre-receive'>> hook does on its standard input. -This hook does not affect the outcome of `git-receive-pack`, as it +This hook does not affect the outcome of 'git-receive-pack', as it is called after the real work is done. This supersedes the <<post-update,'post-update'>> hook in that it gets @@ -251,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 @@ -261,10 +280,10 @@ emails. [[post-update]] 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. +This hook is invoked by 'git-receive-pack' on the remote 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. @@ -272,7 +291,7 @@ It takes a variable number of parameters, each of which is the name of ref that was actually updated. This hook is meant primarily for notification, and cannot affect -the outcome of `git-receive-pack`. +the outcome of 'git-receive-pack'. The 'post-update' hook can tell what are the heads that were pushed, but it does not know what their original and updated values are, @@ -282,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 2881c9cb92..2e7328b830 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -13,9 +13,11 @@ DESCRIPTION ----------- A `gitignore` file specifies intentionally untracked files that -git should ignore. Each line in a `gitignore` file specifies a -pattern. +git should ignore. +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 `gitignore` patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of @@ -26,8 +28,8 @@ precedence, the last matching pattern decides the outcome): * Patterns read from a `.gitignore` file in the same directory as the path, or in any parent directory, with patterns in the - higher level files (up to the root) being overridden by those in - lower level files down to the directory containing the file. + higher level files (up to the toplevel of the work tree) being overridden + by those in lower level files down to the directory containing the file. These patterns match relative to the location of the `.gitignore` file. A project normally includes such `.gitignore` files in its repository, containing patterns for @@ -51,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 -linkgit:git-ls-files[1] and linkgit:git-read-tree[1], 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 linkgit:git-status[1] and linkgit:git-add[1], +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. @@ -78,21 +81,38 @@ 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 + $ git status [...] # Untracked files: [...] @@ -110,7 +130,7 @@ An example: *.html # except foo.html which is maintained by hand !foo.html - $ git-status + $ git status [...] # Untracked files: [...] @@ -131,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 f843f39bf2..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 @@ -21,8 +22,9 @@ git repository. OPTIONS ------- -To control which revisions to shown, the command takes options applicable to -the linkgit:git-rev-list[1] command. This manual page describes only the most +To control which revisions to show, the command takes options applicable to +the 'git rev-list' command (see linkgit:git-rev-list[1]). +This manual page describes only the most frequently used options. -n <number>:: @@ -46,7 +48,20 @@ frequently used options. After an attempt to merge stops with conflicts, show the commits on the history between two branches (i.e. the HEAD and the MERGE_HEAD) - that modify the conflicted files. + that modify the conflicted files and do not exist on all the heads + being merged. + +--argscmd=<command>:: + Command to be run each time gitk has to determine the list of + <revs> to show. The command is expected to print on its standard + output a list of additional revs to be shown, one per line. + Use this instead of explicitly specifying <revs> if the set of + commits to show may vary between refreshes. + +--select-commit=<ref>:: + + Automatically select the specified commit after loading the graph. + Default behavior is equivalent to specifying '--select-commit=HEAD'. <revs>:: @@ -55,19 +70,19 @@ 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>:: +<path>...:: Limit commits to the ones touching files in the given paths. Note, to - avoid ambiguity wrt. revision names use "--" to separate the paths + avoid ambiguity with respect to revision names use "--" to separate the paths from any preceding options. Examples -------- gitk v2.6.12.. include/scsi drivers/scsi:: - Show as the changes since version 'v2.6.12' that changed any + Show the changes since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories gitk --since="2 weeks ago" \-- gitk:: @@ -99,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 f8d122a8b9..4effd78902 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -7,7 +7,7 @@ gitmodules - defining submodule properties SYNOPSIS -------- -gitmodules +$GIT_WORK_DIR/.gitmodules DESCRIPTION @@ -28,7 +28,47 @@ submodule.<name>.path:: be unique within the .gitmodules file. submodule.<name>.url:: - Defines an url from where the submodule repository can be cloned. + Defines a URL from which 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. + If 'checkout' (the default), the new commit specified in the + superproject will be checked out in the submodule on a detached HEAD. + If 'rebase', the current branch of the submodule will be rebased onto + the commit specified in the superproject. If 'merge', the commit + specified in the superproject will be merged into the current branch + in the submodule. + If 'none', the submodule with name `$name` will not be updated + by default. + + This config option is overridden if 'git submodule update' is given + the '--merge', '--rebase' or '--checkout' 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 @@ -47,16 +87,12 @@ Consider the following .gitmodules file: This defines two submodules, `libfoo` and `libbar`. These are expected to be checked out in the paths 'include/foo' and 'include/bar', and for both -submodules an url is specified which can be used for cloning the submodules. +submodules a URL is specified which can be used for cloning the submodules. 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 03c52ff526..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,23 +112,25 @@ 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 - default. To enable, they need to be made executable. - Read linkgit:githooks[5][hooks] for more details about + '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 each hook. index:: @@ -150,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:: @@ -167,18 +162,20 @@ 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 - directory. See the documentation on git-update-ref + directory. See linkgit:git-update-ref[1] for more information. logs/refs/heads/`name`:: 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 e3d5c1fbf0..e00a4d2170 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -7,13 +7,13 @@ gittutorial-2 - A tutorial introduction to git: part two SYNOPSIS -------- +[verse] git * DESCRIPTION ----------- -You should work through linkgit:gittutorial[7][A tutorial introduction to -git] before reading this tutorial. +You should work through linkgit:gittutorial[7] before reading this tutorial. The goal of this tutorial is to introduce two fundamental pieces of git's architecture--the object database and the index file--and to @@ -33,37 +33,42 @@ Initialized empty Git repository in .git/ $ echo 'hello world' > file.txt $ git add . $ git commit -a -m "initial commit" -Created initial commit 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 +[master (root-commit) 54196cc] initial commit + 1 file changed, 1 insertion(+) create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" -Created commit c4d59f390b9cfd4318117afde11d601c1085f241 +[master c4d59f3] add emphasis + 1 file changed, 1 insertion(+), 1 deletion(-) ------------------------------------------------ -What are the 40 digits of hex that git responded to the commit with? +What are the 7 digits of hex that git responded to the commit with? We saw in part one of the tutorial that commits have names like this. It turns out that every object in the git history is stored under -such a 40-digit hex name. That name is the SHA1 hash of the object's +a 40-digit hex name. That name is the SHA1 hash of the object's contents; among other things, this ensures that git will never store the same data twice (since identical data is given an identical SHA1 name), and that the contents of a git object will never change (since -that would change the object's name as well). +that would change the object's name as well). The 7 char hex strings +here are simply the abbreviation of such 40 character long strings. +Abbreviations can be used everywhere where the 40 character strings +can be used, so long as they are unambiguous. It is expected that the content of the commit object you created while following the example above generates a different SHA1 hash than the one shown above because the commit object records the time when it was created and the name of the person performing the commit. -We can ask git about this particular object with the cat-file +We can ask git about this particular object with the `cat-file` command. Don't copy the 40 hex digits from this example but use those from your own version. Note that you can shorten it to only a few characters to save yourself typing all 40 hex digits: ------------------------------------------------ -$ git-cat-file -t 54196cc2 +$ git cat-file -t 54196cc2 commit -$ git-cat-file commit 54196cc2 +$ git cat-file commit 54196cc2 tree 92b8b694ffb1675e5975148e1121810081dbdffe author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 @@ -166,7 +171,7 @@ hello world! and the "parent" object refers to the previous commit: ------------------------------------------------ -$ git-cat-file commit 54196cc2 +$ git cat-file commit 54196cc2 tree 92b8b694ffb1675e5975148e1121810081dbdffe author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 @@ -213,8 +218,8 @@ designate such an argument. The index file -------------- -The primary tool we've been using to create commits is "git commit --a", which creates a commit including every change you've made to +The primary tool we've been using to create commits is `git-commit +-a`, which creates a commit including every change you've made to your working tree. But what if you want to commit changes only to certain files? Or only certain changes to certain files? @@ -246,7 +251,7 @@ The last diff is empty, but no new commits have been made, and the head still doesn't contain the new line: ------------------------------------------------ -$ git-diff HEAD +$ git diff HEAD diff --git a/file.txt b/file.txt index a042389..513feba 100644 --- a/file.txt @@ -256,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: @@ -271,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: ------------------------------------------------ @@ -288,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: @@ -312,8 +317,8 @@ index a042389..513feba 100644 +hello world, again ------------------------------------------------ -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 +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: @@ -330,11 +335,11 @@ index 513feba..ba3da7b 100644 +again? ------------------------------------------------ -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 +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: ------------------------------------------------ @@ -342,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 @@ -369,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 @@ -383,14 +388,14 @@ it is marked "changed but not updated". At this point, running "git commit" would create a commit that added closing.txt (with its new contents), but that didn't modify file.txt. -Also, note that a bare "git diff" shows the changes to file.txt, but +Also, note that a bare `git diff` shows the changes to file.txt, but not the addition of closing.txt, because the version of closing.txt in the index file is identical to the one in the working directory. In addition to being the staging area for new commits, the index file is also populated from the object database when checking out a branch, and is used to hold the trees involved in a merge operation. -See the linkgit:gitcore-tutorial[7][core tutorial] and the relevant man +See linkgit:gitcore-tutorial[7] and the relevant man pages for details. What next? @@ -399,20 +404,19 @@ What next? At this point you should know everything necessary to read the man pages for any of the git commands; one good place to start would be with the commands mentioned in link:everyday.html[Everyday git]. You -should be able to find any unknown jargon in the -linkgit:gitglossary[7][Glossary]. +should be able to find any unknown jargon in linkgit:gitglossary[7]. The link:user-manual.html[Git User's Manual] provides a more comprehensive introduction to git. -The linkgit:gitcvs-migration[7][CVS migration] document explains how to +linkgit:gitcvs-migration[7] explains how to import a CVS repository into git, and shows how to use git in a CVS-like way. For some interesting examples of git use, see the link:howto-index.html[howtos]. -For git developers, the linkgit:gitcore-tutorial[7][Core tutorial] goes +For git developers, linkgit:gitcore-tutorial[7] goes into detail on the lower-level git mechanisms involved in, for example, creating a new commit. @@ -422,6 +426,7 @@ linkgit:gittutorial[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], +linkgit:git-help[1], link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index d465aab64e..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 @@ -19,13 +20,22 @@ If you are instead primarily interested in using git to fetch a project, for example, to test the latest version, you may prefer to start with the first two chapters of link:user-manual.html[The Git User's Manual]. -First, note that you can get documentation for a command such as "git -diff" with: +First, note that you can get documentation for a command such as +`git log --graph` with: ------------------------------------------------ -$ man git-diff +$ man git-log ------------------------------------------------ +or: + +------------------------------------------------ +$ git help log +------------------------------------------------ + +With the latter, you can use the manual viewer of your choice; see +linkgit:git-help[1] for more information. + It is a good idea to introduce yourself to git with your name and public email address before doing any operation. The easiest way to do so is: @@ -58,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 linkgit:git-add[1]: +current directory (note the '.'), with 'git add': ------------------------------------------------ $ git add . @@ -66,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 linkgit:git-commit[1]: +repository with 'git commit': ------------------------------------------------ $ git commit @@ -85,15 +95,15 @@ $ git add file1 file2 file3 ------------------------------------------------ You are now ready to commit. You can see what is about to be committed -using linkgit:git-diff[1] with the --cached option: +using 'git diff' with the --cached option: ------------------------------------------------ $ git diff --cached ------------------------------------------------ -(Without --cached, linkgit:git-diff[1] 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 linkgit:git-status[1]: +summary of the situation with 'git status': ------------------------------------------------ $ git status @@ -117,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 @@ -136,9 +146,9 @@ commit in the body. 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 +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 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. @@ -274,7 +284,7 @@ same machine, wants to contribute. Bob begins with: ------------------------------------------------ -$ git clone /home/alice/project myrepo +bob$ git clone /home/alice/project myrepo ------------------------------------------------ This creates a new directory "myrepo" containing a clone of Alice's @@ -285,7 +295,7 @@ Bob then makes some changes and commits them: ------------------------------------------------ (edit files) -$ git commit -a +bob$ git commit -a (repeat as necessary) ------------------------------------------------ @@ -293,43 +303,94 @@ When he's ready, he tells Alice to pull changes from the repository at /home/bob/myrepo. She does this with: ------------------------------------------------ -$ cd /home/alice/project -$ git pull /home/bob/myrepo master +alice$ cd /home/alice/project +alice$ git pull /home/bob/myrepo master ------------------------------------------------ This merges the changes from Bob's "master" branch into Alice's current branch. If Alice has made her own changes in the meantime, -then she may need to manually fix any conflicts. (Note that the -"master" argument in the above command is actually unnecessary, as it -is the default.) +then she may need to manually fix any conflicts. The "pull" command thus performs two operations: it fetches changes from a remote branch, then merges them into the current branch. +Note that in general, Alice would want her local changes committed before +initiating this "pull". If Bob's work conflicts with what Alice did since +their histories forked, Alice will use her working tree and the index to +resolve conflicts, and existing local changes will interfere with the +conflict resolution process (git will still perform the fetch but will +refuse to merge --- Alice will have to get rid of her local changes in +some way and pull again when this happens). + +Alice can peek at what Bob did without merging first, using the "fetch" +command; this allows Alice to inspect what Bob did, using a special +symbol "FETCH_HEAD", in order to determine if he has anything worth +pulling, like this: + +------------------------------------------------ +alice$ git fetch /home/bob/myrepo master +alice$ git log -p HEAD..FETCH_HEAD +------------------------------------------------ + +This operation is safe even if Alice has uncommitted local changes. +The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable +from the FETCH_HEAD but exclude anything that is reachable from HEAD". +Alice already knows everything that leads to her current state (HEAD), +and reviews what Bob has in his state (FETCH_HEAD) that she has not +seen with this command. + +If Alice wants to visualize what Bob did since their histories forked +she can issue the following command: + +------------------------------------------------ +$ gitk HEAD..FETCH_HEAD +------------------------------------------------ + +This uses the same two-dot range notation we saw earlier with 'git log'. + +Alice may want to view what both of them did since they forked. +She can use three-dot form instead of the two-dot form: + +------------------------------------------------ +$ gitk HEAD...FETCH_HEAD +------------------------------------------------ + +This means "show everything that is reachable from either one, but +exclude anything that is reachable from both of them". + +Please note that these range notation can be used with both gitk +and "git log". + +After inspecting what Bob did, if there is nothing urgent, Alice may +decide to continue working without pulling from Bob. If Bob's history +does have something Alice would immediately need, Alice may choose to +stash her work-in-progress first, do a "pull", and then finally unstash +her work-in-progress on top of the resulting history. + When you are working in a small closely knit group, it is not unusual to interact with the same repository over and over again. By defining 'remote' repository shorthand, you can make it easier: ------------------------------------------------ -$ git remote add bob /home/bob/myrepo +alice$ git remote add bob /home/bob/myrepo ------------------------------------------------ -With this, Alice can perform the first operation alone using the -"git fetch" command without merging them with her own branch, -using: +With this, Alice can perform the first part of the "pull" operation +alone using the 'git fetch' command without merging them with her own +branch, using: ------------------------------------- -$ git fetch bob +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: ------------------------------------- -$ git log -p master..bob/master +alice$ git log -p master..bob/master ------------------------------------- shows a list of all the changes that Bob made since he branched from @@ -339,14 +400,14 @@ After examining those changes, Alice could merge the changes into her master branch: ------------------------------------- -$ git merge bob/master +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: ------------------------------------- -$ git pull . remotes/bob/master +alice$ git pull . remotes/bob/master ------------------------------------- Note that git pull always merges into the current branch, @@ -355,7 +416,7 @@ regardless of what else is given on the command line. Later, Bob can update his repo with Alice's latest changes using ------------------------------------- -$ git pull +bob$ git pull ------------------------------------- Note that he doesn't need to give the path to Alice's repository; @@ -364,19 +425,19 @@ repository in the repository configuration, and that location is used for pulls: ------------------------------------- -$ git config --get remote.origin.url +bob$ git config --get remote.origin.url /home/alice/project ------------------------------------- -(The complete configuration created by git-clone is visible using -"git config -l", and the linkgit:git-config[1] man page +(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.) Git also keeps a pristine copy of Alice's master branch under the name "origin/master": ------------------------------------- -$ git branch -r +bob$ git branch -r origin/master ------------------------------------- @@ -384,7 +445,7 @@ If Bob later decides to work from a different host, he can still perform clones and pulls using the ssh protocol: ------------------------------------- -$ git clone alice.org:/home/alice/project myrepo +bob$ git clone alice.org:/home/alice/project myrepo ------------------------------------- Alternatively, git has a native protocol, or can use rsync or http; @@ -392,13 +453,13 @@ see linkgit:git-pull[1] for details. Git can also be used in a CVS-like mode, with a central repository that various users push changes to; see linkgit:git-push[1] and -linkgit:gitcvs-migration[7][git for CVS users]. +linkgit:gitcvs-migration[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: @@ -411,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. ------------------------------------- @@ -447,7 +508,7 @@ $ git show HEAD^2 # show the second parent of HEAD You can also give commits names of your own; after running ------------------------------------- -$ git-tag v2.5 1b2e1d63ff +$ git tag v2.5 1b2e1d63ff ------------------------------------- you can refer to 1b2e1d63ff by the name "v2.5". If you intend to @@ -469,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 linkgit:git-revert[1] +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 ------------------------------------- @@ -484,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 ------------------------------------- @@ -494,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 @@ -504,32 +565,32 @@ $ 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-release" and "master" diverged from a common +the branches "stable" and "master" diverged from a common commit some time ago, then ------------------------------------- -$ git log stable..experimental +$ git log stable..master ------------------------------------- -will list commits made in the experimental branch but not in the +will list commits made in the master branch but not in the stable branch, while ------------------------------------- -$ git log experimental..stable +$ git log master..stable ------------------------------------- will show the list of commits made on the stable branch but not -the experimental branch. +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, -or git itself) have frequent merges, and gitk does a better job of +Most projects with multiple contributors (such as the Linux kernel, +or git itself) have frequent merges, and 'gitk' does a better job of visualizing their history. For example, ------------------------------------- @@ -549,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 @@ -571,16 +632,16 @@ is based: used to create commits, check out working directories, and hold the various trees involved in a merge. -linkgit:gittutorial-2[7][Part two of this tutorial] explains the object +Part two of this tutorial explains the object database, the index file, and a few other odds and ends that you'll -need to make the most of git. +need to make the most of git. You can find it at linkgit:gittutorial-2[7]. If you don't want to continue with that right away, a few other digressions that may be interesting at this point are: * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert series of git commits into emailed patches, and vice versa, - useful for projects such as the linux kernel which rely heavily + useful for projects such as the Linux kernel which rely heavily on emailed patches. * linkgit:git-bisect[1]: When there is a regression in your @@ -590,9 +651,12 @@ digressions that may be interesting at this point are: smart enough to perform a close-to-optimal search even in the case of complex non-linear history with lots of merged branches. + * linkgit:gitworkflows[7]: Gives an overview of recommended + workflows. + * link:everyday.html[Everyday GIT with 20 Commands Or So] - * linkgit:gitcvs-migration[7][git for CVS users]. + * linkgit:gitcvs-migration[7]: Git for CVS users. SEE ALSO -------- @@ -600,6 +664,8 @@ linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], +linkgit:git-help[1], +linkgit:gitworkflows[7], link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt new file mode 100644 index 0000000000..b9dd56753a --- /dev/null +++ b/Documentation/gitweb.conf.txt @@ -0,0 +1,896 @@ +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. + +$omit_age_column:: + If true, omit the column with date of the most current commit on the + projects list page. It can save a bit of I/O and a fork per repository. + +$omit_owner:: + If true prevents displaying information about repository owner. + +$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..168e8bfed6 --- /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. Its 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 the repository in gitweb is the path to its `$GIT_DIR` (its 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 new file mode 100644 index 0000000000..8b8c6ae5d3 --- /dev/null +++ b/Documentation/gitworkflows.txt @@ -0,0 +1,480 @@ +gitworkflows(7) +=============== + +NAME +---- +gitworkflows - An overview of recommended workflows with git + +SYNOPSIS +-------- +[verse] +git * + + +DESCRIPTION +----------- + +This document attempts to write down and motivate some of the workflow +elements used for `git.git` itself. Many ideas apply in general, +though the full workflow is rarely required for smaller projects with +fewer people involved. + +We formulate a set of 'rules' for quick reference, while the prose +tries to motivate each of them. Do not always take them literally; +you should value good reasons for your actions higher than manpages +such as this one. + + +SEPARATE CHANGES +---------------- + +As a general rule, you should try to split your changes into small +logical steps, and commit each of them. They should be consistent, +working independently of any later commits, pass the test suite, etc. +This makes the review process much easier, and the history much more +useful for later inspection and analysis, for example with +linkgit:git-blame[1] and linkgit:git-bisect[1]. + +To achieve this, try to split your work into small steps from the very +beginning. It is always easier to squash a few commits together than +to split one big commit into several. Don't be afraid of making too +small or imperfect steps along the way. You can always go back later +and edit the commits with `git rebase --interactive` before you +publish them. You can use `git stash save --keep-index` to run the +test suite independent of other uncommitted changes; see the EXAMPLES +section of linkgit:git-stash[1]. + + +MANAGING BRANCHES +----------------- + +There are two main tools that can be used to include changes from one +branch on another: linkgit:git-merge[1] and +linkgit:git-cherry-pick[1]. + +Merges have many advantages, so we try to solve as many problems as +possible with merges alone. Cherry-picking is still occasionally +useful; see "Merging upwards" below for an example. + +Most importantly, merging works at the branch level, while +cherry-picking works at the commit level. This means that a merge can +carry over the changes from 1, 10, or 1000 commits with equal ease, +which in turn means the workflow scales much better to a large number +of contributors (and contributions). Merges are also easier to +understand because a merge commit is a "promise" that all changes from +all its parents are now included. + +There is a tradeoff of course: merges require a more careful branch +management. The following subsections discuss the important points. + + +Graduation +~~~~~~~~~~ + +As a given feature goes from experimental to stable, it also +"graduates" between the corresponding branches of the software. +`git.git` uses the following 'integration branches': + +* 'maint' tracks the commits that should go into the next "maintenance + release", i.e., update of the last released stable version; + +* 'master' tracks the commits that should go into the next release; + +* 'next' is intended as a testing branch for topics being tested for + stability for master. + +There is a fourth official branch that is used slightly differently: + +* 'pu' (proposed updates) is an integration branch for things that are + not quite ready for inclusion yet (see "Integration Branches" + below). + +Each of the four branches is usually a direct descendant of the one +above it. + +Conceptually, the feature enters at an unstable branch (usually 'next' +or 'pu'), and "graduates" to 'master' for the next release once it is +considered stable enough. + + +Merging upwards +~~~~~~~~~~~~~~~ + +The "downwards graduation" discussed above cannot be done by actually +merging downwards, however, since that would merge 'all' changes on +the unstable branch into the stable one. Hence the following: + +.Merge upwards +[caption="Rule: "] +===================================== +Always commit your fixes to the oldest supported branch that require +them. Then (periodically) merge the integration branches upwards into each +other. +===================================== + +This gives a very controlled flow of fixes. If you notice that you +have applied a fix to e.g. 'master' that is also required in 'maint', +you will need to cherry-pick it (using linkgit:git-cherry-pick[1]) +downwards. This will happen a few times and is nothing to worry about +unless you do it very frequently. + + +Topic branches +~~~~~~~~~~~~~~ + +Any nontrivial feature will require several patches to implement, and +may get extra bugfixes or improvements during its lifetime. + +Committing everything directly on the integration branches leads to many +problems: Bad commits cannot be undone, so they must be reverted one +by one, which creates confusing histories and further error potential +when you forget to revert part of a group of changes. Working in +parallel mixes up the changes, creating further confusion. + +Use of "topic branches" solves these problems. The name is pretty +self explanatory, with a caveat that comes from the "merge upwards" +rule above: + +.Topic branches +[caption="Rule: "] +===================================== +Make a side branch for every topic (feature, bugfix, ...). Fork it off +at the oldest integration branch that you will eventually want to merge it +into. +===================================== + +Many things can then be done very naturally: + +* To get the feature/bugfix into an integration branch, simply merge + it. If the topic has evolved further in the meantime, merge again. + (Note that you do not necessarily have to merge it to the oldest + integration branch first. For example, you can first merge a bugfix + to 'next', give it some testing time, and merge to 'maint' when you + know it is stable.) + +* If you find you need new features from the branch 'other' to continue + working on your topic, merge 'other' to 'topic'. (However, do not + do this "just habitually", see below.) + +* If you find you forked off the wrong branch and want to move it + "back in time", use linkgit:git-rebase[1]. + +Note that the last point clashes with the other two: a topic that has +been merged elsewhere should not be rebased. See the section on +RECOVERING FROM UPSTREAM REBASE in linkgit:git-rebase[1]. + +We should point out that "habitually" (regularly for no real reason) +merging an integration branch into your topics -- and by extension, +merging anything upstream into anything downstream on a regular basis +-- is frowned upon: + +.Merge to downstream only at well-defined points +[caption="Rule: "] +===================================== +Do not merge to downstream except with a good reason: upstream API +changes affect your branch; your branch no longer merges to upstream +cleanly; etc. +===================================== + +Otherwise, the topic that was merged to suddenly contains more than a +single (well-separated) change. The many resulting small merges will +greatly clutter up history. Anyone who later investigates the history +of a file will have to find out whether that merge affected the topic +in development. An upstream might even inadvertently be merged into a +"more stable" branch. And so on. + + +Throw-away integration +~~~~~~~~~~~~~~~~~~~~~~ + +If you followed the last paragraph, you will now have many small topic +branches, and occasionally wonder how they interact. Perhaps the +result of merging them does not even work? But on the other hand, we +want to avoid merging them anywhere "stable" because such merges +cannot easily be undone. + +The solution, of course, is to make a merge that we can undo: merge +into a throw-away branch. + +.Throw-away integration branches +[caption="Rule: "] +===================================== +To test the interaction of several topics, merge them into a +throw-away branch. You must never base any work on such a branch! +===================================== + +If you make it (very) clear that this branch is going to be deleted +right after the testing, you can even publish this branch, for example +to give the testers a chance to work with it, or other developers a +chance to see if their in-progress work will be compatible. `git.git` +has such an official throw-away integration branch called 'pu'. + + +Branch management for a release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assuming you are using the merge approach discussed above, when you +are releasing your project you will need to do some additional branch +management work. + +A feature release is created from the 'master' branch, since 'master' +tracks the commits that should go into the next feature release. + +The 'master' branch is supposed to be a superset of 'maint'. If this +condition does not hold, then 'maint' contains some commits that +are not included on 'master'. The fixes represented by those commits +will therefore not be included in your feature release. + +To verify that 'master' is indeed a superset of 'maint', use git log: + +.Verify 'master' is a superset of 'maint' +[caption="Recipe: "] +===================================== +`git log master..maint` +===================================== + +This command should not list any commits. Otherwise, check out +'master' and merge 'maint' into it. + +Now you can proceed with the creation of the feature release. Apply a +tag to the tip of 'master' indicating the release version: + +.Release tagging +[caption="Recipe: "] +===================================== +`git tag -s -m "GIT X.Y.Z" vX.Y.Z master` +===================================== + +You need to push the new tag to a public git server (see +"DISTRIBUTED WORKFLOWS" below). This makes the tag available to +others tracking your project. The push could also trigger a +post-update hook to perform release-related items such as building +release tarballs and preformatted documentation pages. + +Similarly, for a maintenance release, 'maint' is tracking the commits +to be released. Therefore, in the steps above simply tag and push +'maint' rather than 'master'. + + +Maintenance branch management after a feature release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After a feature release, you need to manage your maintenance branches. + +First, if you wish to continue to release maintenance fixes for the +feature release made before the recent one, then you must create +another branch to track commits for that previous release. + +To do this, the current maintenance branch is copied to another branch +named with the previous release version number (e.g. maint-X.Y.(Z-1) +where X.Y.Z is the current release). + +.Copy maint +[caption="Recipe: "] +===================================== +`git branch maint-X.Y.(Z-1) maint` +===================================== + +The 'maint' branch should now be fast-forwarded to the newly released +code so that maintenance fixes can be tracked for the current release: + +.Update maint to new release +[caption="Recipe: "] +===================================== +* `git checkout maint` +* `git merge --ff-only master` +===================================== + +If the merge fails because it is not a fast-forward, then it is +possible some fixes on 'maint' were missed in the feature release. +This will not happen if the content of the branches was verified as +described in the previous section. + + +Branch management for next and pu after a feature release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After a feature release, the integration branch 'next' may optionally be +rewound and rebuilt from the tip of 'master' using the surviving +topics on 'next': + +.Rewind and rebuild next +[caption="Recipe: "] +===================================== +* `git checkout next` +* `git reset --hard master` +* `git merge ai/topic_in_next1` +* `git merge ai/topic_in_next2` +* ... +===================================== + +The advantage of doing this is that the history of 'next' will be +clean. For example, some topics merged into 'next' may have initially +looked promising, but were later found to be undesirable or premature. +In such a case, the topic is reverted out of 'next' but the fact +remains in the history that it was once merged and reverted. By +recreating 'next', you give another incarnation of such topics a clean +slate to retry, and a feature release is a good point in history to do +so. + +If you do this, then you should make a public announcement indicating +that 'next' was rewound and rebuilt. + +The same rewind and rebuild process may be followed for 'pu'. A public +announcement is not necessary since 'pu' is a throw-away branch, as +described above. + + +DISTRIBUTED WORKFLOWS +--------------------- + +After the last section, you should know how to manage topics. In +general, you will not be the only person working on the project, so +you will have to share your work. + +Roughly speaking, there are two important workflows: merge and patch. +The important difference is that the merge workflow can propagate full +history, including merges, while patches cannot. Both workflows can +be used in parallel: in `git.git`, only subsystem maintainers use +the merge workflow, while everyone else sends patches. + +Note that the maintainer(s) may impose restrictions, such as +"Signed-off-by" requirements, that all commits/patches submitted for +inclusion must adhere to. Consult your project's documentation for +more information. + + +Merge workflow +~~~~~~~~~~~~~~ + +The merge workflow works by copying branches between upstream and +downstream. Upstream can merge contributions into the official +history; downstream base their work on the official history. + +There are three main tools that can be used for this: + +* linkgit:git-push[1] copies your branches to a remote repository, + usually to one that can be read by all involved parties; + +* linkgit:git-fetch[1] that copies remote branches to your repository; + and + +* 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 +to merge the remote branch. + +Getting changes out is easy: + +.Push/pull: Publishing branches/topics +[caption="Recipe: "] +===================================== +`git push <remote> <branch>` and tell everyone where they can fetch +from. +===================================== + +You will still have to tell people by other means, such as mail. (Git +provides the linkgit:git-request-pull[1] to send preformatted pull +requests to upstream maintainers to simplify this task.) + +If you just want to get the newest copies of the integration branches, +staying up to date is easy too: + +.Push/pull: Staying up to date +[caption="Recipe: "] +===================================== +Use `git fetch <remote>` or `git remote update` to stay up to date. +===================================== + +Then simply fork your topic branches from the stable remotes as +explained earlier. + +If you are a maintainer and would like to merge other people's topic +branches to the integration branches, they will typically send a +request to do so by mail. Such a request looks like + +------------------------------------- +Please pull from + <url> <branch> +------------------------------------- + +In that case, 'git pull' can do the fetch and merge in one go, as +follows. + +.Push/pull: Merging remote topics +[caption="Recipe: "] +===================================== +`git pull <url> <branch>` +===================================== + +Occasionally, the maintainer may get merge conflicts when he tries to +pull changes from downstream. In this case, he can ask downstream to +do the merge and resolve the conflicts themselves (perhaps they will +know better how to resolve them). It is one of the rare cases where +downstream 'should' merge from upstream. + + +Patch workflow +~~~~~~~~~~~~~~ + +If you are a contributor that sends changes upstream in the form of +emails, you should use topic branches as usual (see above). Then use +linkgit:git-format-patch[1] to generate the corresponding emails +(highly recommended over manually formatting them because it makes the +maintainer's life easier). + +.format-patch/am: Publishing branches/topics +[caption="Recipe: "] +===================================== +* `git format-patch -M upstream..topic` to turn them into preformatted + patch files +* `git send-email --to=<recipient> <patches>` +===================================== + +See the linkgit:git-format-patch[1] and linkgit:git-send-email[1] +manpages for further usage notes. + +If the maintainer tells you that your patch no longer applies to the +current upstream, you will have to rebase your topic (you cannot use a +merge because you cannot format-patch merges): + +.format-patch/am: Keeping topics up to date +[caption="Recipe: "] +===================================== +`git pull --rebase <url> <branch>` +===================================== + +You can then fix the conflicts during the rebase. Presumably you have +not published your topic other than by mail, so rebasing it is not a +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: + +.format-patch/am: Importing patches +[caption="Recipe: "] +===================================== +`git am < patch` +===================================== + +One feature worth pointing out is the three-way merge, which can help +if you get conflicts: `git am -3` will use index information contained +in patches to figure out the merge base. See linkgit:git-am[1] for +other options. + + +SEE ALSO +-------- +linkgit:gittutorial[7], +linkgit:git-push[1], +linkgit:git-pull[1], +linkgit:git-merge[1], +linkgit:git-rebase[1], +linkgit:git-format-patch[1], +linkgit:git-send-email[1], +linkgit:git-am[1] + +GIT +--- +Part of the linkgit:git[1] suite. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 9b4a4f45e9..3595b586bc 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -124,14 +124,14 @@ to point at the new commit. An evil merge is a <<def_merge,merge>> that introduces changes that do not appear in any <<def_parent,parent>>. -[[def_fast_forward]]fast forward:: +[[def_fast_forward]]fast-forward:: A fast-forward is a special type of <<def_merge,merge>> where you have a <<def_revision,revision>> and you are "merging" another <<def_branch,branch>>'s changes that happen to be a descendant of what 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>>. @@ -183,7 +183,8 @@ to point at the new commit. and potentially aborted, and allow for a post-notification after the operation is done. The hook scripts are found in the `$GIT_DIR/hooks/` directory, and are enabled by simply - making them executable. + removing the `.sample` suffix from the filename. In earlier versions + of git you had to make them executable. [[def_index]]index:: A collection of files with stat information, whose contents are stored @@ -219,7 +220,7 @@ to point at the new commit. conflict, manual intervention may be required to complete the merge. + -As a noun: unless it is a <<def_fast_forward,fast forward>>, a +As a noun: unless it is a <<def_fast_forward,fast-forward>>, a successful merge results in the creation of a new <<def_commit,commit>> representing the result of the merge, and having as <<def_parent,parents>> the tips of the merged <<def_branch,branches>>. @@ -259,9 +260,9 @@ 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`". + `git branch -r`. [[def_pack]]pack:: A set of objects which have been compressed into one file (to save space @@ -272,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 @@ -326,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, @@ -348,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 @@ -395,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 @@ -417,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 @@ -448,7 +505,13 @@ This commit is referred to as a "merge commit", or sometimes just a An <<def_object,object>> which is not <<def_reachable,reachable>> from a <<def_branch,branch>>, <<def_tag,tag>>, or any other reference. +[[def_upstream_branch]]upstream branch:: + The default <<def_branch,branch>> that is merged into the branch in + question (or the branch in question is rebased onto). It is configured + via branch.<name>.remote and branch.<name>.merge. If the upstream branch + of 'A' is 'origin/B' sometimes we say "'A' is tracking 'origin/B'". + [[def_working_tree]]working tree:: - The tree of actual checked out files. The working tree is - normally equal to the <<def_HEAD,HEAD>> plus any local changes - that you have made but not yet committed. + The tree of actual checked out files. The working tree normally + contains the contents of the <<def_HEAD,HEAD>> commit's tree, + plus any local changes that you have made but not yet committed. diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index 4357e26913..8823a37067 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -59,7 +59,7 @@ The policy. not yet pass the criteria set for 'next'. - The tips of 'master', 'maint' and 'next' branches will always - fast forward, to allow people to build their own + fast-forward, to allow people to build their own customization on top of them. - Usually 'master' contains all of 'maint', 'next' contains all @@ -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/rebase-and-edit.txt b/Documentation/howto/rebase-and-edit.txt deleted file mode 100644 index 554909fe08..0000000000 --- a/Documentation/howto/rebase-and-edit.txt +++ /dev/null @@ -1,79 +0,0 @@ -Date: Sat, 13 Aug 2005 22:16:02 -0700 (PDT) -From: Linus Torvalds <torvalds@osdl.org> -To: Steve French <smfrench@austin.rr.com> -cc: git@vger.kernel.org -Subject: Re: sending changesets from the middle of a git tree -Abstract: In this article, Linus demonstrates how a broken commit - in a sequence of commits can be removed by rewinding the head and - reapplying selected changes. - -On Sat, 13 Aug 2005, Linus Torvalds wrote: - -> That's correct. Same things apply: you can move a patch over, and create a -> new one with a modified comment, but basically the _old_ commit will be -> immutable. - -Let me clarify. - -You can entirely _drop_ old branches, so commits may be immutable, but -nothing forces you to keep them. Of course, when you drop a commit, you'll -always end up dropping all the commits that depended on it, and if you -actually got somebody else to pull that commit you can't drop it from -_their_ repository, but undoing things is not impossible. - -For example, let's say that you've made a mess of things: you've committed -three commits "old->a->b->c", and you notice that "a" was broken, but you -want to save "b" and "c". What you can do is - - # Create a branch "broken" that is the current code - # for reference - git branch broken - - # Reset the main branch to three parents back: this - # effectively undoes the three top commits - git reset HEAD^^^ - git checkout -f - - # Check the result visually to make sure you know what's - # going on - gitk --all - - # Re-apply the two top ones from "broken" - # - # First "parent of broken" (aka b): - git-diff-tree -p broken^ | git-apply --index - git commit --reedit=broken^ - - # Then "top of broken" (aka c): - git-diff-tree -p broken | git-apply --index - git commit --reedit=broken - -and you've now re-applied (and possibly edited the comments) the two -commits b/c, and commit "a" is basically gone (it still exists in the -"broken" branch, of course). - -Finally, check out the end result again: - - # Look at the new commit history - gitk --all - -to see that everything looks sensible. - -And then, you can just remove the broken branch if you decide you really -don't want it: - - # remove 'broken' branch - git branch -d broken - - # Prune old objects if you're really really sure - git prune - -And yeah, I'm sure there are other ways of doing this. And as usual, the -above is totally untested, and I just wrote it down in this email, so if -I've done something wrong, you'll have to figure it out on your own ;) - - Linus -- -To unsubscribe from this list: send the line "unsubscribe git" in -the body of a message to majordomo@vger.kernel.org -More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt index 7a76045eb7..74a1c0c4ba 100644 --- a/Documentation/howto/rebase-from-internal-branch.txt +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -1,4 +1,4 @@ -From: Junio C Hamano <junkio@cox.net> +From: Junio C Hamano <gitster@pobox.com> To: git@vger.kernel.org Cc: Petr Baudis <pasky@suse.cz>, Linus Torvalds <torvalds@osdl.org> Subject: Re: sending changesets from the middle of a git tree @@ -27,7 +27,7 @@ the kind of task StGIT is designed to do. I just have done a simpler one, this time using only the core GIT tools. -I had a handful commits that were ahead of master in pu, and I +I had a handful of commits that were ahead of master in pu, and I wanted to add some documentation bypassing my usual habit of placing new things in pu first. At the beginning, the commit ancestry graph looked like this: diff --git a/Documentation/howto/rebuild-from-update-hook.txt b/Documentation/howto/rebuild-from-update-hook.txt index 8d55dfbfae..48c67568d3 100644 --- a/Documentation/howto/rebuild-from-update-hook.txt +++ b/Documentation/howto/rebuild-from-update-hook.txt @@ -1,6 +1,6 @@ Subject: [HOWTO] Using post-update hook Message-ID: <7vy86o6usx.fsf@assigned-by-dhcp.cox.net> -From: Junio C Hamano <junkio@cox.net> +From: Junio C Hamano <gitster@pobox.com> Date: Fri, 26 Aug 2005 18:19:10 -0700 Abstract: In this how-to article, JC talks about how he uses the post-update hook to automate git documentation page diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt new file mode 100644 index 0000000000..6fd711996a --- /dev/null +++ b/Documentation/howto/revert-a-faulty-merge.txt @@ -0,0 +1,269 @@ +Date: Fri, 19 Dec 2008 00:45:19 -0800 +From: Linus Torvalds <torvalds@linux-foundation.org>, Junio C Hamano <gitster@pobox.com> +Subject: Re: Odd merge behaviour involving reverts +Abstract: Sometimes a branch that was already merged to the mainline + is later found to be faulty. Linus and Junio give guidance on + recovering from such a premature merge and continuing development + after the offending branch is fixed. +Message-ID: <7vocz8a6zk.fsf@gitster.siamese.dyndns.org> +References: <alpine.LFD.2.00.0812181949450.14014@localhost.localdomain> + +Alan <alan@clueserver.org> said: + + I have a master branch. We have a branch off of that that some + developers are doing work on. They claim it is ready. We merge it + into the master branch. It breaks something so we revert the merge. + They make changes to the code. they get it to a point where they say + it is ok and we merge again. + + When examined, we find that code changes made before the revert are + not in the master branch, but code changes after are in the master + branch. + +and asked for help recovering from this situation. + +The history immediately after the "revert of the merge" would look like +this: + + ---o---o---o---M---x---x---W + / + ---A---B + +where A and B are on the side development that was not so good, M is the +merge that brings these premature changes into the mainline, x are changes +unrelated to what the side branch did and already made on the mainline, +and W is the "revert of the merge M" (doesn't W look M upside down?). +IOW, "diff W^..W" is similar to "diff -R M^..M". + +Such a "revert" of a merge can be made with: + + $ git revert -m 1 M + +After the developers of the side branch fix their mistakes, the history +may look like this: + + ---o---o---o---M---x---x---W---x + / + ---A---B-------------------C---D + +where C and D are to fix what was broken in A and B, and you may already +have some other changes on the mainline after W. + +If you merge the updated side branch (with D at its tip), none of the +changes made in A nor B will be in the result, because they were reverted +by W. That is what Alan saw. + +Linus explains the situation: + + Reverting a regular commit just effectively undoes what that commit + did, and is fairly straightforward. But reverting a merge commit also + undoes the _data_ that the commit changed, but it does absolutely + nothing to the effects on _history_ that the merge had. + + So the merge will still exist, and it will still be seen as joining + the two branches together, and future merges will see that merge as + the last shared state - and the revert that reverted the merge brought + in will not affect that at all. + + So a "revert" undoes the data changes, but it's very much _not_ an + "undo" in the sense that it doesn't undo the effects of a commit on + the repository history. + + So if you think of "revert" as "undo", then you're going to always + miss this part of reverts. Yes, it undoes the data, but no, it doesn't + undo history. + +In such a situation, you would want to first revert the previous revert, +which would make the history look like this: + + ---o---o---o---M---x---x---W---x---Y + / + ---A---B-------------------C---D + +where Y is the revert of W. Such a "revert of the revert" can be done +with: + + $ git revert W + +This history would (ignoring possible conflicts between what W and W..Y +changed) be equivalent to not having W nor Y at all in the history: + + ---o---o---o---M---x---x-------x---- + / + ---A---B-------------------C---D + +and merging the side branch again will not have conflict arising from an +earlier revert and revert of the revert. + + ---o---o---o---M---x---x-------x-------* + / / + ---A---B-------------------C---D + +Of course the changes made in C and D still can conflict with what was +done by any of the x, but that is just a normal merge conflict. + +On the other hand, if the developers of the side branch discarded their +faulty A and B, and redone the changes on top of the updated mainline +after the revert, the history would have looked like this: + + ---o---o---o---M---x---x---W---x---x + / \ + ---A---B A'--B'--C' + +If you reverted the revert in such a case as in the previous example: + + ---o---o---o---M---x---x---W---x---x---Y---* + / \ / + ---A---B A'--B'--C' + +where Y is the revert of W, A' and B' are rerolled A and B, and there may +also be a further fix-up C' on the side branch. "diff Y^..Y" is similar +to "diff -R W^..W" (which in turn means it is similar to "diff M^..M"), +and "diff A'^..C'" by definition would be similar but different from that, +because it is a rerolled series of the earlier change. There will be a +lot of overlapping changes that result in conflicts. So do not do "revert +of revert" blindly without thinking.. + + ---o---o---o---M---x---x---W---x---x + / \ + ---A---B A'--B'--C' + +In the history with rebased side branch, W (and M) are behind the merge +base of the updated branch and the tip of the mainline, and they should +merge without the past faulty merge and its revert getting in the way. + +To recap, these are two very different scenarios, and they want two very +different resolution strategies: + + - If the faulty side branch was fixed by adding corrections on top, then + doing a revert of the previous revert would be the right thing to do. + + - If the faulty side branch whose effects were discarded by an earlier + revert of a merge was rebuilt from scratch (i.e. rebasing and fixing, + as you seem to have interpreted), then re-merging the result without + doing anything else fancy would be the right thing to do. + (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). + +For example, think about what reverting a merge (and then reverting the +revert) does to bisectability. Ignore the fact that the revert of a revert +is undoing it - just think of it as a "single commit that does a lot". +Because that is what it does. + +When you have a problem you are chasing down, and you hit a "revert this +merge", what you're hitting is essentially a single commit that contains +all the changes (but obviously in reverse) of all the commits that got +merged. So it's debugging hell, because now you don't have lots of small +changes that you can try to pinpoint which _part_ of it changes. + +But does it all work? Sure it does. You can revert a merge, and from a +purely technical angle, git did it very naturally and had no real +troubles. It just considered it a change from "state before merge" to +"state after merge", and that was it. Nothing complicated, nothing odd, +nothing really dangerous. Git will do it without even thinking about it. + +So from a technical angle, there's nothing wrong with reverting a merge, +but from a workflow angle it's something that you generally should try to +avoid. + +If at all possible, for example, if you find a problem that got merged +into the main tree, rather than revert the merge, try _really_ hard to +bisect the problem down into the branch you merged, and just fix it, or +try to revert the individual commit that caused it. + +Yes, it's more complex, and no, it's not always going to work (sometimes +the answer is: "oops, I really shouldn't have merged it, because it wasn't +ready yet, and I really need to undo _all_ of the merge"). So then you +really should revert the merge, but when you want to re-do the merge, you +now need to do it by reverting the revert. + +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 865a666324..093c656048 100644 --- a/Documentation/howto/revert-branch-rebase.txt +++ b/Documentation/howto/revert-branch-rebase.txt @@ -1,4 +1,4 @@ -From: Junio C Hamano <junkio@cox.net> +From: Junio C Hamano <gitster@pobox.com> To: git@vger.kernel.org Subject: [HOWTO] Reverting an existing commit Abstract: In this article, JC gives a small real-life example of using @@ -85,7 +85,7 @@ Fortunately I did not have to; what I have in the current branch ------------------------------------------------ $ git checkout master -$ git merge revert-c99 ;# this should be a fast forward +$ git merge revert-c99 ;# this should be a fast-forward Updating from 10d781b9caa4f71495c7b34963bef137216f86a8 to e3a693c... cache.h | 8 ++++---- commit.c | 2 +- @@ -95,7 +95,7 @@ Updating from 10d781b9caa4f71495c7b34963bef137216f86a8 to e3a693c... 5 files changed, 8 insertions(+), 8 deletions(-) ------------------------------------------------ -There is no need to redo the test at this point. We fast forwarded +There is no need to redo the test at this point. We fast-forwarded and we know 'master' matches 'revert-c99' exactly. In fact: ------------------------------------------------ @@ -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/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt index 0d73b31224..6d3eb8ed00 100644 --- a/Documentation/howto/separating-topic-branches.txt +++ b/Documentation/howto/separating-topic-branches.txt @@ -1,4 +1,4 @@ -From: Junio C Hamano <junkio@cox.net> +From: Junio C Hamano <gitster@pobox.com> Subject: Separating topic branches Abstract: In this article, JC describes how to separate topic branches. diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt index 4032748608..622ee5c8dd 100644 --- a/Documentation/howto/setup-git-server-over-http.txt +++ b/Documentation/howto/setup-git-server-over-http.txt @@ -143,7 +143,7 @@ Then, add something like this to your httpd.conf Require valid-user </Location> - Debian automatically reads all files under /etc/apach2/conf.d. + Debian automatically reads all files under /etc/apache2/conf.d. The password file can be somewhere else, but it has to be readable by Apache and preferably not readable by the world. diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt index 88765b5575..b7f8d416d6 100644 --- a/Documentation/howto/update-hook-example.txt +++ b/Documentation/howto/update-hook-example.txt @@ -1,4 +1,4 @@ -From: Junio C Hamano <junkio@cox.net> and Carl Baldwin <cnb@fc.hp.com> +From: Junio C Hamano <gitster@pobox.com> and Carl Baldwin <cnb@fc.hp.com> Subject: control access to branches. Date: Thu, 17 Nov 2005 23:55:32 -0800 Message-ID: <7vfypumlu3.fsf@assigned-by-dhcp.cox.net> @@ -65,10 +65,10 @@ function info { # Implement generic branch and tag policies. # - Tags should not be updated once created. -# - Branches should only be fast-forwarded. +# - Branches should only be fast-forwarded unless their pattern starts with '+' case "$1" in refs/tags/*) - [ -f "$GIT_DIR/$1" ] && + git rev-parse --verify -q "$1" && deny >/dev/null "You can't overwrite an existing tag" ;; refs/heads/*) @@ -76,11 +76,11 @@ case "$1" in if expr "$2" : '0*$' >/dev/null; then info "The branch '$1' is new..." else - # updating -- make sure it is a fast forward + # updating -- make sure it is a fast-forward mb=$(git-merge-base "$2" "$3") case "$mb,$2" in "$2,$mb") info "Update is fast-forward" ;; - *) deny >/dev/null "This is not a fast-forward update." ;; + *) noff=y; info "This is not a fast-forward update.";; esac fi ;; @@ -95,21 +95,30 @@ allowed_users_file=$GIT_DIR/info/allowed-users username=$(id -u -n) info "The user is: '$username'" -if [ -f "$allowed_users_file" ]; then +if test -f "$allowed_users_file" +then rc=$(cat $allowed_users_file | grep -v '^#' | grep -v '^$' | - while read head_pattern user_patterns; do - matchlen=$(expr "$1" : "$head_pattern") - if [ "$matchlen" == "${#1}" ]; then - info "Found matching head pattern: '$head_pattern'" - for user_pattern in $user_patterns; do - info "Checking user: '$username' against pattern: '$user_pattern'" - matchlen=$(expr "$username" : "$user_pattern") - if [ "$matchlen" == "${#username}" ]; then - grant "Allowing user: '$username' with pattern: '$user_pattern'" - fi - done - deny "The user is not in the access list for this branch" - fi + while read heads user_patterns + do + # does this rule apply to us? + head_pattern=${heads#+} + matchlen=$(expr "$1" : "${head_pattern#+}") + test "$matchlen" = ${#1} || continue + + # if non-ff, $heads must be with the '+' prefix + test -n "$noff" && + test "$head_pattern" = "$heads" && continue + + info "Found matching head pattern: '$head_pattern'" + for user_pattern in $user_patterns; do + info "Checking user: '$username' against pattern: '$user_pattern'" + matchlen=$(expr "$username" : "$user_pattern") + if test "$matchlen" = "${#username}" + then + grant "Allowing user: '$username' with pattern: '$user_pattern'" + fi + done + deny "The user is not in the access list for this branch" done ) case "$rc" in @@ -124,23 +133,32 @@ groups=$(id -G -n) info "The user belongs to the following groups:" info "'$groups'" -if [ -f "$allowed_groups_file" ]; then +if test -f "$allowed_groups_file" +then rc=$(cat $allowed_groups_file | grep -v '^#' | grep -v '^$' | - while read head_pattern group_patterns; do - matchlen=$(expr "$1" : "$head_pattern") - if [ "$matchlen" == "${#1}" ]; then - info "Found matching head pattern: '$head_pattern'" - for group_pattern in $group_patterns; do - for groupname in $groups; do - info "Checking group: '$groupname' against pattern: '$group_pattern'" - matchlen=$(expr "$groupname" : "$group_pattern") - if [ "$matchlen" == "${#groupname}" ]; then - grant "Allowing group: '$groupname' with pattern: '$group_pattern'" - fi - done + while read heads group_patterns + do + # does this rule apply to us? + head_pattern=${heads#+} + matchlen=$(expr "$1" : "${head_pattern#+}") + test "$matchlen" = ${#1} || continue + + # if non-ff, $heads must be with the '+' prefix + test -n "$noff" && + test "$head_pattern" = "$heads" && continue + + info "Found matching head pattern: '$head_pattern'" + for group_pattern in $group_patterns; do + for groupname in $groups; do + info "Checking group: '$groupname' against pattern: '$group_pattern'" + matchlen=$(expr "$groupname" : "$group_pattern") + if test "$matchlen" = "${#groupname}" + then + grant "Allowing group: '$groupname' with pattern: '$group_pattern'" + fi done - deny "None of the user's groups are in the access list for this branch" - fi + done + deny "None of the user's groups are in the access list for this branch" done ) case "$rc" in @@ -159,6 +177,7 @@ allowed-groups, to describe which heads can be pushed into by whom. The format of each file would look like this: refs/heads/master junio + +refs/heads/pu junio refs/heads/cogito$ pasky refs/heads/bw/.* linus refs/heads/tmp/.* .* @@ -166,7 +185,8 @@ whom. The format of each file would look like this: With this, Linus can push or create "bw/penguin" or "bw/zebra" or "bw/panda" branches, Pasky can do only "cogito", and JC can -do master branch and make versioned tags. And anybody can do -tmp/blah branches. +do master and pu branches and make versioned tags. And anybody +can do tmp/blah branches. The '+' sign at the pu record means +that JC can make non-fast-forward pushes on it. ------------ diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index 0953a50b69..1ae8d1214e 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -25,7 +25,7 @@ What you want is the 'subtree' merge strategy, which helps you in such a situation. In this example, let's say you have the repository at `/path/to/B` (but -it can be an URL as well, if you want). You want to merge the 'master' +it can be a URL as well, if you want). You want to merge the 'master' branch of that repository to the `dir-B` subdirectory in your current branch. @@ -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/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt new file mode 100644 index 0000000000..98c0033a55 --- /dev/null +++ b/Documentation/howto/using-signed-tag-in-pull-request.txt @@ -0,0 +1,217 @@ +From: Junio C Hamano <gitster@pobox.com> +Date: Tue, 17 Jan 2011 13:00:00 -0800 +Subject: Using signed tag in pull requests +Abstract: Beginning v1.7.9, a contributor can push a signed tag to her + publishing repository and ask her integrator to pull it. This assures the + integrator that the pulled history is authentic and allows others to + later validate it. +Content-type: text/asciidoc + +Using signed tag in pull requests +================================= + +A typical distributed workflow using Git is for a contributor to fork a +project, build on it, publish the result to her public repository, and ask +the "upstream" person (often the owner of the project where she forked +from) to pull from her public repository. Requesting such a "pull" is made +easy by the `git request-pull` command. + +Earlier, a typical pull request may have started like this: + +------------ + The following changes since commit 406da78032179...: + + Froboz 3.2 (2011-09-30 14:20:57 -0700) + + are available in the git repository at: + + example.com:/git/froboz.git for-xyzzy +------------ + +followed by a shortlog of the changes and a diffstat. + +The request was for a branch name (e.g. `for-xyzzy`) in the public +repository of the contributor, and even though it stated where the +contributor forked her work from, the message did not say anything about +the commit to expect at the tip of the for-xyzzy branch. If the site that +hosts the public repository of the contributor cannot be fully trusted, it +was unnecessarily hard to make sure what was pulled by the integrator was +genuinely what the contributor had produced for the project. Also there +was no easy way for third-party auditors to later verify the resulting +history. + +Starting from Git release v1.7.9, a contributor can add a signed tag to +the commit at the tip of the history and ask the integrator to pull that +signed tag. When the integrator runs `git pull`, the signed tag is +automatically verified to assure that the history is not tampered with. +In addition, the resulting merge commit records the content of the signed +tag, so that other people can verify that the branch merged by the +integrator was signed by the contributor, without fetching the signed tag +used to validate the pull request separately and keeping it in the refs +namespace. + +This document describes the workflow between the contributor and the +integrator, using Git v1.7.9 or later. + + +A contributor or a lieutenant +----------------------------- + +After preparing her work to be pulled, the contributor uses `git tag -s` +to create a signed tag: + +------------ + $ git checkout work + $ ... "git pull" from sublieutenants, "git commit" your own work ... + $ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work +------------ + +Note that this example uses the `-m` option to create a signed tag with +just a one-liner message, but this is for illustration purposes only. It +is advisable to compose a well-written explanation of what the topic does +to justify why it is worthwhile for the integrator to pull it, as this +message will eventually become part of the final history after the +integrator responds to the pull request (as we will see later). + +Then she pushes the tag out to her public repository: + +------------ + $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy +------------ + +There is no need to push the `work` branch or anything else. + +Note that the above command line used a plus sign at the beginning of +`+frotz-for-xyzzy` to allow forcing the update of a tag, as the same +contributor may want to reuse a signed tag with the same name after the +previous pull request has already been responded to. + +The contributor then prepares a message to request a "pull": + +------------ + $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt +------------ + +The arguments are: + +. the version of the integrator's commit the contributor based her work on; +. the URL of the repository, to which the contributor has pushed what she + wants to get pulled; and +. the name of the tag the contributor wants to get pulled (earlier, she could + write only a branch name here). + +The resulting msg.txt file begins like so: + +------------ + The following changes since commit 406da78032179...: + + Froboz 3.2 (2011-09-30 14:20:57 -0700) + + are available in the git repository at: + + example.com:/git/froboz.git tags/frotz-for-xyzzy + + for you to fetch changes up to 703f05ad5835c...: + + Add tests and documentation for frotz (2011-12-02 10:02:52 -0800) + + ----------------------------------------------- + Completed frotz feature + ----------------------------------------------- +------------ + +followed by a shortlog of the changes and a diffstat. Comparing this with +the earlier illustration of the output from the traditional `git request-pull` +command, the reader should notice that: + +. The tip commit to expect is shown to the integrator; and +. The signed tag message is shown prominently between the dashed lines + before the shortlog. + +The latter is why the contributor would want to justify why pulling her +work is worthwhile when creating the signed tag. The contributor then +opens her favorite MUA, reads msg.txt, edits and sends it to her upstream +integrator. + + +Integrator +---------- + +After receiving such a pull request message, the integrator fetches and +integrates the tag named in the request, with: + +------------ + $ git pull example.com:/git/froboz.git/ tags/frotz-for-xyzzy +------------ + +This operation will always open an editor to allow the integrator to fine +tune the commit log message when merging a signed tag. Also, pulling a +signed tag will always create a merge commit even when the integrator does +not have any new commit since the contributor's work forked (i.e. 'fast +forward'), so that the integrator can properly explain what the merge is +about and why it was made. + +In the editor, the integrator will see something like this: + +------------ + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/ + + Completed frotz feature + # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB + # gpg: Good signature from "Con Tributor <nitfol@example.com>" +------------ + +Notice that the message recorded in the signed tag "Completed frotz +feature" appears here, and again that is why it is important for the +contributor to explain her work well when creating the signed tag. + +As usual, the lines commented with `#` are stripped out. The resulting +commit records the signed tag used for this validation in a hidden field +so that it can later be used by others to audit the history. There is no +need for the integrator to keep a separate copy of the tag in his +repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the +above example), and there is no need to publish the tag to his public +repository, either. + +After the integrator responds to the pull request and her work becomes +part of the permanent history, the contributor can remove the tag from +her public repository, if she chooses, in order to keep the tag namespace +of her public repository clean, with: + +------------ + $ git push example.com:/git/froboz.git :frotz-for-xyzzy +------------ + + +Auditors +-------- + +The `--show-signature` option can be given to `git log` or `git show` and +shows the verification status of the embedded signed tag in merge commits +created when the integrator responded to a pull request of a signed tag. + +A typical output from `git show --show-signature` may look like this: + +------------ + $ git show --show-signature + commit 02306ef6a3498a39118aef9df7975bdb50091585 + merged tag 'frotz-for-xyzzy' + gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB + gpg: Good signature from "Con Tributor <nitfol@example.com>" + Merge: 406da78 703f05a + Author: Inte Grator <xyzzy@example.com> + Date: Tue Jan 17 13:49:41 2012 -0800 + + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/ + + Completed frotz feature + + * tag 'frotz-for-xyzzy' (100 commits) + Add tests and documentation for frotz + ... +------------ + +There is no need for the auditor to explicitly fetch the contributor's +signature, or to even be aware of what tag(s) the contributor and integrator +used to communicate the signature. All the required information is recorded +as part of the merge commit. diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index 1e188e6e74..625d3154ea 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -7,11 +7,11 @@ At the core level, git is character encoding agnostic. to be what lstat(2) and creat(2) accepts. There is no such thing as pathname encoding translation. - - The contents of the blob objects are uninterpreted sequence + - The contents of the blob objects are uninterpreted sequences of bytes. There is no encoding translation at the core level. - - The commit log messages are uninterpreted sequence of non-NUL + - The commit log messages are uninterpreted sequences of non-NUL bytes. Although we encourage that the commit log messages are encoded @@ -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-tree` (hence, `git-commit` which uses it) 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,9 +37,9 @@ 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` and friends looks at the `encoding` - header of a commit object, and tries to re-code the log - message into UTF-8 unless otherwise specified. You can +. '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 `i18n.logoutputencoding` in `.git/config` file, like this: + diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh index 5433cf8ced..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-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/mailmap.txt b/Documentation/mailmap.txt new file mode 100644 index 0000000000..288f04e70c --- /dev/null +++ b/Documentation/mailmap.txt @@ -0,0 +1,74 @@ +If the file `.mailmap` exists at the toplevel of the repository, or at +the location pointed to by the mailmap.file configuration option, it +is used to map author and committer names and email addresses to +canonical real names and email addresses. + +In the simple form, each line in the file consists of the canonical +real name of an author, whitespace, and an email address used in the +commit (enclosed by '<' and '>') to map to the name. For example: +-- + Proper Name <commit@email.xx> +-- + +The more complex forms are: +-- + <proper@email.xx> <commit@email.xx> +-- +which allows mailmap to replace only the email part of a commit, and: +-- + Proper Name <proper@email.xx> <commit@email.xx> +-- +which allows mailmap to replace both the name and the email of a +commit matching the specified commit email address, and: +-- + Proper Name <proper@email.xx> Commit Name <commit@email.xx> +-- +which allows mailmap to replace both the name and the email of a +commit matching both the specified commit name and email address. + +Example 1: Your history contains commits by two authors, Jane +and Joe, whose names appear in the repository under several forms: + +------------ +Joe Developer <joe@example.com> +Joe R. Developer <joe@example.com> +Jane Doe <jane@example.com> +Jane Doe <jane@laptop.(none)> +Jane D. <jane@desktop.(none)> +------------ + +Now suppose that Joe wants his middle name initial used, and Jane +prefers her family name fully spelled out. A proper `.mailmap` file +would look like: + +------------ +Jane Doe <jane@desktop.(none)> +Joe R. Developer <joe@example.com> +------------ + +Note how there is no need for an entry for <jane@laptop.(none)>, because the +real name of that author is already correct. + +Example 2: Your repository contains commits from the following +authors: + +------------ +nick1 <bugs@company.xx> +nick2 <bugs@company.xx> +nick2 <nick2@company.xx> +santa <me@company.xx> +claus <me@company.xx> +CTO <cto@coompany.xx> +------------ + +Then you might want a `.mailmap` file that looks like: +------------ +<cto@company.xx> <cto@coompany.xx> +Some Dude <some@dude.xx> nick1 <bugs@company.xx> +Other Author <other@author.xx> nick2 <bugs@company.xx> +Other Author <other@author.xx> <nick2@company.xx> +Santa Claus <santa.claus@northpole.xx> <me@company.xx> +------------ + +Use hash '#' for comments that are either on their own line, or after +the email address. diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl index 4065a3a27a..b4d315cb8c 100644 --- a/Documentation/manpage-1.72.xsl +++ b/Documentation/manpage-1.72.xsl @@ -1,21 +1,14 @@ -<!-- Based on callouts.xsl. Fixes man page callouts for DocBook 1.72 XSL --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> +<!-- manpage-1.72.xsl: + special settings for manpages rendered from asciidoc+docbook + handles peculiarities in docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> -<xsl:param name="man.output.quietly" select="1"/> -<xsl:param name="refentry.meta.get.quietly" select="1"/> +<xsl:import href="manpage-base.xsl"/> -<xsl:template match="co"> - <xsl:value-of select="concat('▓fB(',substring-after(@id,'-'),')▓fR')"/> -</xsl:template> -<xsl:template match="calloutlist"> - <xsl:text>⌂sp </xsl:text> - <xsl:apply-templates/> - <xsl:text> </xsl:text> -</xsl:template> -<xsl:template match="callout"> - <xsl:value-of select="concat('▓fB',substring-after(@arearefs,'-'),'. ▓fR')"/> - <xsl:apply-templates/> - <xsl:text>⌂br </xsl:text> -</xsl:template> +<!-- these are the special values for the roff control characters + needed for docbook-xsl 1.72.0 --> +<xsl:param name="git.docbook.backslash">▓</xsl:param> +<xsl:param name="git.docbook.dot" >⌂</xsl:param> </xsl:stylesheet> diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in new file mode 100644 index 0000000000..e800904df3 --- /dev/null +++ b/Documentation/manpage-base-url.xsl.in @@ -0,0 +1,10 @@ +<!-- manpage-base-url.xsl: + special settings for manpages rendered from newer docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- set a base URL for relative links --> +<xsl:param name="man.base.url.for.relative.links" + >@@MAN_BASE_URL@@</xsl:param> + +</xsl:stylesheet> diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl new file mode 100644 index 0000000000..a264fa6160 --- /dev/null +++ b/Documentation/manpage-base.xsl @@ -0,0 +1,35 @@ +<!-- manpage-base.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- these params silence some output from xmlto --> +<xsl:param name="man.output.quietly" select="1"/> +<xsl:param name="refentry.meta.get.quietly" select="1"/> + +<!-- convert asciidoc callouts to man page format; + git.docbook.backslash and git.docbook.dot params + must be supplied by another XSL file or other means --> +<xsl:template match="co"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB(', + substring-after(@id,'-'),')', + $git.docbook.backslash,'fR')"/> +</xsl:template> +<xsl:template match="calloutlist"> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>sp </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="callout"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB', + substring-after(@arearefs,'-'), + '. ',$git.docbook.backslash,'fR')"/> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>br </xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl new file mode 100644 index 0000000000..608eb5df62 --- /dev/null +++ b/Documentation/manpage-bold-literal.xsl @@ -0,0 +1,17 @@ +<!-- manpage-bold-literal.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- render literal text as bold (instead of plain or monospace); + this makes literal text easier to distinguish in manpages + viewed on a tty --> +<xsl:template match="literal"> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fB</xsl:text> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fR</xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl new file mode 100644 index 0000000000..a48f5b11f3 --- /dev/null +++ b/Documentation/manpage-normal.xsl @@ -0,0 +1,13 @@ +<!-- manpage-normal.xsl: + special settings for manpages rendered from asciidoc+docbook + handles anything we want to keep away from docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<xsl:import href="manpage-base.xsl"/> + +<!-- these are the normal values for the roff control characters --> +<xsl:param name="git.docbook.backslash">\</xsl:param> +<xsl:param name="git.docbook.dot" >.</xsl:param> + +</xsl:stylesheet> diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl new file mode 100644 index 0000000000..aeb8839f33 --- /dev/null +++ b/Documentation/manpage-quote-apos.xsl @@ -0,0 +1,16 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- work around newer groff/man setups using a prettier apostrophe + that unfortunately does not quote anything when cut&pasting + examples to the shell --> +<xsl:template name="escape.apostrophe"> + <xsl:param name="content"/> + <xsl:call-template name="string.subst"> + <xsl:with-param name="string" select="$content"/> + <xsl:with-param name="target">'</xsl:with-param> + <xsl:with-param name="replacement">\(aq</xsl:with-param> + </xsl:call-template> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl new file mode 100644 index 0000000000..a63c7632a8 --- /dev/null +++ b/Documentation/manpage-suppress-sp.xsl @@ -0,0 +1,21 @@ +<!-- manpage-suppress-sp.xsl: + special settings for manpages rendered from asciidoc+docbook + handles erroneous, inline .sp in manpage output of some + versions of docbook-xsl --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- attempt to work around spurious .sp at the tail of the line + that some versions of docbook stylesheets seem to add --> +<xsl:template match="simpara"> + <xsl:variable name="content"> + <xsl:apply-templates/> + </xsl:variable> + <xsl:value-of select="normalize-space($content)"/> + <xsl:if test="not(ancestor::authorblurb) and + not(ancestor::personblurb)"> + <xsl:text> </xsl:text> + </xsl:if> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 48ce747cf4..861bd6f553 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -1,22 +1,63 @@ -merge.stat:: - Whether to print the diffstat berween ORIG_HEAD and merge result - at the end of the merge. True by default. +merge.conflictstyle:: + Specify the style in which conflicted hunks are written out to + working tree files upon merge. The default is "merge", which + shows a `<<<<<<<` conflict marker, changes made by one side, + a `=======` marker, changes made by the other side, and then + a `>>>>>>>` marker. An alternate style, "diff3", adds a `|||||||` + marker and the original text before the `=======` marker. + +merge.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", and - "opendiff". Any other value is treated is custom merge tool - and there must be a corresponing mergetool.<tool>.cmd option. + 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:: Controls the amount of output shown by the recursive merge @@ -24,10 +65,10 @@ merge.verbosity:: message if conflicts were detected. Level 1 outputs only conflicts, 2 outputs conflicts and file changes. Level 5 and above outputs debugging information. The default is level 2. - Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. + Can be overridden by the 'GIT_MERGE_VERBOSITY' environment variable. merge.<driver>.name:: - Defines a human readable name for a custom low-level + Defines a human-readable name for a custom low-level merge driver. See linkgit:gitattributes[5] for details. merge.<driver>.driver:: diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index ffbc6e9861..0bcbe0ac3c 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -1,60 +1,107 @@ ---stat:: - Show a diffstat at the end of the merge. The diffstat is also - controlled by the configuration option merge.stat. +--commit:: +--no-commit:: + Perform the merge and commit the result. This option can + be used to override --no-commit. ++ +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. --n:: ---no-stat:: - Do not show diffstat at the end of the merge. +--edit:: +--no-edit:: + Invoke an editor before committing successful mechanical merge to + further edit the auto-generated merge message, so that the user + can explain and justify the merge. The `--no-edit` option can be + used to accept the auto-generated message (this is generally + discouraged). The `--edit` option is still useful if you are + giving a draft message with the `-m` option from the command line + and want to edit it in the editor. ++ +Older scripts may depend on the historical behaviour of not allowing the +user to edit the merge log message. They will see an editor opened when +they run `git merge`. To make it easier to adjust such scripts to the +updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be +set to `no` at the beginning of them. ---summary:: ---no-summary:: - Synonyms to --stat and --no-stat; these are deprecated and will be - removed in the future. +--ff:: + When the merge resolves as a fast-forward, only update the branch + pointer, without creating a merge commit. This is the default + behavior. ---log:: - In addition to branch names, populate the log message with - one-line descriptions from the actual commits that are being - merged. +--no-ff:: + Create a merge commit even when the merge resolves as a + fast-forward. + +--ff-only:: + Refuse to merge and exit with a non-zero status unless the + current `HEAD` is already up-to-date or the merge can be + resolved as a fast-forward. +--log[=<n>]:: --no-log:: - Do not list one-line descriptions from the actual commits being - merged. + In addition to branch names, populate the log message with + 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. ---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. ---commit:: - Perform the merge and commit the result. This option can - be used to override --no-commit. +--stat:: +-n:: +--no-stat:: + Show a diffstat at the end of the merge. The diffstat is also + controlled by the configuration option merge.stat. ++ +With -n or --no-stat do not show a diffstat at the end of the +merge. --squash:: +--no-squash:: Produce the working tree and index state as if a real - merge happened, but do not actually make a commit or + merge happened (except for the merge information), + but do not actually make a commit or move the `HEAD`, nor record `$GIT_DIR/MERGE_HEAD` to cause the next `git commit` command to create a merge commit. This allows you to create a single commit on top of the current branch whose effect is the same as merging another branch (or more in case of an octopus). - ---no-squash:: - Perform the merge and commit the result. This option can - be used to override --squash. - ---no-ff:: - Generate a merge commit even if the merge resolved as a - fast-forward. - ---ff:: - Do not generate a merge commit if the merge resolved as - a fast-forward, only update the branch pointer. This is - the default behavior of git-merge. ++ +With --no-squash perform the merge and commit the result. This +option can be used to override --squash. -s <strategy>:: --strategy=<strategy>:: 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. 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 1276f858ad..595a3cf1a7 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -1,17 +1,22 @@ 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 3-way merge + and another branch you pulled from) using a 3-way merge algorithm. It tries to carefully detect criss-cross merge ambiguities and is considered generally safe and fast. recursive:: - This can only resolve two heads using 3-way merge - algorithm. When there are more than one common - ancestors that can be used for 3-way merge, it creates a + This can only resolve two heads using a 3-way merge + algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a merged tree of the common ancestors and uses that as the reference tree for the 3-way merge. This has been reported to result in fewer merge conflicts without @@ -20,19 +25,80 @@ 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 more than two-head case, but refuses to do - complex merge that needs manual resolution. It is + This resolves cases with more than two heads, but refuses to do + a complex merge that needs manual resolution. It is primarily meant to be used for bundling topic branch heads together. This is the default merge strategy when - pulling or merging more than one branches. + pulling or merging more than one branch. ours:: - This resolves any number of heads, but the result of the - merge is always the current branch head. It is meant to + This resolves any number of heads, but the resulting tree of the + 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 ec37555794..e3d8a83b23 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' @@ -30,7 +35,7 @@ This is designed to be as compact as possible. commit <sha1> Author: <author> - Date: <date> + Date: <author date> <title line> @@ -49,10 +54,10 @@ This is designed to be as compact as possible. * 'fuller' commit <sha1> - Author: <author> - AuthorDate: <date & time> - Commit: <committer> - CommitDate: <date & time> + Author: <author> + AuthorDate: <author date> + Commit: <committer> + CommitDate: <committer date> <title line> @@ -62,7 +67,7 @@ This is designed to be as compact as possible. From <sha1> <date> From: <author> - Date: <date & time> + Date: <author date> Subject: [PATCH] <title line> <full commit message> @@ -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'. @@ -101,29 +106,66 @@ The placeholders are: - '%P': parent hashes - '%p': abbreviated parent hashes - '%an': author name +- '%aN': author name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%ae': author email -- '%ad': author date +- '%aE': author email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%ad': author date (format respects --date= option) - '%aD': author date, RFC2822 style - '%ar': author date, relative - '%at': author date, UNIX timestamp - '%ai': author date, ISO 8601 format - '%cn': committer name +- '%cN': committer name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%ce': committer email +- '%cE': committer email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%cd': committer date - '%cD': committer date, RFC2822 style - '%cr': committer date, relative - '%ct': committer date, UNIX timestamp - '%ci': committer date, ISO 8601 format +- '%d': ref names, like the --decorate option of linkgit:git-log[1] - '%e': encoding - '%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}` +- '%gn': reflog identity name +- '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%ge': reflog identity email +- '%gE': reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%gs': reflog subject - '%Cred': switch color to red - '%Cgreen': switch color to green - '%Cblue': switch color to blue - '%Creset': reset color +- '%C(...)': color specification, as described in color.branch.* config option - '%m': left, right or boundary mark - '%n': newline +- '%%': 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]. + +NOTE: Some placeholders may depend on other options given to the +revision traversal engine. For example, the `%g*` reflog options will +insert an empty string unless we are traversing reflog entries (e.g., by +`git log -g`). The `%d` placeholder will use the "short" decoration +format if `--decorate` was not already provided on the command line. + +If you add a `+` (plus sign) after '%' of a placeholder, a line-feed +is inserted immediately before the expansion if and only if the +placeholder expands to a non-empty string. + +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:' + @@ -146,3 +188,12 @@ $ git log -2 --pretty=tformat:%h 4da45bef \ 4da45be 7134973 --------------------- ++ +In addition, any unrecognized string that has a `%` in it is interpreted +as if it has `tformat:` in front of it. For example, these two are +equivalent: ++ +--------------------- +$ git log -2 --pretty=tformat:%h 4da45bef +$ git log -2 --pretty=%h 4da45bef +--------------------- diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 6d66c74cc1..2a3dc8664f 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -1,25 +1,68 @@ ---pretty[='<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]). --abbrev-commit:: Instead of showing the full 40-byte hexadecimal commit object - name, show only handful hexdigits prefix. Non default number of + name, show only a partial prefix. Non default number of digits can be specified with "--abbrev=<n>" (which also modifies diff output, if it is displayed). + 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. + --encoding[=<encoding>]:: The commit objects record the encoding used for the log message in their encoding header; this option can be used to tell the 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/pt_BR/gittutorial.txt b/Documentation/pt_BR/gittutorial.txt new file mode 100644 index 0000000000..beba065252 --- /dev/null +++ b/Documentation/pt_BR/gittutorial.txt @@ -0,0 +1,675 @@ +gittutorial(7) +============== + +NOME +---- +gittutorial - Um tutorial de introdução ao git (para versão 1.5.1 ou mais nova) + +SINOPSE +-------- +git * + +DESCRIÇÃO +----------- + +Este tutorial explica como importar um novo projeto para o git, +adicionar mudanças a ele, e compartilhar mudanças com outros +desenvolvedores. + +Se, ao invés disso, você está interessado primariamente em usar git para +obter um projeto, por exemplo, para testar a última versão, você pode +preferir começar com os primeiros dois capÃtulos de +link:user-manual.html[O Manual do Usuário Git]. + +Primeiro, note que você pode obter documentação para um comando como +`git log --graph` com: + +------------------------------------------------ +$ man git-log +------------------------------------------------ + +ou: + +------------------------------------------------ +$ git help log +------------------------------------------------ + +Com a última forma, você pode usar o visualizador de manual de sua +escolha; veja linkgit:git-help[1] para maior informação. + +É uma boa idéia informar ao git seu nome e endereço público de email +antes de fazer qualquer operação. A maneira mais fácil de fazê-lo é: + +------------------------------------------------ +$ git config --global user.name "Seu Nome Vem Aqui" +$ git config --global user.email voce@seudominio.exemplo.com +------------------------------------------------ + + +Importando um novo projeto +----------------------- + +Assuma que você tem um tarball project.tar.gz com seu trabalho inicial. +Você pode colocá-lo sob controle de revisão git da seguinte forma: + +------------------------------------------------ +$ tar xzf project.tar.gz +$ cd project +$ git init +------------------------------------------------ + +Git irá responder + +------------------------------------------------ +Initialized empty Git repository in .git/ +------------------------------------------------ + +Agora que você iniciou seu diretório de trabalho, você deve ter notado que um +novo diretório foi criado com o nome de ".git". + +A seguir, diga ao git para gravar um instantâneo do conteúdo de todos os +arquivos sob o diretório atual (note o '.'), com 'git-add': + +------------------------------------------------ +$ git add . +------------------------------------------------ + +Este instantâneo está agora armazenado em uma área temporária que o git +chama de "index" ou Ãndice. Você pode armazenar permanentemente o +conteúdo do Ãndice no repositório com 'git-commit': + +------------------------------------------------ +$ git commit +------------------------------------------------ + +Isto vai te pedir por uma mensagem de commit. Você agora gravou sua +primeira versão de seu projeto no git. + +Fazendo mudanças +-------------- + +Modifique alguns arquivos, e, então, adicione seu conteúdo atualizado ao +Ãndice: + +------------------------------------------------ +$ git add file1 file2 file3 +------------------------------------------------ + +Você está agora pronto para fazer o commit. Você pode ver o que está +para ser gravado usando 'git-diff' com a opção --cached: + +------------------------------------------------ +$ git diff --cached +------------------------------------------------ + +(Sem --cached, o comando 'git-diff' irá te mostrar quaisquer mudanças +que você tenha feito mas ainda não adicionou ao Ãndice.) Você também +pode obter um breve sumário da situação com 'git-status': + +------------------------------------------------ +$ git status +# On branch master +# Changes to be committed: +# (use "git reset HEAD <file>..." to unstage) +# +# modified: file1 +# modified: file2 +# modified: file3 +# +------------------------------------------------ + +Se você precisar fazer qualquer outro ajuste, faça-o agora, e, então, +adicione qualquer conteúdo modificado ao Ãndice. Finalmente, grave suas +mudanças com: + +------------------------------------------------ +$ git commit +------------------------------------------------ + +Ao executar esse comando, ele irá te pedir uma mensagem descrevendo a mudança, +e, então, irá gravar a nova versão do projeto. + +Alternativamente, ao invés de executar 'git-add' antes, você pode usar + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +o que irá automaticamente notar quaisquer arquivos modificados (mas não +novos), adicioná-los ao Ãndices, e gravar, tudo em um único passo. + +Uma nota em mensagens de commit: Apesar de não ser exigido, é uma boa +idéia começar a mensagem com uma simples e curta (menos de 50 +caracteres) linha sumarizando a mudança, seguida de uma linha em branco +e, então, uma descrição mais detalhada. Ferramentas que transformam +commits em email, por exemplo, usam a primeira linha no campo de +cabeçalho "Subject:" e o resto no corpo. + +Git rastreia conteúdo, não arquivos +---------------------------- + +Muitos sistemas de controle de revisão provêem um comando `add` que diz +ao sistema para começar a rastrear mudanças em um novo arquivo. O +comando `add` do git faz algo mais simples e mais poderoso: 'git-add' é +usado tanto para arquivos novos e arquivos recentemente modificados, e +em ambos os casos, ele tira o instantâneo dos arquivos dados e armazena +o conteúdo no Ãndice, pronto para inclusão do próximo commit. + +Visualizando a história do projeto +----------------------- + +Em qualquer ponto você pode visualizar a história das suas mudanças +usando + +------------------------------------------------ +$ git log +------------------------------------------------ + +Se você também quiser ver a diferença completa a cada passo, use + +------------------------------------------------ +$ git log -p +------------------------------------------------ + +Geralmente, uma visão geral da mudança é útil para ter a sensação de +cada passo + +------------------------------------------------ +$ git log --stat --summary +------------------------------------------------ + +Gerenciando "branches"/ramos +----------------- + +Um simples repositório git pode manter múltiplos ramos de +desenvolvimento. Para criar um novo ramo chamado "experimental", use + +------------------------------------------------ +$ git branch experimental +------------------------------------------------ + +Se você executar agora + +------------------------------------------------ +$ git branch +------------------------------------------------ + +você vai obter uma lista de todos os ramos existentes: + +------------------------------------------------ + experimental +* master +------------------------------------------------ + +O ramo "experimental" é o que você acaba de criar, e o ramo "master" é o +ramo padrão que foi criado pra você automaticamente. O asterisco marca +o ramo em que você está atualmente; digite + +------------------------------------------------ +$ git checkout experimental +------------------------------------------------ + +para mudar para o ramo experimental. Agora edite um arquivo, grave a +mudança, e mude de volta para o ramo master: + +------------------------------------------------ +(edita arquivo) +$ git commit -a +$ git checkout master +------------------------------------------------ + +Verifique que a mudança que você fez não está mais visÃvel, já que ela +foi feita no ramo experimental e você está de volta ao ramo master. + +Você pode fazer uma mudança diferente no ramo master: + +------------------------------------------------ +(edit file) +$ git commit -a +------------------------------------------------ + +neste ponto, os dois ramos divergiram, com diferentes mudanças feitas em +cada um. Para unificar as mudanças feitas no experimental para o +master, execute + +------------------------------------------------ +$ git merge experimental +------------------------------------------------ + +Se as mudanças não conflitarem, estará pronto. Se existirem conflitos, +marcadores serão deixados nos arquivos problemáticos exibindo o +conflito; + +------------------------------------------------ +$ git diff +------------------------------------------------ + +vai exibir isto. Após você editar os arquivos para resolver os +conflitos, + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +irá gravar o resultado da unificação. Finalmente, + +------------------------------------------------ +$ gitk +------------------------------------------------ + +vai mostrar uma bela representação gráfica da história resultante. + +Neste ponto você pode remover seu ramo experimental com + +------------------------------------------------ +$ git branch -d experimental +------------------------------------------------ + +Este comando garante que as mudanças no ramo experimental já estão no +ramo atual. + +Se você desenvolve em um ramo ideia-louca, e se arrepende, você pode +sempre remover o ramo com + +------------------------------------- +$ git branch -D ideia-louca +------------------------------------- + +Ramos são baratos e fáceis, então isto é uma boa maneira de experimentar +alguma coisa. + +Usando git para colaboração +--------------------------- + +Suponha que Alice começou um novo projeto com um repositório git em +/home/alice/project, e que Bob, que tem um diretório home na mesma +máquina, quer contribuir. + +Bob começa com: + +------------------------------------------------ +bob$ git clone /home/alice/project myrepo +------------------------------------------------ + +Isso cria um novo diretório "myrepo" contendo um clone do repositório de +Alice. O clone está no mesmo pé que o projeto original, possuindo sua +própria cópia da história do projeto original. + +Bob então faz algumas mudanças e as grava: + +------------------------------------------------ +(editar arquivos) +bob$ git commit -a +(repetir conforme necessário) +------------------------------------------------ + +Quanto está pronto, ele diz a Alice para puxar as mudanças do +repositório em /home/bob/myrepo. Ela o faz com: + +------------------------------------------------ +alice$ cd /home/alice/project +alice$ git pull /home/bob/myrepo master +------------------------------------------------ + +Isto unifica as mudanças do ramo "master" do Bob ao ramo atual de Alice. +Se Alice fez suas próprias mudanças no intervalo, ela, então, pode +precisar corrigir manualmente quaisquer conflitos. (Note que o argumento +"master" no comando acima é, de fato, desnecessário, já que é o padrão.) + +O comando "pull" executa, então, duas operações: ele obtém mudanças de +um ramo remoto, e, então, as unifica no ramo atual. + +Note que, em geral, Alice gostaria que suas mudanças locais fossem +gravadas antes de iniciar este "pull". Se o trabalho de Bob conflita +com o que Alice fez desde que suas histórias se ramificaram, Alice irá +usar seu diretório de trabalho e o Ãndice para resolver conflitos, e +mudanças locais existentes irão interferir com o processo de resolução +de conflitos (git ainda irá realizar a obtenção mas irá se recusar a +unificar --- Alice terá que se livrar de suas mudanças locais de alguma +forma e puxar de novo quando isso acontecer). + +Alice pode espiar o que Bob fez sem unificar primeiro, usando o comando +"fetch"; isto permite Alice inspecionar o que Bob fez, usando um sÃmbolo +especial "FETCH_HEAD", com o fim de determinar se ele tem alguma coisa +que vale puxar, assim: + +------------------------------------------------ +alice$ git fetch /home/bob/myrepo master +alice$ git log -p HEAD..FETCH_HEAD +------------------------------------------------ + +Esta operação é segura mesmo se Alice tem mudanças locais não gravadas. +A notação de intervalo "HEAD..FETCH_HEAD" significa mostrar tudo que é +alcançável de FETCH_HEAD mas exclua tudo o que é alcançável de HEAD. +Alice já sabe tudo que leva a seu estado atual (HEAD), e revisa o que Bob +tem em seu estado (FETCH_HEAD) que ela ainda não viu com esse comando. + +Se Alice quer visualizar o que Bob fez desde que suas histórias se +ramificaram, ela pode disparar o seguinte comando: + +------------------------------------------------ +$ gitk HEAD..FETCH_HEAD +------------------------------------------------ + +Isto usa a mesma notação de intervalo que vimos antes com 'git log'. + +Alice pode querer ver o que ambos fizeram desde que ramificaram. Ela +pode usar a forma com três pontos ao invés da forma com dois pontos: + +------------------------------------------------ +$ gitk HEAD...FETCH_HEAD +------------------------------------------------ + +Isto significa "mostre tudo que é alcançável de qualquer um deles, mas +exclua tudo que é alcançável a partir de ambos". + +Por favor, note que essas notações de intervalo podem ser usadas tanto +com gitk quanto com "git log". + +Após inspecionar o que Bob fez, se não há nada urgente, Alice pode +decidir continuar trabalhando sem puxar de Bob. Se a história de Bob +tem alguma coisa que Alice precisa imediatamente, Alice pode optar por +separar seu trabalho em progresso primeiro, fazer um "pull", e, então, +finalmente, retomar seu trabalho em progresso em cima da história +resultante. + +Quando você está trabalhando em um pequeno grupo unido, não é incomum +interagir com o mesmo repositório várias e várias vezes. Definindo um +repositório remoto antes de tudo, você pode fazê-lo mais facilmente: + +------------------------------------------------ +alice$ git remote add bob /home/bob/myrepo +------------------------------------------------ + +Com isso, Alice pode executar a primeira parte da operação "pull" usando +o comando 'git-fetch' sem unificar suas mudanças com seu próprio ramo, +usando: + +------------------------------------- +alice$ git fetch bob +------------------------------------- + +Diferente da forma longa, quando Alice obteve de Bob usando um +repositório remoto antes definido com 'git-remote', o que foi obtido é +armazenado em um ramo remoto, neste caso `bob/master`. Então, após isso: + +------------------------------------- +alice$ git log -p master..bob/master +------------------------------------- + +mostra uma lista de todas as mudanças que Bob fez desde que ramificou do +ramo master de Alice. + +Após examinar essas mudanças, Alice pode unificá-las em seu ramo master: + +------------------------------------- +alice$ git merge bob/master +------------------------------------- + +Esse `merge` pode também ser feito puxando de seu próprio ramo remoto, +assim: + +------------------------------------- +alice$ git pull . remotes/bob/master +------------------------------------- + +Note que 'git pull' sempre unifica ao ramo atual, independente do que +mais foi passado na linha de comando. + +Depois, Bob pode atualizar seu repositório com as últimas mudanças de +Alice, usando + +------------------------------------- +bob$ git pull +------------------------------------- + +Note que ele não precisa dar o caminho do repositório de Alice; quando +Bob clonou seu repositório, o git armazenou a localização de seu +repositório na configuração do mesmo, e essa localização é usada +para puxar: + +------------------------------------- +bob$ git config --get remote.origin.url +/home/alice/project +------------------------------------- + +(A configuração completa criada por 'git-clone' é visÃvel usando `git +config -l`, e a página de manual linkgit:git-config[1] explica o +significado de cada opção.) + +Git também mantém uma cópia limpa do ramo master de Alice sob o nome +"origin/master": + +------------------------------------- +bob$ git branch -r + origin/master +------------------------------------- + +Se Bob decidir depois em trabalhar em um host diferente, ele ainda pode +executar clones e puxar usando o protocolo ssh: + +------------------------------------- +bob$ git clone alice.org:/home/alice/project myrepo +------------------------------------- + +Alternativamente, o git tem um protocolo nativo, ou pode usar rsync ou +http; veja linkgit:git-pull[1] para detalhes. + +Git pode também ser usado em um modo parecido com CVS, com um +repositório central para o qual vários usuários empurram modificações; +veja linkgit:git-push[1] e linkgit:gitcvs-migration[7]. + +Explorando história +----------------- + +A história no git é representada como uma série de commits +interrelacionados. Nós já vimos que o comando 'git-log' pode listar +esses commits. Note que a primeira linha de cada entrada no log também +dá o nome para o commit: + +------------------------------------- +$ git log +commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 +Author: Junio C Hamano <junkio@cox.net> +Date: Tue May 16 17:18:22 2006 -0700 + + merge-base: Clarify the comments on post processing. +------------------------------------- + +Nós podemos dar este nome ao 'git-show' para ver os detalhes sobre este +commit. + +------------------------------------- +$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 +------------------------------------- + +Mas há outras formas de se referir aos commits. Você pode usar qualquer +parte inicial do nome que seja longo o bastante para identificar +unicamente o commit: + +------------------------------------- +$ git show c82a22c39c # os primeiros caracteres do nome são o bastante + # usualmente +$ git show HEAD # a ponta do ramo atual +$ git show experimental # a ponta do ramo "experimental" +------------------------------------- + +Todo commit normalmente tem um commit "pai" que aponta para o estado +anterior do projeto: + +------------------------------------- +$ git show HEAD^ # para ver o pai de HEAD +$ git show HEAD^^ # para ver o avô de HEAD +$ git show HEAD~4 # para ver o trisavô de HEAD +------------------------------------- + +Note que commits de unificação podem ter mais de um pai: + +------------------------------------- +$ git show HEAD^1 # mostra o primeiro pai de HEAD (o mesmo que HEAD^) +$ git show HEAD^2 # mostra o segundo pai de HEAD +------------------------------------- + +Você também pode dar aos commits nomes à sua escolha; após executar + +------------------------------------- +$ git tag v2.5 1b2e1d63ff +------------------------------------- + +você pode se referir a 1b2e1d63ff pelo nome "v2.5". Se você pretende +compartilhar esse nome com outras pessoas (por exemplo, para identificar +uma versão de lançamento), você deveria criar um objeto "tag", e talvez +assiná-lo; veja linkgit:git-tag[1] para detalhes. + +Qualquer comando git que precise conhecer um commit pode receber +quaisquer desses nomes. Por exemplo: + +------------------------------------- +$ git diff v2.5 HEAD # compara o HEAD atual com v2.5 +$ git branch stable v2.5 # inicia um novo ramo chamado "stable" baseado + # em v2.5 +$ git reset --hard HEAD^ # reseta seu ramo atual e seu diretório de + # trabalho a seu estado em HEAD^ +------------------------------------- + +Seja cuidadoso com o último comando: além de perder quaisquer mudanças +em seu diretório de trabalho, ele também remove todos os commits +posteriores desse ramo. Se esse ramo é o único ramo contendo esses +commits, eles serão perdidos. Também, não use 'git-reset' num ramo +publicamente visÃvel de onde outros desenvolvedores puxam, já que vai +forçar unificações desnecessárias para que outros desenvolvedores limpem +a história. Se você precisa desfazer mudanças que você empurrou, use +'git-revert' no lugar. + +O comando 'git-grep' pode buscar strings em qualquer versão de seu +projeto, então + +------------------------------------- +$ git grep "hello" v2.5 +------------------------------------- + +procura por todas as ocorrências de "hello" em v2.5. + +Se você deixar de fora o nome do commit, 'git-grep' irá procurar +quaisquer dos arquivos que ele gerencia no diretório corrente. Então + +------------------------------------- +$ git grep "hello" +------------------------------------- + +é uma forma rápida de buscar somente os arquivos que são rastreados pelo +git. + +Muitos comandos git também recebem um conjunto de commits, o que pode +ser especificado de várias formas. Aqui estão alguns exemplos com 'git-log': + +------------------------------------- +$ git log v2.5..v2.6 # commits entre v2.5 e v2.6 +$ git log v2.5.. # commits desde v2.5 +$ git log --since="2 weeks ago" # commits das últimas 2 semanas +$ git log v2.5.. Makefile # commits desde v2.5 que modificam + # Makefile +------------------------------------- + +Você também pode dar ao 'git-log' um "intervalo" de commits onde o +primeiro não é necessariamente um ancestral do segundo; por exemplo, se +as pontas dos ramos "stable" e "master" divergiram de um commit +comum algum tempo atrás, então + +------------------------------------- +$ git log stable..master +------------------------------------- + +irá listar os commits feitos no ramo "master" mas não no ramo +"stable", enquanto + +------------------------------------- +$ git log master..stable +------------------------------------- + +irá listar a lista de commits feitos no ramo "stable" mas não no ramo +"master". + +O comando 'git-log' tem uma fraqueza: ele precisa mostrar os commits em +uma lista. Quando a história tem linhas de desenvolvimento que +divergiram e então foram unificadas novamente, a ordem em que 'git-log' +apresenta essas mudanças é irrelevante. + +A maioria dos projetos com múltiplos contribuidores (como o kernel +Linux, ou o próprio git) tem unificações frequentes, e 'gitk' faz um +trabalho melhor de visualizar sua história. Por exemplo, + +------------------------------------- +$ gitk --since="2 weeks ago" drivers/ +------------------------------------- + +permite a você navegar em quaisquer commits desde as últimas duas semanas +de commits que modificaram arquivos sob o diretório "drivers". (Nota: +você pode ajustar as fontes do gitk segurando a tecla control enquanto +pressiona "-" ou "+".) + +Finalmente, a maioria dos comandos que recebem nomes de arquivo permitirão +também, opcionalmente, preceder qualquer nome de arquivo por um +commit, para especificar uma versão particular do arquivo: + +------------------------------------- +$ git diff v2.5:Makefile HEAD:Makefile.in +------------------------------------- + +Você pode usar 'git-show' para ver tal arquivo: + +------------------------------------- +$ git show v2.5:Makefile +------------------------------------- + +Próximos passos +---------- + +Este tutorial deve ser o bastante para operar controle de revisão +distribuÃdo básico para seus projetos. No entanto, para entender +plenamente a profundidade e o poder do git você precisa entender duas +idéias simples nas quais ele se baseia: + + * A base de objetos é um sistema bem elegante usado para armazenar a + história de seu projeto--arquivos, diretórios, e commits. + + * O arquivo de Ãndice é um cache do estado de uma árvore de diretório, + usado para criar commits, restaurar diretórios de trabalho, e + armazenar as várias árvores envolvidas em uma unificação. + +A parte dois deste tutorial explica a base de objetos, o arquivo de +Ãndice, e algumas outras coisinhas que você vai precisar pra usar o +máximo do git. Você pode encontrá-la em linkgit:gittutorial-2[7]. + +Se você não quiser continuar com o tutorial agora nesse momento, algumas +outras digressões que podem ser interessantes neste ponto são: + + * linkgit:git-format-patch[1], linkgit:git-am[1]: Estes convertem + séries de commits em patches para email, e vice-versa, úteis para + projetos como o kernel Linux que dependem fortemente de patches + enviados por email. + + * linkgit:git-bisect[1]: Quando há uma regressão em seu projeto, uma + forma de rastrear um bug é procurando pela história para encontrar o + commit culpado. Git bisect pode ajudar a executar uma busca binária + por esse commit. Ele é inteligente o bastante para executar uma + busca próxima da ótima mesmo no caso de uma história complexa + não-linear com muitos ramos unificados. + + * link:everyday.html[GIT diariamente com 20 e tantos comandos] + + * linkgit:gitcvs-migration[7]: Git para usuários de CVS. + +VEJA TAMBÉM +-------- +linkgit:gittutorial-2[7], +linkgit:gitcvs-migration[7], +linkgit:gitcore-tutorial[7], +linkgit:gitglossary[7], +linkgit:git-help[1], +link:everyday.html[git diariamente], +link:user-manual.html[O Manual do Usuário git] + +GIT +--- +Parte da suite linkgit:git[1]. diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index cbee369947..94a9d32f1d 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -4,17 +4,23 @@ (see the section <<URLS,GIT URLS>> below) or the name of a remote (see the section <<REMOTES,REMOTES>> below). +ifndef::git-pull[] +<group>:: + A name referring to a list of repositories as the value + of remotes.<group> in the configuration file. + (See linkgit:git-config[1]). +endif::git-pull[] + <refspec>:: - The canonical format of a <refspec> parameter is - `+?<src>:<dst>`; that is, an optional plus `+`, followed - by the source ref, followed by a colon `:`, followed by - the destination ref. + The format of a <refspec> parameter is an optional plus + `+`, followed by the source ref <src>, followed + by a colon `:`, followed by the destination ref <dst>. + The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local -ref that matches it is fast forwarded using <src>. -Again, if the optional plus `+` is used, the local ref -is updated even if it does not result in a fast forward +ref that matches it is fast-forwarded using <src>. +If the optional plus `+` is used, the local ref +is updated even if it does not result in a fast-forward update. + [NOTE] @@ -32,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 @@ -44,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 37dd1d61ea..1ae3c899ef 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -1,171 +1,54 @@ -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}:: - - 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=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. - -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 line 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. - -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 hunks that show differences from only - one parent, or show the same change from all but one parent for - an Octopus merge. - --r:: - - Show recursive diffs. - --t:: - - Show the tree objects in the diff output. This implies '-r'. - 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':: +--max-count=<number>:: - Limit the number of commits output. + Limit the number of commits to output. ---skip='number':: +--skip=<number>:: Skip 'number' commits before starting to show the commit output. ---since='date':: ---after='date':: +--since=<date>:: +--after=<date>:: Show commits more recent than a specific date. ---until='date':: ---before='date':: +--until=<date>:: +--before=<date>:: Show commits older than a specific date. ifdef::git-rev-list[] ---max-age='timestamp':: ---min-age='timestamp':: +--max-age=<timestamp>:: +--min-age=<timestamp>:: Limit the commits output to specified time range. endif::git-rev-list[] ---author='pattern':: ---committer='pattern':: +--author=<pattern>:: +--committer=<pattern>:: Limit the commits output to ones with author/committer header lines that match the specified pattern (regular expression). ---grep='pattern':: +--grep=<pattern>:: Limit the commits output to ones with log message that matches the specified pattern (regular expression). +--all-match:: + Limit the commits output to ones that match all given --grep, + --author and --committer instead of ones that match at least one. + -i:: --regexp-ignore-case:: @@ -187,17 +70,28 @@ endif::git-rev-list[] Stop when a given path disappears from the tree. ---full-history:: +--merges:: - Show also parts of history irrelevant to current state of a given - path. This turns off history simplification, which removed merges - which didn't change anything at all at some child. It will still actually - simplify away merges that didn't change anything at all into either - child. + 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 @@ -215,15 +109,58 @@ 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>'. -ifdef::git-rev-list[] +--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 '?', + '{asterisk}', or '[', '/{asterisk}' 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 '?', '{asterisk}', + or '[', '/{asterisk}' at the end is implied. + +--remotes[=<pattern>]:: + + 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 '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. + +--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 '?', '{asterisk}', + or '[', '/{asterisk}' at the end is implied. + +--ignore-missing:: + + 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 `refs/bisect/bad` + was listed and as if it was followed by `--not` and the good + bisection refs `refs/bisect/good-*` on the command + line. +endif::git-rev-list[] + --stdin:: In addition to the '<commit>' listed on the command - line, read them from the standard input. + line, read them from the standard input. If a '--' separator is + seen, stop reading commits and start reading paths to limit the + result. +ifdef::git-rev-list[] --quiet:: Don't print anything to standard output. This form @@ -233,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 @@ -241,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 `+` 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:: @@ -254,17 +217,16 @@ 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 taken from the reflog. By default, 'commit@\{Nth}' notation is used in the output. When the starting commit is specified as -'commit@{now}', output also uses 'commit@\{timestamp}' notation +'commit@\{now}', output also uses 'commit@\{timestamp}' notation instead. Under '\--pretty=oneline', the commit message is prefixed with this information on the same line. - -Cannot be combined with '\--reverse'. +This option cannot be combined with '\--reverse'. See also linkgit:git-reflog[1]. --merge:: @@ -277,32 +239,302 @@ See also linkgit:git-reflog[1]. Output uninteresting commits at the boundary, which are usually not shown. +-- + +History Simplification +~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes you are only interested in parts of the history, for example the +commits modifying a particular <path>. But there are two parts of +'History Simplification', one part is selecting the commits and the other +is how to do it, as there are various strategies to simplify the history. + +The following options select the commits to be shown: + +<paths>:: + + Commits modifying the given <paths> are selected. + +--simplify-by-decoration:: + + Commits that are referred by some branch or tag are selected. + +Note that extra commits can be shown to give a meaningful history. + +The following options affect the way the simplification is performed: + +Default mode:: + + Simplifies the history to the simplest history explaining the + final state of the tree. Simplest because it prunes some side + branches if the end result is the same (i.e. merging branches + with the same content) + +--full-history:: + + Same as the default mode, but does not prune some history. + +--dense:: + + Only the selected commits are shown, plus some to have a + meaningful history. + +--sparse:: + + All commits in the simplified history are shown. + +--simplify-merges:: + + Additional option to '--full-history' to remove some needless + 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 +that modify `foo` !TREESAME, and the rest TREESAME. (In a diff +filtered for `foo`, they look different and equal, respectively.) + +In the following, we will always refer to the same example history to +illustrate the differences between simplification settings. We assume +that you are filtering for a file `foo` in this commit graph: +----------------------------------------------------------------------- + .-A---M---N---O---P + / / / / / + I B C D E + \ / / / / + `-------------' +----------------------------------------------------------------------- +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 + "asdf", and a file `quux` exists with contents "quux". Initial + commits are compared to an empty tree, so `I` is !TREESAME. + +* In `A`, `foo` contains just "foo". + +* `B` contains the same change as `A`. Its merge `M` is trivial and + hence TREESAME to all parents. + +* `C` does not change `foo`, but its merge `N` changes it to "foobar", + so it is not TREESAME to any parent. + +* `D` sets `foo` to "baz". Its merge `O` combines the strings from + `N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent. + +* `E` changes `quux` to "xyzzy", and its merge `P` combines the + strings to "quux xyzzy". Despite appearing interesting, `P` is + TREESAME to all parents. + +'rev-list' walks backwards through history, including or excluding +commits based on whether '\--full-history' and/or parent rewriting +(via '\--parents' or '\--children') are used. The following settings +are available. + +Default mode:: + + Commits are included if they are not TREESAME to any parent + (though this can be changed, see '\--sparse' below). If the + commit was a merge, and it was TREESAME to one parent, follow + only that parent. (Even if there are several TREESAME + parents, follow only one of them.) Otherwise, follow all + parents. ++ +This results in: ++ +----------------------------------------------------------------------- + .-A---N---O + / / / + I---------D +----------------------------------------------------------------------- ++ +Note how the rule to only follow the TREESAME parent, if one is +available, removed `B` from consideration entirely. `C` was +considered via `N`, but is TREESAME. Root commits are compared to an +empty tree, so `I` is !TREESAME. ++ +Parent/child relations are only visible with --parents, but that does +not affect the commits selected in default mode, so we have shown the +parent lines. + +--full-history without parent rewriting:: + + This mode differs from the default in one point: always follow + all parents of a merge, even if it is TREESAME to one of them. + Even if more than one side of the merge has commits that are + included, this does not imply that the merge itself is! In + the example, we get ++ +----------------------------------------------------------------------- + I A B N D O +----------------------------------------------------------------------- ++ +`P` and `M` were excluded because they are TREESAME to a parent. `E`, +`C` and `B` were all walked, but only `B` was !TREESAME, so the others +do not appear. ++ +Note that without parent rewriting, it is not really possible to talk +about the parent/child relationships between the commits, so we show +them disconnected. + +--full-history with parent rewriting:: + + Ordinary commits are only included if they are !TREESAME + (though this can be changed, see '\--sparse' below). ++ +Merges are always included. However, their parent list is rewritten: +Along each parent, prune away commits that are not included +themselves. This results in ++ +----------------------------------------------------------------------- + .-A---M---N---O---P + / / / / / + I B / D / + \ / / / / + `-------------' +----------------------------------------------------------------------- ++ +Compare to '\--full-history' without rewriting above. Note that `E` +was pruned away because it is TREESAME, but the parent list of P was +rewritten to contain `E`'s parent `I`. The same happened for `C` and +`N`. Note also that `P` was included despite being TREESAME. + +In addition to the above settings, you can change whether TREESAME +affects inclusion: + --dense:: + + Commits that are walked are included if they are not TREESAME + to any parent. + --sparse:: -When optional paths are given, the default behaviour ('--dense') is to -only output commits that changes at least one of them, and also ignore -merges that do not touch the given paths. + All commits that are walked are included. ++ +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. + +--simplify-merges:: + + First, build a history graph in the same way that + '\--full-history' with parent rewriting does (see above). ++ +Then simplify each commit `C` to its replacement `C'` in the final +history according to the following rules: ++ +-- +* Set `C'` to `C`. ++ +* Replace each parent `P` of `C'` with its simplification `P'`. In + the process, drop parents that are ancestors of other parents, and + remove duplicates. ++ +* If after this parent rewriting, `C'` is a root or merge commit (has + zero or >1 parents), a boundary commit, or !TREESAME, it remains. + Otherwise, it is replaced with its only parent. +-- ++ +The effect of this is best shown by way of comparing to +'\--full-history' with parent rewriting. The example turns into: ++ +----------------------------------------------------------------------- + .-A---M---N---O + / / / + I B D + \ / / + `---------' +----------------------------------------------------------------------- ++ +Note the major differences in `N` and `P` over '--full-history': ++ +-- +* `N`'s parent list had `I` removed, because it is an ancestor of the + other parent `M`. Still, `N` remained because it is !TREESAME. ++ +* `P`'s parent list similarly had `I` removed. `P` was then + 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 +----------------------------------------------------------------------- -Use the '--sparse' flag to makes the command output all eligible commits -(still subject to count and age limitation), but apply merge -simplification nevertheless. +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 +(in other words, kept after history simplification rules described +above) if (1) they are referenced by tags, or (2) they change the +contents of the paths given on the command line. All other +commits are marked as TREESAME (subject to be simplified away). ifdef::git-rev-list[] +Bisection Helpers +~~~~~~~~~~~~~~~~~ + --bisect:: Limit output to the one commit object which is roughly halfway between -the included and excluded commits. Thus, if +included and excluded commits. Note that the bad bisection ref +`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 `refs/bisect/`, if ----------------------------------------------------------------------- - $ git-rev-list --bisect foo ^bar ^baz + $ git rev-list --bisect foo ^bar ^baz ----------------------------------------------------------------------- outputs 'midpoint', the output of the two commands ----------------------------------------------------------------------- - $ git-rev-list foo ^midpoint - $ git-rev-list midpoint ^bar ^baz + $ git rev-list foo ^midpoint + $ git rev-list midpoint ^bar ^baz ----------------------------------------------------------------------- would be of roughly the same length. Finding the change which @@ -312,33 +544,34 @@ one. --bisect-vars:: -This calculates the same as `--bisect`, but 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 to `bisect_nr`, the expected number of commits to be -tested if `bisect_rev` turns out to be good to `bisect_good`, -the expected number of commits to be tested if `bisect_rev` -turns out to be bad to `bisect_bad`, and the number of commits -we are bisecting right now to `bisect_all`. +This calculates the same as `--bisect`, except that refs in +`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 +to `bisect_nr`, the expected number of commits to be tested if +`bisect_rev` turns out to be good to `bisect_good`, the expected +number of commits to be tested if `bisect_rev` turns out to be bad to +`bisect_bad`, and the number of commits we are bisecting right now to +`bisect_all`. --bisect-all:: This outputs all the commit objects between the included and excluded commits, ordered by their distance to the included and excluded -commits. The farthest from them is displayed first. (This is the only -one displayed by `--bisect`.) - +commits. Refs in `refs/bisect/` are not used. The farthest +from them is displayed first. (This is the only one displayed by +`--bisect`.) ++ This is useful because it makes it easy to choose a good commit to test when you want to avoid to test some of them for some reason (they may not compile for example). - ++ This option can be used along with `--bisect-vars`, in this case, after all the sorted commit objects, there will be the same text as if `--bisect-vars` had been used alone. endif::git-rev-list[] --- Commit Ordering ~~~~~~~~~~~~~~~ @@ -393,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..1725661837 --- /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 ancestor 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..5747f442f2 --- /dev/null +++ b/Documentation/sequencer.txt @@ -0,0 +1,12 @@ +--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. + +--quit:: + Forget about the current operation in progress. Can be used + to clear the sequencer state after a failed cherry-pick or + revert. + +--abort:: + Cancel the operation and return to the pre-sequence state. diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt new file mode 100644 index 0000000000..1b7d8f140c --- /dev/null +++ b/Documentation/technical/api-argv-array.txt @@ -0,0 +1,51 @@ +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_pushl`:: + Push a list of strings onto the end of the array. The arguments + should be a list of `const char *` strings, terminated by a NULL + argument. + +`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 52cdb4c520..b0cafe87be 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -4,7 +4,7 @@ builtin API Adding a new built-in --------------------- -There are 4 things to do to add a bulit-in command implementation to +There are 4 things to do to add a built-in command implementation to git: . Define the implementation of the built-in command `foo` with @@ -18,8 +18,8 @@ git: defined in `git.c`. The entry should look like: { "foo", cmd_foo, <options> }, - - where options is the bitwise-or of: ++ +where options is the bitwise-or of: `RUN_SETUP`:: @@ -33,6 +33,12 @@ git: If the standard output is connected to a tty, spawn a pager and feed our output to it. +`NEED_WORK_TREE`:: + + Make sure there is a work tree, i.e. the command cannot act + on bare repositories. + This only makes sense when `RUN_SETUP` is also set. + . Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. Additionally, if `foo` is a new command, there are 3 more things to do: @@ -41,8 +47,9 @@ Additionally, if `foo` is a new command, there are 3 more things to do: . Write documentation in `Documentation/git-foo.txt`. -. Add an entry for `git-foo` to the list at the end of - `Documentation/cmd-list.perl`. +. 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-config.txt b/Documentation/technical/api-config.txt new file mode 100644 index 0000000000..edf8dfb99b --- /dev/null +++ b/Documentation/technical/api-config.txt @@ -0,0 +1,140 @@ +config API +========== + +The config API gives callers a way to access git configuration files +(and files which have the same syntax). See linkgit:git-config[1] for a +discussion of the config file syntax. + +General Usage +------------- + +Config files are parsed linearly, and each variable found is passed to a +caller-provided callback function. The callback function is responsible +for any actions to be taken on the config option, and is free to ignore +some options. It is not uncommon for the configuration to be parsed +several times during the run of a git program, with different callbacks +picking out different variables useful to themselves. + +A config callback function takes three parameters: + +- the name of the parsed variable. This is in canonical "flat" form: the + section, subsection, and variable segments will be separated by dots, + and the section and variable segments will be all lowercase. E.g., + `core.ignorecase`, `diff.SomeType.textconv`. + +- the value of the found variable, as a string. If the variable had no + value specified, the value will be NULL (typically this means it + should be interpreted as boolean true). + +- a void pointer passed in by the caller of the config API; this can + contain callback-specific data + +A config callback should return 0 for success, or -1 if the variable +could not be parsed properly. + +Basic Config Querying +--------------------- + +Most programs will simply want to look up variables in all config files +that git knows about, using the normal precedence rules. To do this, +call `git_config` with a callback function and void data pointer. + +`git_config` will read all config sources in order of increasing +priority. Thus a callback should typically overwrite previously-seen +entries with new ones (e.g., if both the user-wide `~/.gitconfig` and +repo-specific `.git/config` contain `color.ui`, the config machinery +will first feed the user-wide one to the callback, and then the +repo-specific one; by overwriting, the higher-priority repo-specific +value is left at the end). + +The `git_config_with_options` function lets the caller examine config +while adjusting some of the default behavior of `git_config`. It should +almost never be used by "regular" git code that is looking up +configuration variables. It is intended for advanced callers like +`git-config`, which are intentionally tweaking the normal config-lookup +process. It takes two extra parameters: + +`filename`:: +If this parameter is non-NULL, it specifies the name of a file to +parse for configuration, rather than looking in the usual files. Regular +`git_config` defaults to `NULL`. + +`respect_includes`:: +Specify whether include directives should be followed in parsed files. +Regular `git_config` defaults to `1`. + +There is a special version of `git_config` called `git_config_early`. +This version takes an additional parameter to specify the repository +config, instead of having it looked up via `git_path`. This is useful +early in a git program before the repository has been found. Unless +you're working with early setup code, you probably don't want to use +this. + +Reading Specific Files +---------------------- + +To read a specific file in git-config format, use +`git_config_from_file`. This takes the same callback and data parameters +as `git_config`. + +Value Parsing Helpers +--------------------- + +To aid in parsing string values, the config API provides callbacks with +a number of helper functions, including: + +`git_config_int`:: +Parse the string to an integer, including unit factors. Dies on error; +otherwise, returns the parsed result. + +`git_config_ulong`:: +Identical to `git_config_int`, but for unsigned longs. + +`git_config_bool`:: +Parse a string into a boolean value, respecting keywords like "true" and +"false". Integer values are converted into true/false values (when they +are non-zero or zero, respectively). Other values cause a die(). If +parsing is successful, the return value is the result. + +`git_config_bool_or_int`:: +Same as `git_config_bool`, except that integers are returned as-is, and +an `is_bool` flag is unset. + +`git_config_maybe_bool`:: +Same as `git_config_bool`, except that it returns -1 on error rather +than dying. + +`git_config_string`:: +Allocates and copies the value string into the `dest` parameter; if no +string is given, prints an error message and returns -1. + +`git_config_pathname`:: +Similar to `git_config_string`, but expands `~` or `~user` into the +user's home directory when found at the beginning of the path. + +Include Directives +------------------ + +By default, the config parser does not respect include directives. +However, a caller can use the special `git_config_include` wrapper +callback to support them. To do so, you simply wrap your "real" callback +function and data pointer in a `struct config_include_data`, and pass +the wrapper to the regular config-reading functions. For example: + +------------------------------------------- +int read_file_with_include(const char *file, config_fn_t fn, void *data) +{ + struct config_include_data inc = CONFIG_INCLUDE_INIT; + inc.fn = fn; + inc.data = data; + return git_config_from_file(git_config_include, file, &inc); +} +------------------------------------------- + +`git_config` respects includes automatically. The lower-level +`git_config_from_file` does not. + +Writing Config Files +-------------------- + +TODO diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt new file mode 100644 index 0000000000..4ef1db39ab --- /dev/null +++ b/Documentation/technical/api-credentials.txt @@ -0,0 +1,298 @@ +credentials API +=============== + +The credentials API provides an abstracted way of gathering username and +password credentials from the user (even though credentials in the wider +world can take many forms, in this document the word "credential" always +refers to a username and password pair). + +This document describes two interfaces: the C API that the credential +subsystem provides to the rest of git, and the protocol that git uses to +communicate with system-specific "credential helpers". If you are +writing git code that wants to look up or prompt for credentials, see +the section "C API" below. If you want to write your own helper, see +the section on "Credential Helpers" below. + +Typical setup +------------- + +------------ ++-----------------------+ +| git code (C) |--- to server requiring ---> +| | authentication +|.......................| +| C credential API |--- prompt ---> User ++-----------------------+ + ^ | + | pipe | + | v ++-----------------------+ +| git credential helper | ++-----------------------+ +------------ + +The git code (typically a remote-helper) will call the C API to obtain +credential data like a login/password pair (credential_fill). The +API will itself call a remote helper (e.g. "git credential-cache" or +"git credential-store") that may retrieve credential data from a +store. If the credential helper cannot find the information, the C API +will prompt the user. Then, the caller of the API takes care of +contacting the server, and does the actual authentication. + +C API +----- + +The credential C API is meant to be called by git code which needs to +acquire or store a credential. It is centered around an object +representing a single credential and provides three basic operations: +fill (acquire credentials by calling helpers and/or prompting the user), +approve (mark a credential as successfully used so that it can be stored +for later use), and reject (mark a credential as unsuccessful so that it +can be erased from any persistent storage). + +Data Structures +~~~~~~~~~~~~~~~ + +`struct credential`:: + + This struct represents a single username/password combination + along with any associated context. All string fields should be + heap-allocated (or NULL if they are not known or not applicable). + The meaning of the individual context fields is the same as + their counterparts in the helper protocol; see the section below + for a description of each field. ++ +The `helpers` member of the struct is a `string_list` of helpers. Each +string specifies an external helper which will be run, in order, to +either acquire or store credentials. See the section on credential +helpers below. ++ +This struct should always be initialized with `CREDENTIAL_INIT` or +`credential_init`. + + +Functions +~~~~~~~~~ + +`credential_init`:: + + Initialize a credential structure, setting all fields to empty. + +`credential_clear`:: + + Free any resources associated with the credential structure, + returning it to a pristine initialized state. + +`credential_fill`:: + + Instruct the credential subsystem to fill the username and + password fields of the passed credential struct by first + consulting helpers, then asking the user. After this function + returns, the username and password fields of the credential are + guaranteed to be non-NULL. If an error occurs, the function will + die(). + +`credential_reject`:: + + Inform the credential subsystem that the provided credentials + have been rejected. This will cause the credential subsystem to + notify any helpers of the rejection (which allows them, for + example, to purge the invalid credentials from storage). It + will also free() the username and password fields of the + credential and set them to NULL (readying the credential for + another call to `credential_fill`). Any errors from helpers are + ignored. + +`credential_approve`:: + + Inform the credential subsystem that the provided credentials + were successfully used for authentication. This will cause the + credential subsystem to notify any helpers of the approval, so + that they may store the result to be used again. Any errors + from helpers are ignored. + +`credential_from_url`:: + + Parse a URL into broken-down credential fields. + +Example +~~~~~~~ + +The example below shows how the functions of the credential API could be +used to login to a fictitious "foo" service on a remote host: + +----------------------------------------------------------------------- +int foo_login(struct foo_connection *f) +{ + int status; + /* + * Create a credential with some context; we don't yet know the + * username or password. + */ + + struct credential c = CREDENTIAL_INIT; + c.protocol = xstrdup("foo"); + c.host = xstrdup(f->hostname); + + /* + * Fill in the username and password fields by contacting + * helpers and/or asking the user. The function will die if it + * fails. + */ + credential_fill(&c); + + /* + * Otherwise, we have a username and password. Try to use it. + */ + status = send_foo_login(f, c.username, c.password); + switch (status) { + case FOO_OK: + /* It worked. Store the credential for later use. */ + credential_accept(&c); + break; + case FOO_BAD_LOGIN: + /* Erase the credential from storage so we don't try it + * again. */ + credential_reject(&c); + break; + default: + /* + * Some other error occured. We don't know if the + * credential is good or bad, so report nothing to the + * credential subsystem. + */ + } + + /* Free any associated resources. */ + credential_clear(&c); + + return status; +} +----------------------------------------------------------------------- + + +Credential Helpers +------------------ + +Credential helpers are programs executed by git to fetch or save +credentials from and to long-term storage (where "long-term" is simply +longer than a single git process; e.g., credentials may be stored +in-memory for a few minutes, or indefinitely on disk). + +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:git-config[1]). +The string is transformed by git into a command to be executed using +these rules: + + 1. If the helper string begins with "!", it is considered a shell + snippet, and everything after the "!" becomes the command. + + 2. Otherwise, if the helper string begins with an absolute path, the + verbatim helper string becomes the command. + + 3. Otherwise, the string "git credential-" is prepended to the helper + string, and the result becomes the command. + +The resulting command then has an "operation" argument appended to it +(see below for details), and the result is executed by the shell. + +Here are some example specifications: + +---------------------------------------------------- +# run "git credential-foo" +foo + +# same as above, but pass an argument to the helper +foo --bar=baz + +# the arguments are parsed by the shell, so use shell +# quoting if necessary +foo --bar="whitespace arg" + +# you can also use an absolute path, which will not use the git wrapper +/path/to/my/helper --with-arguments + +# or you can specify your own shell snippet +!f() { echo "password=`cat $HOME/.secret`"; }; f +---------------------------------------------------- + +Generally speaking, rule (3) above is the simplest for users to specify. +Authors of credential helpers should make an effort to assist their +users by naming their program "git-credential-$NAME", and putting it in +the $PATH or $GIT_EXEC_PATH during installation, which will allow a user +to enable it with `git config credential.helper $NAME`. + +When a helper is executed, it will have one "operation" argument +appended to its command line, which is one of: + +`get`:: + + Return a matching credential, if any exists. + +`store`:: + + Store the credential, if applicable to the helper. + +`erase`:: + + Remove a matching credential, if any, from the helper's storage. + +The details of the credential will be provided on the helper's stdin +stream. The credential is split into a set of named attributes. +Attributes are provided to the helper, one per line. Each attribute is +specified by a key-value pair, separated by an `=` (equals) sign, +followed by a newline. The key may contain any bytes except `=`, +newline, or NUL. The value may contain any bytes except newline or NUL. +In both cases, all bytes are treated as-is (i.e., there is no quoting, +and one cannot transmit a value with newline or NUL in it). The list of +attributes is terminated by a blank line or end-of-file. + +Git will send the following attributes (but may not send all of +them for a given credential; for example, a `host` attribute makes no +sense when dealing with a non-network protocol): + +`protocol`:: + + The protocol over which the credential will be used (e.g., + `https`). + +`host`:: + + The remote hostname for a network credential. + +`path`:: + + The path with which the credential will be used. E.g., for + accessing a remote https repository, this will be the + repository's path on the server. + +`username`:: + + The credential's username, if we already have one (e.g., from a + URL, from the user, or from a previously run helper). + +`password`:: + + The credential's password, if we are asking it to be stored. + +For a `get` operation, the helper should produce a list of attributes +on stdout in the same format. A helper is free to produce a subset, or +even no values at all if it has nothing useful to provide. Any provided +attributes will overwrite those already known about by git. + +For a `store` or `erase` operation, the helper's output is ignored. +If it fails to perform the requested operation, it may complain to +stderr to inform the user. If it does not support the requested +operation (e.g., a read-only store), it should silently ignore the +request. + +If a helper receives any other operation, it should silently ignore the +request. This leaves room for future operations to be added (older +helpers will just ignore the new requests). + +See also +-------- + +linkgit:gitcredentials[7] + +linkgit:git-config[5] (See configuration variables `credential.*`) 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-directory-listing.txt b/Documentation/technical/api-directory-listing.txt index 5bbd18f020..add6f435b5 100644 --- a/Documentation/technical/api-directory-listing.txt +++ b/Documentation/technical/api-directory-listing.txt @@ -58,6 +58,9 @@ The result of the enumeration is left in these fields:: Calling sequence ---------------- +Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE +marked. If you to exclude files, make sure you have loaded index first. + * Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, sizeof(dir))`. 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-hash.txt b/Documentation/technical/api-hash.txt index c784d3edcb..e5061e0677 100644 --- a/Documentation/technical/api-hash.txt +++ b/Documentation/technical/api-hash.txt @@ -1,6 +1,52 @@ hash API ======== -Talk about <hash.h> +The hash API is a collection of simple hash table functions. Users are expected +to implement their own hashing. -(Linus) +Data Structures +--------------- + +`struct hash_table`:: + + The hash table structure. The `array` member points to the hash table + entries. The `size` member counts the total number of valid and invalid + entries in the table. The `nr` member keeps track of the number of + valid entries. + +`struct hash_table_entry`:: + + An opaque structure representing an entry in the hash table. The `hash` + member is the entry's hash key and the `ptr` member is the entry's + value. + +Functions +--------- + +`init_hash`:: + + Initialize the hash table. + +`free_hash`:: + + Release memory associated with the hash table. + +`insert_hash`:: + + Insert a pointer into the hash table. If an entry with that hash + already exists, a pointer to the existing entry's value is returned. + Otherwise NULL is returned. This allows callers to implement + chaining, etc. + +`lookup_hash`:: + + Lookup an entry in the hash table. If an entry with that hash exists + the entry's value is returned. Otherwise NULL is returned. + +`for_each_hash`:: + + Call a function for each entry in the hash table. The function is + expected to take the entry's value as its only argument and return an + int. If the function returns a negative int the loop is aborted + immediately. Otherwise, the return value is accumulated and the sum + returned upon completion of the loop. diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt index e9559790a3..d6fc90ac7e 100644 --- a/Documentation/technical/api-history-graph.txt +++ b/Documentation/technical/api-history-graph.txt @@ -11,9 +11,6 @@ Core functions: * `graph_init()` creates a new `struct git_graph` -* `graph_release()` destroys a `struct git_graph`, and frees the memory - associated with it. - * `graph_update()` moves the graph to a new commit. * `graph_next_line()` outputs the next line of the graph into a strbuf. It @@ -134,8 +131,6 @@ while ((commit = get_revision(opts)) != NULL) { putchar(opts->diffopt.line_termination); } } - -graph_release(graph); ------------ Sample output @@ -148,22 +143,22 @@ outputting that information, if desired. ------------ * * -M +* |\ * | | | * | \ \ | \ \ -M-. \ \ +*-. \ \ |\ \ \ \ | | * | | | | | | | * | | | | | * -| | | | | M +| | | | | * | | | | | |\ | | | | | | * | * | | | | | -| | | | | M \ +| | | | | * \ | | | | | |\ | | | | | * | | | | | | | * | | | 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 b7cda94f54..3062389404 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -1,6 +1,278 @@ parse-options API ================= -Talk about <parse-options.h> +The parse-options API is used to parse and massage options in git +and to provide a usage help with consistent look. -(Pierre) +Basics +------ + +The argument vector `argv[]` may usually contain mandatory or optional +'non-option arguments', e.g. a filename or a branch, and 'options'. +Options are optional arguments that start with a dash and +that allow to change the behavior of a command. + +* There are basically three types of options: + 'boolean' options, + options with (mandatory) 'arguments' and + options with 'optional arguments' + (i.e. a boolean option that can be adjusted). + +* There are basically two forms of options: + 'Short options' consist of one dash (`-`) and one alphanumeric + character. + 'Long options' begin with two dashes (`--`) and some + alphanumeric characters. + +* Options are case-sensitive. + Please define 'lower-case long options' only. + +The parse-options API allows: + +* 'sticked' and 'separate form' of options with arguments. + `-oArg` is sticked, `-o Arg` is separate form. + `--option=Arg` is sticked, `--option Arg` is separate form. + +* Long options may be 'abbreviated', as long as the abbreviation + is unambiguous. + +* Short options may be bundled, e.g. `-a -b` can be specified as `-ab`. + +* Boolean long options can be 'negated' (or 'unset') by prepending + `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely, + options that begin with `no-` can be 'negated' by removing it. + +* Options and non-option arguments can clearly be separated using the `--` + option, e.g. `-a -b --option -- --this-is-a-file` indicates that + `--this-is-a-file` must not be processed as an option. + +Steps to parse options +---------------------- + +. `#include "parse-options.h"` + +. define a NULL-terminated + `static const char * const builtin_foo_usage[]` array + containing alternative usage strings + +. define `builtin_foo_options` array as described below + in section 'Data Structure'. + +. in `cmd_foo(int argc, const char **argv, const char *prefix)` + call + + argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags); ++ +`parse_options()` will filter out the processed options of `argv[]` and leave the +non-option arguments in `argv[]`. +`argc` is updated appropriately because of the assignment. ++ +You can also pass NULL instead of a usage array as the fifth parameter of +parse_options(), to avoid displaying a help screen with usage info and +option list. This should only be done if necessary, e.g. to implement +a limited parser for only a subset of the options that needs to be run +before the full parser, which in turn shows the full help message. ++ +Flags are the bitwise-or of: + +`PARSE_OPT_KEEP_DASHDASH`:: + Keep the `--` that usually separates options from + non-option arguments. + +`PARSE_OPT_STOP_AT_NON_OPTION`:: + Usually the whole argument vector is massaged and reordered. + Using this flag, processing is stopped at the first non-option + argument. + +`PARSE_OPT_KEEP_ARGV0`:: + Keep the first argument, which contains the program name. It's + removed from argv[] by default. + +`PARSE_OPT_KEEP_UNKNOWN`:: + Keep unknown arguments instead of erroring out. This doesn't + work for all combinations of arguments as users might expect + it to do. E.g. if the first argument in `--unknown --known` + takes a value (which we can't know), the second one is + mistakenly interpreted as a known option. Similarly, if + `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in + `--unknown value` will be mistakenly interpreted as a + non-option, not as a value belonging to the unknown option, + the parser early. That's why parse_options() errors out if + both options are set. + +`PARSE_OPT_NO_INTERNAL_HELP`:: + By default, parse_options() handles `-h`, `--help` and + `--help-all` internally, by showing a help screen. This option + turns it off and allows one to add custom handlers for these + options, or to just leave them unknown. + +Data Structure +-------------- + +The main data structure is an array of the `option` struct, +say `static struct option builtin_add_options[]`. +There are some macros to easily define options: + +`OPT__ABBREV(&int_var)`:: + Add `--abbrev[=<n>]`. + +`OPT__COLOR(&int_var, description)`:: + Add `--color[=<when>]` and `--no-color`. + +`OPT__DRY_RUN(&int_var, description)`:: + Add `-n, --dry-run`. + +`OPT__FORCE(&int_var, description)`:: + Add `-f, --force`. + +`OPT__QUIET(&int_var, description)`:: + Add `-q, --quiet`. + +`OPT__VERBOSE(&int_var, description)`:: + Add `-v, --verbose`. + +`OPT_GROUP(description)`:: + Start an option group. `description` is a short string that + describes the group or an empty string. + Start the description with an upper-case letter. + +`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. + If used, `int_var` is bitwise-ored with `mask`. + +`OPT_NEGBIT(short, long, &int_var, description, mask)`:: + Introduce a boolean option. + If used, `int_var` is bitwise-anded with the inverted `mask`. + +`OPT_SET_INT(short, long, &int_var, description, 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. + If used, set `ptr_var` to `ptr`. + +`OPT_STRING(short, long, &str_var, arg_str, description)`:: + Introduce an option with string argument. + The string argument is put into `str_var`. + +`OPT_INTEGER(short, long, &int_var, description)`:: + Introduce an option with integer argument. + The integer is put into `int_var`. + +`OPT_DATE(short, long, &int_var, description)`:: + Introduce an option with date argument, see `approxidate()`. + The timestamp is put into `int_var`. + +`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: + Introduce an option with argument. + The argument will be fed into the function given by `func_ptr` + and the result will be put into `var`. + See 'Option Callbacks' below for a more elaborate description. + +`OPT_FILENAME(short, long, &var, description)`:: + Introduce an option with a filename argument. + The filename will be prefixed by passing the filename along with + the prefix argument of `parse_options()` to `prefix_filename()`. + +`OPT_ARGUMENT(long, description)`:: + Introduce a long-option argument that will be kept in `argv[]`. + +`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: + Recognize numerical options like -123 and feed the integer as + if it was an argument to the function given by `func_ptr`. + The result will be put into `var`. There can be only one such + option definition. It cannot be negated and it takes no + 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), + +* `long` is a string for the long option + (e.g. `"example"` for `--example`, use `NULL` to omit), + +* `int_var` is an integer variable, + +* `str_var` is a string variable (`char *`), + +* `arg_str` is the string that is shown as argument + (e.g. `"branch"` will result in `<branch>`). + If set to `NULL`, three dots (`...`) will be displayed. + +* `description` is a short string to describe the effect of the option. + It shall begin with a lower-case letter and a full stop (`.`) shall be + omitted at the end. + +Option Callbacks +---------------- + +The function must be defined in this form: + + int func(const struct option *opt, const char *arg, int unset) + +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 + use `OPT_CALLBACK()`. + 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 + value will invoke `usage_with_options()` and, thus, die. + +* If the user negates the option, `arg` is `NULL` and `unset` is 1. + +Sophisticated option parsing +---------------------------- + +If you need, for example, option callbacks with optional arguments +or without arguments at all, or if you need other special cases, +that are not handled by the macros above, you need to specify the +members of the `option` structure manually. + +This is not covered in this document, but well documented +in `parse-options.h` itself. + +Examples +-------- + +See `test-parse-options.c` and +`builtin-add.c`, +`builtin-clone.c`, +`builtin-commit.c`, +`builtin-fetch.c`, +`builtin-fsck.c`, +`builtin-rm.c` +for real-world examples. diff --git a/Documentation/technical/api-path-list.txt b/Documentation/technical/api-path-list.txt deleted file mode 100644 index 9dbedd0a67..0000000000 --- a/Documentation/technical/api-path-list.txt +++ /dev/null @@ -1,126 +0,0 @@ -path-list API -============= - -The path_list API offers a data structure and functions to handle sorted -and unsorted string lists. - -The name is a bit misleading, a path_list may store not only paths but -strings in general. - -The caller: - -. Allocates and clears a `struct path_list` variable. - -. Initializes the members. You might want to set the flag `strdup_paths` - if the strings should be strdup()ed. For example, this is necessary - when you add something like git_path("..."), since that function returns - a static buffer that will change with the next call to git_path(). -+ -If you need something advanced, you can manually malloc() the `items` -member (you need this if you add things later) and you should set the -`nr` and `alloc` members in that case, too. - -. Adds new items to the list, using `path_list_append` or `path_list_insert`. - -. Can check if a string is in the list using `path_list_has_path` or - `unsorted_path_list_has_path` and get it from the list using - `path_list_lookup` for sorted lists. - -. Can sort an unsorted list using `sort_path_list`. - -. Finally it should free the list using `path_list_clear`. - -Example: - ----- -struct path_list list; -int i; - -memset(&list, 0, sizeof(struct path_list)); -path_list_append("foo", &list); -path_list_append("bar", &list); -for (i = 0; i < list.nr; i++) - printf("%s\n", list.items[i].path) ----- - -NOTE: It is more efficient to build an unsorted list and sort it -afterwards, instead of building a sorted list (`O(n log n)` instead of -`O(n^2)`). -+ -However, if you use the list to check if a certain string was added -already, you should not do that (using unsorted_path_list_has_path()), -because the complexity would be quadratic again (but with a worse factor). - -Functions ---------- - -* General ones (works with sorted and unsorted lists as well) - -`print_path_list`:: - - Dump a path_list to stdout, useful mainly for debugging purposes. It - can take an optional header argument and it writes out the - string-pointer pairs of the path_list, each one in its own line. - -`path_list_clear`:: - - Free a path_list. The `path` pointer of the items will be freed in case - the `strdup_paths` member of the path_list is set. The second parameter - controls if the `util` pointer of the items should be freed or not. - -* Functions for sorted lists only - -`path_list_has_path`:: - - Determine if the path_list has a given string or not. - -`path_list_insert`:: - - Insert a new element to the path_list. The returned pointer can be handy - if you want to write something to the `util` pointer of the - path_list_item containing the just added string. -+ -Since this function uses xrealloc() (which die()s if it fails) if the -list needs to grow, it is safe not to check the pointer. I.e. you may -write `path_list_insert(...)->util = ...;`. - -`path_list_lookup`:: - - Look up a given string in the path_list, returning the containing - path_list_item. If the string is not found, NULL is returned. - -* Functions for unsorted lists only - -`path_list_append`:: - - Append a new string to the end of the path_list. - -`sort_path_list`:: - - Make an unsorted list sorted. - -`unsorted_path_list_has_path`:: - - It's like `path_list_has_path()` but for unsorted lists. -+ -This function needs to look through all items, as opposed to its -counterpart for sorted lists, which performs a binary search. - -Data structures ---------------- - -* `struct path_list_item` - -Represents an item of the list. The `path` member is a pointer to the -string, and you may use the `util` member for any purpose, if you want. - -* `struct path_list` - -Represents the list itself. - -. The array of items are available via the `items` member. -. The `nr` member contains the number of items stored in the list. -. The `alloc` member is used to avoid reallocating at every insertion. - You should not tamper with it. -. Setting the `strdup_paths` member to 1 will strdup() the strings - before adding them, see above. 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-remote.txt b/Documentation/technical/api-remote.txt index 073b22bd83..c54b17db69 100644 --- a/Documentation/technical/api-remote.txt +++ b/Documentation/technical/api-remote.txt @@ -18,6 +18,10 @@ struct remote An array of all of the url_nr URLs configured for the remote +`pushurl`:: + + An array of all of the pushurl_nr push URLs configured for the remote + `push`:: An array of refspecs configured for pushing, with diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt index 996da0503a..b7d0d9a8a7 100644 --- a/Documentation/technical/api-revision-walking.txt +++ b/Documentation/technical/api-revision-walking.txt @@ -56,6 +56,11 @@ function. returning a `struct commit *` each time you call it. The end of the revision list is indicated by returning a NULL pointer. +`reset_revision_walk`:: + + Reset the flags used by the revision walking api. You can use + this to do multiple sequencial revision walks. + Data structures --------------- diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 3e1342acf4..f18b4f4817 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -30,28 +30,63 @@ Functions start_command() followed by finish_command(). Takes a pointer to a `struct child_process` that specifies the details. -`run_command_v_opt`, `run_command_v_opt_dir`, `run_command_v_opt_cd_env`:: +`run_command_v_opt`, `run_command_v_opt_cd_env`:: Convenience functions that encapsulate a sequence of start_command() followed by finish_command(). The argument argv specifies the program and its arguments. The argument opt is zero - or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, or - `RUN_COMMAND_STDOUT_TO_STDERR` that correspond to the members - .no_stdin, .git_cmd, .stdout_to_stderr of `struct child_process`. + or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, + `RUN_COMMAND_STDOUT_TO_STDERR`, or `RUN_SILENT_EXEC_FAILURE` + that correspond to the members .no_stdin, .git_cmd, + .stdout_to_stderr, .silent_exec_failure of `struct child_process`. The argument dir corresponds the member .dir. The argument env corresponds to the member .env. +The functions above do the following: + +. If a system call failed, errno is set and -1 is returned. A diagnostic + is printed. + +. If the program was not found, then -1 is returned and errno is set to + 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 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 + signal number - 128, ie. it is negative and so indicates an unusual + condition; a diagnostic is printed. This return value can be passed to + exit(2), which will report the same code to the parent process that a + POSIX shell's $? would report for a program that died from the signal. + + `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`:: Wait for the completion of an asynchronous function that was started with start_async(). +`run_hook`:: + + Run a hook. + The first argument is a pathname to an index file, or NULL + if the hook uses the default index file or no index is needed. + The second argument is the name of the hook. + The further arguments correspond to the hook arguments. + The last argument has to be NULL to terminate the arguments list. + If the hook does not exist or is not executable, the return + value will be zero. + If it is executable, the hook will be executed and the exit + status of the hook is returned. + On execution, .stdout_to_stderr and .no_stdin will be set. + (See below.) + Data structures --------------- @@ -100,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! @@ -128,6 +163,11 @@ string pointers (NULL terminated) in .env: To specify a new initial working directory for the sub-process, specify it in the .dir member. +If the program cannot be found, the functions return -1 and set +errno to ENOENT. Normally, an error message is printed, but if +.silent_exec_failure is set to 1, no message is printed for this +special error condition. + * `struct async` @@ -140,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. @@ -161,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 a9668e5f2d..95a8bf3846 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -12,7 +12,7 @@ strbuf API actually relies on the string being free of NULs. strbufs has some invariants that are very important to keep in mind: -. The `buf` member is never NULL, so you it can be used in any usual C +. The `buf` member is never NULL, so it can be used in any usual C string operations safely. strbuf's _have_ to be initialized either by `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though. + @@ -21,7 +21,7 @@ allocated memory or not), use `strbuf_detach()` to unwrap a memory buffer from its strbuf shell in a safe way. That is the sole supported way. This will give you a malloced buffer that you can later `free()`. + -However, it it totally safe to modify anything in the string pointed by +However, it is totally safe to modify anything in the string pointed by the `buf` member, between the indices `0` and `len-1` (inclusive). . The `buf` member is a byte array that has at least `len + 1` bytes @@ -55,7 +55,7 @@ Data structures * `struct strbuf` -This is string buffer structure. The `len` member can be used to +This is the string buffer structure. The `len` member can be used to determine the current length of the string, and `buf` member provides access to the string itself. @@ -133,8 +133,10 @@ Functions * Adding data to the buffer -NOTE: All of these functions in this section will grow the buffer as - necessary. +NOTE: All of the functions in this section will grow the buffer as necessary. +If they fail for some reason other than memory shortage and the buffer hadn't +been allocated before (i.e. the `struct strbuf` was set to `STRBUF_INIT`), +then they will free() it. `strbuf_addch`:: @@ -197,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. @@ -205,6 +211,20 @@ In order to facilitate caching and to make it possible to give parameters to the callback, `strbuf_expand()` passes a context pointer, which can be used by the programmer of the callback as she sees fit. +`strbuf_expand_dict_cb`:: + + Used as callback for `strbuf_expand()`, expects an array of + struct strbuf_expand_dict_entry as context, i.e. pairs of + placeholder and replacement string. The array needs to be + terminated by an entry with placeholder set to NULL. + +`strbuf_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. @@ -213,7 +233,7 @@ which can be used by the programmer of the callback as she sees fit. Read a given size of data from a FILE* pointer to the buffer. + -NOTE: The buffer is rewinded if the read fails. If -1 is returned, +NOTE: The buffer is rewound if the read fails. If -1 is returned, `errno` must be consulted, like you would do for `read(3)`. `strbuf_read()`, `strbuf_read_file()` and `strbuf_getline()` has the same behaviour as well. @@ -228,10 +248,31 @@ same behaviour as well. Read the contents of a file, specified by its path. The third argument can be used to give a hint about the file size, to avoid reallocs. +`strbuf_readlink`:: + + Read the target of a symbolic link, specified by its path. The third + argument can be used to give a hint about the size, to avoid reallocs. + `strbuf_getline`:: - Read a line from a FILE* pointer. The second argument specifies the line + Read a line from a FILE *, overwriting the existing contents + of the strbuf. The second argument specifies the line terminator character, typically `'\n'`. + Reading stops after the terminator or at EOF. The terminator + is removed from the buffer before returning. Returns 0 unless + there was nothing left before EOF, in which case it returns `EOF`. + +`strbuf_getwholeline`:: + + Like `strbuf_getline`, but keeps the trailing terminator (if + any) in the buffer. + +`strbuf_getwholeline_fd`:: + + Like `strbuf_getwholeline`, but operates on a file descriptor. + It reads one character at a time, so it is very slow. Do not + use it unless you need the correct position in the file + descriptor. `stripspace`:: @@ -239,3 +280,9 @@ same behaviour as well. comments are considered contents to be removed or not. `launch_editor`:: + + Launch the user preferred editor to edit a file and fill the buffer + with the file's contents upon the user completing their editing. The + third argument can be used to set the environment which the editor is + run in. If the buffer is NULL the editor is launched as usual but the + file's contents are not read into the buffer upon completion. diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt new file mode 100644 index 0000000000..5a0c14fceb --- /dev/null +++ b/Documentation/technical/api-string-list.txt @@ -0,0 +1,144 @@ +string-list API +=============== + +The string_list API offers a data structure and functions to handle sorted +and unsorted string lists. + +The 'string_list' struct used to be called 'path_list', but was renamed +because it is not specific to paths. + +The caller: + +. Allocates and clears a `struct string_list` variable. + +. Initializes the members. You might want to set the flag `strdup_strings` + if the strings should be strdup()ed. For example, this is necessary + when you add something like git_path("..."), since that function returns + a static buffer that will change with the next call to git_path(). ++ +If you need something advanced, you can manually malloc() the `items` +member (you need this if you add things later) and you should set the +`nr` and `alloc` members in that case, too. + +. Adds new items to the list, using `string_list_append` or + `string_list_insert`. + +. Can check if a string is in the list using `string_list_has_string` or + `unsorted_string_list_has_string` and get it from the list using + `string_list_lookup` for sorted lists. + +. 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: + +---- +struct string_list list; +int i; + +memset(&list, 0, sizeof(struct string_list)); +string_list_append(&list, "foo"); +string_list_append(&list, "bar"); +for (i = 0; i < list.nr; i++) + printf("%s\n", list.items[i].string) +---- + +NOTE: It is more efficient to build an unsorted list and sort it +afterwards, instead of building a sorted list (`O(n log n)` instead of +`O(n^2)`). ++ +However, if you use the list to check if a certain string was added +already, you should not do that (using unsorted_string_list_has_string()), +because the complexity would be quadratic again (but with a worse factor). + +Functions +--------- + +* General ones (works with sorted and unsorted lists as well) + +`print_string_list`:: + + Dump a string_list to stdout, useful mainly for debugging purposes. It + can take an optional header argument and it writes out the + string-pointer pairs of the string_list, each one in its own line. + +`string_list_clear`:: + + Free 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 second + parameter controls if the `util` pointer of the items should be freed + or not. + +* Functions for sorted lists only + +`string_list_has_string`:: + + Determine if the string_list has a given string or not. + +`string_list_insert`:: + + Insert a new element to the string_list. The returned pointer can be + handy if you want to write something to the `util` pointer of the + string_list_item containing the just added string. If the given + string already exists the insertion will be skipped and the + pointer to the existing item returned. ++ +Since this function uses xrealloc() (which die()s if it fails) if the +list needs to grow, it is safe not to check the pointer. I.e. you may +write `string_list_insert(...)->util = ...;`. + +`string_list_lookup`:: + + Look up a given string in the string_list, returning the containing + string_list_item. If the string is not found, NULL is returned. + +* Functions for unsorted lists only + +`string_list_append`:: + + Append a new string to the end of the string_list. + +`sort_string_list`:: + + Make an unsorted list sorted. + +`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. ++ +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 +--------------- + +* `struct string_list_item` + +Represents an item of the list. The `string` member is a pointer to the +string, and you may use the `util` member for any purpose, if you want. + +* `struct string_list` + +Represents the list itself. + +. The array of items are available via the `items` member. +. The `nr` member contains the number of items stored in the list. +. The `alloc` member is used to avoid reallocating at every insertion. + You should not tamper with it. +. Setting the `strdup_strings` member to 1 will strdup() the strings + before adding them, see above. diff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt index e3ddf91284..14af37c3f1 100644 --- a/Documentation/technical/api-tree-walking.txt +++ b/Documentation/technical/api-tree-walking.txt @@ -1,12 +1,147 @@ tree walking API ================ -Talk about <tree-walk.h>, things like +The tree walking API is used to traverse and inspect trees. -* struct tree_desc -* init_tree_desc -* tree_entry_extract -* update_tree_entry -* get_tree_entry +Data Structures +--------------- -(JC, Linus) +`struct name_entry`:: + + An entry in a tree. Each entry has a sha1 identifier, pathname, and + mode. + +`struct tree_desc`:: + + A semi-opaque data structure used to maintain the current state of the + walk. ++ +* `buffer` is a pointer into the memory representation of the tree. It always +points at the current entry being visited. + +* `size` counts the number of bytes left in the `buffer`. + +* `entry` points to the current entry being visited. + +`struct traverse_info`:: + + A structure used to maintain the state of a traversal. ++ +* `prev` points to the traverse_info which was used to descend into the +current tree. If this is the top-level tree `prev` will point to +a dummy traverse_info. + +* `name` is the entry for the current tree (if the tree is a subtree). + +* `pathlen` is the length of the full path for the current tree. + +* `conflicts` can be used by callbacks to maintain directory-file conflicts. + +* `fn` is a callback called for each entry in the tree. See Traversing for more +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 +------------ + +`init_tree_desc`:: + + Initialize a `tree_desc` and decode its first entry. The buffer and + size parameters are assumed to be the same as the buffer and size + members of `struct tree`. + +`fill_tree_descriptor`:: + + Initialize a `tree_desc` and decode its first entry given the sha1 of + a tree. Returns the `buffer` member if the sha1 is a valid tree + identifier and NULL otherwise. + +`setup_traverse_info`:: + + Initialize a `traverse_info` given the pathname of the tree to start + traversing from. The `base` argument is assumed to be the `path` + member of the `name_entry` being recursed into unless the tree is a + top-level tree in which case the empty string ("") is used. + +Walking +------- + +`tree_entry`:: + + Visit the next entry in a tree. Returns 1 when there are more entries + left to visit and 0 when all entries have been visited. This is + commonly used in the test of a while loop. + +`tree_entry_len`:: + + Calculate the length of a tree entry's pathname. This utilizes the + memory structure of a tree entry to avoid the overhead of using a + generic strlen(). + +`update_tree_entry`:: + + Walk to the next entry in a tree. This is commonly used in conjunction + with `tree_entry_extract` to inspect the current entry. + +`tree_entry_extract`:: + + Decode the entry currently being visited (the one pointed to by + `tree_desc's` `entry` member) and return the sha1 of the entry. The + `pathp` and `modep` arguments are set to the entry's pathname and mode + respectively. + +`get_tree_entry`:: + + Find an entry in a tree given a pathname and the sha1 of a tree to + search. Returns 0 if the entry is found and -1 otherwise. The third + and fourth parameters are set to the entry's sha1 and mode + respectively. + +Traversing +---------- + +`traverse_trees`:: + + Traverse `n` number of trees in parallel. The `fn` callback member of + `traverse_info` is called once for each tree entry. + +`traverse_callback_t`:: + The arguments passed to the traverse callback are as follows: ++ +* `n` counts the number of trees being traversed. + +* `mask` has its nth bit set if something exists in the nth entry. + +* `dirmask` has its nth bit set if the nth tree's entry is a directory. + +* `entry` is an array of size `n` where the nth entry is from the nth tree. + +* `info` maintains the state of the traversal. + ++ +Returning a negative value will terminate the traversal. Otherwise the +return value is treated as an update mask. If the nth bit is set the nth tree +will be updated and if the bit is not set the nth tree entry will be the +same in the next callback invocation. + +`make_traverse_path`:: + + Generate the full pathname of a tree entry based from the root of the + traversal. For example, if the traversal has recursed into another + tree named "bar" the pathname of an entry "baz" in the "bar" + tree would be "bar/baz". + +`traverse_path_len`:: + + Calculate the length of a pathname returned by `make_traverse_path`. + This utilizes the memory structure of a tree entry to avoid the + overhead of using a generic strlen(). + +Authors +------- + +Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds +<torvalds@linux-foundation.org> diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt new file mode 100644 index 0000000000..9d25b30178 --- /dev/null +++ b/Documentation/technical/index-format.txt @@ -0,0 +1,199 @@ +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). + + (Version 4) In version 4, the entry path name is prefix-compressed + relative to the path name for the previous entry (the very first + entry is encoded as if the path name for the previous entry is an + empty string). At the beginning of an entry, an integer N in the + variable width encoding (the same encoding as the offset is encoded + for OFS_DELTA pack entries; see pack-format.txt) is stored, followed + by a NUL-terminated string S. Removing N bytes from the end of the + path name for the previous entry, and replacing it with the string S + yields the path name for this entry. + + 1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes + while keeping the name NUL-terminated. + + (Version 4) In version 4, the padding after the pathname does not + exist. + +== 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 9cd48b4859..49cdc571cd 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -1,41 +1,546 @@ -Pack transfer protocols -======================= - -There are two Pack push-pull protocols. - -upload-pack (S) | fetch/clone-pack (C) protocol: - - # Tell the puller what commits we have and what their names are - S: SHA1 name - S: ... - S: SHA1 name - S: # flush -- it's your turn - # Tell the pusher what commits we want, and what we have - C: want name - C: .. - C: want name - C: have SHA1 - C: have SHA1 - C: ... - C: # flush -- occasionally ask "had enough?" - S: NAK - C: have SHA1 - C: ... - C: have SHA1 - S: ACK - C: done - S: XXXXXXX -- packfile contents. - -send-pack | receive-pack protocol. - - # Tell the pusher what commits we have and what their names are - C: SHA1 name - C: ... - C: SHA1 name - C: # flush -- it's your turn - # Tell the puller what the pusher has - S: old-SHA1 new-SHA1 name - S: old-SHA1 new-SHA1 name - S: ... - S: # flush -- done with the list - S: XXXXXXX --- packfile contents. +Packfile transfer protocols +=========================== + +Git supports transferring data in packfiles over the ssh://, git:// and +file:// transports. There exist two sets of protocols, one for pushing +data from a client to a server and another for fetching data from a +server to a client. All three transports (ssh, git, file) use the same +protocol to transfer data. + +The processes invoked in the canonical Git implementation are 'upload-pack' +on the server side and 'fetch-pack' on the client side for fetching data; +then 'receive-pack' on the server and 'send-pack' on the client for pushing +data. The protocol functions to have a server tell a client what is +currently on the server, then for the two to negotiate the smallest amount +of data to send in order to fully update one or the other. + +Transports +---------- +There are three transports over which the packfile protocol is +initiated. The Git transport is a simple, unauthenticated server that +takes the command (almost always 'upload-pack', though Git +servers can be configured to be globally writable, in which 'receive- +pack' initiation is also allowed) with which the client wishes to +communicate and executes it and connects it to the requesting +process. + +In the SSH transport, the client just runs the 'upload-pack' +or 'receive-pack' process on the server over the SSH protocol and then +communicates with that invoked process over the SSH connection. + +The file:// transport runs the 'upload-pack' or 'receive-pack' +process locally and communicates with it over a pipe. + +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 parameter, terminated by a NUL byte. + + 0032git-upload-pack /project.git\0host=myserver.com\0 + +-- + git-proto-request = request-command SP pathname NUL [ host-parameter NUL ] + request-command = "git-upload-pack" / "git-receive-pack" / + "git-upload-archive" ; case sensitive + pathname = *( %x01-ff ) ; exclude NUL + host-parameter = "host=" hostname [ ":" port ] +-- + +Only host-parameter is allowed in the git-proto-request. Clients +MUST NOT attempt to send additional parameters. It is used for the +git-daemon name based virtual hosting. See --interpolated-path +option to git daemon, with the %H/%CH format characters. + +Basically what the Git client is doing to connect to an 'upload-pack' +process on the server side over the Git protocol is this: + + $ echo -e -n \ + "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 +------------- + +Initiating the upload-pack or receive-pack processes over SSH is +executing the binary on the server via SSH remote execution. +It is basically equivalent to running this: + + $ ssh git.example.com "git-upload-pack '/project.git'" + +For a server to support Git pushing and pulling for a given user over +SSH, that user needs to be able to execute one or both of those +commands via the SSH shell that they are provided on login. On some +systems, that shell access is limited to only being able to run those +two commands, or even just one of them. + +In an ssh:// format URI, it's absolute in the URI, so the '/' after +the host name (or port number) is sent as an argument, which is then +read by the remote git-upload-pack exactly as is, so it's effectively +an absolute path in the remote filesystem. + + git clone ssh://user@example.com/project.git + | + v + ssh user@example.com "git-upload-pack '/project.git'" + +In a "user@host:path" format URI, its relative to the user's home +directory, because the Git client will run: + + git clone user@example.com:project.git + | + v + ssh user@example.com "git-upload-pack 'project.git'" + +The exception is if a '~' is used, in which case +we execute it without the leading '/'. + + ssh://user@example.com/~alice/project.git, + | + v + ssh user@example.com "git-upload-pack '~alice/project.git'" + +A few things to remember here: + +- The "command name" is spelled with dash (e.g. git-upload-pack), but + this can be overridden by the client; + +- The repository path is always quoted with single quotes. + +Fetching Data From a Server +=========================== + +When one Git repository wants to get data that a second repository +has, the first can 'fetch' from the second. This operation determines +what data the server has that the client does not then streams that +data down to the client in packfile format. + + +Reference Discovery +------------------- + +When the client initially connects the server will immediately respond +with a listing of each reference it has (all branches and tags) along +with the object name that each reference currently points to. + + $ echo -e -n "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" | + nc -v example.com 9418 + 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag + 00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration + 003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master + 003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9 + 003c525128480b96c89e6418b1e40909bf6c5b2d580f refs/tags/v1.0 + 003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{} + 0000 + +Server SHOULD terminate each non-flush line using LF ("\n") terminator; +client MUST NOT complain if there is no terminator. + +The returned response is a pkt-line stream describing each ref and +its current value. The stream MUST be sorted by name according to +the C locale ordering. + +If HEAD is a valid ref, HEAD MUST appear as the first advertised +ref. If HEAD is not a valid ref, HEAD MUST NOT appear in the +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 it's an annotated tag. + +---- + advertised-refs = (no-refs / list-of-refs) + flush-pkt + + no-refs = PKT-LINE(zero-id SP "capabilities^{}" + NUL capability-list LF) + + list-of-refs = first-ref *other-ref + first-ref = PKT-LINE(obj-id SP refname + NUL capability-list LF) + + other-ref = PKT-LINE(other-tip / other-peeled) + other-tip = obj-id SP refname LF + other-peeled = obj-id SP refname "^{}" LF + + capability-list = capability *(SP capability) + capability = 1*(LC_ALPHA / DIGIT / "-" / "_") + LC_ALPHA = %x61-7A +---- + +Server and client MUST use lowercase for obj-id, both MUST treat obj-id +as case-insensitive. + +See protocol-capabilities.txt for a list of allowed server capabilities +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, 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 + *shallow-line + *1depth-request + flush-pkt + + want-list = first-want + *additional-want + + 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) + + depth = 1*DIGIT +---- + +Clients MUST send all the obj-ids it wants from the reference +discovery phase as 'want' lines. Clients MUST send at least one +'want' command in the request body. Clients MUST NOT mention an +obj-id in a 'want' command which did not appear in the response +obtained through ref discovery. + +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. + +---- + shallow-update = *shallow-line + *unshallow-line + flush-pkt + + shallow-line = PKT-LINE("shallow" SP obj-id) + + unshallow-line = PKT-LINE("unshallow" SP obj-id) +---- + +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, 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 +server will ACK obj-ids differently depending on which ack mode is +chosen by the client. + +In multi_ack mode: + + * the server will respond with 'ACK obj-id continue' for any common + commits. + + * once the server has found an acceptable common base commit and is + ready to make a packfile, it will blindly ACK all 'have' obj-ids + back to the client. + + * the server will then send a 'NACK' and then wait for another response + from the client - either a 'done' or another list of 'have' lines. + +In multi_ack_detailed mode: + + * the server will differentiate the ACKs where it is signaling + that it is ready to send data with 'ACK obj-id ready' lines, and + signals the identified common commits with 'ACK obj-id common' lines. + +Without either multi_ack or multi_ack_detailed: + + * upload-pack sends "ACK obj-id" on the first common object it finds. + After that it says nothing until the client gives it a "done". + + * 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, 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 +(in the canonical implementation, this is determined when it has received +enough ACKs that it can color everything left in the --date-order queue +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 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 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" +during a prior round. This helps to ensure that at least one common +ancestor is found before we give up entirely. + +Once the 'done' line is read from the client, the server will either +send a final 'ACK obj-id' or it will send a 'NAK'. The server only sends +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 its packfile data. + +---- + server-response = *ack_multi ack / nak + ack_multi = PKT-LINE("ACK" SP obj-id ack_status LF) + ack_status = "continue" / "common" / "ready" + ack = PKT-LINE("ACK SP obj-id LF) + nak = PKT-LINE("NAK" LF) +---- + +A simple clone may look like this (with no 'have' lines): + +---- + C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \ + side-band-64k ofs-delta\n + C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n + C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n + C: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n + C: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\n + C: 0000 + C: 0009done\n + + S: 0008NAK\n + S: [PACKFILE] +---- + +An incremental update (fetch) response might look like this: + +---- + C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \ + side-band-64k ofs-delta\n + C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n + C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n + C: 0000 + C: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n + C: [30 more have lines] + C: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\n + C: 0000 + + S: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\n + S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\n + S: 0008NAK\n + + C: 0009done\n + + S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n + S: [PACKFILE] +---- + + +Packfile Data +------------- + +Now that the client and server have finished negotiation about what +the minimal amount of data that needs to be sent to the client is, the server +will construct and send the required data in packfile format. + +See pack-format.txt for what the packfile itself actually looks like. + +If 'side-band' or 'side-band-64k' capabilities have been specified by +the client, the server will send the packfile data multiplexed. + +Each packet starting with the packet-line length of the amount of data +that follows, followed by a single byte specifying the sideband the +following data is coming in on. + +In 'side-band' mode, it will send up to 999 data bytes plus 1 control +code, for a total of up to 1000 bytes in a pkt-line. In 'side-band-64k' +mode it will send up to 65519 data bytes plus 1 control code, for a +total of up to 65520 bytes in a pkt-line. + +The sideband byte will be a '1', '2' or a '3'. Sideband '1' will contain +packfile data, sideband '2' will be used for progress information that the +client will generally print to stderr and sideband '3' is used for error +information. + +If no 'side-band' capability was specified, the server will stream the +entire packfile without multiplexing. + + +Pushing Data To a Server +======================== + +Pushing data to a server will invoke the 'receive-pack' process on the +server, which will allow the client to tell it which references it should +update and then send all the data the server will need for those new +references to be complete. Once all the data is received and validated, +the server will then update its references to what the client specified. + +Authentication +-------------- + +The protocol itself contains no authentication mechanisms. That is to be +handled by the transport, such as SSH, before the 'receive-pack' process is +invoked. If 'receive-pack' is configured over the Git transport, those +repositories will be writable by anyone who can access that port (9418) as +that transport is unauthenticated. + +Reference Discovery +------------------- + +The reference discovery phase is done nearly the same way as it is in the +fetching protocol. Each reference obj-id and name on the server is sent +in packet-line format to the client, followed by a flush-pkt. The only +real difference is that the capability listing is different - the only +possible values are 'report-status', 'delete-refs' and 'ofs-delta'. + +Reference Update Request and Packfile Transfer +---------------------------------------------- + +Once the client knows what references the server is at, it can send a +list of reference update requests. For each reference on the server +that it wants to update, it sends a line listing the obj-id currently on +the server, the obj-id the client would like to update it to and the name +of the reference. + +This list is followed by a flush-pkt and then the packfile that should +contain all the objects that the server will need to complete the new +references. + +---- + update-request = command-list [pack-file] + + command-list = PKT-LINE(command NUL capability-list LF) + *PKT-LINE(command LF) + flush-pkt + + command = create / delete / update + create = zero-id SP new-id SP name + delete = old-id SP zero-id SP name + update = old-id SP new-id SP name + + old-id = obj-id + new-id = obj-id + + pack-file = "PACK" 28*(OCTET) +---- + +If the receiving end does not support delete-refs, the sending end MUST +NOT ask for delete command. + +The pack-file MUST NOT be sent if the only command used is 'delete'. + +A pack-file MUST be sent if either create or update command is used, +even if the server already has all the necessary objects. In this +case the client MUST send an empty pack-file. The only time this +is likely to happen is if the client is creating +a new branch or a tag that points to an existing obj-id. + +The server will receive the packfile, unpack it, then validate each +reference that is being updated that it hasn't changed while the request +was being processed (the obj-id is still the same as the old-id), and +it will run any update hooks to make sure that the update is acceptable. +If all of that is fine, the server will then update the references. + +Report Status +------------- + +After receiving the pack data from the sender, the receiver sends a +report if 'report-status' capability is in effect. +It is a short listing of what happened in that update. It will first +list the status of the packfile unpacking as either 'unpack ok' or +'unpack [error]'. Then it will list the status for each of the references +that it tried to update. Each line is either 'ok [refname]' if the +update was successful, or 'ng [refname] [error]' if the update was not. + +---- + report-status = unpack-status + 1*(command-status) + flush-pkt + + unpack-status = PKT-LINE("unpack" SP unpack-result LF) + unpack-result = "ok" / error-msg + + command-status = command-ok / command-fail + command-ok = PKT-LINE("ok" SP refname LF) + command-fail = PKT-LINE("ng" SP refname SP error-msg LF) + + error-msg = 1*(OCTECT) ; where not "ok" +---- + +Updates can be unsuccessful for a number of reasons. The reference can have +changed since the reference discovery phase was originally sent, meaning +someone pushed in the meantime. The reference being pushed could be a +non-fast-forward reference and the update hooks or configuration could be +set to not allow that, etc. Also, some references can be updated while others +can be rejected. + +An example client/server communication might look like this: + +---- + S: 007c74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n + S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n + S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n + S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n + S: 0000 + + C: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n + C: 003e74730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n + C: 0000 + C: [PACKDATA] + + 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 new file mode 100644 index 0000000000..b15517fa06 --- /dev/null +++ b/Documentation/technical/protocol-capabilities.txt @@ -0,0 +1,187 @@ +Git Protocol Capabilities +========================= + +Servers SHOULD support all capabilities defined in this document. + +On the very first line of the initial server response of either +receive-pack and upload-pack the first reference is followed by +a NUL byte and then a list of space delimited server capabilities. +These allow the server to declare what it can and cannot support +to the client. + +Client will then send a space separated list of capabilities it wants +to be in effect. The client MUST NOT ask for capabilities the server +did not say it supports. + +Server MUST diagnose and abort if capabilities it does not understand +was sent. Server MUST NOT ignore capabilities that client requested +and server advertised. As a consequence of these rules, server MUST +NOT advertise capabilities it does not understand. + +The 'report-status' and 'delete-refs' capabilities are sent and +recognized by the receive-pack (push to server) process. + +The 'ofs-delta' capability is sent and recognized by both upload-pack +and receive-pack protocols. + +All other capabilities are only recognized by the upload-pack (fetch +from server) process. + +multi_ack +--------- + +The 'multi_ack' capability allows the server to return "ACK obj-id +continue" as soon as it finds a commit that it can use as a common +base, between the client's wants and the client's have set. + +By sending this early, the server can potentially head off the client +from walking any further down that particular branch of the client's +repository history. The client may still need to walk down other +branches, sending have lines for those, until the server has a +complete cut across the DAG, or the client has said "done". + +Without multi_ack, a client sends have lines in --date-order until +the server has found a common base. That means the client will send +have lines that are already known by the server to be common, because +they overlap in time with another branch that the server hasn't found +a common base on yet. + +For example suppose the client has commits in caps that the server +doesn't and the server has commits in lower case that the client +doesn't, as in the following diagram: + + +---- u ---------------------- x + / +----- y + / / + a -- b -- c -- d -- E -- F + \ + +--- Q -- R -- S + +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 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. + +Without multi_ack the client would have sent that c-b-a chain anyway, +interleaved with S-R-Q. + +thin-pack +--------- + +This capability means that the server can send a 'thin' pack, a pack +which does not contain base objects; if those base objects are available +on client side. Client requests 'thin-pack' capability when it +understands how to "thicken" it by adding required delta bases making +it self-contained. + +Client MUST NOT request 'thin-pack' capability if it cannot turn a thin +pack into a self-contained pack. + + +side-band, side-band-64k +------------------------ + +This capability means that server can send, and client understand multiplexed +progress reports and error info interleaved with the packfile itself. + +These two options are mutually exclusive. A modern client always +favors 'side-band-64k'. + +Either mode indicates that the packfile data will be streamed broken +up into packets of up to either 1000 bytes in the case of 'side_band', +or 65520 bytes in the case of 'side_band_64k'. Each packet is made up +of a leading 4-byte pkt-line length of how much data is in the packet, +followed by a 1-byte stream code, followed by the actual data. + +The stream code can be one of: + + 1 - pack data + 2 - progress messages + 3 - fatal error message just before stream aborts + +The "side-band-64k" capability came about as a way for newer clients +that can handle much larger packets to request packets that are +actually crammed nearly full, while maintaining backward compatibility +for the older clients. + +Further, with side-band and its up to 1000-byte messages, it's actually +999 bytes of payload and 1 byte for the stream code. With side-band-64k, +same deal, you have up to 65519 bytes of data and 1 byte for the stream +code. + +The client MUST send only maximum of one of "side-band" and "side- +band-64k". Server MUST diagnose it as an error if client requests +both. + +ofs-delta +--------- + +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. + +shallow +------- + +This capability adds "deepen", "shallow" and "unshallow" commands to +the fetch-pack/upload-pack protocol so clients can request shallow +clones. + +no-progress +----------- + +The client was started with "git clone -q" or something, and doesn't +want that side band 2. Basically the client just says "I do not +wish to receive stream 2 on sideband, so do not send it to me, and if +you did, I will drop it on the floor anyway". However, the sideband +channel 3 is still used for error responses. + +include-tag +----------- + +The 'include-tag' capability is about sending annotated tags if we are +sending objects they point to. If we pack an object to the client, and +a tag object points exactly at that object, we pack the tag object too. +In general this allows a client to get all new annotated tags when it +fetches a branch, in a single network connection. + +Clients MAY always send include-tag, hardcoding it into a request when +the server advertises this capability. The decision for a client to +request include-tag only has to do with the client's desires for tag +data, whether or not a server had advertised objects in the +refs/tags/* namespace. + +Servers MUST pack the tags if their referrant is packed and the client +has requested include-tags. + +Clients MUST be prepared for the case where a server has ignored +include-tag and has not actually sent tags in the pack. In such +cases the client SHOULD issue a subsequent fetch to acquire the tags +that include-tag would have otherwise given the client. + +The server SHOULD send include-tag, if it supports it, regardless +of whether or not there are tags available. + +report-status +------------- + +The upload-pack process can receive a 'report-status' capability, +which tells it that the client wants a report of what happened after +a packfile upload and reference update. If the pushing client requests +this capability, after unpacking and updating references the server +will respond with whether the packfile unpacked successfully and if +each reference was updated successfully. If any of those were not +successful, it will send back an error message. See pack-protocol.txt +for example messages. + +delete-refs +----------- + +If the server sends back the 'delete-refs' capability, it means that +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/technical/protocol-common.txt b/Documentation/technical/protocol-common.txt new file mode 100644 index 0000000000..fb7ff084f8 --- /dev/null +++ b/Documentation/technical/protocol-common.txt @@ -0,0 +1,96 @@ +Documentation Common to Pack and Http Protocols +=============================================== + +ABNF Notation +------------- + +ABNF notation as described by RFC 5234 is used within the protocol documents, +except the following replacement core rules are used: +---- + HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" +---- + +We also define the following common rules: +---- + NUL = %x00 + zero-id = 40*"0" + obj-id = 40*(HEXDIGIT) + + refname = "HEAD" + refname /= "refs/" <see discussion below> +---- + +A refname is a hierarchical octet string beginning with "refs/" and +not violating the 'git-check-ref-format' command's validation rules. +More specifically, they: + +. They can include slash `/` for hierarchical (directory) + grouping, but no slash-separated component can begin with a + dot `.`. + +. They must contain at least one `/`. This enforces the presence of a + category like `heads/`, `tags/` etc. but the actual names are not + restricted. + +. 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 `^`, colon `:`, question-mark `?`, asterisk `*`, + or open bracket `[` anywhere. + +. They cannot end with a slash `/` nor a dot `.`. + +. They cannot end with the sequence `.lock`. + +. They cannot contain a sequence `@{`. + +. They cannot contain a `\\`. + + +pkt-line Format +--------------- + +Much (but not all) of the payload is described around pkt-lines. + +A pkt-line is a variable length binary string. The first four bytes +of the line, the pkt-len, indicates the total length of the line, +in hexadecimal. The pkt-len includes the 4 bytes used to contain +the length's hexadecimal representation. + +A pkt-line MAY contain binary data, so implementors MUST ensure +pkt-line parsing/formatting routines are 8-bit clean. + +A non-binary line SHOULD BE terminated by an LF, which if present +MUST be included in the total length. + +The maximum length of a pkt-line's data component is 65520 bytes. +Implementations MUST NOT send pkt-line whose length exceeds 65524 +(65520 bytes of payload + 4 bytes of length data). + +Implementations SHOULD NOT send an empty pkt-line ("0004"). + +A pkt-line with a length field of 0 ("0000"), called a flush-pkt, +is a special case and MUST be handled differently than an empty +pkt-line ("0004"). + +---- + pkt-line = data-pkt / flush-pkt + + data-pkt = pkt-len pkt-payload + pkt-len = 4*(HEXDIG) + pkt-payload = (pkt-len - 4)*(OCTET) + + flush-pkt = "0000" +---- + +Examples (as C-style strings): + +---- + pkt-line actual value + --------------------------------- + "0006a\n" "a\n" + "0005a" "a" + "000bfoobar\n" "foobar\n" + "0004" "" +---- diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 6bdf034b3a..53aa0c82c2 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -42,10 +42,12 @@ compared, but this is not enabled by default because this member is not stable on network filesystems. With `USE_NSEC` compile-time option, `st_mtim.tv_nsec` and `st_ctim.tv_nsec` members are also compared, but this is not enabled by default -because the value of this member becomes meaningless once the -inode is evicted from the inode cache on filesystems that do not -store it on disk. - +because in-core timestamps can have finer granularity than +on-disk timestamps, resulting in meaningless changes when an +inode is evicted from the inode cache. See commit 8ce13b0 +of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git +([PATCH] Sync in core time granuality with filesystems, +2005-01-04). Racy git -------- @@ -135,7 +137,7 @@ them, and give the same timestamp to the index file: This will make all index entries racily clean. The linux-2.6 project, for example, there are over 20,000 files in the working -tree. On my Athron 64X2 3800+, after the above: +tree. On my Athlon 64 X2 3800+, after the above: $ /usr/bin/time git diff-files 1.68user 0.54system 0:02.22elapsed 100%CPU (0avgtext+0avgdata 0maxresident)k diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index 99753006e2..00f7e79c44 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -27,10 +27,13 @@ config file would appear like this: ------------ [remote "<name>"] url = <url> + pushurl = <pushurl> push = <refspec> fetch = <refspec> ------------ +The `<pushurl>` is used for pushes only. It is optional and defaults +to `<url>`. Named file in `$GIT_DIR/remotes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -49,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. @@ -68,13 +71,22 @@ This file should have the following format: ------------ `<url>` is required; `#<head>` is optional. -When you do not provide a refspec on the command line, -git will use the following refspec, where `<head>` defaults to `master`, -and `<repository>` is the name of this file -you provided in the command line. + +Depending on the operation, git will use one of the following +refspecs, if you don't provide one on the command line. +`<branch>` is the name of this file in `$GIT_DIR/branches` and +`<head>` defaults to `master`. + +git fetch uses: + +------------ + refs/heads/<head>:refs/heads/<branch> +------------ + +git push uses: ------------ - refs/heads/<head>:<repository> + HEAD:refs/heads/<head> ------------ diff --git a/Documentation/urls.txt b/Documentation/urls.txt index fa34c67471..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/path/to/repo.git/ -- https://host.xz/path/to/repo.git/ -- git://host.xz/path/to/repo.git/ -- git://host.xz/~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 @@ -67,3 +74,21 @@ For example, with this: a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be rewritten in any context that takes a URL to be "git://git.host.xz/repo.git". +If you want to rewrite URLs for push only, you can create a +configuration section of the form: + +------------ + [url "<actual url base>"] + pushInsteadOf = <other url base> +------------ + +For example, with this: + +------------ + [url "ssh://example.org/"] + pushInsteadOf = git://example.org/ +------------ + +a URL like "git://example.org/path/to/repo.git" will be rewritten to +"ssh://example.org/path/to/repo.git" for pushes, but pulls will still +use the original URL. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 64a820bf60..1b942074b6 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -13,17 +13,27 @@ to build and test a particular version of a software project, search for regressions, and so on. People needing to do actual development will also want to read -<<Developing-with-git>> and <<sharing-development>>. +<<Developing-With-git>> and <<sharing-development>>. Further chapters cover more specialized topics. Comprehensive reference documentation is available through the man -pages. For a command such as "git clone", just use +pages, or linkgit:git-help[1] command. For example, for the command +"git clone <repo>", you can either use: ------------------------------------------------ $ man git-clone ------------------------------------------------ +or: + +------------------------------------------------ +$ git help clone +------------------------------------------------ + +With the latter, you can use the manual viewer of your choice; see +linkgit:git-help[1] for more information. + See also <<git-quick-start>> for a brief overview of git commands, without any explanation. @@ -49,7 +59,7 @@ project in mind, here are some interesting examples: ------------------------------------------------ # git itself (approx. 10MB download): $ git clone git://git.kernel.org/pub/scm/git/git.git - # the linux kernel (approx. 150MB download): + # the Linux kernel (approx. 150MB download): $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git ------------------------------------------------ @@ -178,7 +188,7 @@ As you can see, a commit shows who made the latest change, what they did, and why. Every commit has a 40-hexdigit id, sometimes called the "object name" or the -"SHA1 id", shown on the first line of the "git show" output. You can usually +"SHA-1 id", shown on the first line of the "git show" output. You can usually refer to a commit by a shorter name, such as a tag or a branch name, but this longer name can also be useful. Most importantly, it is a globally unique name for this commit: so if you tell somebody else the object name (for @@ -297,7 +307,7 @@ ref: refs/heads/master Examining an old version without creating a new branch ------------------------------------------------------ -The git-checkout command normally expects a branch head, but will also +The `git checkout` command normally expects a branch head, but will also accept an arbitrary commit; for example, you can check out the commit referenced by a tag: @@ -310,7 +320,7 @@ If you want to create a new branch from this checkout, you may do so HEAD is now at 427abfa... Linux v2.6.17 ------------------------------------------------ -The HEAD then refers to the SHA1 of the commit instead of to a branch, +The HEAD then refers to the SHA-1 of the commit instead of to a branch, and git branch shows that you are no longer on a branch: ------------------------------------------------ @@ -334,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]: ------------------------------------------------ @@ -349,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. @@ -387,9 +408,9 @@ 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]] Updating a repository with git fetch ------------------------------------ @@ -425,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 @@ -479,10 +500,10 @@ Bisecting: 3537 revisions left to test after this ------------------------------------------------- If you run "git branch" at this point, you'll see that git has -temporarily moved you to a new branch named "bisect". This branch -points to a commit (with commit id 65934...) that is reachable from -"master" but not from v2.6.18. Compile and test it, and see whether -it crashes. Assume it does crash. Then: +temporarily moved you in "(no branch)". HEAD is now detached from any +branch and points directly to a commit (with commit id 65934...) that +is reachable from "master" but not from v2.6.18. Compile and test it, +and see whether it crashes. Assume it does crash. Then: ------------------------------------------------- $ git bisect bad @@ -504,10 +525,9 @@ report with the commit id. Finally, run $ git bisect reset ------------------------------------------------- -to return you to the branch you were on before and delete the -temporary "bisect" branch. +to return you to the branch you were on before. -Note that the version which git-bisect checks out for you at each +Note that the version which `git bisect` checks out for you at each point is just a suggestion, and you're free to try a different version if you think it would be a good idea. For example, occasionally you may land on a commit that broke something unrelated; @@ -518,7 +538,7 @@ $ git bisect visualize ------------------------------------------------- which will run gitk and label the commit it chose with a marker that -says "bisect". Chose a safe-looking commit nearby, note its commit +says "bisect". Choose a safe-looking commit nearby, note its commit id, and check it out with: ------------------------------------------------- @@ -528,6 +548,22 @@ $ git reset --hard fb47ddb2db... then test, run "bisect good" or "bisect bad" as appropriate, and continue. +Instead of "git bisect visualize" and then "git reset --hard +fb47ddb2db...", you might just want to tell git that you want to skip +the current commit: + +------------------------------------------------- +$ git bisect skip +------------------------------------------------- + +In this case, though, git may not eventually be able to tell the first +bad one between some first skipped commits and a later bad commit. + +There are also ways to automate the bisecting process if you have a +test script that can tell a good from a bad commit. See +linkgit:git-bisect[1] for more information about this and other "git +bisect" features. + [[naming-commits]] Naming commits -------------- @@ -543,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: ------------------------------------------------- @@ -567,11 +603,11 @@ In addition to HEAD, there are several other special names for commits: Merges (to be discussed later), as well as operations such as -git-reset, which change the currently checked-out commit, generally +`git reset`, which change the currently checked-out commit, generally set ORIG_HEAD to the value HEAD had before the current operation. -The git-fetch operation always stores the head of the last fetched -branch in FETCH_HEAD. For example, if you run git fetch without +The `git fetch` operation always stores the head of the last fetched +branch in FETCH_HEAD. For example, if you run `git fetch` without specifying a local branch as the target of the operation ------------------------------------------------- @@ -714,7 +750,7 @@ $ git log --pretty=oneline origin..mybranch | wc -l ------------------------------------------------- Alternatively, you may often see this sort of thing done with the -lower-level command linkgit:git-rev-list[1], which just lists the SHA1's +lower-level command linkgit:git-rev-list[1], which just lists the SHA-1's of all the given commits: ------------------------------------------------- @@ -884,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]] @@ -930,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -947,7 +983,7 @@ Figuring out why this works is left as an exercise to the (advanced) student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and linkgit:git-hash-object[1] man pages may prove helpful. -[[Developing-with-git]] +[[Developing-With-git]] Developing with git =================== @@ -984,7 +1020,7 @@ $ git init If you have some initial content (say, a tarball): ------------------------------------------------- -$ tar -xzvf project.tar.gz +$ tar xzvf project.tar.gz $ cd project $ git init $ git add . # include everything below ./ in the first commit: @@ -1050,7 +1086,7 @@ shows the difference between the working tree and the index file. Note that "git add" always adds just the current contents of a file to the index; further changes to the same file will be ignored unless -you run git-add on the file again. +you run `git add` on the file again. When you're ready, just run @@ -1111,10 +1147,10 @@ Ignoring files A project will often generate files that you do 'not' want to track with git. This typically includes files generated by a build process or temporary backup files made by your editor. Of course, 'not' tracking files with git -is just a matter of 'not' calling "`git add`" on them. But it quickly becomes +is just a matter of 'not' calling `git add` on them. But it quickly becomes annoying to have these untracked files lying around; e.g. they make -"`git add .`" and "`git commit -a`" practically useless, and they keep -showing up in the output of "`git status`". +`git add .` practically useless, and they keep showing up in the output of +`git status`. You can tell git to ignore certain files by creating a file called .gitignore in the top level of your working directory, with contents such as: @@ -1158,7 +1194,23 @@ $ git merge branchname ------------------------------------------------- merges the development in the branch "branchname" into the current -branch. If there are conflicts--for example, if the same file is +branch. + +A merge is made by combining the changes made in "branchname" and the +changes made up to the latest commit in your current branch since +their histories forked. The work tree is overwritten by the result of +the merge when this combining is done cleanly, or overwritten by a +half-merged results when this combining results in conflicts. +Therefore, if you have uncommitted changes touching the same files as +the ones impacted by the merge, Git will refuse to proceed. Most of +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 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 modified in two different ways in the remote branch and the local branch--then you are warned; the output may look something like this: @@ -1303,7 +1355,7 @@ $ git diff -3 file.txt # diff against stage 3 $ git diff --theirs file.txt # same as the above. ------------------------------------------------- -The linkgit:git-log[1] and gitk[1] commands also provide special help +The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help for merges: ------------------------------------------------- @@ -1315,7 +1367,7 @@ These will display all commits which exist only on HEAD or on MERGE_HEAD, and which touch an unmerged file. You may also use linkgit:git-mergetool[1], which lets you merge the -unmerged files using external tools such as emacs or kdiff3. +unmerged files using external tools such as Emacs or kdiff3. Each time you resolve the conflicts in a file and update the index: @@ -1324,7 +1376,7 @@ $ git add file.txt ------------------------------------------------- the different stages of that file will be "collapsed", after which -git-diff will (by default) no longer show diffs for that file. +`git diff` will (by default) no longer show diffs for that file. [[undoing-a-merge]] Undoing a merge @@ -1359,7 +1411,7 @@ were merged. However, if the current branch is a descendant of the other--so every commit present in the one is already contained in the other--then git -just performs a "fast forward"; the head of the current branch is moved +just performs a "fast-forward"; the head of the current branch is moved forward to point at the head of the merged-in branch, without any new commits being created. @@ -1421,7 +1473,7 @@ Fixing a mistake by rewriting history If the problematic commit is the most recent commit, and you have not yet made that commit public, then you may just -<<undoing-a-merge,destroy it using git-reset>>. +<<undoing-a-merge,destroy it using `git reset`>>. Alternatively, you can edit the working directory and update the index to fix your @@ -1449,7 +1501,7 @@ Checking out an old version of a file In the process of undoing a previous bad change, you may find it useful to check out an older version of a particular file using -linkgit:git-checkout[1]. We've used git checkout before to switch +linkgit:git-checkout[1]. We've used `git checkout` before to switch branches, but it has quite different behavior if it is given a path name: the command @@ -1482,7 +1534,7 @@ so on a different branch and then coming back), unstash the work-in-progress changes. ------------------------------------------------ -$ git stash "work in progress for foo feature" +$ git stash save "work in progress for foo feature" ------------------------------------------------ This command will save your changes away to the `stash`, and @@ -1495,10 +1547,10 @@ $ git commit -a -m "blorpl: typofix" ------------------------------------------------ After that, you can go back to what you were working on with -`git stash apply`: +`git stash pop`: ------------------------------------------------ -$ git stash apply +$ git stash pop ------------------------------------------------ @@ -1517,7 +1569,7 @@ $ git gc ------------------------------------------------- to recompress the archive. This can be very time-consuming, so -you may prefer to run git-gc when you are not doing other work. +you may prefer to run `git gc` when you are not doing other work. [[ensuring-reliability]] @@ -1530,7 +1582,7 @@ Checking the repository for corruption The linkgit:git-fsck[1] command runs a number of self-consistency checks on the repository, and reports on any problems. This may take some -time. The most common warning by far is about "dangling" objects: +time. ------------------------------------------------- $ git fsck @@ -1545,9 +1597,11 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f ... ------------------------------------------------- -Dangling objects are not a problem. At worst they may take up a little -extra disk space. They can sometimes provide a last-resort method for -recovering lost work--see <<dangling-objects>> for details. +You will see informational messages on dangling objects. They are objects +that still exist in the repository but are no longer referenced by any of +your branches, and can (and will) be removed after a while with "gc". +You can run `git fsck --no-dangling` to supress these messages, and still +view real errors. [[recovering-lost-changes]] Recovering lost changes @@ -1557,7 +1611,7 @@ Recovering lost changes Reflogs ^^^^^^^ -Say you modify a branch with `linkgit:git-reset[1] --hard`, and then +Say you modify a branch with +linkgit:git-reset[1] \--hard+, and then realize that the branch was the only reference you had to that point in history. @@ -1594,7 +1648,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 @@ -1609,7 +1663,7 @@ In some situations the reflog may not be able to save you. For example, suppose you delete a branch, then realize you need the history it contained. The reflog is also deleted; however, if you have not yet pruned the repository, then you may still be able to find the lost -commits in the dangling objects that git-fsck reports. See +commits in the dangling objects that `git fsck` reports. See <<dangling-objects>> for the details. ------------------------------------------------- @@ -1650,16 +1704,16 @@ dangling objects can arise in other situations. Sharing development with others =============================== -[[getting-updates-with-git-pull]] +[[getting-updates-With-git-pull]] Getting updates with git pull ----------------------------- -After you clone a repository and make a few changes of your own, you +After you clone a repository and commit a few changes of your own, you may wish to check the original repository for updates and merge them into your own work. -We have already seen <<Updating-a-repository-with-git-fetch,how to -keep remote tracking branches up to date>> with linkgit:git-fetch[1], +We have already seen <<Updating-a-repository-With-git-fetch,how to +keep remote-tracking branches up to date>> with linkgit:git-fetch[1], and how to merge two branches. So you can merge in changes from the original repository's master branch with: @@ -1675,15 +1729,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 @@ -1694,10 +1754,10 @@ producing a default commit message documenting the branch and repository that you pulled from. (But note that no such commit will be created in the case of a -<<fast-forwards,fast forward>>; instead, your branch will just be +<<fast-forwards,fast-forward>>; instead, your branch will just be updated to point to the latest commit from the upstream branch.) -The git-pull command can also be given "." as the "remote" repository, +The `git pull` command can also be given "." as the "remote" repository, in which case it just merges in a branch from the current repository; so the commands @@ -1769,8 +1829,8 @@ Public git repositories Another way to submit changes to a project is to tell the maintainer of that project to pull the changes from your repository using -linkgit:git-pull[1]. In the section "<<getting-updates-with-git-pull, -Getting updates with git pull>>" we described this as a way to get +linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull, +Getting updates with `git pull`>>" we described this as a way to get updates from the "main" repository, but it works just as well in the other direction. @@ -1822,7 +1882,7 @@ Setting up a public repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Assume your personal repository is in the directory ~/proj. We -first create a new clone of the repository and tell git-daemon that it +first create a new clone of the repository and tell `git daemon` that it is meant to be public: ------------------------------------------------- @@ -1853,10 +1913,10 @@ repository>>", below. Otherwise, all you need to do is start linkgit:git-daemon[1]; it will listen on port 9418. By default, it will allow access to any directory that looks like a git directory and contains the magic file -git-daemon-export-ok. Passing some directory paths as git-daemon +git-daemon-export-ok. Passing some directory paths as `git daemon` arguments will further restrict the exports to those paths. -You can also run git-daemon as an inetd service; see the +You can also run `git daemon` as an inetd service; see the linkgit:git-daemon[1] man page for details. (See especially the examples section.) @@ -1875,12 +1935,11 @@ adjustments to give web clients some extra information they need: $ mv proj.git /home/you/public_html/proj.git $ cd proj.git $ git --bare update-server-info -$ chmod a+x hooks/post-update +$ mv hooks/post-update.sample hooks/post-update ------------------------------------------------- (For an explanation of the last two lines, see -linkgit:git-update-server-info[1], and the documentation -linkgit:githooks[5][Hooks used by git].) +linkgit:git-update-server-info[1] and linkgit:githooks[5].) Advertise the URL of proj.git. Anybody else should then be able to clone or pull from that URL, for example with a command line like: @@ -1918,8 +1977,8 @@ or just $ git push ssh://yourserver.com/~you/proj.git master ------------------------------------------------- -As with git-fetch, git-push will complain if this does not result in a -<<fast-forwards,fast forward>>; see the following section for details on +As with `git fetch`, `git push` will complain if this does not result in a +<<fast-forwards,fast-forward>>; see the following section for details on handling this case. Note that the target of a "push" is normally a @@ -1928,7 +1987,7 @@ repository that has a checked-out working tree, but the working tree will not be updated by the push. This may lead to unexpected results if the branch you push to is the currently checked-out branch! -As with git-fetch, you may also set up configuration options to +As with `git fetch`, you may also set up configuration options to save typing; so, for example, after ------------------------------------------------- @@ -1952,7 +2011,7 @@ details. What to do when a push fails ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If a push would not result in a <<fast-forwards,fast forward>> of the +If a push would not result in a <<fast-forwards,fast-forward>> of the remote branch, then it will fail with an error like: ------------------------------------------------- @@ -1970,7 +2029,7 @@ This can happen, for example, if you: - use `git rebase` to rebase any already-published commits (as in <<using-git-rebase>>). -You may force git-push to perform the update anyway by preceding the +You may force `git push` to perform the update anyway by preceding the branch name with a plus sign: ------------------------------------------------- @@ -1980,7 +2039,7 @@ $ git push ssh://yourserver.com/~you/proj.git +master Normally whenever a branch head in a public repository is modified, it is modified to point to a descendant of the commit that it pointed to before. By forcing a push in this situation, you break that convention. -(See <<problems-with-rewriting-history>>.) +(See <<problems-With-rewriting-history>>.) Nevertheless, this is a common practice for people that need a simple way to publish a work-in-progress patch series, and it is an acceptable @@ -1989,10 +2048,10 @@ intend to manage the branch. It's also possible for a push to fail in this way when other people have the right to push to the same repository. In that case, the correct -solution is to retry the push after first updating your work by either a -pull or a fetch followed by a rebase; see the +solution is to retry the push after first updating your work: either by a +pull, or by a fetch followed by a rebase; see the <<setting-up-a-shared-repository,next section>> and -linkgit:gitcvs-migration[7][git for CVS users] for more. +linkgit:gitcvs-migration[7] for more. [[setting-up-a-shared-repository]] Setting up a shared repository @@ -2001,7 +2060,7 @@ Setting up a shared repository Another way to collaborate is by using a model similar to that commonly used in CVS, where several developers with special rights all push to and pull from a single shared repository. See -linkgit:gitcvs-migration[7][git for CVS users] for instructions on how to +linkgit:gitcvs-migration[7] for instructions on how to set this up. However, while there is nothing wrong with git's support for shared @@ -2012,7 +2071,7 @@ advantages over the central shared repository: - Git's ability to quickly import and merge patches allows a single maintainer to process incoming changes even at very - high rates. And when that becomes too much, git-pull provides + high rates. And when that becomes too much, `git pull` provides an easy way for that maintainer to delegate this job to other maintainers while still allowing optional review of incoming changes. @@ -2066,7 +2125,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 @@ -2091,7 +2150,7 @@ $ git checkout release && git pull Important note! If you have any local changes in these branches, then this merge will create a commit object in the history (with no local -changes git will simply do a "Fast forward" merge). Many people dislike +changes git will simply do a "fast-forward" merge). Many people dislike the "noise" that this creates in the Linux history, so you should avoid doing this capriciously in the "release" branch, as these noisy commits will become part of the permanent history when you ask Linus to pull @@ -2131,11 +2190,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 @@ -2171,7 +2233,7 @@ they are for, or what status they are in. To get a reminder of what changes are in a specific branch, use: ------------------------------------------------- -$ git log linux..branchname | git-shortlog +$ git log linux..branchname | git shortlog ------------------------------------------------- To see whether it has already been merged into the test or release branches, @@ -2380,7 +2442,7 @@ use them, and then explain some of the problems that can arise because you are rewriting history. [[using-git-rebase]] -Keeping a patch series up to date using git-rebase +Keeping a patch series up to date using git rebase -------------------------------------------------- Suppose that you create a branch "mywork" on a remote-tracking branch @@ -2399,9 +2461,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 @@ -2432,7 +2494,7 @@ $ git rebase origin ------------------------------------------------- This will remove each of your commits from mywork, temporarily saving -them as patches (in a directory named ".dotest"), update mywork to +them as patches (in a directory named ".git/rebase-apply"), update mywork to point at the latest version of origin, then apply each of the saved patches to the new mywork. The result will look like: @@ -2444,9 +2506,9 @@ patches to the new mywork. The result will look like: ................................................ In the process, it may discover conflicts. In that case it will stop -and allow you to fix the conflicts; after fixing conflicts, use "git -add" to update the index with those contents, and then, instead of -running git-commit, just run +and allow you to fix the conflicts; after fixing conflicts, use `git add` +to update the index with those contents, and then, instead of +running `git commit`, just run ------------------------------------------------- $ git rebase --continue @@ -2484,7 +2546,7 @@ with $ git tag bad mywork~5 ------------------------------------------------- -(Either gitk or git-log may be useful for finding the commit.) +(Either gitk or `git log` may be useful for finding the commit.) Then check out that commit, edit it, and rebase the rest of the series on top of it (note that we could check out the commit on a temporary @@ -2525,12 +2587,12 @@ $ gitk origin..mywork & and browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using `commit --amend`. +cherry-pick, and possibly modifying them as you go using `git commit --amend`. The linkgit:git-gui[1] command may also help as it allows you to individually select diff hunks for inclusion in the index (by right-clicking on the diff hunk and choosing "Stage Hunk for Commit"). -Another technique is to use git-format-patch to create a series of +Another technique is to use `git format-patch` to create a series of patches, then reset the state to before the patches: ------------------------------------------------- @@ -2545,11 +2607,11 @@ them again with linkgit:git-am[1]. Other tools ----------- -There are numerous other tools, such as StGIT, which exist for the +There are numerous other tools, such as StGit, which exist for the purpose of maintaining a patch series. These are outside of the scope of this manual. -[[problems-with-rewriting-history]] +[[problems-With-rewriting-history]] Problems with rewriting history ------------------------------- @@ -2638,7 +2700,7 @@ you know is that D is bad, that Z is good, and that linkgit:git-bisect[1] identifies C as the culprit, how will you figure out that the problem is due to this change in semantics? -When the result of a git-bisect is a non-merge commit, you should +When the result of a `git bisect` is a non-merge commit, you should normally be able to discover the problem by examining just that commit. Developers can make this easy by breaking their changes into small self-contained commits. That won't help in the case above, however, @@ -2701,13 +2763,13 @@ master branch. In more detail: git fetch and fast-forwards --------------------------- -In the previous example, when updating an existing branch, "git -fetch" checks to make sure that the most recent commit on the remote +In the previous example, when updating an existing branch, "git fetch" +checks to make sure that the most recent commit on the remote branch is a descendant of the most recent commit on your copy of the branch before updating your copy of the branch to point at the new -commit. Git calls this process a <<fast-forwards,fast forward>>. +commit. Git calls this process a <<fast-forwards,fast-forward>>. -A fast forward looks something like this: +A fast-forward looks something like this: ................................................ o--o--o--o <-- old head of the branch @@ -2757,8 +2819,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 @@ -2812,7 +2874,7 @@ $ git config remote.example.fetch +master:ref/remotes/example/master ------------------------------------------------- Don't do this unless you're sure you won't mind "git fetch" possibly -throwing away commits on mybranch. +throwing away commits on 'example/master'. Also note that all of the above configuration can be performed by directly editing the file .git/config instead of using @@ -2841,8 +2903,8 @@ The Object Database We already saw in <<understanding-commits>> that all commits are stored under a 40-digit "object name". In fact, all the information needed to represent the history of a project is stored in objects with such names. -In each case the name is calculated by taking the SHA1 hash of the -contents of the object. The SHA1 hash is a cryptographic hash function. +In each case the name is calculated by taking the SHA-1 hash of the +contents of the object. The SHA-1 hash is a cryptographic hash function. What that means to us is that it is impossible to find two different objects with the same name. This has a number of advantages; among others: @@ -2853,16 +2915,16 @@ others: same content stored in two repositories will always be stored under the same name. - Git can detect errors when it reads an object, by checking that the - object's name is still the SHA1 hash of its contents. + object's name is still the SHA-1 hash of its contents. (See <<object-details>> for the details of the object formatting and -SHA1 calculation.) +SHA-1 calculation.) There are four different types of objects: "blob", "tree", "commit", and "tag". - A <<def_blob_object,"blob" object>> is used to store file data. -- A <<def_tree_object,"tree" object>> is an object that ties one or more +- A <<def_tree_object,"tree" object>> ties one or more "blob" objects into a directory structure. In addition, a tree object can refer to other tree objects, thus creating a directory hierarchy. - A <<def_commit_object,"commit" object>> ties such directory hierarchies @@ -2902,9 +2964,9 @@ committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700 As you can see, a commit is defined by: -- a tree: The SHA1 name of a tree object (as defined below), representing +- a tree: The SHA-1 name of a tree object (as defined below), representing the contents of a directory at a certain point in time. -- parent(s): The SHA1 name of some number of commits which represent the +- parent(s): The SHA-1 name of some number of commits which represent the immediately previous step(s) in the history of the project. The example above has one parent; merge commits may have more than one. A commit with no parents is called a "root" commit, and @@ -2953,13 +3015,13 @@ $ git ls-tree fb3a8bdd0ce ------------------------------------------------ As you can see, a tree object contains a list of entries, each with a -mode, object type, SHA1 name, and name, sorted by name. It represents +mode, object type, SHA-1 name, and name, sorted by name. It represents the contents of a single directory tree. The object type may be a blob, representing the contents of a file, or another tree, representing the contents of a subdirectory. Since trees -and blobs, like all other objects, are named by the SHA1 hash of their -contents, two trees have the same SHA1 name if and only if their +and blobs, like all other objects, are named by the SHA-1 hash of their +contents, two trees have the same SHA-1 name if and only if their contents (including, recursively, the contents of all subdirectories) are identical. This allows git to quickly determine the differences between two related tree objects, since it can ignore any entries with @@ -3005,15 +3067,15 @@ currently checked out. Trust ~~~~~ -If you receive the SHA1 name of a blob from one source, and its contents +If you receive the SHA-1 name of a blob from one source, and its contents from another (possibly untrusted) source, you can still trust that those -contents are correct as long as the SHA1 name agrees. This is because -the SHA1 is designed so that it is infeasible to find different contents +contents are correct as long as the SHA-1 name agrees. This is because +the SHA-1 is designed so that it is infeasible to find different contents that produce the same hash. -Similarly, you need only trust the SHA1 name of a top-level tree object +Similarly, you need only trust the SHA-1 name of a top-level tree object to trust the contents of the entire directory that it refers to, and if -you receive the SHA1 name of a commit from a trusted source, then you +you receive the SHA-1 name of a commit from a trusted source, then you can easily verify the entire history of commits reachable through parents of that commit, and all of those contents of the trees referred to by those commits. @@ -3025,7 +3087,7 @@ that you trust that commit, and the immutability of the history of commits tells others that they can trust the whole history. In other words, you can easily validate a whole archive by just -sending out a single email that tells the people the name (SHA1 hash) +sending out a single email that tells the people the name (SHA-1 hash) of the top commit, and digitally sign that email using something like GPG/PGP. @@ -3037,7 +3099,7 @@ Tag Object A tag object contains an object, object type, tag name, the name of the person ("tagger") who created the tag, and a message, which may contain -a signature, as can be seen using the linkgit:git-cat-file[1]: +a signature, as can be seen using linkgit:git-cat-file[1]: ------------------------------------------------ $ git cat-file tag v1.5.0 @@ -3066,7 +3128,7 @@ How git stores objects efficiently: pack files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Newly created objects are initially created in a file named after the -object's SHA1 hash (stored in .git/objects). +object's SHA-1 hash (stored in .git/objects). Unfortunately this system becomes inefficient once a project has a lot of objects. Try this on an old project: @@ -3201,9 +3263,9 @@ and they'll be gone. But you should only run "git prune" on a quiescent repository--it's kind of like doing a filesystem fsck recovery: you don't want to do that while the filesystem is mounted. -(The same is true of "git-fsck" itself, btw, but since -git-fsck never actually *changes* the repository, it just reports -on what it found, git-fsck itself is never "dangerous" to run. +(The same is true of "git fsck" itself, btw, but since +`git fsck` never actually *changes* the repository, it just reports +on what it found, `git fsck` itself is never 'dangerous' to run. Running it while somebody is actually changing the repository can cause confusing and scary messages, but it won't actually do anything bad. In contrast, running "git prune" while somebody is actively changing the @@ -3235,15 +3297,12 @@ it is with linkgit:git-fsck[1]; this may be time-consuming. Assume the output looks like this: ------------------------------------------------ -$ git-fsck --full +$ git fsck --full --no-dangling broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 to blob 4b9458b3786228369c63936db65827de3cc06200 missing blob 4b9458b3786228369c63936db65827de3cc06200 ------------------------------------------------ -(Typically there will be some "dangling object" messages too, but they -aren't interesting.) - Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 points to it. If you could find just one copy of that missing blob object, possibly in some other repository, you could move it into @@ -3273,7 +3332,7 @@ $ git hash-object -w somedirectory/myfile ------------------------------------------------ which will create and store a blob object with the contents of -somedirectory/myfile, and output the sha1 of that object. if you're +somedirectory/myfile, and output the SHA-1 of that object. if you're extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in which case you've guessed right, and the corruption is fixed! @@ -3335,7 +3394,7 @@ The index ----------- The index is a binary file (generally kept in .git/index) containing a -sorted list of path names, each with permissions and the SHA1 of a blob +sorted list of path names, each with permissions and the SHA-1 of a blob object; linkgit:git-ls-files[1] can show you the contents of the index: ------------------------------------------------- @@ -3459,7 +3518,7 @@ $ cd super $ git init $ for i in a b c d do - git submodule add ~/git/$i + git submodule add ~/git/$i $i done ------------------------------------------------- @@ -3472,10 +3531,10 @@ $ ls -a . .. .git .gitmodules a b c d ------------------------------------------------- -The `git submodule add` command does a couple of things: +The `git submodule add <repo> <path>` command does a couple of things: -- It clones the submodule under the current directory and by default checks out - the master branch. +- It clones the submodule from <repo> to the given <path> under the + current directory and by default checks out the master branch. - It adds the submodule's clone path to the linkgit:gitmodules[5] file and adds this file to the index, ready to be committed. - It adds the submodule's current commit ID to the index, ready to be @@ -3600,6 +3659,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. @@ -3695,7 +3774,7 @@ removed. The only thing `--remove` means is that update-index will be considering a removed file to be a valid thing, and if the file really does not exist any more, it will update the index accordingly. -As a special case, you can also do `git-update-index --refresh`, which +As a special case, you can also do `git update-index --refresh`, which will refresh the "stat" information of each index to match the current stat information. It will 'not' update the object status itself, and it will only update the fields that are used to quickly test whether @@ -3730,7 +3809,7 @@ unsaved state that you might want to restore later!) your current index. Normal operation is just ------------------------------------------------- -$ git-read-tree <sha1 of tree> +$ git read-tree <SHA-1 of tree> ------------------------------------------------- and your index file will now be equivalent to the tree that you saved @@ -3745,7 +3824,7 @@ You update your working directory from the index by "checking out" files. This is not a very common operation, since normally you'd just keep your files updated, and rather than write to your working directory, you'd tell the index files about the changes in your -working directory (i.e. `git-update-index`). +working directory (i.e. `git update-index`). However, if you decide to jump to a new version, or check out somebody else's version, or just restore a previous tree, you'd populate your @@ -3753,12 +3832,12 @@ index file with read-tree, and then you need to check out the result with ------------------------------------------------- -$ git-checkout-index filename +$ git checkout-index filename ------------------------------------------------- or, if you want to check out all of the index, use `-a`. -NOTE! git-checkout-index normally refuses to overwrite old files, so +NOTE! `git checkout-index` normally refuses to overwrite old files, so if you have an old version of the tree already checked out, you will need to use the "-f" flag ('before' the "-a" flag or the filename) to 'force' the checkout. @@ -3771,7 +3850,7 @@ from one representation to the other: Tying it all together ~~~~~~~~~~~~~~~~~~~~~ -To commit a tree you have instantiated with "git-write-tree", you'd +To commit a tree you have instantiated with "git write-tree", you'd create a "commit" object that refers to that tree and the history behind it--most notably the "parent" commits that preceded it in history. @@ -3790,13 +3869,13 @@ 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 redirection from a pipe or file, or by just typing it at the tty). -git-commit-tree will return the name of the object that represents +`git commit-tree` will return the name of the object that represents that commit, and you should save it away for later use. Normally, you'd commit a new `HEAD` state, and while git doesn't care where you save the note about that state, in practice we tend to just write the @@ -3853,19 +3932,19 @@ linkgit:git-cat-file[1] to examine details about the object: ------------------------------------------------- -$ git-cat-file -t <objectname> +$ git cat-file -t <objectname> ------------------------------------------------- shows the type of the object, and once you have the type (which is usually implicit in where you find the object), you can use ------------------------------------------------- -$ git-cat-file blob|tree|commit|tag <objectname> +$ git cat-file blob|tree|commit|tag <objectname> ------------------------------------------------- to show its contents. NOTE! Trees have binary content, and as a result there is a special helper for showing that content, called -`git-ls-tree`, which turns the binary content into a more easily +`git ls-tree`, which turns the binary content into a more easily readable form. It's especially instructive to look at "commit" objects, since those @@ -3874,7 +3953,7 @@ follow the convention of having the top commit name in `.git/HEAD`, you can do ------------------------------------------------- -$ git-cat-file commit HEAD +$ git cat-file commit HEAD ------------------------------------------------- to see what the top commit was. @@ -3898,7 +3977,7 @@ To get the "base" for the merge, you first look up the common parent of two commits with ------------------------------------------------- -$ git-merge-base <commit1> <commit2> +$ git merge-base <commit1> <commit2> ------------------------------------------------- which will return you the commit they are both based on. You should @@ -3906,7 +3985,7 @@ now look up the "tree" objects of those commits, which you can easily do with (for example) ------------------------------------------------- -$ git-cat-file commit <commitname> | head -1 +$ git cat-file commit <commitname> | head -1 ------------------------------------------------- since the tree object information is always the first line in a commit @@ -3923,12 +4002,12 @@ you have in your current index anyway). To do the merge, do ------------------------------------------------- -$ git-read-tree -m -u <origtree> <yourtree> <targettree> +$ git read-tree -m -u <origtree> <yourtree> <targettree> ------------------------------------------------- which will do all trivial merge operations for you directly in the index file, and you can just write the result out with -`git-write-tree`. +`git write-tree`. [[merging-multiple-trees-2]] @@ -3942,25 +4021,25 @@ entries" in it. Such an index tree can 'NOT' be written out to a tree object, and you will have to resolve any such merge clashes using other tools before you can write out the result. -You can examine such index state with `git-ls-files --unmerged` +You can examine such index state with `git ls-files --unmerged` command. An example: ------------------------------------------------ -$ git-read-tree -m $orig HEAD $target -$ git-ls-files --unmerged +$ git read-tree -m $orig HEAD $target +$ git ls-files --unmerged 100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c 100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c ------------------------------------------------ -Each line of the `git-ls-files --unmerged` output begins with -the blob mode bits, blob SHA1, 'stage number', and the +Each line of the `git ls-files --unmerged` output begins with +the blob mode bits, blob SHA-1, 'stage number', and the filename. The 'stage number' is git's way to say which tree it came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD` tree, and stage3 `$target` tree. Earlier we said that trivial merges are done inside -`git-read-tree -m`. For example, if the file did not change +`git read-tree -m`. For example, if the file did not change from `$orig` to `HEAD` nor `$target`, or if the file changed from `$orig` to `HEAD` and `$orig` to `$target` the same way, obviously the final outcome is what is in `HEAD`. What the @@ -3971,9 +4050,9 @@ program, e.g. `diff3`, `merge`, or git's own merge-file, on the blob objects from these three stages yourself, like this: ------------------------------------------------ -$ git-cat-file blob 263414f... >hello.c~1 -$ git-cat-file blob 06fa6a2... >hello.c~2 -$ git-cat-file blob cc44c73... >hello.c~3 +$ git cat-file blob 263414f... >hello.c~1 +$ git cat-file blob 06fa6a2... >hello.c~2 +$ git cat-file blob cc44c73... >hello.c~3 $ git merge-file hello.c~2 hello.c~1 hello.c~3 ------------------------------------------------ @@ -3984,20 +4063,20 @@ merge result for this file is by: ------------------------------------------------- $ mv -f hello.c~2 hello.c -$ git-update-index hello.c +$ git update-index hello.c ------------------------------------------------- -When a path is in unmerged state, running `git-update-index` for +When a path is in the "unmerged" state, running `git update-index` for that path tells git to mark the path resolved. The above is the description of a git merge at the lowest level, to help you understand what conceptually happens under the hood. -In practice, nobody, not even git itself, uses three `git-cat-file` -for this. There is `git-merge-index` program that extracts the +In practice, nobody, not even git itself, runs `git cat-file` three times +for this. There is a `git merge-index` program that extracts the stages to temporary files and calls a "merge" script on it: ------------------------------------------------- -$ git-merge-index git-merge-one-file hello.c +$ git merge-index git-merge-one-file hello.c ------------------------------------------------- and that is what higher level `git merge -s resolve` is implemented with. @@ -4021,12 +4100,12 @@ objects). There are currently four different object types: "blob", Regardless of object type, all objects share the following characteristics: they are all deflated with zlib, and have a header that not only specifies their type, but also provides size information -about the data in the object. It's worth noting that the SHA1 hash +about the data in the object. It's worth noting that the SHA-1 hash that is used to name the object is the hash of the original data plus this header, so `sha1sum` 'file' does not match the object name for 'file'. (Historical note: in the dawn of the age of git the hash -was the sha1 of the 'compressed' object.) +was the SHA-1 of the 'compressed' object.) As a result, the general consistency of an object can always be tested independently of the contents or the type of the object: all objects can @@ -4037,7 +4116,7 @@ size> {plus} <byte\0> {plus} <binary object data>. The structured objects can further have their structure and connectivity to other objects verified. This is generally done with -the `git-fsck` program, which generates a full dependency graph +the `git fsck` program, which generates a full dependency graph of all objects, and verifies their internal consistency (in addition to just verifying their superficial consistency through the hash). @@ -4062,7 +4141,7 @@ Note that terminology has changed since that revision. For example, the README in that revision uses the word "changeset" to describe what we now call a <<def_commit_object,commit>>. -Also, we do not call it "cache" any more, but "index", however, the +Also, we do not call it "cache" any more, but rather "index"; however, the file is still called `cache.h`. Remark: Not much reason to change it now, especially since there is no good single name for it anyway, because it is basically _the_ header file which is included by _all_ of Git's C sources. @@ -4105,20 +4184,20 @@ $ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \ What does this mean? -`git-rev-list` is the original version of the revision walker, which +`git rev-list` is the original version of the revision walker, which _always_ printed a list of revisions to stdout. It is still functional, -and needs to, since most new Git programs start out as scripts using -`git-rev-list`. +and needs to, since most new Git commands start out as scripts using +`git rev-list`. -`git-rev-parse` is not as important any more; it was only used to filter out +`git rev-parse` is not as important any more; it was only used to filter out options that were relevant for the different plumbing commands that were called by the script. -Most of what `git-rev-list` did is contained in `revision.c` and +Most of what `git rev-list` did is contained in `revision.c` and `revision.h`. It wraps the options in a struct named `rev_info`, which controls how and what revisions are walked, and more. -The original job of `git-rev-parse` is now taken by the function +The original job of `git rev-parse` is now taken by the function `setup_revisions()`, which parses the revisions and the common command line options for the revision walker. This information is stored in the struct `rev_info` for later consumption. You can do your own command line option @@ -4128,7 +4207,7 @@ commits one by one with the function `get_revision()`. If you are interested in more details of the revision walking process, just have a look at the first implementation of `cmd_log()`; call -`git-show v1.3.0{tilde}155^2{tilde}4` and scroll down to that function (note that you +`git show v1.3.0~155^2~4` and scroll down to that function (note that you no longer need to call `setup_pager()` directly). Nowadays, `git log` is a builtin, which means that it is _contained_ in the @@ -4174,7 +4253,7 @@ it does. ------------------------------------------------------------------ git_config(git_default_config); if (argc != 3) - usage("git-cat-file [-t|-s|-e|-p|<type>] <sha1>"); + usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>"); if (get_sha1(argv[2], sha1)) die("Not a valid object name %s", argv[2]); ------------------------------------------------------------------ @@ -4191,9 +4270,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 *`, 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 *`, it is the binary representation, as opposed to the ASCII representation in hex characters, which is passed as `char *`. @@ -4251,7 +4330,7 @@ You see, Git is actually the best tool to find out about the source of Git itself! [[glossary]] -GIT Glossary +Git Glossary ============ include::glossary-content.txt[] @@ -4342,7 +4421,9 @@ $ git remote show example # get details * remote example URL: git://example.com/project.git Tracked remote branches - master next ... + master + next + ... $ git fetch example # update branches from example $ git branch -r # list all remote branches ----------------------------------------------- @@ -4504,7 +4585,7 @@ The basic requirements: - Whenever possible, section headings should clearly describe the task they explain how to do, in language that requires no more knowledge than necessary: for example, "importing patches into a project" rather - than "the git-am command" + than "the `git am` command" Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading @@ -4546,4 +4627,3 @@ Alternates, clone -reference, etc. More on recovery from repository corruption. See: http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2 http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 - http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 |