diff options
Diffstat (limited to 'Documentation')
194 files changed, 3722 insertions, 1612 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index a37b2152b..2f938f471 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -2,6 +2,7 @@ *.html *.[1-8] *.made +git.info howto-index.txt doc.dep cmds-*.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index d88664177..7b0685b7b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -2,10 +2,14 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ gitk.txt -MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt +MAN5_TXT=gitattributes.txt gitignore.txt gitcli.txt gitmodules.txt MAN7_TXT=git.txt -DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) +MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) +MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) +MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) + +DOC_HTML=$(MAN_HTML) ARTICLES = tutorial ARTICLES += tutorial-2 @@ -20,6 +24,9 @@ ARTICLES += git-tools ARTICLES += glossary # with their own formatting rules. SP_ARTICLES = howto/revert-branch-rebase user-manual +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 DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) @@ -29,6 +36,7 @@ DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) prefix?=$(HOME) bindir?=$(prefix)/bin +htmldir?=$(prefix)/share/doc/git-doc mandir?=$(prefix)/share/man man1dir=$(mandir)/man1 man5dir=$(mandir)/man5 @@ -45,6 +53,9 @@ infodir?=$(prefix)/share/info MAKEINFO=makeinfo INSTALL_INFO=install-info DOCBOOK2X_TEXI=docbook2x-texi +ifndef PERL_PATH + PERL_PATH = /usr/bin/perl +endif -include ../config.mak.autogen -include ../config.mak @@ -76,25 +87,29 @@ man1: $(DOC_MAN1) man5: $(DOC_MAN5) man7: $(DOC_MAN7) -info: git.info +info: git.info gitman.info install: man - $(INSTALL) -d -m755 $(DESTDIR)$(man1dir) - $(INSTALL) -d -m755 $(DESTDIR)$(man5dir) - $(INSTALL) -d -m755 $(DESTDIR)$(man7dir) - $(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir) - $(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir) - $(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir) + $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir) + $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir) + $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) + $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir) + $(INSTALL) -m 644 $(DOC_MAN5) $(DESTDIR)$(man5dir) + $(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir) install-info: info - $(INSTALL) -d -m755 $(DESTDIR)$(infodir) - $(INSTALL) -m644 git.info $(DESTDIR)$(infodir) + $(INSTALL) -d -m 755 $(DESTDIR)$(infodir) + $(INSTALL) -m 644 git.info gitman.info $(DESTDIR)$(infodir) if test -r $(DESTDIR)$(infodir)/dir; then \ $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\ + $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) gitman.info ;\ else \ echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \ fi +install-html: html + sh ./install-webdoc.sh $(DESTDIR)$(htmldir) + ../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE $(MAKE) -C ../ GIT-VERSION-FILE @@ -105,7 +120,7 @@ install-info: info # doc.dep : $(wildcard *.txt) build-docdep.perl $(RM) $@+ $@ - perl ./build-docdep.perl >$@+ + $(PERL_PATH) ./build-docdep.perl >$@+ mv $@+ $@ -include doc.dep @@ -122,18 +137,21 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ $(cmds_txt): cmd-list.made -cmd-list.made: cmd-list.perl $(MAN1_TXT) +cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) $(RM) $@ - perl ./cmd-list.perl + $(PERL_PATH) ./cmd-list.perl ../command-list.txt date >$@ git.7 git.html: git.txt clean: - $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ howto-index.txt howto/*.html doc.dep + $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 + $(RM) *.texi *.texi+ git.info gitman.info + $(RM) howto-index.txt howto/*.html doc.dep + $(RM) technical/api-*.html technical/api-index.txt $(RM) $(cmds_txt) *.made -%.html : %.txt +$(MAN_HTML): %.html : %.txt $(RM) $@+ $@ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< @@ -152,18 +170,41 @@ clean: user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC) -b docbook -d book $< +technical/api-index.txt: technical/api-index-skel.txt \ + technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) + cd technical && sh ./api-index.sh + +$(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt + $(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) $< -git.info: user-manual.xml - $(RM) $@ $*.texi $*.texi+ - $(DOCBOOK2X_TEXI) user-manual.xml --to-stdout >$*.texi+ - perl fix-texi.perl <$*.texi+ >$*.texi +git.info: user-manual.texi + $(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 >$@+ + mv $@+ $@ + +gitman.texi: $(MAN_XML) cat-texi.perl + $(RM) $@+ $@ + ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --to-stdout $(xml);)) | \ + $(PERL_PATH) cat-texi.perl $@ >$@+ + mv $@+ $@ + +gitman.info: gitman.texi $(MAKEINFO) --no-split $*.texi - $(RM) $*.texi $*.texi+ + +$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml + $(RM) $@+ $@ + $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ + mv $@+ $@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) $(RM) $@+ $@ @@ -184,6 +225,6 @@ install-webdoc : html sh ./install-webdoc.sh $(WEBDOC_DEST) quick-install: - sh ./install-doc-quick.sh $(DOC_REF) $(mandir) + sh ./install-doc-quick.sh $(DOC_REF) $(DESTDIR)$(mandir) .PHONY: .FORCE-GIT-VERSION-FILE diff --git a/Documentation/RelNotes-1.5.4.txt b/Documentation/RelNotes-1.5.4.txt new file mode 100644 index 000000000..c05de3d1d --- /dev/null +++ b/Documentation/RelNotes-1.5.4.txt @@ -0,0 +1,363 @@ +GIT v1.5.4 Release Notes +======================== + +Removal +------- + + * "git svnimport" was removed in favor of "git svn". It is still there + in the source tree (contrib/examples) but unsupported. + + * As git-commit and git-status have been rewritten, "git runstatus" + helper script lost all its users and has been removed. + + +Deprecation notices +------------------- + + * The next feature release of git (this change is scheduled for v1.6.0) + will by default install dashed form of commands (e.g. "git-commit") + outside of users' normal $PATH, and will install only selected + commands ("git" itself, and "gitk") in $PATH. This implies: + + - Using dashed forms of git commands (e.g. "git-commit") from the + command line has been informally deprecated since early 2006, but + now it officially is, and will be removed in the future. Use + dashless forms (e.g. "git commit") instead. + + - Using dashed forms from your scripts, without first prepending the + return value from "git --exec-path" to the scripts' PATH, has been + informally deprecated since early 2006, but now it officially is. + + - Use of dashed forms with "PATH=$(git --exec-path):$PATH; export + PATH" early in your script is not deprecated with this change. + + Users are strongly encouraged to adjust their habits and scripts now + to prepare for this. + + * The post-receive hook was introduced in March 2007 to supersede + the post-update hook, primarily to overcome the command line length + limitation of the latter. Use of post-update hook will be deprecated + in future versions of git, starting from v1.6.0. + + * "git lost-found" was deprecated in favor of "git fsck"'s --lost-found + option, and will be removed in the future. + + * "git peek-remote" is deprecated, as "git ls-remote" was written in C + and works for all transports; "git peek-remote" will be removed in + the future. + + * From v1.6.0, the repack.usedeltabaseoffset config option will default + to true, which will give denser packfiles (i.e. more efficient storage). + The downside is that git older than version 1.4.4 will not be able + to directly use a repository packed using this setting. + + * From v1.6.0, the pack.indexversion config option will default to 2, + which is slightly more efficient, and makes repacking more immune to + data corruptions. Git older than version 1.5.2 may revert to version 1 + of the pack index with a manual "git index-pack" to be able to directly + access corresponding pack files. + + +Updates since v1.5.3 +-------------------- + + * Comes with much improved gitk. + + * Comes with "git gui" 0.9.1 with i18n. + + * gitk is now merged as a subdirectory of git.git project, in + preparation for its i18n. + + * progress displays from many commands are a lot nicer to the eye. + Transfer commands show throughput data. + + * many commands that pay attention to per-directory .gitignore now do + so lazily, which makes the usual case go much faster. + + * Output processing for '--pretty=format:<user format>' has been + optimized. + + * Rename detection of diff family while detecting exact matches has + been greatly optimized. + + * Rename detection of diff family tries to make more natural looking + pairing. Earlier, if multiple identical rename sources were + found in the preimage, the source used was picked pretty much at random. + + * Value "true" for color.diff and color.status configuration used to + mean "always" (even when the output is not going to a terminal). + This has been corrected to mean the same thing as "auto". + + * "git diff" Porcelain now respects diff.external configuration, which + is another way to specify GIT_EXTERNAL_DIFF. + + * "git diff" can be told to use different prefixes other than + "a/" and "b/" e.g. "git diff --src-prefix=l/ --dst-prefix=k/". + + * "git diff" sometimes did not quote paths with funny + characters properly. + + * "git log" (and any revision traversal commands) misbehaved + when --diff-filter is given but was not asked to actually + produce diff. + + * HTTP proxy can be specified per remote repository using + remote.*.httpproxy configuration, or global http.proxy configuration + variable. + + * Various Perforce importer updates. + + * Example update and post-receive hooks have been improved. + + * Any command that wants to take a commit object name can now use + ":/string" syntax to name a commit. + + * "git reset" is now built-in and its output can be squelched with -q. + + * "git reset --hard" does not make any sense in a bare + repository, but did not error out; fixed. + + * "git send-email" can optionally talk over ssmtp and use SMTP-AUTH. + + * "git rebase" learned --whitespace option. + + * In "git rebase", when you decide not to replay a particular change + after the command stopped with a conflict, you can say "git rebase + --skip" without first running "git reset --hard", as the command now + runs it for you. + + * "git rebase --interactive" mode can now work on detached HEAD. + + * Other minor to serious bugs in "git rebase -i" have been fixed. + + * "git rebase" now detaches head during its operation, so after a + successful "git rebase" operation, the reflog entry branch@{1} for + the current branch points at the commit before the rebase was + started. + + * "git rebase -i" also triggers rerere to help your repeated merges. + + * "git merge" can call the "post-merge" hook. + + * "git pack-objects" can optionally run deltification with multiple + threads. + + * "git archive" can optionally substitute keywords in files marked with + export-subst attribute. + + * "git cherry-pick" made a misguided attempt to repeat the original + command line in the generated log message, when told to cherry-pick a + commit by naming a tag that points at it. It does not anymore. + + * "git for-each-ref" learned %(xxxdate:<dateformat>) syntax to show the + various date fields in different formats. + + * "git gc --auto" is a low-impact way to automatically run a variant of + "git repack" that does not lose unreferenced objects (read: safer + than the usual one) after the user accumulates too many loose + objects. + + * "git clean" has been rewritten in C. + + * You need to explicitly set clean.requireForce to "false" to allow + "git clean" without -f to do any damage (lack of the configuration + variable used to mean "do not require -f option to lose untracked + files", but we now use the safer default). + + * The kinds of whitespace errors "git diff" and "git apply" notice (and + fix) can be controlled via 'core.whitespace' configuration variable + and 'whitespace' attribute in .gitattributes file. + + * "git push" learned --dry-run option to show what would happen if a + push is run. + + * "git push" does not update a tracking ref on the local side when the + remote refused to update the corresponding ref. + + * "git push" learned --mirror option. This is to push the local refs + one-to-one to the remote, and deletes refs from the remote that do + not exist anymore in the repository on the pushing side. + + * "git push" can remove a corrupt ref at the remote site with the usual + ":ref" refspec. + + * "git remote" knows --mirror mode. This is to set up configuration to + push into a remote repository to store local branch heads to the same + branch on the remote side, and remove branch heads locally removed + from local repository at the same time. Suitable for pushing into a + back-up repository. + + * "git remote" learned "rm" subcommand. + + * "git cvsserver" can be run via "git shell". Also, "cvs" is + recognized as a synonym for "git cvsserver", so that CVS users + can be switched to git just by changing their login shell. + + * "git cvsserver" acts more like receive-pack by running post-receive + and post-update hooks. + + * "git am" and "git rebase" are far less verbose. + + * "git pull" learned to pass --[no-]ff option to underlying "git + merge". + + * "git pull --rebase" is a different way to integrate what you fetched + into your current branch. + + * "git fast-export" produces datastream that can be fed to fast-import + to reproduce the history recorded in a git repository. + + * "git add -i" takes pathspecs to limit the set of files to work on. + + * "git add -p" is a short-hand to go directly to the selective patch + subcommand in the interactive command loop and to exit when done. + + * "git add -i" UI has been colorized. The interactive prompt + and menu can be colored by setting color.interactive + configuration. The diff output (including the hunk picker) + are colored with color.diff configuration. + + * "git commit --allow-empty" allows you to create a single-parent + commit that records the same tree as its parent, overriding the usual + safety valve. + + * "git commit --amend" can amend a merge that does not change the tree + from its first parent. + + * "git commit" used to unconditionally strip comment lines that + began with '#' and removed excess blank lines. This + behaviour has been made configurable. + + * "git commit" has been rewritten in C. + + * "git stash random-text" does not create a new stash anymore. It was + a UI mistake. Use "git stash save random-text", or "git stash" + (without extra args) for that. + + * "git stash clear extra-text" does not clear the whole stash + anymore. It is tempting to expect "git stash clear stash@{2}" + to drop only a single named stash entry, and it is rude to + discard everything when that is asked (but not provided). + + * "git prune --expire <time>" can exempt young loose objects from + getting pruned. + + * "git branch --contains <commit>" can list branches that are + descendants of a given commit. + + * "git log" learned --early-output option to help interactive GUI + implementations. + + * "git bisect" learned "skip" action to mark untestable commits. + + * "git bisect visualize" learned a shorter synonym "git bisect view". + + * "git bisect visualize" runs "git log" in a non-windowed + environments. It also can be told what command to run (e.g. "git + bisect visualize tig"). + + * "git format-patch" learned "format.numbered" configuration variable + to automatically turn --numbered option on when more than one commits + are formatted. + + * "git ls-files" learned "--exclude-standard" to use the canned set of + exclude files. + + * "git tag -a -f existing" begins the editor session using the existing + annotation message. + + * "git tag -m one -m bar" (multiple -m options) behaves similarly to + "git commit"; the parameters to -m options are formatted as separate + paragraphs. + + * The format "git show" outputs an annotated tag has been updated to + include "Tagger: " and "Date: " lines from the tag itself. Strictly + speaking this is a backward incompatible change, but this is a + reasonable usability fix and people's scripts shouldn't have been + relying on the exact output from "git show" Porcelain anyway. + + * "git cvsimport" did not notice errors from underlying "cvsps" + and produced a corrupt import silently. + + * "git cvsexportcommit" learned -w option to specify and switch to the + CVS working directory. + + * "git checkout" from a subdirectory learned to use "../path" to allow + checking out a path outside the current directory without cd'ing up. + + * "git checkout" from and to detached HEAD leaves a bit more + information in the reflog. + + * "git send-email --dry-run" shows full headers for easier diagnosis. + + * "git merge-ours" is now built-in. + + * "git svn" learned "info" and "show-externals" subcommands. + + * "git svn" run from a subdirectory failed to read settings from the + .git/config. + + * "git svn" learned --use-log-author option, which picks up more + descriptive name from From: and Signed-off-by: lines in the commit + message. + + * "git svn" wasted way too much disk to record revision mappings + between svn and git; a new representation that is much more compact + for this information has been introduced to correct this. + + * "git svn" left temporary index files it used without cleaning them + up; this was corrected. + + * "git status" from a subdirectory now shows relative paths, which + makes copy-and-pasting for git-checkout/git-add/git-rm easier. The + traditional behaviour to show the full path relative to the top of + the work tree can be had by setting status.relativepaths + configuration variable to false. + + * "git blame" kept text for each annotated revision in core needlessly; + this has been corrected. + + * "git shortlog" learned to default to HEAD when the standard input is + a terminal and the user did not give any revision parameter. + + * "git shortlog" learned "-e" option to show e-mail addresses as well as + authors' names. + + * "git help" learned "-w" option to show documentation in browsers. + + * In addition there are quite a few internal clean-ups. Notably + + - many fork/exec have been replaced with run-command API, + brought from the msysgit effort. + + - introduction and more use of the option parser API. + + - enhancement and more use of the strbuf API. + + +Fixes since v1.5.3 +------------------ + +All of the fixes in v1.5.3 maintenance series are included in +this release, unless otherwise noted. + +These fixes are only in v1.5.4 and not backported to v1.5.3 maintenance +series. + + * The way "git diff --check" behaves is much more consistent with the way + "git apply --whitespace=warn" works. + + * "git svn" talking with the SVN over http will correctly quote branch + and project names. + + * "git config" did not work correctly on platforms that define + REG_NOMATCH to an even number. + + * Recent versions of AsciiDoc 8 has a change to break our + documentation; a workaround has been implemented. + +-- +exec >/var/tmp/1 +O=v1.5.4-rc2-59-g2370781 +echo O=`git describe refs/heads/master` +git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 99d8874aa..10c1a151a 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -1,6 +1,6 @@ -## gitlink: macro +## linkgit: macro # -# Usage: gitlink:command[manpage-section] +# Usage: linkgit:command[manpage-section] # # Note, {0} is the manpage section, while {target} is the command. # @@ -15,7 +15,7 @@ endsb=] tilde=~ ifdef::backend-docbook[] -[gitlink-inlinemacro] +[linkgit-inlinemacro] {0%{target}} {0#<citerefentry>} {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} @@ -61,6 +61,6 @@ endif::backend-docbook[] endif::doctype-manpage[] ifdef::backend-xhtml11[] -[gitlink-inlinemacro] +[linkgit-inlinemacro] <a href="{target}.html">{target}{0?({0})}</a> endif::backend-xhtml11[] diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 17379f057..ea1007bfb 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -39,7 +39,7 @@ 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 gitlink:git-rev-list[1]. + Use revs from revs-file instead of calling linkgit:git-rev-list[1]. -p, --porcelain:: Show in a format designed for machine consumption. diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl new file mode 100755 index 000000000..e3d8e9faa --- /dev/null +++ b/Documentation/cat-texi.perl @@ -0,0 +1,38 @@ +#!/usr/bin/perl -w + +my @menu = (); +my $output = $ARGV[0]; + +open TMP, '>', "$output.tmp"; + +while (<STDIN>) { + next if (/^\\input texinfo/../\@node Top/); + next if (/^\@bye/ || /^\.ft/); + if (s/^\@top (.*)/\@node $1,,,Top/) { + push @menu, $1; + } + s/\(\@pxref{\[URLS\]}\)//; + print TMP; +} +close TMP; + +printf '\input texinfo +@setfilename gitman.info +@documentencoding us-ascii +@node Top,,%s +@top Git Manual Pages +@documentlanguage en +@menu +', $menu[0]; + +for (@menu) { + print "* ${_}::\n"; +} +print "\@end menu\n"; +open TMP, '<', "$output.tmp"; +while (<TMP>) { + print; +} +close TMP; +print "\@bye\n"; +unlink "$output.tmp"; diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 4ee76eaf9..04f99778d 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -3,7 +3,8 @@ use File::Compare qw(compare); sub format_one { - my ($out, $name) = @_; + my ($out, $nameattr) = @_; + my ($name, $attr) = @$nameattr; my ($state, $description); $state = 0; open I, '<', "$name.txt" or die "No such file $name.txt"; @@ -26,8 +27,11 @@ sub format_one { die "No description found in $name.txt"; } if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) { - print $out "gitlink:$name\[1\]::\n"; - print $out "\t$text.\n\n"; + print $out "linkgit:$name\[1\]::\n\t"; + if ($attr =~ / deprecated /) { + print $out "(deprecated) "; + } + print $out "$text.\n\n"; } else { die "Description does not match $name: $description"; @@ -35,12 +39,13 @@ sub format_one { } my %cmds = (); -while (<DATA>) { +for (sort <>) { next if /^#/; chomp; - my ($name, $cat) = /^(\S+)\s+(.*)$/; - push @{$cmds{$cat}}, $name; + my ($name, $cat, $attr) = /^(\S+)\s+(.*?)(?:\s+(.*))?$/; + $attr = '' unless defined $attr; + push @{$cmds{$cat}}, [$name, " $attr "]; } for my $cat (qw(ancillaryinterrogators @@ -67,138 +72,3 @@ for my $cat (qw(ancillaryinterrogators rename "$out+", "$out"; } } - -# The following list is sorted with "sort -d" to make it easier -# to find entry in the resulting git.html manual page. -__DATA__ -git-add mainporcelain -git-am mainporcelain -git-annotate ancillaryinterrogators -git-apply plumbingmanipulators -git-archimport foreignscminterface -git-archive mainporcelain -git-bisect mainporcelain -git-blame ancillaryinterrogators -git-branch mainporcelain -git-bundle mainporcelain -git-cat-file plumbinginterrogators -git-check-attr purehelpers -git-checkout mainporcelain -git-checkout-index plumbingmanipulators -git-check-ref-format purehelpers -git-cherry ancillaryinterrogators -git-cherry-pick mainporcelain -git-citool mainporcelain -git-clean mainporcelain -git-clone mainporcelain -git-commit mainporcelain -git-commit-tree plumbingmanipulators -git-config ancillarymanipulators -git-convert-objects ancillarymanipulators -git-count-objects ancillaryinterrogators -git-cvsexportcommit foreignscminterface -git-cvsimport foreignscminterface -git-cvsserver foreignscminterface -git-daemon synchingrepositories -git-describe mainporcelain -git-diff mainporcelain -git-diff-files plumbinginterrogators -git-diff-index plumbinginterrogators -git-diff-tree plumbinginterrogators -git-fast-import ancillarymanipulators -git-fetch mainporcelain -git-fetch-pack synchingrepositories -git-filter-branch ancillarymanipulators -git-fmt-merge-msg purehelpers -git-for-each-ref plumbinginterrogators -git-format-patch mainporcelain -git-fsck ancillaryinterrogators -git-gc mainporcelain -git-get-tar-commit-id ancillaryinterrogators -git-grep mainporcelain -git-gui mainporcelain -git-hash-object plumbingmanipulators -git-http-fetch synchelpers -git-http-push synchelpers -git-imap-send foreignscminterface -git-index-pack plumbingmanipulators -git-init mainporcelain -git-instaweb ancillaryinterrogators -gitk mainporcelain -git-local-fetch synchingrepositories -git-log mainporcelain -git-lost-found ancillarymanipulators -git-ls-files plumbinginterrogators -git-ls-remote plumbinginterrogators -git-ls-tree plumbinginterrogators -git-mailinfo purehelpers -git-mailsplit purehelpers -git-merge mainporcelain -git-merge-base plumbinginterrogators -git-merge-file plumbingmanipulators -git-merge-index plumbingmanipulators -git-merge-one-file purehelpers -git-mergetool ancillarymanipulators -git-merge-tree ancillaryinterrogators -git-mktag plumbingmanipulators -git-mktree plumbingmanipulators -git-mv mainporcelain -git-name-rev plumbinginterrogators -git-pack-objects plumbingmanipulators -git-pack-redundant plumbinginterrogators -git-pack-refs ancillarymanipulators -git-parse-remote synchelpers -git-patch-id purehelpers -git-peek-remote purehelpers -git-prune ancillarymanipulators -git-prune-packed plumbingmanipulators -git-pull mainporcelain -git-push mainporcelain -git-quiltimport foreignscminterface -git-read-tree plumbingmanipulators -git-rebase mainporcelain -git-receive-pack synchelpers -git-reflog ancillarymanipulators -git-relink ancillarymanipulators -git-remote ancillarymanipulators -git-repack ancillarymanipulators -git-request-pull foreignscminterface -git-rerere ancillaryinterrogators -git-reset mainporcelain -git-revert mainporcelain -git-rev-list plumbinginterrogators -git-rev-parse ancillaryinterrogators -git-rm mainporcelain -git-runstatus ancillaryinterrogators -git-send-email foreignscminterface -git-send-pack synchingrepositories -git-shell synchelpers -git-shortlog mainporcelain -git-show mainporcelain -git-show-branch ancillaryinterrogators -git-show-index plumbinginterrogators -git-show-ref plumbinginterrogators -git-sh-setup purehelpers -git-ssh-fetch synchingrepositories -git-ssh-upload synchingrepositories -git-stash mainporcelain -git-status mainporcelain -git-stripspace purehelpers -git-submodule mainporcelain -git-svn foreignscminterface -git-svnimport foreignscminterface -git-symbolic-ref plumbingmanipulators -git-tag mainporcelain -git-tar-tree plumbinginterrogators -git-unpack-file plumbinginterrogators -git-unpack-objects plumbingmanipulators -git-update-index plumbingmanipulators -git-update-ref plumbingmanipulators -git-update-server-info synchingrepositories -git-upload-archive synchelpers -git-upload-pack synchelpers -git-var plumbinginterrogators -git-verify-pack plumbinginterrogators -git-verify-tag ancillaryinterrogators -git-whatchanged ancillaryinterrogators -git-write-tree plumbingmanipulators diff --git a/Documentation/config.txt b/Documentation/config.txt index 83bc33c42..1b6d6d6fa 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -115,7 +115,7 @@ porcelain configuration variables in the respective porcelain documentation. core.fileMode:: If false, the executable bit differences between the index and the working copy are ignored; useful on broken filesystems like FAT. - See gitlink:git-update-index[1]. True by default. + See linkgit:git-update-index[1]. True by default. core.quotepath:: The commands that output paths (e.g. `ls-files`, @@ -141,8 +141,8 @@ core.autocrlf:: core.symlinks:: If false, symbolic links are checked out as small plain files that - contain the link text. gitlink:git-update-index[1] and - gitlink:git-add[1] will not change the recorded type to regular + 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. @@ -163,7 +163,7 @@ core.ignoreStat:: The working copy files are assumed to stay unchanged 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 gitlink:git-update-index[1]. + slow, such as Microsoft Windows. See linkgit:git-update-index[1]. False by default. core.preferSymlinkRefs:: @@ -176,10 +176,10 @@ core.bare:: If true this repository is assumed to be 'bare' and has no working directory associated with it. If this is the case a number of commands that require a working directory will be - disabled, such as gitlink:git-add[1] or gitlink:git-merge[1]. + disabled, such as linkgit:git-add[1] or linkgit:git-merge[1]. + -This setting is automatically guessed by gitlink:git-clone[1] or -gitlink:git-init[1] when the repository was created. By default a +This setting is automatically guessed by linkgit:git-clone[1] or +linkgit:git-init[1] when the repository was created. By default a repository that ends in "/.git" is assumed to be not bare (bare = false), while all other repositories are assumed to be bare (bare = true). @@ -188,7 +188,7 @@ 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). - This can be overriden by the GIT_WORK_TREE environment + This can be overridden by the GIT_WORK_TREE environment variable and the '--work-tree' command line option. core.logAllRefUpdates:: @@ -216,7 +216,7 @@ core.sharedRepository:: group-writable). When 'all' (or 'world' or 'everybody'), the repository will be readable by all users, additionally to being group-shareable. When 'umask' (or 'false'), git will use permissions - reported by umask(2). See gitlink:git-init[1]. False by default. + reported by umask(2). See linkgit:git-init[1]. False by default. core.warnAmbiguousRefs:: If true, git will warn you if the ref name you passed it is ambiguous @@ -281,7 +281,7 @@ 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 - gitlink:gitignore[5]. + linkgit:gitignore[5]. core.editor:: Commands such as `commit` and `tag` that lets you edit @@ -295,8 +295,22 @@ core.pager:: The command that git will use to paginate output. Can be overridden with the `GIT_PAGER` environment variable. +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: ++ +* `trailing-space` 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). + alias.*:: - Command aliases for the gitlink:git[1] command wrapper - e.g. + Command aliases for the linkgit:git[1] command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation "git last" is equivalent to "git cat-file commit HEAD". To avoid confusion and troubles with script usage, aliases that @@ -312,11 +326,11 @@ it will be treated as a shell command. For example, defining apply.whitespace:: Tells `git-apply` how to handle whitespaces, in the same way - as the '--whitespace' option. See gitlink:git-apply[1]. + as the '--whitespace' option. See linkgit:git-apply[1]. branch.autosetupmerge:: Tells `git-branch` and `git-checkout` to setup new branches - so that gitlink:git-pull[1] will appropriately merge from that + so that linkgit:git-pull[1] will appropriately merge from that remote branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` and `--no-track` options. This option defaults to false. @@ -326,10 +340,11 @@ branch.<name>.remote:: If this option is not given, `git fetch` defaults to remote "origin". branch.<name>.merge:: - When in branch <name>, it tells `git fetch` the default refspec to - be marked for merging in FETCH_HEAD. The value has exactly to match - a remote part of one of the refspecs which are fetched from the remote - given by "branch.<name>.remote". + 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. @@ -339,14 +354,27 @@ branch.<name>.merge:: 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 + 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. + *NOTE*: this is a possibly dangerous operation; do *not* use + it unless you understand the implications (see linkgit:git-rebase[1] + for details). + clean.requireForce:: - A boolean to make git-clean do nothing unless given -f or -n. Defaults - to false. + A boolean to make git-clean do nothing unless given -f + or -n. Defaults to true. color.branch:: A boolean to enable/disable color in the output of - gitlink:git-branch[1]. May be set to `true` (or `always`), - `false` (or `never`) or `auto`, in which case colors are used + linkgit:git-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.branch.<slot>:: @@ -364,17 +392,30 @@ second is the background. The position of the attribute, if any, doesn't matter. color.diff:: - When true (or `always`), always use colors in patch. - When false (or `never`), never. When set to `auto`, use - colors only when the output is to the terminal. + 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. 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 dubious - whitespace). The values of these variables may be specified as + `commit` (commit headers), or `whitespace` (highlighting + whitespace errors). 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"). + 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 in color.branch.<slot>. color.pager:: @@ -383,8 +424,8 @@ color.pager:: color.status:: A boolean to enable/disable color in the output of - gitlink:git-status[1]. May be set to `true` (or `always`), - `false` (or `never`) or `auto`, in which case colors are used + linkgit:git-status[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.<slot>:: @@ -408,6 +449,13 @@ diff.autorefreshindex:: 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'. @@ -427,9 +475,15 @@ fetch.unpackLimit:: pack from a push can make the push operation complete faster, especially on slow filesystems. +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 + linkgit:git-format-patch[1]. + format.headers:: Additional email headers to include in a patch to be submitted - by mail. See gitlink:git-format-patch[1]. + by mail. See linkgit:git-format-patch[1]. format.suffix:: The default for format-patch is to output files with the suffix @@ -441,6 +495,19 @@ gc.aggressiveWindow:: algorithm used by 'git gc --aggressive'. This defaults to 10. +gc.auto:: + When there are approximately more than this many loose + objects in the repository, `git gc --auto` will pack them. + Some Porcelain commands use this command to perform a + light-weight garbage collection from time to time. Setting + this to 0 disables it. + +gc.autopacklimit:: + When there are more than this many packs that are not + marked with `*.keep` file in the repository, `git gc + --auto` consolidates them into one larger pack. Setting + this to 0 disables this. + 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 @@ -464,25 +531,27 @@ gc.reflogexpireunreachable:: gc.rerereresolved:: Records of conflicted merge you resolved earlier are kept for this many days when `git rerere gc` is run. - The default is 60 days. See gitlink:git-rerere[1]. + 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. - The default is 15 days. See gitlink:git-rerere[1]. + 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. See gitlink:git-rerere[1]. + be encountered again. linkgit:git-rerere[1] command is by + default enabled, but can be disabled by setting this option to + false. gitcvs.enabled:: Whether the CVS server interface is enabled for this repository. - See gitlink:git-cvsserver[1]. + See linkgit:git-cvsserver[1]. gitcvs.logfile:: Path to a log file where the CVS server interface well... logs - various stuff. See gitlink:git-cvsserver[1]. + various stuff. See linkgit:git-cvsserver[1]. gitcvs.allbinary:: If true, all files are sent to the client in mode '-kb'. This @@ -495,7 +564,7 @@ gitcvs.dbname:: derived from the git repository. The exact meaning depends on the used database driver, for SQLite (which is the default driver) this is a filename. Supports variable substitution (see - gitlink:git-cvsserver[1] for details). May not contain semicolons (`;`). + linkgit:git-cvsserver[1] for details). May not contain semicolons (`;`). Default: '%Ggitcvs.%m.sqlite' gitcvs.dbdriver:: @@ -504,19 +573,33 @@ gitcvs.dbdriver:: with 'DBD::SQLite', reported to work with 'DBD::Pg', and reported *not* to work with 'DBD::mysql'. Experimental feature. May not contain double colons (`:`). Default: 'SQLite'. - See gitlink:git-cvsserver[1]. + See linkgit:git-cvsserver[1]. gitcvs.dbuser, gitcvs.dbpass:: Database user and password. Only useful if setting 'gitcvs.dbdriver', since SQLite has no concept of database users and/or passwords. 'gitcvs.dbuser' supports variable substitution (see - gitlink:git-cvsserver[1] for details). + linkgit:git-cvsserver[1] for details). All gitcvs variables except for 'gitcvs.allbinary' can also be specified as 'gitcvs.<access_method>.<varname>' (where 'access_method' is one of "ext" and "pserver") to make them apply only for the given access method. +help.browser:: + Specify the browser that will be used to display help in the + 'web' format. See linkgit:git-help[1]. + +help.format:: + Override the default help format used by linkgit:git-help[1]. + Values 'man', 'info', 'web' and 'html' are supported. 'man' is + the default. 'web' and 'html' are the same. + +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 + http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment @@ -563,16 +646,35 @@ i18n.commitEncoding:: does not care per se, but this information is necessary e.g. when importing commits from emails or in the gitk graphical history browser (and possibly at other places in the future or in other - porcelains). See e.g. gitlink:git-mailinfo[1]. Defaults to 'utf-8'. + porcelains). See e.g. linkgit:git-mailinfo[1]. Defaults to 'utf-8'. i18n.logOutputEncoding:: Character encoding the commit messages are converted to when running `git-log` and friends. +instaweb.browser:: + Specify the program that will be used to browse your working + repository in gitweb. See linkgit:git-instaweb[1]. + +instaweb.httpd:: + The HTTP daemon command-line to start gitweb on your working + repository. See linkgit:git-instaweb[1]. + +instaweb.local:: + If true the web server started by linkgit:git-instaweb[1] will + 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]. + +instaweb.port:: + The port number to bind the gitweb httpd to. See + linkgit:git-instaweb[1]. + log.showroot:: If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. - Tools like gitlink:git-log[1] or gitlink:git-whatchanged[1], which + Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which normally hide the root commit will now show it. True by default. merge.summary:: @@ -581,7 +683,7 @@ merge.summary:: merge.tool:: Controls which merge resolution program is used by - gitlink:git-mergetool[1]. Valid values are: "kdiff3", "tkdiff", + linkgit:git-mergetool[1]. Valid values are: "kdiff3", "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", and "opendiff". merge.verbosity:: @@ -590,31 +692,35 @@ 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 overriden by 'GIT_MERGE_VERBOSITY' environment variable. + Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. merge.<driver>.name:: Defines a human readable name for a custom low-level - merge driver. See gitlink:gitattributes[5] for details. + merge driver. See linkgit:gitattributes[5] for details. merge.<driver>.driver:: Defines the command that implements a custom low-level - merge driver. See gitlink:gitattributes[5] for details. + merge driver. See linkgit:gitattributes[5] for details. merge.<driver>.recursive:: Names a low-level merge driver to be used when performing an internal merge between common ancestors. - See gitlink:gitattributes[5] for details. + See linkgit:gitattributes[5] for details. + +mergetool.<tool>.path:: + Override the path for the given tool. This is useful in case + your tool is not in the PATH. pack.window:: - The size of the window used by gitlink:git-pack-objects[1] when no + 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. pack.depth:: - The maximum delta depth used by gitlink:git-pack-objects[1] when no + The maximum delta depth used by linkgit:git-pack-objects[1] when no maximum depth is given on the command line. Defaults to 50. pack.windowMemory:: - The window memory size limit used by gitlink:git-pack-objects[1] + The window memory size limit used by linkgit:git-pack-objects[1] when no limit is given on the command line. The value can be suffixed with "k", "m", or "g". Defaults to 0, meaning no limit. @@ -630,12 +736,29 @@ pack.compression:: pack.deltaCacheSize:: The maximum memory in bytes used for caching deltas in - gitlink:git-pack-objects[1]. + linkgit:git-pack-objects[1]. A value of 0 means no limit. Defaults to 0. pack.deltaCacheLimit:: - The maxium size of a delta, that is cached in - gitlink:git-pack-objects[1]. Defaults to 1000. + The maximum size of a delta, that is cached in + linkgit:git-pack-objects[1]. Defaults to 1000. + +pack.threads:: + Specifies the number of threads to spawn when searching for best + delta matches. This requires that linkgit:git-pack-objects[1] + 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. + +pack.indexVersion:: + Specify the default pack index version. Valid values are 1 for + 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. pull.octopus:: The default merge strategy to use when pulling multiple branches @@ -645,28 +768,33 @@ pull.twohead:: The default merge strategy to use when pulling a single branch. remote.<name>.url:: - The URL of a remote repository. See gitlink:git-fetch[1] or - gitlink:git-push[1]. + The URL of a remote repository. See linkgit:git-fetch[1] or + 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 + disable proxying for that remote. remote.<name>.fetch:: - The default set of "refspec" for gitlink:git-fetch[1]. See - gitlink:git-fetch[1]. + The default set of "refspec" for linkgit:git-fetch[1]. See + linkgit:git-fetch[1]. remote.<name>.push:: - The default set of "refspec" for gitlink:git-push[1]. See - gitlink:git-push[1]. + The default set of "refspec" for linkgit:git-push[1]. See + linkgit:git-push[1]. remote.<name>.skipDefaultUpdate:: If true, this remote will be skipped by default when updating - using the remote subcommand of gitlink:git-remote[1]. + using the update subcommand of linkgit:git-remote[1]. remote.<name>.receivepack:: The default program to execute on the remote side when pushing. See - option \--exec of gitlink:git-push[1]. + option \--exec of linkgit:git-push[1]. remote.<name>.uploadpack:: The default program to execute on the remote side when fetching. See - option \--exec of gitlink:git-fetch-pack[1]. + option \--exec of linkgit:git-fetch-pack[1]. remote.<name>.tagopt:: Setting this value to --no-tags disables automatic tag following when fetching @@ -674,51 +802,57 @@ remote.<name>.tagopt:: remotes.<group>:: The list of remotes which are fetched by "git remote update - <group>". See gitlink:git-remote[1]. + <group>". See linkgit:git-remote[1]. repack.usedeltabaseoffset:: - Allow gitlink:git-repack[1] to create packs that uses + Allow linkgit:git-repack[1] to create packs that uses delta-base offset. Defaults to false. show.difftree:: - The default gitlink:git-diff-tree[1] arguments to be used - for gitlink:git-show[1]. + The default linkgit:git-diff-tree[1] arguments to be used + for linkgit:git-show[1]. showbranch.default:: - The default set of branches for gitlink:git-show-branch[1]. - See gitlink:git-show-branch[1]. + The default set of branches for linkgit:git-show-branch[1]. + See linkgit:git-show-branch[1]. + +status.relativePaths:: + By default, linkgit:git-status[1] shows paths relative to the + current directory. Setting this variable to `false` shows paths + relative to the repository root (this was the default for git + prior to v1.5.4). tar.umask:: This variable can be used to restrict the permission bits of 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) and - gitlink:git-archive[1]. + linkgit:git-archive[1]. 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 - 'EMAIL' environment variables. See gitlink:git-commit-tree[1]. + 'EMAIL' environment variables. See linkgit:git-commit-tree[1]. user.name:: Your full name to be recorded in any newly created commits. Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME' - environment variables. See gitlink:git-commit-tree[1]. + environment variables. See linkgit:git-commit-tree[1]. user.signingkey:: - If gitlink:git-tag[1] is not selecting the key you want it to + If linkgit:git-tag[1] is not selecting the key you want it to automatically when creating a signed tag, you can override the default selection with this variable. This option is passed unchanged to gpg's --local-user parameter, so you may specify a key using any method that gpg supports. whatchanged.difftree:: - The default gitlink:git-diff-tree[1] arguments to be used - for gitlink:git-whatchanged[1]. + 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 gitlink:git-imap-send[1]. + in linkgit:git-imap-send[1]. receive.unpackLimit:: If the number of objects received in a push is below this @@ -738,3 +872,8 @@ receive.denyNonFastForwards:: transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are not set, the value of this variable is used instead. + +web.browser:: + Specify a web browser that may be used by some commands. + Currently only linkgit:git-instaweb[1] and linkgit:git-help[1] + may use it. diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index c3f0be535..bd6cd4124 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -553,13 +553,8 @@ can explore on your own. [NOTE] Most likely, you are not directly using the core -git Plumbing commands, but using Porcelain like Cogito on top -of it. Cogito works a bit differently and you usually do not -have to run `git-update-index` yourself for changed files (you -do tell underlying git about additions and removals via -`cg-add` and `cg-rm` commands). Just before you make a commit -with `cg-commit`, Cogito figures out which files you modified, -and runs `git-update-index` on them for you. +git Plumbing commands, but using Porcelain such as `git-add`, `git-rm' +and `git-commit'. Tagging a version @@ -686,8 +681,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` is the -above two lines implemented in `git-reset`, but some things like +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 basic git commands. @@ -805,8 +800,8 @@ you have, you can say $ git branch ------------ -which is nothing more than a simple script around `ls .git/refs/heads`. -There will be asterisk in front of the branch you are currently on. +which used to be nothing more than a simple script around `ls .git/refs/heads`. +There will be an asterisk in front of the branch you are currently on. Sometimes you may wish to create a new branch _without_ actually checking it out and switching to it. If so, just use the command @@ -936,12 +931,13 @@ Another useful tool, especially if you do not always work in X-Window environment, is `git show-branch`. ------------------------------------------------ -$ git show-branch --topo-order master mybranch +$ git-show-branch --topo-order --more=1 master mybranch * [master] Merge work in mybranch ! [mybranch] Some work. -- - [master] Merge work in mybranch *+ [mybranch] Some work. +* [master^] Some fun. ------------------------------------------------ The first two lines indicate that it is showing the two branches @@ -952,17 +948,29 @@ the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` branch. Three commits are shown along with their log messages. All of them have non blank characters in the first column (`*` -shows an ordinary commit on the current branch, `.` is a merge commit), which +shows an ordinary commit on the current branch, `-` is a merge commit), which means they are now part of the `master` branch. Only the "Some work" commit has the plus `+` character in the second column, because `mybranch` has not been merged to incorporate these 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~1' is the first parent of 'master' +are branch heads. 'master^' is the first parent of 'master' branch head. Please see 'git-rev-parse' documentation if you see more complex cases. +[NOTE] +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. + +[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 +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 @@ -1188,7 +1196,7 @@ $ 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. BTW, the common +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 tell it by: @@ -1454,8 +1462,7 @@ Although git is a truly distributed system, it is often convenient to organize your project with an informal hierarchy of developers. Linux kernel development is run this way. There is a nice illustration (page 17, "Merges to Mainline") in -link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf -[Randy Dunlap's presentation]. +link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation]. It should be stressed that this hierarchy is purely *informal*. There is nothing fundamental in git that enforces the "chain of diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 3b6b49416..ea9890022 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -36,12 +36,12 @@ them first before running git pull. ================================ 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 gitlink:git-config[1] man +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 gitlink:git-push[1] command: +your changes, and then using the linkgit:git-push[1] command: ------------------------------------------------ $ git push origin master @@ -88,7 +88,7 @@ Next, give every team member read/write access to this repository. One easy way to do this is to give all the team members ssh access to the machine where the repository is hosted. If you don't want to give them a full shell on the machine, there is a restricted shell which only allows -users to do git pushes and pulls; see gitlink:git-shell[1]. +users to do git pushes and pulls; see linkgit:git-shell[1]. Put all the committers in the same group, and make the repository writable by that group: @@ -106,7 +106,7 @@ Importing a CVS archive First, install version 2.1 or higher of cvsps from link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make sure it is in your path. Then cd to a checked out CVS working directory -of the project you are interested in and run gitlink:git-cvsimport[1]: +of the project you are interested in and run linkgit:git-cvsimport[1]: ------------------------------------------- $ git cvsimport -C <destination> <module> @@ -146,7 +146,7 @@ Providing CVS Access to a git Repository ---------------------------------------- It is also possible to provide true CVS access to a git repository, so -that developers can still use CVS; see gitlink:git-cvsserver[1] for +that developers can still use CVS; see linkgit:git-cvsserver[1] for details. Alternative Development Models diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 9709c35c9..400cbb3b1 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -83,161 +83,65 @@ Note that 'combined diff' lists only files which were modified from all parents. -Generating patches with -p --------------------------- - -When "git-diff-index", "git-diff-tree", or "git-diff-files" are run -with a '-p' option, or "git diff" without the '--raw' option, they -do not produce the output described above; instead they produce a -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. - -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. -+ -When rename/copy is involved, `file1` and `file2` show the -name of the source file of the rename/copy and the name of -the file that rename/copy produces, respectively. - -2. It is followed by one or more extended header lines: - - old mode <mode> - new mode <mode> - deleted file mode <mode> - new file mode <mode> - copy from <path> - copy to <path> - rename from <path> - rename to <path> - 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. - -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. - - -combined diff format --------------------- - -"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or -'--cc' option to produce 'combined diff', which looks like this: - ------------- -diff --combined describe.c -index fabadb8,cc95eb0..4866510 ---- a/describe.c -+++ b/describe.c -@@@ -98,20 -98,12 +98,20 @@@ - return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; - } - -- static void describe(char *arg) - -static void describe(struct commit *cmit, int last_one) -++static void describe(char *arg, int last_one) - { - + unsigned char sha1[20]; - + struct commit *cmit; - struct commit_list *list; - static int initialized = 0; - struct commit_name *n; - - + if (get_sha1(arg, sha1) < 0) - + usage(describe_usage); - + cmit = lookup_commit_reference(sha1); - + if (!cmit) - + usage(describe_usage); - + - if (!initialized) { - initialized = 1; - for_each_ref(get_name); ------------- - -1. It is preceded with a "git diff" header, that looks like - this (when '-c' option is used): - - diff --combined file -+ -or like this (when '--cc' option is used): - - diff --c file - -2. It is followed by one or more extended header lines - (this example shows a merge with two parents): - - index <hash>,<hash>..<hash> - mode <mode>,<mode>..<mode> - new file mode <mode> - deleted file mode <mode>,<mode> -+ -The `mode <mode>,<mode>..<mode>` line appears only if at least one of -the <mode> is different from the rest. Extended headers with -information about detected contents movement (renames and -copying detection) are designed to work with diff of two -<tree-ish> and are not used by combined diff format. - -3. It is followed by two-line from-file/to-file header - - --- a/file - +++ b/file -+ -Similar to two-line header for traditional 'unified' diff -format, `/dev/null` is used to signal created or deleted -files. - -4. Chunk header format is modified to prevent people from - accidentally feeding it to `patch -p1`. Combined diff format - was created for review of merge commit changes, and was not - meant for apply. The change is similar to the change in the - extended 'index' header: - - @@@ <from-file-range> <from-file-range> <to-file-range> @@@ -+ -There are (number of parents + 1) `@` characters in the chunk -header for combined diff format. - -Unlike the traditional 'unified' diff format, which shows two -files A and B with a single column that has `-` (minus -- -appears in A but removed in B), `+` (plus -- missing in A but -added to B), or `" "` (space -- unchanged) prefix, this format -compares two or more files file1, file2,... with one file X, and -shows how X differs from each of fileN. One column for each of -fileN is prepended to the output line to note how X's line is -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, -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 ` +`). - -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 -parents). When shown by `git diff-files -c`, it compares the -two unresolved merge parents with the working tree file -(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka -"their version"). +include::diff-generate-patch.txt[] + + +other diff formats +------------------ + +The `--summary` option describes newly added, deleted, renamed and +copied files. The `--stat` option adds diffstat(1) graph to the +output. These options can be combined with other options, such as +`-p`, and are meant for human consumption. + +When showing a change that involves a rename or a copy, `--stat` output +formats the pathnames compactly by combining common prefix and suffix of +the pathnames. For example, a change that moves `arch/i386/Makefile` to +`arch/x86/Makefile` while modifying 4 lines will be shown like this: + +------------------------------------ +arch/{i386 => x86}/Makefile | 4 +-- +------------------------------------ + +The `--numstat` option gives the diffstat(1) information but is designed +for easier machine consumption. An entry in `--numstat` output looks +like this: + +---------------------------------------- +1 2 README +3 1 arch/{i386 => x86}/Makefile +---------------------------------------- + +That is, from left to right: + +. the number of added lines; +. a tab; +. the number of deleted lines; +. a tab; +. pathname (possibly with rename/copy information); +. a newline. + +When `-z` output option is in effect, the output is formatted this way: + +---------------------------------------- +1 2 README NUL +3 1 NUL arch/i386/Makefile NUL arch/x86/Makefile NUL +---------------------------------------- + +That is: + +. the number of added lines; +. a tab; +. the number of deleted lines; +. a tab; +. a NUL (only exists if renamed/copied); +. pathname in preimage; +. a NUL (only exists if renamed/copied); +. pathname in postimage (only exists if renamed/copied); +. a NUL. + +The extra `NUL` before the preimage path in renamed case is to allow +scripts that read the output to tell if the current record being read is +a single-path record or a rename/copy record without reading ahead. +After reading added and deleted lines, reading up to `NUL` would yield +the pathname, but if that is `NUL`, the record will show two paths. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt new file mode 100644 index 000000000..029c5f2b8 --- /dev/null +++ b/Documentation/diff-generate-patch.txt @@ -0,0 +1,161 @@ +Generating patches with -p +-------------------------- + +When "git-diff-index", "git-diff-tree", or "git-diff-files" are run +with a '-p' option, "git diff" without the '--raw' option, or +"git log" with the "-p" option, they +do not produce the output described above; instead they produce a +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. + +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. ++ +When rename/copy is involved, `file1` and `file2` show the +name of the source file of the rename/copy and the name of +the file that rename/copy produces, respectively. + +2. It is followed by one or more extended header lines: + + old mode <mode> + new mode <mode> + deleted file mode <mode> + new file mode <mode> + copy from <path> + copy to <path> + rename from <path> + rename to <path> + 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. + +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. + + +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. +A 'combined diff' format looks like this: + +------------ +diff --combined describe.c +index fabadb8,cc95eb0..4866510 +--- a/describe.c ++++ b/describe.c +@@@ -98,20 -98,12 +98,20 @@@ + return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; + } + +- static void describe(char *arg) + -static void describe(struct commit *cmit, int last_one) +++static void describe(char *arg, int last_one) + { + + unsigned char sha1[20]; + + struct commit *cmit; + struct commit_list *list; + static int initialized = 0; + struct commit_name *n; + + + if (get_sha1(arg, sha1) < 0) + + usage(describe_usage); + + cmit = lookup_commit_reference(sha1); + + if (!cmit) + + usage(describe_usage); + + + if (!initialized) { + initialized = 1; + for_each_ref(get_name); +------------ + +1. It is preceded with a "git diff" header, that looks like + this (when '-c' option is used): + + diff --combined file ++ +or like this (when '--cc' option is used): + + diff --c file + +2. It is followed by one or more extended header lines + (this example shows a merge with two parents): + + index <hash>,<hash>..<hash> + mode <mode>,<mode>..<mode> + new file mode <mode> + deleted file mode <mode>,<mode> ++ +The `mode <mode>,<mode>..<mode>` line appears only if at least one of +the <mode> is different from the rest. Extended headers with +information about detected contents movement (renames and +copying detection) are designed to work with diff of two +<tree-ish> and are not used by combined diff format. + +3. It is followed by two-line from-file/to-file header + + --- a/file + +++ b/file ++ +Similar to two-line header for traditional 'unified' diff +format, `/dev/null` is used to signal created or deleted +files. + +4. Chunk header format is modified to prevent people from + accidentally feeding it to `patch -p1`. Combined diff format + was created for review of merge commit changes, and was not + meant for apply. The change is similar to the change in the + extended 'index' header: + + @@@ <from-file-range> <from-file-range> <to-file-range> @@@ ++ +There are (number of parents + 1) `@` characters in the chunk +header for combined diff format. + +Unlike the traditional 'unified' diff format, which shows two +files A and B with a single column that has `-` (minus -- +appears in A but removed in B), `+` (plus -- missing in A but +added to B), or `" "` (space -- unchanged) prefix, this format +compares two or more files file1, file2,... with one file X, and +shows how X differs from each of fileN. One column for each of +fileN is prepended to the output line to note how X's line is +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, +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 ` +`). + +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 +parents). When shown by `git diff-files -c`, it compares the +two unresolved merge parents with the working tree file +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka +"their version"). diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index b1f528ae8..8d35cbd60 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -1,5 +1,27 @@ +// Please don't remove this comment as asciidoc behaves badly when +// the first non-empty line is ifdef/ifndef. The symptom is that +// without this comment the <git-diff-core> attribute conditionally +// defined below ends up being defined unconditionally. +// Last checked with asciidoc 7.0.2. + +ifndef::git-format-patch[] +ifndef::git-diff[] +ifndef::git-log[] +:git-diff-core: 1 +endif::git-log[] +endif::git-diff[] +endif::git-format-patch[] + +ifdef::git-format-patch[] -p:: - Generate patch (see section on generating patches) + Generate patches without diffstat. +endif::git-format-patch[] + +ifndef::git-format-patch[] +-p:: + Generate patch (see section on generating patches). + {git-diff? This is the default.} +endif::git-format-patch[] -u:: Synonym for "-p". @@ -13,6 +35,7 @@ --raw:: Generate the raw format. + {git-diff-core? This is the default.} --patch-with-raw:: Synonym for "-p --raw". @@ -41,6 +64,7 @@ --patch-with-stat:: Synonym for "-p --stat". + {git-format-patch? This is the default.} -z:: NUL-line termination on output. This affects the --raw @@ -69,7 +93,9 @@ --check:: Warn if changes introduce trailing whitespace - or an indent that uses a space before a tab. + or an indent that uses a space before a tab. Exits with + non-zero status if problems are found. Not compatible with + --exit-code. --full-index:: Instead of the first handful characters, show full @@ -151,19 +177,19 @@ Shorthand for "--text". --ignore-space-at-eol:: - Ignore changes in white spaces at EOL. + Ignore changes in whitespace at EOL. --ignore-space-change:: - Ignore changes in amount of white space. This ignores white - space at line end, and consider all other sequences of one or - more white space characters to be equivalent. + 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". --ignore-all-space:: - Ignore white space when comparing lines. This ignores - difference even if one line has white space where the other + Ignore whitespace when comparing lines. This ignores + differences even if one line has whitespace where the other line has none. -w:: @@ -179,11 +205,20 @@ --ext-diff:: Allow an external diff helper to be executed. If you set an - external diff driver with gitlink:gitattributes[5], you need - to use this option with gitlink:git-log[1] and friends. + external diff driver with linkgit:gitattributes[5], you need + to use this option with linkgit:git-log[1] and friends. --no-ext-diff:: Disallow external diff drivers. +--src-prefix=<prefix>:: + Show the given source prefix instead of "a/". + +--dst-prefix=<prefix>:: + Show the given destination prefix instead of "b/". + +--no-prefix:: + Do not show any source or destination prefix. + For more detailed explanation on these common options, see also link:diffcore.html[diffcore documentation]. diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index ce7c170d6..fdbd15a18 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -25,16 +25,12 @@ Basic Repository[[Basic Repository]] Everybody uses these commands to maintain git repositories. - * gitlink:git-init[1] or gitlink:git-clone[1] to create a + * linkgit:git-init[1] or linkgit:git-clone[1] to create a new repository. - * gitlink:git-fsck[1] to check the repository for errors. + * linkgit:git-fsck[1] to check the repository for errors. - * gitlink:git-prune[1] to remove unused objects in the repository. - - * gitlink:git-repack[1] to pack loose objects for efficiency. - - * gitlink:git-gc[1] to do common housekeeping tasks such as + * linkgit:git-gc[1] to do common housekeeping tasks such as repack and prune. Examples @@ -45,24 +41,21 @@ Check health and remove cruft.:: ------------ $ git fsck <1> $ git count-objects <2> -$ git repack <3> -$ git gc <4> +$ 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> without `-a` repacks incrementally. repacking every 4-5MB -of loose objects accumulation may be a good rule of thumb. -<4> it is easier to use `git gc` than individual housekeeping commands -such as `prune` and `repack`. This runs `repack -a -d`. +<3> repacks the local repository and performs other housekeeping tasks. Running +without `--prune` is a safe operation even while other ones are in progress. Repack a small project into single pack.:: + ------------ -$ git repack -a -d <1> -$ git prune +$ git gc <1> +$ git gc --prune ------------ + <1> pack all the objects reachable from the refs into one pack, @@ -76,28 +69,28 @@ A standalone individual developer does not exchange patches with other people, and works alone in a single repository, using the following commands. - * gitlink:git-show-branch[1] to see where you are. + * linkgit:git-show-branch[1] to see where you are. - * gitlink:git-log[1] to see what happened. + * linkgit:git-log[1] to see what happened. - * gitlink:git-checkout[1] and gitlink:git-branch[1] to switch + * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch branches. - * gitlink:git-add[1] to manage the index file. + * linkgit:git-add[1] to manage the index file. - * gitlink:git-diff[1] and gitlink:git-status[1] to see what + * linkgit:git-diff[1] and linkgit:git-status[1] to see what you are in the middle of doing. - * gitlink:git-commit[1] to advance the current branch. + * linkgit:git-commit[1] to advance the current branch. - * gitlink:git-reset[1] and gitlink:git-checkout[1] (with + * linkgit:git-reset[1] and linkgit:git-checkout[1] (with pathname parameters) to undo changes. - * gitlink:git-merge[1] to merge between local branches. + * linkgit:git-merge[1] to merge between local branches. - * gitlink:git-rebase[1] to maintain topic branches. + * linkgit:git-rebase[1] to maintain topic branches. - * gitlink:git-tag[1] to mark known point. + * linkgit:git-tag[1] to mark known point. Examples ~~~~~~~~ @@ -163,16 +156,16 @@ A developer working as a participant in a group project needs to learn how to communicate with others, and uses these commands in addition to the ones needed by a standalone developer. - * gitlink:git-clone[1] from the upstream to prime your local + * linkgit:git-clone[1] from the upstream to prime your local repository. - * gitlink:git-pull[1] and gitlink:git-fetch[1] from "origin" + * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin" to keep up-to-date with the upstream. - * gitlink:git-push[1] to shared repository, if you adopt CVS + * linkgit:git-push[1] to shared repository, if you adopt CVS style shared repository workflow. - * gitlink:git-format-patch[1] to prepare e-mail submission, if + * linkgit:git-format-patch[1] to prepare e-mail submission, if you adopt Linux kernel-style public forum workflow. Examples @@ -189,7 +182,7 @@ $ git pull <3> $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> $ git reset --hard ORIG_HEAD <6> -$ git prune <7> +$ git gc --prune <7> $ git fetch --tags <8> ------------ + @@ -265,17 +258,17 @@ project receives changes made by others, reviews and integrates them and publishes the result for others to use, using these commands in addition to the ones needed by participants. - * gitlink:git-am[1] to apply patches e-mailed in from your + * linkgit:git-am[1] to apply patches e-mailed in from your contributors. - * gitlink:git-pull[1] to merge from your trusted lieutenants. + * linkgit:git-pull[1] to merge from your trusted lieutenants. - * gitlink:git-format-patch[1] to prepare and send suggested + * linkgit:git-format-patch[1] to prepare and send suggested alternative to contributors. - * gitlink:git-revert[1] to undo botched commits. + * linkgit:git-revert[1] to undo botched commits. - * gitlink:git-push[1] to publish the bleeding edge. + * linkgit:git-push[1] to publish the bleeding edge. Examples @@ -350,10 +343,10 @@ Repository Administration[[Repository Administration]] A repository administrator uses the following tools to set up and maintain access to the repository by developers. - * gitlink:git-daemon[1] to allow anonymous download from + * linkgit:git-daemon[1] to allow anonymous download from repository. - * gitlink:git-shell[1] can be used as a 'restricted login shell' + * linkgit:git-shell[1] can be used as a 'restricted login shell' for shared central repository users. link:howto/update-hook-example.txt[update hook howto] has a good diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index da034223f..61e48ccf0 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -50,5 +50,5 @@ \--depth=<depth>:: Deepen the history of a 'shallow' repository created by - `git clone` with `--depth=<depth>` option (see gitlink:git-clone[1]) + `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) by the specified number of commits. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index fd82fc19b..9d2ac865d 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -8,7 +8,7 @@ git-add - Add file contents to the index SYNOPSIS -------- [verse] -'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--refresh] +'git-add' [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh] [--] <filepattern>... DESCRIPTION @@ -37,7 +37,7 @@ directory recursion or filename globbing performed by Git (quote your globs before the shell) will be silently ignored. The 'add' command can be used to add ignored files with the `-f` (force) option. -Please see gitlink:git-commit[1] for alternative ways to add content to a +Please see linkgit:git-commit[1] for alternative ways to add content to a commit. @@ -50,10 +50,10 @@ OPTIONS and `dir/file2`) can be given to add all files in the directory, recursively. --n:: +-n, \--dry-run:: Don't actually add the file(s), just show if they exist. --v:: +-v, \--verbose:: Be verbose. -f:: @@ -61,7 +61,14 @@ OPTIONS -i, \--interactive:: Add modified contents in the working tree interactively to - the index. + the index. Optional path arguments may be supplied to limit + operation to a subset of the working tree. See ``Interactive + mode'' for details. + +-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. -u:: Update only files that git already knows about. This is similar @@ -210,6 +217,8 @@ patch:: k - do not decide on this hunk now, and view the previous undecided hunk K - do not decide on this hunk now, and view the previous hunk + s - split the current hunk into smaller hunks + ? - 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. @@ -222,12 +231,12 @@ diff:: See Also -------- -gitlink:git-status[1] -gitlink:git-rm[1] -gitlink:git-reset[1] -gitlink:git-mv[1] -gitlink:git-commit[1] -gitlink:git-update-index[1] +linkgit:git-status[1] +linkgit:git-rm[1] +linkgit:git-reset[1] +linkgit:git-mv[1] +linkgit:git-commit[1] +linkgit:git-update-index[1] Author ------ @@ -239,4 +248,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index e4a6b3a6f..2ffba2102 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -37,10 +37,10 @@ OPTIONS area to store extracted patches. -k, --keep:: - Pass `-k` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). + Pass `-k` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]). -u, --utf8:: - Pass `-u` flag to `git-mailinfo` (see gitlink: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 @@ -51,7 +51,7 @@ default. You could use `--no-utf8` to override this. --no-utf8:: Pass `-n` flag to `git-mailinfo` (see - gitlink:git-mailinfo[1]). + linkgit:git-mailinfo[1]). -3, --3way:: When the patch does not apply cleanly, fall back on @@ -61,15 +61,15 @@ default. You could use `--no-utf8` to override this. -b, --binary:: Pass `--allow-binary-replacement` flag to `git-apply` - (see gitlink:git-apply[1]). + (see linkgit:git-apply[1]). --whitespace=<option>:: - This flag is passed to the `git-apply` (see gitlink:git-apply[1]) + 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 gitlink:git-apply[1]) + These flags are passed to the `git-apply` (see linkgit:git-apply[1]) program that applies the patch. @@ -144,7 +144,7 @@ names. SEE ALSO -------- -gitlink:git-apply[1]. +linkgit:git-apply[1]. Author @@ -157,4 +157,4 @@ Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.o GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index 02dc4740d..45a6a7251 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -20,7 +20,7 @@ include::blame-options.txt[] SEE ALSO -------- -gitlink:git-blame[1] +linkgit:git-blame[1] AUTHOR ------ @@ -28,4 +28,4 @@ Written by Ryan Anderson <ryan@michonline.com>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index c1c54bfe0..2dec2ec1c 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -13,7 +13,7 @@ SYNOPSIS [--apply] [--no-add] [--build-fake-ancestor <file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof] [--cached] - [--whitespace=<nowarn|warn|error|error-all|strip>] + [--whitespace=<nowarn|warn|fix|error|error-all>] [--exclude=PATH] [--verbose] [<patch>...] DESCRIPTION @@ -77,7 +77,7 @@ the information is read from the current index instead. Apply the patch in reverse. --reject:: - For atomicity, gitlink:git-apply[1] by default fails the whole patch and + For atomicity, linkgit:git-apply[1] 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 @@ -101,7 +101,7 @@ the information is read from the current index instead. ever ignored. --unidiff-zero:: - By default, gitlink:git-apply[1] expects that the patch being + By default, linkgit:git-apply[1] 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 @@ -112,14 +112,14 @@ discouraged. --apply:: If you use any of the options marked "Turns off - 'apply'" above, gitlink:git-apply[1] reads and outputs the + 'apply'" above, linkgit:git-apply[1] reads and outputs the information you asked 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 common part between + patch. This can be used to extract the common part between 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. @@ -135,25 +135,32 @@ discouraged. be useful when importing patchsets, where you want to exclude certain files or directories. ---whitespace=<option>:: - When applying a patch, detect a new or modified line - that ends with trailing whitespaces (this includes a - line that solely consists of whitespaces). By default, - the command outputs warning messages and applies the - patch. - When gitlink:git-apply[1] is used for statistics and not applying a - patch, it defaults to `nowarn`. - You can use different `<option>` to control this - behavior: +--whitespace=<action>:: + When applying a patch, detect a new or modified line that has + 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. ++ +By default, the command outputs warning messages but applies the patch. +When linkgit:git-apply[1] is used for statistics and not applying a +patch, it defaults to `nowarn`. ++ +You can use different `<action>` to control this +behavior: + * `nowarn` turns off the trailing whitespace warning. * `warn` outputs warnings for a few such errors, but applies the - patch (default). + 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 + 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. -* `strip` outputs warnings for a few such errors, strips out the - trailing whitespaces and applies the patch. --inaccurate-eof:: Under certain circumstances, some versions of diff do not correctly @@ -176,7 +183,7 @@ apply.whitespace:: Submodules ---------- -If the patch contains any changes to submodules then gitlink:git-apply[1] +If the patch contains any changes to submodules then linkgit:git-apply[1] treats these changes as follows. If --index is specified (explicitly or implicitly), then the submodule @@ -199,4 +206,4 @@ Documentation by Junio C Hamano GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 7091b8d61..bd20fd820 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -117,4 +117,4 @@ Documentation by Junio C Hamano, Martin Langhoff and the git-list <git@vger.kern GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 7cd652655..d3eaa16af 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -118,4 +118,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 1072fb87d..96585ae8d 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -16,8 +16,9 @@ The command takes various subcommands, and different options depending on the subcommand: git bisect start [<bad> [<good>...]] [--] [<paths>...] - git bisect bad <rev> - git bisect good <rev> + git bisect bad [<rev>] + git bisect good [<rev>...] + git bisect skip [<rev>...] git bisect reset [<branch>] git bisect visualize git bisect replay <logfile> @@ -91,7 +92,16 @@ During the bisection process, you can say $ git bisect visualize ------------ -to see the currently remaining suspects in `gitk`. +to see the currently remaining suspects in `gitk`. `visualize` is a bit +too long to type and `view` is provided as a synonym. + +If `DISPLAY` environment variable is not set, `git log` is used +instead. You can even give command line options such as `-p` and +`--stat`. + +------------ +$ git bisect view --stat +------------ Bisect log and bisect replay ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -134,6 +144,20 @@ $ git reset --hard HEAD~3 # try 3 revs before what Then compile and test the one you chose to try. After that, tell bisect what the result was as usual. +Bisect skip +~~~~~~~~~~~~ + +Instead of choosing by yourself a nearby commit, you may just want git +to do it for you using: + +------------ +$ 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. + Cutting down bisection by giving more parameters to bisect start ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -167,14 +191,18 @@ $ git bisect run my_script ------------ Note that the "run" script (`my_script` in the above example) should -exit with code 0 in case the current source code is good and with a -code between 1 and 127 (included) in case the current source code is -bad. +exit with code 0 in case the current source code is good. 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".) +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 @@ -199,4 +227,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 66f120370..14163b65f 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -21,7 +21,7 @@ last modified the line. Optionally, start annotating from the given revision. Also it can 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 gitlink:git-diff[1] or the "pickaxe" +replaced; you need to use a tool such as linkgit:git-diff[1] or the "pickaxe" interface briefly mentioned in the following paragraph. Apart from supporting file annotation, git also supports searching the @@ -41,7 +41,7 @@ OPTIONS include::blame-options.txt[] -c:: - Use the same output mode as gitlink:git-annotate[1] (Default: off). + Use the same output mode as linkgit:git-annotate[1] (Default: off). --score-debug:: Include debugging information related to the movement of @@ -184,7 +184,7 @@ commit commentary), a blame viewer won't ever care. SEE ALSO -------- -gitlink:git-annotate[1] +linkgit:git-annotate[1] AUTHOR ------ @@ -192,4 +192,4 @@ Written by Junio C Hamano <junkio@cox.net> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index d64ad2502..f920c04cc 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -10,6 +10,7 @@ SYNOPSIS [verse] 'git-branch' [--color | --no-color] [-r | -a] [-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>... @@ -20,6 +21,9 @@ 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). 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>. @@ -31,7 +35,7 @@ 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 can setup the -branch so that gitlink:git-pull[1] will appropriately merge from that +branch so that linkgit:git-pull[1] will appropriately merge from that remote branch. If this behavior is desired, it is possible to make it the default using the global `branch.autosetupmerge` configuration flag. Otherwise, it can be chosen per-branch using the `--track` @@ -49,8 +53,8 @@ has a reflog then the reflog will also be deleted. Use -r together with -d to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist -in remote repository or if gitlink:git-fetch[1] was configured not to fetch -them again. See also 'prune' subcommand of gitlink:git-remote[1] for way to +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. @@ -90,7 +94,7 @@ OPTIONS -a:: List both remote-tracking branches and local branches. --v:: +-v, --verbose:: Show sha1 and commit subject line for each head. --abbrev=<length>:: @@ -118,7 +122,7 @@ OPTIONS <branchname>:: The name of the branch to create or delete. The new branch name must pass all checks defined by - gitlink:git-check-ref-format[1]. Some of these checks + linkgit:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a branch name. <start-point>:: @@ -160,7 +164,7 @@ $ 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 -gitlink:git-fetch[1]. +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. @@ -183,4 +187,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 0cc6511bd..72f080a97 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -23,7 +23,7 @@ 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 in an archive at the originating machine, then importing those into -another repository using gitlink:git-fetch[1] and gitlink:git-pull[1] +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 basis for the bundle that is held by the destination repository: the @@ -51,12 +51,12 @@ list-heads <file>:: printed out. unbundle <file>:: - Passes the objects in the bundle to gitlink:git-index-pack[1] + 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 - gitlink:git-fetch[1]. + linkgit:git-fetch[1]. [git-rev-list-args...]:: A list of arguments, acceptable to git-rev-parse and @@ -73,7 +73,7 @@ unbundle <file>:: 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 gitlink:git-fetch-pack[1]). + acting like linkgit:git-fetch-pack[1]). SPECIFYING REFERENCES --------------------- @@ -145,4 +145,4 @@ Written by Mark Levedahl <mdl123@verizon.net> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index afa095c79..df42cb10f 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -21,7 +21,7 @@ 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 gitlink:git-rev-parse[1]. + "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. -t:: Instead of the content, show the object type identified by @@ -70,4 +70,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 856d2af2e..290f10f16 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -23,6 +23,11 @@ OPTIONS be treated as an attribute. +SEE ALSO +-------- +linkgit:gitattributes[5]. + + Author ------ Written by Junio C Hamano <junkio@cox.net> @@ -33,4 +38,4 @@ Documentation by James Bowes. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 13a5f4304..a67688042 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -35,7 +35,7 @@ imposes the following rules on how refs are named: These rules makes it easy for shell script based tools to parse refnames, pathname expansion by the shell when a refname is used unquoted (by mistake), and also avoids ambiguities in certain -refname expressions (see gitlink:git-rev-parse[1]). Namely: +refname expressions (see linkgit:git-rev-parse[1]). Namely: . double-dot `..` are often used as in `ref1..ref2`, and in some context this notation means `{caret}ref1 ref2` (i.e. not in @@ -47,9 +47,9 @@ refname expressions (see gitlink:git-rev-parse[1]). Namely: . 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 - gitlink:git-cat-file[1] "git-cat-file blob v1.3.3:refs.c". + linkgit:git-cat-file[1] "git-cat-file blob v1.3.3:refs.c". GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index b1a8ce110..cbbb0b509 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -181,4 +181,4 @@ Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 2e58481ed..584359ff3 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -44,7 +44,7 @@ OPTIONS -b:: Create a new branch named <new_branch> and start it at <branch>. The new branch name must pass all checks defined - by gitlink:git-check-ref-format[1]. Some of these checks + by linkgit:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a branch name. --track:: @@ -216,4 +216,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 47b1e8c2f..3bcc12c13 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -7,7 +7,7 @@ git-cherry-pick - Apply the change introduced by an existing commit SYNOPSIS -------- -'git-cherry-pick' [--edit] [-n] [-x] <commit> +'git-cherry-pick' [--edit] [-n] [-m parent-number] [-x] <commit> DESCRIPTION ----------- @@ -20,18 +20,19 @@ OPTIONS <commit>:: Commit to cherry-pick. For a more complete list of ways to spell commits, see - "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. + "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. -e|--edit:: With this option, `git-cherry-pick` will let you edit the commit message prior committing. -x:: - Cause the command to append which commit was - cherry-picked after the original commit message when - making a commit. 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 + 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 + 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 other hand you are cherry-picking between two publicly visible branches (e.g. backporting a fix to a maintenance branch for an older release from a @@ -43,6 +44,13 @@ OPTIONS described above, and `-r` was to disable it. Now the default is not to do `-x` so this option is a no-op. +-m parent-number|--mainline parent-number:: + Usually you cannot revert a merge because you do not know which + side of the merge should be considered the mainline. This + option specifies the parent number (starting from 1) of + the mainline and allows cherry-pick to replay the change + relative to the specified parent. + -n|--no-commit:: Usually the command automatically creates a commit with a commit log message stating which commit was @@ -67,4 +75,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index e6943822c..b0468aa74 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -66,4 +66,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.txt index 5217ab223..aca1d75e5 100644 --- a/Documentation/git-citool.txt +++ b/Documentation/git-citool.txt @@ -14,10 +14,10 @@ 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 gitlink:git-commit[1] program. +to the less interactive linkgit:git-commit[1] program. git-citool is actually a standard alias for 'git gui citool'. -See gitlink:git-gui[1] for more details. +See linkgit:git-gui[1] for more details. Author ------ @@ -29,4 +29,4 @@ Documentation by Shawn O. Pearce <spearce@spearce.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index e3252d59d..5e9da036b 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -39,7 +39,7 @@ OPTIONS -x:: Don't use the ignore rules. This allows removing all untracked files, including build products. This can be used (possibly in - conjunction with gitlink:git-reset[1]) to create a pristine + conjunction with linkgit:git-reset[1]) to create a pristine working directory to test a clean build. -X:: @@ -54,4 +54,4 @@ Written by Pavel Roskin <proski@gnu.org> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index cca14d6b5..fdccbd4cb 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git-clone' [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>] [--reference <repository>] - [--depth <depth>] <repository> [<directory>] + [--depth <depth>] [--] <repository> [<directory>] DESCRIPTION ----------- @@ -130,6 +130,7 @@ OPTIONS for "host.xz:foo/.git"). Cloning into an existing directory is not allowed. +:git-clone: 1 include::urls.txt[] Examples @@ -190,4 +191,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index a2537e179..170803a6d 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- This is usually not what an end user wants to run directly. See -gitlink:git-commit[1] instead. +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 @@ -90,7 +90,7 @@ include::i18n.txt[] See Also -------- -gitlink:git-write-tree[1] +linkgit:git-write-tree[1] Author @@ -103,4 +103,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index d4bfd49ce..c3725b2ed 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -10,8 +10,8 @@ SYNOPSIS [verse] 'git-commit' [-a | --interactive] [-s] [-v] [-u] [(-c | -C) <commit> | -F <file> | -m <msg> | --amend] - [--no-verify] [-e] [--author <author>] - [--] [[-i | -o ]<file>...] + [--allow-empty] [--no-verify] [-e] [--author <author>] + [--cleanup=<mode>] [--] [[-i | -o ]<file>...] DESCRIPTION ----------- @@ -20,11 +20,11 @@ commit along with a log message describing the changes you have made. The content to be added can be specified in several ways: -1. by using gitlink:git-add[1] to incrementally "add" changes to the +1. by using linkgit:git-add[1] to incrementally "add" changes to the index before using the 'commit' command (Note: even modified files must be "added"); -2. by using gitlink:git-rm[1] to remove files from the working tree +2. by using linkgit:git-rm[1] 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 @@ -41,13 +41,13 @@ The content to be added can be specified in several ways: by one which files should be part of the commit, before finalizing the operation. Currently, this is done by invoking `git-add --interactive`. -The gitlink:git-status[1] command can be used to obtain a +The linkgit:git-status[1] command 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. If you make a commit and then found a mistake immediately after -that, you can recover from it with gitlink:git-reset[1]. +that, you can recover from it with linkgit:git-reset[1]. OPTIONS @@ -86,9 +86,25 @@ OPTIONS Add Signed-off-by line at the end of the commit message. --no-verify:: - This option bypasses the pre-commit hook. + This option bypasses the pre-commit and commit-msg hooks. See also link:hooks.html[hooks]. +--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. + +--cleanup=<mode>:: + This option sets how the commit message is cleaned up. + The '<mode>' can be one of 'verbatim', 'whitespace', 'strip', + and 'default'. The 'default' mode will strip leading and + trailing empty lines and #commentary from the commit message + only if the message is to be edited. Otherwise only whitespace + removed. The 'verbatim' mode does not change message at all, + 'whitespace' removes just leading/trailing whitespace lines + and 'strip' removes both whitespace and commentary. + -e|--edit:: The message taken from file with `-F`, command line with `-m`, and from file with `-C` are usually used as the @@ -154,7 +170,7 @@ 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 gitlink:git-add[1]. A file can be +called the "index" with linkgit:git-add[1]. 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 @@ -213,13 +229,13 @@ $ git commit this second commit would record the changes to `hello.c` and `hello.h` as expected. -After a merge (initiated by either gitlink:git-merge[1] or -gitlink:git-pull[1]) stops because of conflicts, cleanly merged +After a merge (initiated by either linkgit:git-merge[1] or +linkgit:git-pull[1]) 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 gitlink:git-status[1] +check which paths are conflicting with linkgit:git-status[1] and after fixing them manually in your working tree, you would -stage the result as usual with gitlink:git-add[1]: +stage the result as usual with linkgit:git-add[1]: ------------ $ git status | grep unmerged @@ -271,11 +287,11 @@ information. SEE ALSO -------- -gitlink:git-add[1], -gitlink:git-rm[1], -gitlink:git-mv[1], -gitlink:git-merge[1], -gitlink:git-commit-tree[1] +linkgit:git-add[1], +linkgit:git-rm[1], +linkgit:git-mv[1], +linkgit:git-merge[1], +linkgit:git-commit-tree[1] Author ------ @@ -285,4 +301,4 @@ Junio C Hamano <junkio@cox.net> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index a592b61e2..e4d0e4752 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -20,6 +20,8 @@ SYNOPSIS '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] DESCRIPTION ----------- @@ -134,6 +136,21 @@ See also <<FILES>>. output without getting confused e.g. by values that contain line breaks. +--get-colorbool name [stdout-is-tty]:: + + Find the color setting for `name` (e.g. `color.diff`) and output + "true" or "false". `stdout-is-tty` should be either "true" or + "false", and is taken into account when configuration says + "auto". If `stdout-is-tty` is missing, then checks the standard + output of the command itself, and exits with status 0 if color + is to be used, or exits with status 1 otherwise. + +--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`. [[FILES]] FILES @@ -292,6 +309,15 @@ To add a new proxy, without altering any of the existing ones, use % git config core.gitproxy '"proxy-command" for example.com' ------------ +An example to use customized color from the configuration in your +script: + +------------ +#!/bin/sh +WS=$(git config --get-color color.diff.whitespace "blue reverse") +RESET=$(git config --get-color "" "reset") +echo "${WS}your whitespace color or blue reverse${RESET}" +------------ include::config.txt[] @@ -306,4 +332,4 @@ Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.ker GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-convert-objects.txt b/Documentation/git-convert-objects.txt deleted file mode 100644 index 9718abf86..000000000 --- a/Documentation/git-convert-objects.txt +++ /dev/null @@ -1,28 +0,0 @@ -git-convert-objects(1) -====================== - -NAME ----- -git-convert-objects - Converts old-style git repository - - -SYNOPSIS --------- -'git-convert-objects' - -DESCRIPTION ------------ -Converts old-style git repository to the latest format - - -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 gitlink:git[7] suite diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 81614111a..7fb08e934 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -34,4 +34,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index c3922f923..9a47b4c39 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,7 +8,7 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- -'git-cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID +'git-cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-w cvsworkdir] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID DESCRIPTION @@ -16,8 +16,9 @@ DESCRIPTION Exports a commit from GIT to a CVS checkout, making it easier to merge patches from a git repository into a CVS repository. -Execute it from the root of the CVS working copy. GIT_DIR must be defined. -See examples below. +Specify the name of a CVS checkout using the -w switch or execute it +from the root of the CVS working copy. In the latter case GIT_DIR must +be defined. See examples below. It does its best to do the safe thing, it will check that the files are unchanged and up to date in the CVS checkout, and it will not autocommit @@ -61,6 +62,11 @@ OPTIONS -u:: Update affected files from CVS repository before attempting export. +-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 + current directory is within a git repository. + -v:: Verbose. @@ -76,6 +82,12 @@ $ 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> +------------ + Merge pending patches into CVS automatically -- only if you really know what you are doing:: + ------------ @@ -86,12 +98,12 @@ $ git-cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git-cvsexportcommit Author ------ -Written by Martin Langhoff <martin@catalyst.net.nz> +Written by Martin Langhoff <martin@catalyst.net.nz> and others. Documentation -------------- -Documentation by Martin Langhoff <martin@catalyst.net.nz> +Documentation by Martin Langhoff <martin@catalyst.net.nz> and others. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index fdd7ec7ed..dbce50369 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -142,7 +142,7 @@ 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 -gitlink:git-cvsexportcommit[1]. +linkgit:git-cvsexportcommit[1]. -h:: Print a short usage message and exit. @@ -166,4 +166,4 @@ Documentation by Matthias Urlichs <smurf@smurf.noris.de>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 258a62f7e..d75e40134 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -28,7 +28,7 @@ OPTIONS ------- All these options obviously only make sense if enforced by the server side. -They have been implemented to resemble the gitlink:git-daemon[1] options as +They have been implemented to resemble the linkgit:git-daemon[1] options as closely as possible. --base-path <path>:: @@ -319,4 +319,4 @@ Documentation by Martyn Smith <martyn@catalyst.net.nz>, Martin Langhoff <martin@ GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 99e47c9c2..fd83bc783 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -31,8 +31,8 @@ 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-peek-remote` clients that are invoked -from `git-fetch`, `git-ls-remote`, 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. @@ -166,7 +166,7 @@ the per-repository configuration file can be used to enable or disable them. upload-pack:: - This serves `git-fetch-pack` and `git-peek-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`. @@ -272,4 +272,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index ac23e28f2..0742152b8 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -123,4 +123,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index d8a0a8602..6d2ea16a2 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -57,4 +57,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 7bd262cef..e86777859 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -129,4 +129,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 6b3f74efe..58d02c6a2 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -165,4 +165,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 201d5daf1..57c28628b 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -21,7 +21,7 @@ tree and the index file, or the index file and the working tree. the index (staging area for the next commit). In other words, the differences are what you _could_ tell git to further add to the index but you still haven't. You can - stage these changes by using gitlink:git-add[1]. + 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 @@ -67,14 +67,15 @@ for the last two forms that use ".." notations, can be any <tree-ish>. For a more complete list of ways to spell <commit>, see -"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. +"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. However, "diff" is about comparing two _endpoints_, not ranges, and the range notations ("<commit>..<commit>" and "<commit>\...<commit>") do not mean a range as defined in the -"SPECIFYING RANGES" section in gitlink:git-rev-parse[1]. +"SPECIFYING RANGES" section in linkgit:git-rev-parse[1]. OPTIONS ------- +:git-diff: 1 include::diff-options.txt[] <path>...:: @@ -128,7 +129,7 @@ $ git diff topic...master <3> + <1> Changes between the tips of the topic and the master branches. <2> Same as above. -<3> Changes that occured on the master branch since when the topic +<3> Changes that occurred on the master branch since when the topic branch was started off it. Limiting the diff output:: @@ -167,4 +168,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt new file mode 100644 index 000000000..6dac475a0 --- /dev/null +++ b/Documentation/git-fast-export.txt @@ -0,0 +1,83 @@ +git-fast-export(1) +================== + +NAME +---- +git-fast-export - Git data exporter + + +SYNOPSIS +-------- +'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]. + +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]. + + +OPTIONS +------- +--progress=<n>:: + Insert 'progress' statements every <n> objects, to be shown by + linkgit:git-fast-import[1] during import. + +--signed-tags=(verbatim|warn|strip|abort):: + Specify how to handle signed tags. Since any transformation + after the export can change the tag names (which can also happen + when excluding revisions) the signatures will not match. ++ +When asking to 'abort' (which is the default), this program will die +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. + + +EXAMPLES +-------- + +------------------------------------------------------------------- +$ git fast-export --all | (cd /empty/repository && git fast-import) +------------------------------------------------------------------- + +This will export the whole repository and import it into the existing +empty repository. Except for reencoding commits that are not in +UTF-8, it would be a one-to-one mirror. + +----------------------------------------------------- +$ git fast-export master~5..master | + sed "s|refs/heads/master|refs/heads/other|" | + git fast-import +----------------------------------------------------- + +This makes a new branch called 'other' from 'master~5..master' +(i.e. if 'master' has linear history, it will take the last 5 commits). + +Note that this assumes that none of the blobs and commit messages +referenced by that revision range contains the string +'refs/heads/master'. + + +Limitations +----------- + +Since linkgit:git-fast-import[1] 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[7] suite diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index d5119678b..bd625abab 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -24,7 +24,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 gitlink:git-init[1]) or incrementally +has already been initialized by linkgit:git-init[1]) 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. @@ -82,7 +82,7 @@ OPTIONS This information may be useful after importing projects whose total object set exceeds the 4 GiB packfile limit, as these commits can be used as edge points during calls - to gitlink:git-pack-objects[1]. + to linkgit:git-pack-objects[1]. --quiet:: Disable all non-fatal output, making fast-import silent when it @@ -220,7 +220,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 gitlink:git-am[1] when applying patches +same parser used by linkgit:git-am[1] when applying patches received from email. + Some malformed strings may be accepted as valid dates. In some of @@ -256,7 +256,7 @@ timezone. This particular format is supplied as its 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 -gitlink:git-update-index[1]. +linkgit:git-update-index[1]. + If separate `author` and `committer` commands are used in a `commit` the timestamps may not match, as the system clock will be polled @@ -411,7 +411,7 @@ Marks must be declared (via `mark`) before they can be used. * A complete 40 byte or abbreviated commit SHA-1 in hex. * Any valid Git SHA-1 expression that resolves to a commit. See - ``SPECIFYING REVISIONS'' in gitlink:git-rev-parse[1] for details. + ``SPECIFYING REVISIONS'' in linkgit:git-rev-parse[1] for details. The special case of restarting an incremental import from the current branch value should be written as: @@ -649,7 +649,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 gitlink:git-tag[1] process. +with the standard linkgit:git-tag[1] process. `reset` ~~~~~~~ @@ -863,7 +863,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 gitlink:git-blame[1] to track +Doing so will allow tools such as linkgit:git-blame[1] to track through the real commit history and properly annotate the source files. @@ -892,7 +892,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 gitlink:git-repack[1]. +\--window=50 (or higher) when you run linkgit:git-repack[1]. 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. @@ -1027,4 +1027,4 @@ Documentation by Shawn O. Pearce <spearce@spearce.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index a99a5b321..2b8ffe532 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -12,7 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -Usually you would want to use gitlink:git-fetch[1] which is a +Usually you would want to use linkgit:git-fetch[1] which is a higher level wrapper of this command instead. Invokes 'git-upload-pack' on a potentially remote repository, @@ -93,4 +93,4 @@ Documentation by Junio C Hamano. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 900347359..d982f961f 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -39,7 +39,7 @@ include::urls-remotes.txt[] SEE ALSO -------- -gitlink:git-pull[1] +linkgit:git-pull[1] Author @@ -53,4 +53,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 895d75031..e22dfa580 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -72,7 +72,7 @@ OPTIONS This is the filter for modifying the environment in which the commit will be performed. Specifically, you might want to rewrite the author/committer name/email/time environment - variables (see gitlink:git-commit[1] for details). Do not forget + variables (see linkgit:git-commit[1] for details). Do not forget to re-export the variables. --tree-filter <command>:: @@ -86,13 +86,13 @@ 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 gitlink:git-update-index[1]. + faster. 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 gitlink:git-commit-tree[1]: empty for + a format accepted by 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. @@ -105,7 +105,7 @@ OPTIONS --commit-filter <command>:: This is the filter for performing the commit. If this filter is specified, it will be called instead of the - gitlink:git-commit-tree[1] command, with arguments of the form + linkgit:git-commit-tree[1] 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. + @@ -116,7 +116,7 @@ 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 gitlink:git-rebase[1] instead). +that, use linkgit:git-rebase[1] instead). --tag-name-filter <command>:: This is the filter for rewriting tag names. When passed, @@ -159,7 +159,7 @@ definition impossible to preserve signatures at any rate.) <rev-list-options>:: When options are given after the new branch name, they will - be passed to gitlink:git-rev-list[1]. Only commits in the resulting + 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. @@ -249,7 +249,7 @@ will print. *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 gitlink:git-rebase[1]. +interactive mode of linkgit:git-rebase[1]. Consider this history: @@ -295,4 +295,4 @@ Documentation by Petr Baudis and the git list. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 7088ed409..8615ae353 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -46,7 +46,7 @@ merge.summary:: SEE ALSO -------- -gitlink:git-merge[1] +linkgit:git-merge[1] Author @@ -59,4 +59,4 @@ Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.o GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 6df8e8500..f1f90cca6 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -100,6 +100,11 @@ In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error. It returns an empty string instead. +As a special case for the date-type fields, you may specify a format for +the date by adding one of `:default`, `:relative`, `:short`, `:local`, +`:iso8601` or `:rfc2822` to the end of the fieldname; e.g. +`%(taggerdate:relative)`. + EXAMPLES -------- diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index f0617efa0..651efe6ca 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -9,9 +9,10 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--thread] +'git-format-patch' [-k] [-o <dir> | --stdout] [--thread] [--attach[=<boundary>] | --inline[=<boundary>]] [-s | --signoff] [<common diff options>] + [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] @@ -24,7 +25,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 gitlink:git-am[1]. +for use with linkgit:git-am[1]. There are two ways to specify which commits to operate on. @@ -33,7 +34,7 @@ There are two ways to specify which commits to operate on. that leads to the <since> to be output. 2. Generic <revision range> expression (see "SPECIFYING - REVISIONS" section in gitlink:git-rev-parse[1]) means the + REVISIONS" section in linkgit:git-rev-parse[1]) means the commits in the specified range. A single commit, when interpreted as a <revision range> @@ -65,6 +66,7 @@ reference. OPTIONS ------- +:git-format-patch: 1 include::diff-options.txt[] -<n>:: @@ -77,6 +79,9 @@ include::diff-options.txt[] -n|--numbered:: Name output in '[PATCH n/m]' format. +-N|--no-numbered:: + Name output in '[PATCH]' format. + --start-number <n>:: Start numbering the patches at <n> instead of 1. @@ -142,15 +147,16 @@ not add any suffix. CONFIGURATION ------------- -You can specify extra mail header lines to be added to each -message in the repository configuration. You can also specify -new defaults for the subject prefix and file suffix. +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. ------------ [format] headers = "Organization: git-foo\n" subjectprefix = CHANGE suffix = .txt + numbered = auto ------------ @@ -186,7 +192,7 @@ git-format-patch -3:: See Also -------- -gitlink:git-am[1], gitlink:git-send-email[1] +linkgit:git-am[1], linkgit:git-send-email[1] Author @@ -199,4 +205,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt index f21061ecf..6e9f71764 100644 --- a/Documentation/git-fsck-objects.txt +++ b/Documentation/git-fsck-objects.txt @@ -13,5 +13,5 @@ SYNOPSIS DESCRIPTION ----------- -This is a synonym for gitlink:git-fsck[1]. Please refer to the +This is a synonym for linkgit:git-fsck[1]. Please refer to the documentation of that command. diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 45c0bee50..f16cb9861 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -150,4 +150,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index c7742ca96..c4354bb6a 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -8,18 +8,19 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- -'git-gc' [--prune] [--aggressive] +'git-gc' [--prune] [--aggressive] [--auto] 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 gitlink:git-add[1]. +created from prior invocations of linkgit:git-add[1]. Users are encouraged to run this task on a regular basis within each repository to maintain good disk space utilization and good -operating performance. +operating performance. Some git commands may automatically run +`git-gc`; see the `--auto` flag below for details. OPTIONS ------- @@ -43,6 +44,25 @@ OPTIONS 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 + 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. ++ +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 +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 +automatic consolidation of packs. + Configuration ------------- @@ -78,15 +98,15 @@ The optional configuration variable 'gc.aggressiveWindow' controls how 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 gitlink:git-repack[1] for +the documentation for the --window' option in linkgit:git-repack[1] for more details. This defaults to 10. See Also -------- -gitlink:git-prune[1] -gitlink:git-reflog[1] -gitlink:git-repack[1] -gitlink:git-rerere[1] +linkgit:git-prune[1] +linkgit:git-reflog[1] +linkgit:git-repack[1] +linkgit:git-rerere[1] Author ------ @@ -94,4 +114,4 @@ Written by Shawn O. Pearce <spearce@spearce.org> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 60d1c52f4..dea41490c 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- Acts as a filter, extracting the commit ID stored in archives created by -gitlink:git-archive[1]. It reads only the first 1024 bytes of input, thus its +linkgit:git-archive[1]. 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 @@ -33,4 +33,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 97faaa1d3..f3cb24f25 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -143,4 +143,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index 13252a1aa..6d6cd5d87 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -16,7 +16,7 @@ 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 gitlink:gitk[1], git-gui focuses on commit generation +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. @@ -112,4 +112,4 @@ Documentation by Shawn O. Pearce <spearce@spearce.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 616f196d8..33030c022 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -42,4 +42,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt new file mode 100644 index 000000000..09904c75c --- /dev/null +++ b/Documentation/git-help.txt @@ -0,0 +1,103 @@ +git-help(1) +=========== + +NAME +---- +git-help - display help information about git + +SYNOPSIS +-------- +'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND] + +DESCRIPTION +----------- + +With no options and no COMMAND given, the synopsis of the 'git' +command and a list of the most commonly used git commands are printed +on the standard output. + +If the option '--all' or '-a' is given, then all available commands are +printed on the standard output. + +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 +former is internally converted into the latter. + +OPTIONS +------- +-a|--all:: + Prints all the available commands on the standard output. This + option supersedes any other option. + +-i|--info:: + Use the 'info' program to display the manual page, instead of + the 'man' program that is used by default. + +-m|--man:: + Use the 'man' program to display the manual page. This may be + used to override a value set in the 'help.format' + configuration variable. + +-w|--web:: + Use a web browser to display the HTML manual page, instead of + the 'man' program that is used by default. ++ +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-help--browse' helper script +(called by 'git-help') will pick a suitable default. ++ +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-help--browse' assumes the tool +is available in PATH. ++ +Note that the script tries, as much as possible, to display the HTML +page in a new tab on an already opened browser. + +CONFIGURATION VARIABLES +----------------------- + +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 +line option: + +* "man" corresponds to '-m|--man', +* "info" corresponds to '-i|--info', +* "web" or "html" correspond to '-w|--web', + +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. + +Note that these configuration variables should probably be set using +the '--global' flag, for example like this: + +------------------------------------------------ +$ git config --global help.format web +$ 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[7] 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[7] suite diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 389c6edfb..b784a9d07 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -53,4 +53,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index 9afb86038..cca77f10d 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -8,7 +8,7 @@ git-http-push - Push objects over HTTP/DAV to another repository SYNOPSIS -------- -'git-http-push' [--all] [--force] [--verbose] <url> <ref> [<ref>...] +'git-http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] DESCRIPTION ----------- @@ -30,6 +30,9 @@ OPTIONS the remote repository can lose commits; use it with care. +--dry-run:: + Do everything except actually send the updates. + --verbose:: Report the list of objects being walked locally and the list of objects successfully sent to the remote repository. @@ -95,4 +98,4 @@ Documentation by Nick Hengeveld GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index eca9e9cce..522b73c12 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -59,4 +59,4 @@ Documentation by Mike McCormack GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index a8a7f6f04..72b5d0011 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -43,10 +43,10 @@ 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 - gitlink::git-repack[1] . + linkgit:git-repack[1]. --fix-thin:: - It is possible for gitlink:git-pack-objects[1] to build + 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 @@ -59,7 +59,7 @@ OPTIONS 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 gitlink:git-repack[1] process from deleting + simultaneous linkgit:git-repack[1] process from deleting the newly constructed pack and index before refs can be updated to use objects contained in the pack. @@ -83,7 +83,7 @@ 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 gitlink:git-repack[1] +.keep file used as a lock to prevent the race with linkgit:git-repack[1] mentioned above. @@ -97,4 +97,4 @@ Documentation by Sergey Vlasov GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index d4e01cb32..439cabb73 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -14,5 +14,5 @@ SYNOPSIS DESCRIPTION ----------- -This is a synonym for gitlink:git-init[1]. Please refer to the +This is a synonym for linkgit:git-init[1]. Please refer to the documentation of that command. diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 07484a4fd..62914da97 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -52,7 +52,7 @@ is given: - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository readable by all users. -By default, the configuration flag receive.denyNonFastforward is enabled +By default, the configuration flag receive.denyNonFastForwards is enabled in shared repositories, so that you cannot force a non fast-forwarding push into it. @@ -111,4 +111,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index cec60ee78..841e8fac7 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -27,7 +27,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 and apache2 are the only supported servers. + Currently lighttpd, apache2 and webrick are supported. (Default: lighttpd) -m|--module-path:: @@ -71,6 +71,9 @@ 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. + Author ------ Written by Eric Wong <normalperson@yhbt.net> @@ -81,4 +84,4 @@ Documentation by Eric Wong <normalperson@yhbt.net>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-local-fetch.txt b/Documentation/git-local-fetch.txt deleted file mode 100644 index e830deeff..000000000 --- a/Documentation/git-local-fetch.txt +++ /dev/null @@ -1,66 +0,0 @@ -git-local-fetch(1) -================== - -NAME ----- -git-local-fetch - Duplicate another git repository on a local system - - -SYNOPSIS --------- -[verse] -'git-local-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [-l] [-s] [-n] - commit-id path - -DESCRIPTION ------------ -THIS COMMAND IS DEPRECATED. - -Duplicates another git repository on a local system. - -OPTIONS -------- --c:: - Get the commit objects. --t:: - Get trees associated with the commit objects. --a:: - Get all the objects. --v:: - Report what is downloaded. --s:: - Instead of regular file-to-file copying use symbolic links to the objects - in the remote repository. --l:: - Before attempting symlinks (if -s is specified) or file-to-file copying the - remote objects, try to hardlink the remote objects into the local - repository. --n:: - Never attempt to file-to-file copy remote objects. Only useful with - -s or -l command-line options. - --w <filename>:: - Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on - the local end after the transfer is complete. - ---stdin:: - Instead of a commit id on the command line (which is not expected in this - case), 'git-local-fetch' expects lines on stdin in the format - - <commit-id>['\t'<filename-as-in--w>] - ---recover:: - Verify that everything reachable from target is fetched. Used after - an earlier fetch is interrupted. - -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>. - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 5ec547cc0..5985f4739 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -14,9 +14,9 @@ DESCRIPTION ----------- Shows the commit logs. -The command takes options applicable to the gitlink:git-rev-list[1] +The command takes options applicable to the linkgit:git-rev-list[1] command to control what is shown and how, and options applicable to -the gitlink:git-diff-tree[1] commands to control how the changes +the linkgit:git-diff-tree[1] commands to control how the changes each commit introduces are shown. This manual page describes only the most frequently used options. @@ -27,6 +27,9 @@ OPTIONS include::pretty-options.txt[] +:git-log: 1 +include::diff-options.txt[] + -<n>:: Limits the number of commits to show. @@ -36,21 +39,22 @@ include::pretty-options.txt[] `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 - gitlink:git-rev-parse[1]. + linkgit:git-rev-parse[1]. --first-parent:: Follow only the first parent commit upon seeing a merge - commit. This option gives a better overview of the - evolution of a particular branch. - --p:: - Show the change the commit introduces in a patch form. + commit. This option can give a better overview when + viewing the evolution of a particular topic branch, + because merges into a topic branch tend to be only about + adjusting to updated upstream from time to time, and + this option allows you to ignore the individual commits + brought in to your history by such a merge. -g, \--walk-reflogs:: Show commits as they were recorded in the reflog. The log contains a record about how the tip of a reference was changed. Cannot be combined with --reverse. - See also gitlink:git-reflog[1]. + See also linkgit:git-reflog[1]. --decorate:: Print out the ref names of any commits that are shown. @@ -78,6 +82,7 @@ include::pretty-options.txt[] include::pretty-formats.txt[] +include::diff-generate-patch.txt[] Examples -------- @@ -124,4 +129,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index bc739117b..b1c797f10 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -11,6 +11,10 @@ SYNOPSIS DESCRIPTION ----------- + +*NOTE*: this command is deprecated. Use linkgit:git-fsck[1] with +the option '--lost-found' instead. + Finds dangling commits and tags from the object database, and creates refs to them in the .git/lost-found/ directory. Commits and tags that dereference to commits are stored in .git/lost-found/commit, @@ -74,4 +78,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 9e454f0a4..da9ebf405 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -15,6 +15,7 @@ SYNOPSIS [-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>]\* @@ -77,6 +78,10 @@ OPTIONS read additional exclude patterns that apply only to the directory and its subdirectories in <file>. +--exclude-standard:: + Add the standard git exclusions: .git/info/exclude, .gitignore + in each directory, and the user's global exclusion file. + --error-unmatch:: If any <file> does not appear in the index, treat this as an error (return 1). @@ -100,7 +105,8 @@ OPTIONS -v:: Similar to `-t`, but use lowercase letters for files - that are marked as 'always matching index'. + that are marked as 'assume unchanged' (see + linkgit:git-update-index[1]). --full-name:: When run from a subdirectory, the command usually @@ -146,7 +152,7 @@ Exclude Patterns '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. gitlink:gitignore[5] +flags --others or --ignored are specified. linkgit:gitignore[5] specifies the format of exclude patterns. These exclude patterns come from these places, in order: @@ -173,7 +179,7 @@ pattern file appears in. See Also -------- -gitlink:git-read-tree[1], gitlink:gitignore[5] +linkgit:git-read-tree[1], linkgit:gitignore[5] Author @@ -186,4 +192,4 @@ Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index 93e9a6033..c5ba0aad1 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -27,10 +27,10 @@ OPTIONS displayed. -u <exec>, --upload-pack=<exec>:: - Specify the full path of gitlink:git-upload-pack[1] on the remote + Specify the full path of linkgit:git-upload-pack[1] 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. Also see the '--exec' option for gitlink:git-peek-remote[1]. + user. <repository>:: Location of the repository. The shorthand defined in @@ -69,4 +69,4 @@ Written by Junio C Hamano <junkio@cox.net> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 7b7859967..360c0a1b9 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -91,4 +91,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 64aa6a1ea..3846f0e6e 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -18,7 +18,7 @@ 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 to create a commit. It is usually not necessary to use this -command directly. See gitlink:git-am[1] instead. +command directly. See linkgit:git-am[1] instead. OPTIONS @@ -66,4 +66,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index c4f4cabbd..8243f6911 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -55,4 +55,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 6b71880ec..07f78b4ae 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -39,4 +39,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 31882abb8..c513184ba 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -41,7 +41,7 @@ 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 -gitlink:git[1]. +linkgit:git[1]. OPTIONS @@ -89,4 +89,4 @@ with parts copied from the original documentation of RCS merge. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 17e9f10c6..5d816d0d8 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -40,7 +40,7 @@ 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 the a script calling git's imitation of +Typically this is run with a script calling git's imitation of the merge command from the RCS package. A sample script called "git-merge-one-file" is included in the @@ -84,4 +84,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt index f35d0e1b4..ee95df3bc 100644 --- a/Documentation/git-merge-one-file.txt +++ b/Documentation/git-merge-one-file.txt @@ -26,4 +26,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index 6892fdac3..4cc0964e7 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -33,4 +33,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 827838f7d..ed3a92404 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -42,7 +42,7 @@ include::merge-strategies.txt[] If you tried a merge which resulted in a complex conflicts and would want to start over, you can recover with -gitlink:git-reset[1]. +linkgit:git-reset[1]. CONFIGURATION ------------- @@ -59,6 +59,10 @@ merge.verbosity:: above outputs debugging information. The default is level 2. Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. +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 --------------- @@ -159,7 +163,8 @@ After seeing a conflict, you can do two things: SEE ALSO -------- -gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1] +linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], +linkgit:gitattributes[5] Author @@ -173,4 +178,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 6c32c6d18..50f106ec5 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -13,7 +13,7 @@ DESCRIPTION ----------- Use 'git mergetool' to run one of several merge utilities to resolve -merge conflicts. It is typically run after gitlink:git-merge[1]. +merge conflicts. It is typically run after linkgit:git-merge[1]. 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 @@ -25,12 +25,18 @@ OPTIONS -t or --tool=<tool>:: Use the merge resolution program specified by <tool>. Valid merge tools are: - kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, and opendiff + kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, and opendiff + 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' 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 tool +is available in PATH. Author ------ @@ -42,4 +48,4 @@ Documentation by Theodore Y Ts'o. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index ea7a75234..82db9f5d8 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -43,4 +43,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 638abc7d0..f312036ab 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -31,4 +31,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 2c9cf743c..bff3fbe74 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -34,7 +34,7 @@ OPTIONS condition. An error happens when a source is neither existing nor controlled by GIT, or when it would overwrite an existing file unless '-f' is given. --n:: +-n, \--dry-run:: Do nothing; only show what would happen @@ -50,4 +50,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 306e1a495..efcabdc27 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -38,7 +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 gitlink::git-describe[1] more closely. This option + of linkgit:git-describe[1] more closely. This option cannot be combined with --stdin. EXAMPLE @@ -75,4 +75,4 @@ Documentation by Johannes Schindelin. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index d18259d93..74cc7c1cb 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -58,7 +58,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 gitlink:git-rev-list[1] with `--objects` flag + the same way as linkgit:git-rev-list[1] with `--objects` flag uses its `commit` arguments to build the list of objects it outputs. The objects on the resulting list are packed. @@ -169,6 +169,14 @@ base-name:: length, this option typically shrinks the resulting packfile by 3-5 per-cent. +--threads=<n>:: + Specifies the number of threads to spawn when searching for best + delta matches. This requires that pack-objects 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. + --index-version=<version>[,<offset>]:: This is intended to be used by the test suite only. It allows to force the version for the generated pack index, and to force @@ -185,10 +193,10 @@ Documentation by Junio C Hamano See Also -------- -gitlink:git-rev-list[1] -gitlink:git-repack[1] -gitlink:git-prune-packed[1] +linkgit:git-rev-list[1] +linkgit:git-repack[1] +linkgit:git-prune-packed[1] GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index f2ceebac4..af4aa4a2e 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -48,10 +48,10 @@ Documentation by Lukas Sandström <lukass@etek.chalmers.se> See Also -------- -gitlink:git-pack-objects[1] -gitlink:git-repack[1] -gitlink:git-prune-packed[1] +linkgit:git-pack-objects[1] +linkgit:git-repack[1] +linkgit:git-prune-packed[1] GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index a20fc7de4..e4ff93471 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -63,4 +63,4 @@ Written by Linus Torvalds <torvalds@osdl.org> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt index 11b1f4d2e..deb8b2f01 100644 --- a/Documentation/git-parse-remote.txt +++ b/Documentation/git-parse-remote.txt @@ -47,4 +47,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index ad528a922..894852a78 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -39,4 +39,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index abc171266..000171007 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -12,8 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -Lists the references the remote repository has, and optionally -stores them in the local repository under the same name. +This command is deprecated; use `git-ls-remote` instead. OPTIONS ------- @@ -29,9 +28,6 @@ OPTIONS shells, but prefer having a lean .bashrc file (they set most of the things up in .bash_profile). -\--exec=<git-upload-pack>:: - Same \--upload-pack=<git-upload-pack>. - <host>:: A remote host that houses the repository. When this part is specified, 'git-upload-pack' is invoked via @@ -51,4 +47,4 @@ Documentation by Junio C Hamano. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 9f85f3833..93ee82ae5 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -44,9 +44,9 @@ Documentation by Ryan Anderson <ryan@michonline.com> See Also -------- -gitlink:git-pack-objects[1] -gitlink:git-repack[1] +linkgit:git-pack-objects[1] +linkgit:git-repack[1] GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 0ace233d1..f151cff5d 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -8,7 +8,7 @@ git-prune - Prune all unreachable objects from the object database SYNOPSIS -------- -'git-prune' [-n] [--] [<head>...] +'git-prune' [-n] [--expire <expire>] [--] [<head>...] DESCRIPTION ----------- @@ -31,6 +31,9 @@ OPTIONS \--:: Do not interpret any more arguments as options. +\--expire <time>:: + Only expire loose objects older than <time>. + <head>...:: In addition to objects reachable from any of our references, keep objects @@ -57,4 +60,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index e1eb2c1d0..77fdaf146 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -33,6 +33,16 @@ include::urls-remotes.txt[] include::merge-strategies.txt[] +\--rebase:: + Instead of a merge, perform a rebase after fetching. + *NOTE:* This is a potentially _dangerous_ mode of operation. + It rewrites history, which does not bode well when you + published that history already. Do *not* use this option + unless you have read linkgit:git-rebase[1] carefully. + +\--no-rebase:: + Override earlier \--rebase. + DEFAULT BEHAVIOUR ----------------- @@ -96,7 +106,7 @@ git pull, git pull origin:: current branch. Normally the branch merged in is the HEAD of the remote repository, but the choice is determined by the branch.<name>.remote and - branch.<name>.merge options; see gitlink:git-config[1] + branch.<name>.merge options; see linkgit:git-config[1] for details. git pull origin next:: @@ -143,12 +153,12 @@ 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 -gitlink:git-reset[1]. +linkgit:git-reset[1]. SEE ALSO -------- -gitlink:git-fetch[1], gitlink:git-merge[1], gitlink:git-config[1] +linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] Author @@ -164,4 +174,4 @@ Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 6bc559ddd..5f2494495 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -9,8 +9,8 @@ git-push - Update remote refs along with associated objects SYNOPSIS -------- [verse] -'git-push' [--all] [--tags] [--receive-pack=<git-receive-pack>] - [--repo=all] [-f | --force] [-v] [<repository> <refspec>...] +'git-push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] + [--repo=all] [-f | --force] [-v | --verbose] [<repository> <refspec>...] DESCRIPTION ----------- @@ -20,7 +20,7 @@ necessary to complete the given refs. You can make interesting things happen to a repository every time you push into it, by setting up 'hooks' there. See -documentation for gitlink:git-receive-pack[1]. +documentation for linkgit:git-receive-pack[1]. OPTIONS @@ -63,6 +63,17 @@ the remote repository. Instead of naming each ref to push, specifies that all refs under `$GIT_DIR/refs/heads/` be pushed. +\--mirror:: + Instead of naming each ref to push, specifies that all + refs under `$GIT_DIR/refs/heads/` and `$GIT_DIR/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 + will be removed from the remote end. + +\--dry-run:: + Do everything except actually send the updates. + \--tags:: All refs under `$GIT_DIR/refs/tags` are pushed, in addition to refspecs explicitly listed on the command @@ -92,7 +103,7 @@ the remote repository. transfer spends extra cycles to minimize the number of objects to be sent and meant to be used on slower connection. --v:: +-v, \--verbose:: Run verbosely. include::urls-remotes.txt[] @@ -134,4 +145,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index 1c3ef4c59..0fc2b56c1 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -57,4 +57,4 @@ Documentation by Eric Biederman <ebiederm@lnxi.com> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 74c5478ba..8421d1fd7 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -15,7 +15,7 @@ DESCRIPTION ----------- Reads the tree information given by <tree-ish> into the index, but does not actually *update* any of the files it "caches". (see: -gitlink:git-checkout-index[1]) +linkgit:git-checkout-index[1]) Optionally, it can merge a tree into the index, perform a fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m` @@ -347,8 +347,8 @@ have finished your work-in-progress), attempt the merge again. See Also -------- -gitlink:git-write-tree[1]; gitlink:git-ls-files[1]; -gitlink:gitignore[5] +linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; +linkgit:gitignore[5] Author @@ -361,4 +361,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index dfb8a0da5..c11c6453e 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,8 +8,9 @@ git-rebase - Forward-port local commits to the updated upstream head SYNOPSIS -------- [verse] -'git-rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] [-C<n>] - [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>] +'git-rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] + [-C<n>] [ --whitespace=<option>] [-p | --preserve-merges] + [--onto <newbase>] <upstream> [<branch>] 'git-rebase' --continue | --skip | --abort DESCRIPTION @@ -27,7 +28,10 @@ The current branch is reset to <upstream>, or <newbase> if the `git reset --hard <upstream>` (or <newbase>). The commits that were previously saved into the temporary area are -then reapplied to the current branch, one by one, in order. +then reapplied to the current branch, one by one, in order. Note that +any commits in HEAD which introduce the same textual changes as a commit +in HEAD..<upstream> are omitted (i.e., a patch already accepted upstream +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 @@ -61,6 +65,26 @@ would be: The latter form is just a short-hand of `git checkout topic` followed by `git rebase master`. +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 +following history (in which A' and A introduce the same set of changes, +but have different committer information): + +------------ + A---B---C topic + / + D---E---A'---F master +------------ + +will result in: + +------------ + B'---C' topic + / + D---E---A'---F master +------------ + Here is how you would transplant a topic branch based on one branch to another, to pretend that you forked the topic branch from the latter branch, using `rebase --onto`. @@ -209,6 +233,10 @@ 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 + (see linkgit:git-apply[1]) that applies the patch. + -i, \--interactive:: Make a list of the commits which are about to be rebased. Let the user edit that list before rebasing. This mode can also be used to @@ -346,8 +374,8 @@ add other commits. This can be used to split a commit into two: 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 gitlink:git-add[1] (possibly interactively) and/or - gitlink:git-gui[1] to do that. + commit. You can use linkgit:git-add[1] (possibly interactively) and/or + linkgit:git-gui[1] to do that. - Commit the now-current index with whatever commit message is appropriate now. @@ -358,7 +386,7 @@ add other commits. This can be used to split a commit into two: If you are not absolutely sure that the intermediate revisions are consistent (they compile, pass the testsuite, etc.) you should use -gitlink:git-stash[1] to stash away the not-yet-committed changes +linkgit:git-stash[1] to stash away the not-yet-committed changes after each commit, test, and amend the commit if fixes are necessary. @@ -373,4 +401,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 2633d94c5..4111434bb 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -149,7 +149,7 @@ if the repository is packed and is served via a dumb transport. SEE ALSO -------- -gitlink:git-send-pack[1] +linkgit:git-send-pack[1] Author @@ -162,4 +162,4 @@ Documentation by Junio C Hamano. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 25003c386..f9bba36c2 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -28,19 +28,19 @@ 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 tip, are removed from the reflog. This is typically not used -directly by the end users -- instead, see gitlink:git-gc[1]. +directly by the end users -- instead, see linkgit:git-gc[1]. 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'; -see gitlink:git-log[1]. +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 gitlink:git-rev-parse[1] for +point to one week ago", and so on. See linkgit:git-rev-parse[1] for more details. @@ -88,4 +88,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index fe631bb3d..ccbda9fba 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -33,4 +33,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 886bc03c4..10f6fa58b 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,7 +10,8 @@ SYNOPSIS -------- [verse] 'git-remote' -'git-remote' add [-t <branch>] [-m <branch>] [-f] <name> <url> +'git-remote' add [-t <branch>] [-m <branch>] [-f] [--mirror] <name> <url> +'git-remote' rm <name> 'git-remote' show <name> 'git-remote' prune <name> 'git-remote' update [group] @@ -45,6 +46,15 @@ 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. ++ +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. + +'rm':: + +Remove the remote named <name>. All remote tracking branches and +configuration settings for the remote are removed. 'show':: @@ -71,7 +81,7 @@ remotes.<group>. If a named group is not specified on the command line, the configuration parameter remotes.default will get 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 gitlink:git-config[1]). +be updated. (See linkgit:git-config[1]). DISCUSSION @@ -79,7 +89,7 @@ DISCUSSION The remote configuration is achieved using the `remote.origin.url` and `remote.origin.fetch` configuration variables. (See -gitlink:git-config[1]). +linkgit:git-config[1]). Examples -------- @@ -118,9 +128,9 @@ $ git merge origin See Also -------- -gitlink:git-fetch[1] -gitlink:git-branch[1] -gitlink:git-config[1] +linkgit:git-fetch[1] +linkgit:git-branch[1] +linkgit:git-config[1] Author ------ @@ -134,4 +144,4 @@ Documentation by J. Bruce Fields and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 12e2079a7..3d957492f 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -40,19 +40,19 @@ OPTIONS -d:: After packing, if the newly created packs make some existing packs redundant, remove the redundant packs. - Also runs gitlink:git-prune-packed[1]. + Also runs linkgit:git-prune-packed[1]. -l:: Pass the `--local` option to `git pack-objects`, see - gitlink:git-pack-objects[1]. + linkgit:git-pack-objects[1]. -f:: Pass the `--no-reuse-delta` option to `git pack-objects`, see - gitlink:git-pack-objects[1]. + linkgit:git-pack-objects[1]. -q:: Pass the `-q` option to `git pack-objects`, see - gitlink:git-pack-objects[1]. + linkgit:git-pack-objects[1]. -n:: Do not update the server information with @@ -109,9 +109,9 @@ Documentation by Ryan Anderson <ryan@michonline.com> See Also -------- -gitlink:git-pack-objects[1] -gitlink:git-prune-packed[1] +linkgit:git-pack-objects[1] +linkgit:git-prune-packed[1] GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index 2deba3176..2ca39946b 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -14,5 +14,5 @@ SYNOPSIS DESCRIPTION ----------- -This is a synonym for gitlink:git-config[1]. Please refer to the +This is a synonym for linkgit:git-config[1]. Please refer to the documentation of that command. diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 087eeb7cc..270df9b18 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -36,4 +36,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index c4d426323..3793267da 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -22,10 +22,6 @@ 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. -[NOTE] -You need to set the config variable rerere.enabled to enable this -command. - COMMANDS -------- @@ -37,7 +33,7 @@ its working state. 'clear':: This resets the metadata used by rerere if a merge resolution is to be -is aborted. Calling gitlink:git-am[1] --skip or gitlink:git-rebase[1] +is aborted. Calling linkgit:git-am[1] --skip or linkgit:git-rebase[1] [--skip|--abort] will automatically invoke this command. 'diff':: @@ -208,4 +204,4 @@ Written by Junio C Hamano <junkio@cox.net> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 87afa6f8d..a4e0a779d 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,8 +8,8 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git-reset' [--mixed | --soft | --hard] [<commit>] -'git-reset' [--mixed] <commit> [--] <paths>... +'git-reset' [--mixed | --soft | --hard] [-q] [<commit>] +'git-reset' [--mixed] [-q] [<commit>] [--] <paths>... DESCRIPTION ----------- @@ -21,7 +21,7 @@ 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, -gitlink:git-revert[1] is your friend. +linkgit:git-revert[1] is your friend. The second form with 'paths' is used to revert selected paths in the index from a given commit, without moving HEAD. @@ -37,7 +37,7 @@ OPTIONS --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 "Added but not yet committed", as gitlink:git-status[1] would + files "Added but not yet committed", as linkgit:git-status[1] would put it. --hard:: @@ -45,8 +45,11 @@ OPTIONS switched to. Any changes to tracked files in the working tree since <commit> are lost. +-q:: + Be quiet, only report errors. + <commit>:: - Commit to make the current HEAD. + Commit to make the current HEAD. If not given defaults to HEAD. Examples -------- @@ -68,7 +71,7 @@ message, or both. Leaves working tree as it was before "reset". commit by starting with its log message. If you do not need to edit the message further, you can give -C option instead. + -See also the --amend option to gitlink:git-commit[1]. +See also the --amend option to linkgit:git-commit[1]. Undo commits permanently:: + @@ -183,4 +186,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 7cd0e8913..db42cd8a9 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -15,11 +15,13 @@ SYNOPSIS [ \--min-age=timestamp ] [ \--sparse ] [ \--no-merges ] + [ \--first-parent ] [ \--remove-empty ] [ \--full-history ] [ \--not ] [ \--all ] [ \--stdin ] + [ \--quiet ] [ \--topo-order ] [ \--parents ] [ \--timestamp ] @@ -34,6 +36,7 @@ SYNOPSIS [ \--pretty | \--header ] [ \--bisect ] [ \--bisect-vars ] + [ \--bisect-all ] [ \--merge ] [ \--reverse ] [ \--walk-reflogs ] @@ -76,11 +79,11 @@ between the two operands. The following two commands are equivalent: $ git-rev-list A...B ----------------------------------------------------------------------- -gitlink:git-rev-list[1] is a very essential git program, since it +linkgit:git-rev-list[1] is a very essential git program, 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 gitlink:git-bisect[1] and -gitlink:git-repack[1]. +used by commands as different as linkgit:git-bisect[1] and +linkgit:git-repack[1]. OPTIONS ------- @@ -88,9 +91,9 @@ OPTIONS Commit Formatting ~~~~~~~~~~~~~~~~~ -Using these options, gitlink:git-rev-list[1] will act similar to the -more specialized family of commit log tools: gitlink:git-log[1], -gitlink:git-show[1], and gitlink:git-whatchanged[1] +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] include::pretty-options.txt[] @@ -164,8 +167,8 @@ Diff Formatting ~~~~~~~~~~~~~~~ Below are listed options that control the formatting of diff output. -Some of them are specific to gitlink:git-rev-list[1], however other diff -options may be given. See gitlink:git-diff-files[1] for more options. +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:: @@ -254,6 +257,15 @@ limiting may be applied. Do not print commits with more than one parent. +--first-parent:: + Follow only the first parent commit upon seeing a merge + commit. This option can give a better overview when + viewing the evolution of a particular topic branch, + because merges into a topic branch tend to be only about + adjusting to updated upstream from time to time, and + this option allows you to ignore the individual commits + brought in to your history by such a merge. + --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) @@ -269,6 +281,14 @@ limiting may be applied. In addition to the '<commit>' listed on the command line, read them from the standard input. +--quiet:: + + Don't print anything to standard output. This form of + git-rev-list is primarily meant to allow the caller to + test the exit status to see if a range of objects is fully + connected (or not). It is faster than redirecting stdout + to /dev/null as the output does not have to be formatted. + --cherry-pick:: Omit any commit that introduces the same change as @@ -354,6 +374,21 @@ 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`.) + +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. + -- Commit Ordering @@ -393,7 +428,7 @@ These options are mostly targeted for packing of git repositories. Similar to '--objects', but also print the IDs of excluded commits prefixed with a "-" character. This is used by - gitlink:git-pack-objects[1] to build "thin" pack, which records + linkgit:git-pack-objects[1] to build "thin" pack, which records objects in deltified form based on objects contained in these excluded commits to reduce network traffic. @@ -425,4 +460,4 @@ and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 4758c33de..5d9c36985 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -23,6 +23,13 @@ distinguish between them. OPTIONS ------- +--parseopt:: + Use `git-rev-parse` in option parsing mode (see PARSEOPT section below). + +--keep-dash-dash:: + Only meaningful in `--parseopt` mode. Tells the option parser to echo + out the first `--` met instead of skipping it. + --revs-only:: Do not output flags and parameters not meant for `git-rev-list` command. @@ -63,6 +70,13 @@ OPTIONS possible '{caret}' prefix); this option makes them output in a form as close to the original input as possible. +--symbolic-full-name:: + This is similar to \--symbolic, but it omits input that + are not refs (i.e. branch or tag names; or more + explicitly disambiguating "heads/master" form, when you + want to name the "master" branch when there is an + unfortunately named tag "master"), and show them as full + refnames (e.g. "refs/heads/master"). --all:: Show all refs found in `$GIT_DIR/refs`. @@ -288,10 +302,75 @@ Here are a handful examples: C^@ I J F F^! D G H D F +PARSEOPT +-------- + +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` +to replace the arguments with normalized ones. In case of error, it outputs +usage on the standard error stream, and exits with code 129. + +Input Format +~~~~~~~~~~~~ + +`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. + +Each line of options has this format: + +------------ +<opt_spec><arg_spec>? SP+ help LF +------------ + +`<opt_spec>`:: + its format is the short option character, then the long option name + separated by a comma. Both parts are not required, though at least one + is necessary. `h,help`, `dry-run` and `f` are all three correct + `<opt_spec>`. + +`<arg_spec>`:: + an `<arg_spec>` tells the option parser if the option has an argument + (`=`), an optional one (`?` though its use is discouraged) or none + (no `<arg_spec>` in that case). + +The remainder of the line, after stripping the spaces, is used +as the help associated to the option. + +Blank lines are ignored, and lines that don't match this specification are used +as option group headers (start the line with a space to create such +lines on purpose). + +Example +~~~~~~~ + +------------ +OPTS_SPEC="\ +some-command [options] <args>... + +some-command does foo and bar! +-- +h,help show the help + +foo some nifty option --foo +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 $?` +------------ + + Author ------ -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net> +Written by Linus Torvalds <torvalds@osdl.org> . +Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org> Documentation -------------- @@ -299,4 +378,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 69db49844..494fc7f84 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -7,7 +7,7 @@ git-revert - Revert an existing commit SYNOPSIS -------- -'git-revert' [--edit | --no-edit] [-n] <commit> +'git-revert' [--edit | --no-edit] [-n] [-m parent-number] <commit> DESCRIPTION ----------- @@ -20,13 +20,20 @@ OPTIONS <commit>:: Commit to revert. For a more complete list of ways to spell commit names, see - "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. + "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. -e|--edit:: With this option, `git-revert` will let you edit the commit message prior committing the revert. This is the default if you run the command from a terminal. +-m parent-number|--mainline parent-number:: + Usually you cannot revert a merge because you do not know which + side of the merge should be considered the mainline. This + option specifies the parent number (starting from 1) of + the mainline and allows revert to reverse the change + relative to the specified parent. + --no-edit:: With this option, `git-revert` will not start the commit message editor. @@ -55,4 +62,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index be61a8216..dc36c662a 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -30,7 +30,7 @@ OPTIONS -f:: Override the up-to-date check. --n:: +-n, \--dry-run:: Don't actually remove the file(s), just show if they exist in the index. @@ -51,7 +51,7 @@ OPTIONS \--ignore-unmatch:: Exit with a zero status even if no files matched. -\--quiet:: +-q, \--quiet:: git-rm normally outputs one line (in the form of an "rm" command) for each file removed. This option suppresses that output. @@ -83,7 +83,7 @@ git-rm -f git-*.sh:: See Also -------- -gitlink:git-add[1] +linkgit:git-add[1] Author ------ @@ -95,4 +95,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-runstatus.txt b/Documentation/git-runstatus.txt deleted file mode 100644 index dee5d0da9..000000000 --- a/Documentation/git-runstatus.txt +++ /dev/null @@ -1,68 +0,0 @@ -git-runstatus(1) -================ - -NAME ----- -git-runstatus - A helper for git-status and git-commit - - -SYNOPSIS --------- -'git-runstatus' [--color|--nocolor] [--amend] [--verbose] [--untracked] - - -DESCRIPTION ------------ -Examines paths in the working tree that has changes unrecorded -to the index file, and changes between the index file and the -current HEAD commit. The former paths are what you _could_ -commit by running 'git add' (or 'git rm' if you are deleting) before running 'git -commit', and the latter paths are what you _would_ commit by -running 'git commit'. - -If there is no path that is different between the index file and -the current HEAD commit, the command exits with non-zero status. - -Note that this is _not_ the user level command you would want to -run from the command line. Use 'git-status' instead. - - -OPTIONS -------- ---color:: - Show colored status, highlighting modified file names. - ---nocolor:: - Turn off coloring. - ---amend:: - Show status based on HEAD^1, not HEAD, i.e. show what - 'git-commit --amend' would do. - ---verbose:: - Show unified diff of all file changes. - ---untracked:: - Show files in untracked directories, too. Without this - option only its name and a trailing slash are displayed - for each untracked directory. - - -OUTPUT ------- -The output from this command is designed to be used as a commit -template comments, and all the output lines are prefixed with '#'. - - -Author ------- -Originally written by Linus Torvalds <torvalds@osdl.org> as part -of git-commit, and later rewritten in C by Jeff King. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 16bfd7be2..4b8ec8a20 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -75,6 +75,12 @@ The --cc option must be repeated for each user you want on the cc list. Make git-send-email less verbose. One line per email should be all that is output. +--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:: If set, specifies the outgoing SMTP server to use (e.g. `smtp.example.com` or a raw IP address). Alternatively it can @@ -85,14 +91,29 @@ 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:: + Specifies a port different from the default port (SMTP + servers typically listen to smtp port 25 and ssmtp port + 465). + +--smtp-user, --smtp-pass:: + Username and password for SMTP-AUTH. Defaults are the values of + the configuration values 'sendemail.smtpuser' and + 'sendemail.smtppass', but see also 'sendemail.identity'. + If not set, authentication is not attempted. + +--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, if it - shows up in a From: line. + 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. @@ -122,6 +143,13 @@ The --to option must be repeated for each user you want on the to list. 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 email aliases files. You must also supply 'sendemail.aliasfiletype'. @@ -130,6 +158,9 @@ sendemail.aliasfiletype:: Format of the file(s) specified in sendemail.aliasesfile. Must be one of 'mutt', 'mailrc', 'pine', or 'gnus'. +sendemail.to:: + Email address (or alias) to always send to. + sendemail.cccmd:: Command to execute to generate per patch file specific "Cc:"s. @@ -141,7 +172,16 @@ sendemail.chainreplyto:: parameter. sendemail.smtpserver:: - Default smtp server to use. + Default SMTP server to use. + +sendemail.smtpuser:: + Default SMTP-AUTH username. + +sendemail.smtppass:: + Default SMTP-AUTH password. + +sendemail.smtpssl:: + Boolean value specifying the default to the '--smtp-ssl' parameter. Author ------ @@ -156,4 +196,4 @@ Documentation by Ryan Anderson GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 3271e8818..777515b12 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -8,11 +8,11 @@ git-send-pack - Push objects over git protocol to another repository SYNOPSIS -------- -'git-send-pack' [--all] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] +'git-send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] DESCRIPTION ----------- -Usually you would want to use gitlink:git-push[1] which is a +Usually you would want to use linkgit:git-push[1] which is a higher level wrapper of this command instead. Invokes 'git-receive-pack' on a possibly remote repository, and @@ -34,6 +34,9 @@ OPTIONS Instead of explicitly specifying which refs to update, update all heads that locally exist. +\--dry-run:: + Do everything except actually send the updates. + \--force:: Usually, the command refuses to update a remote ref that is not an ancestor of the local ref used to overwrite it. @@ -82,7 +85,9 @@ Each pattern pair consists of the source side (before the colon) 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. +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. - It is an error if <src> does not match exactly one of the local refs. @@ -120,4 +125,4 @@ Documentation by Junio C Hamano. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 1ea1faa1b..16b8b7514 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -44,6 +44,11 @@ set_reflog_action:: end-user action in the reflog, when the script updates a ref. +git_editor:: + runs an editor of user's choice (GIT_EDITOR, core.editor, VISUAL or + EDITOR) on a given file, but error out if no editor is specified + and the terminal is dumb. + is_bare_repository:: outputs `true` or `false` to the standard output stream to indicate if the repository is a bare repository @@ -57,6 +62,10 @@ require_work_tree:: if so. Used by scripts that require working tree (e.g. `checkout`). +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 ------ @@ -68,4 +77,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 48f2d57b7..bc031e0cc 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -31,4 +31,4 @@ Documentation by Petr Baudis and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 2220ef6ea..c7752575d 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] -git-shortlog [-n|--numbered] [-s|--summary] [<committish>...] +git-log --pretty=short | 'git-shortlog' [-h] [-n] [-s] [-e] +git-shortlog [-n|--numbered] [-s|--summary] [-e|--email] [<committish>...] DESCRIPTION ----------- @@ -32,18 +32,22 @@ OPTIONS -s, \--summary:: Suppress commit description and provide a commit count summary only. +-e, \--email:: + Show the email address of each author. + FILES ----- -.mailmap:: - If this file 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: +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)> +------------ +# Keep alphabetized +Adam Morrow <adam@localhost.localdomain> +Eve Jones <eve@laptop.(none)> +------------ Author ------ @@ -55,4 +59,4 @@ Documentation by Junio C Hamano. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index ba5313d51..0bb8250b2 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -190,4 +190,4 @@ Documentation by Junio C Hamano. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index 764d99356..535a88464 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -31,4 +31,4 @@ Documentation by Junio C Hamano GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 2355aa5e8..ce0e643fb 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -130,7 +130,7 @@ When using the '--verify' flag, the command requires an exact path: will only match the exact branch called "master". -If nothing matches, gitlink:git-show-ref[1] will return an error code of 1, +If nothing matches, linkgit:git-show-ref[1] 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 @@ -160,7 +160,7 @@ to get a listing of all tags together with what they dereference. SEE ALSO -------- -gitlink:git-ls-remote[1], gitlink:git-peek-remote[1] +linkgit:git-ls-remote[1] AUTHORS ------- @@ -169,4 +169,4 @@ Man page by Jonas Fonseca <fonseca@diku.dk>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index a42e12115..dccf0e20e 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -20,12 +20,12 @@ presents the merge commit in a special format as produced by For tags, it shows the tag message and the referenced objects. -For trees, it shows the names (equivalent to gitlink:git-ls-tree[1] +For trees, it shows the names (equivalent to linkgit:git-ls-tree[1] with \--name-only). For plain blobs, it shows the plain contents. -The command takes options applicable to the gitlink:git-diff-tree[1] command to +The command takes options applicable to the linkgit:git-diff-tree[1] command to control how the changes the commit introduces are shown. This manual page describes only the most frequently used options. @@ -36,7 +36,7 @@ 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 gitlink:git-rev-parse[1]. + "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. include::pretty-options.txt[] @@ -83,4 +83,4 @@ This manual page is a stub. You can help the git documentation by expanding it. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-ssh-fetch.txt b/Documentation/git-ssh-fetch.txt deleted file mode 100644 index 8d3e2ffb2..000000000 --- a/Documentation/git-ssh-fetch.txt +++ /dev/null @@ -1,52 +0,0 @@ -git-ssh-fetch(1) -================ - -NAME ----- -git-ssh-fetch - Fetch from a remote repository over ssh connection - - - -SYNOPSIS --------- -'git-ssh-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url - -DESCRIPTION ------------ -THIS COMMAND IS DEPRECATED. - -Pulls from a remote repository over ssh connection, invoking -git-ssh-upload on the other end. It functions identically to -git-ssh-upload, aside from which end you run it on. - - -OPTIONS -------- -commit-id:: - Either the hash or the filename under [URL]/refs/ to - pull. - --c:: - Get the commit objects. --t:: - Get trees associated with the commit objects. --a:: - Get all the objects. --v:: - Report what is downloaded. --w:: - Writes the commit-id into the filename under $GIT_DIR/refs/ on - the local end after the transfer is complete. - - -Author ------- -Written by Daniel Barkalow <barkalow@iabervon.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git-ssh-upload.txt b/Documentation/git-ssh-upload.txt deleted file mode 100644 index 5e2ca8dcc..000000000 --- a/Documentation/git-ssh-upload.txt +++ /dev/null @@ -1,48 +0,0 @@ -git-ssh-upload(1) -================= - -NAME ----- -git-ssh-upload - Push to a remote repository over ssh connection - - -SYNOPSIS --------- -'git-ssh-upload' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url - -DESCRIPTION ------------ -THIS COMMAND IS DEPRECATED. - -Pushes from a remote repository over ssh connection, invoking -git-ssh-fetch on the other end. It functions identically to -git-ssh-fetch, aside from which end you run it on. - -OPTIONS -------- -commit-id:: - Id of commit to push. - --c:: - Get the commit objects. --t:: - Get tree associated with the requested commit object. --a:: - Get all the objects. --v:: - Report what is uploaded. --w:: - Writes the commit-id into the filename under [URL]/refs/ on - the remote end after the transfer is complete. - -Author ------- -Written by Daniel Barkalow <barkalow@iabervon.org> - -Documentation --------------- -Documentation by Daniel Barkalow - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 5723bb06f..9889806a5 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -57,7 +57,7 @@ stash@{1}: On master: 9cc0589... Add git-stash show [<stash>]:: - Show the changes recorded in the stash as a diff between the the + 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 @@ -156,10 +156,10 @@ $ git stash apply SEE ALSO -------- -gitlink:git-checkout[1], -gitlink:git-commit[1], -gitlink:git-reflog[1], -gitlink:git-reset[1] +linkgit:git-checkout[1], +linkgit:git-commit[1], +linkgit:git-reflog[1], +linkgit:git-reset[1] AUTHOR ------ @@ -167,4 +167,4 @@ Written by Nanako Shiraishi <nanako3@bluebottle.com> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 8fd0fc623..3ea269aa7 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -12,33 +12,32 @@ SYNOPSIS DESCRIPTION ----------- -Examines paths in the working tree that has changes unrecorded -to the index file, and changes between the index file and the -current HEAD commit. The former paths are what you _could_ -commit by running 'git add' before running 'git -commit', and the latter paths are what you _would_ commit by -running 'git commit'. - -If there is no path that is different between the index file and -the current HEAD commit, the command exits with non-zero -status. +Displays paths that have differences between the index file and the +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 +`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 any paths have been touched in the working tree (that is, -their modification times have changed) but their contents and -permissions are identical to those in the index file, the command -updates the index file. Running `git-status` can thus speed up -subsequent operations such as `git-diff` if the working tree -contains many paths that have been touched but not modified. +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. OUTPUT ------ The output from this command is designed to be used as a commit -template comments, and all the output lines are prefixed with '#'. +template comment, and all the output lines are prefixed with '#'. + +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. CONFIGURATION @@ -49,9 +48,13 @@ mean the same thing and the latter is kept for backward compatibility) and `color.status.<slot>` configuration variables to colorize its output. +If the config variable `status.relativePaths` is set to false, then all +paths shown are relative to the repository root, not to the current +directory. + See Also -------- -gitlink:gitignore[5] +linkgit:gitignore[5] Author ------ @@ -64,4 +67,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index f80526ba7..fc5687502 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -32,4 +32,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c48936fc..cffc6d48f 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -21,11 +21,14 @@ add:: repository is cloned at the specified path, 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. 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 gitlink:git-describe[1] for the + submodule path and the output of linkgit:git-describe[1] 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 does not match the SHA-1 found in the index of the containing @@ -64,8 +67,9 @@ FILES ----- When initializing submodules, a .gitmodules file in the top-level directory of the containing repository is used to find the url of each submodule. -This file should be formatted in the same way as $GIR_DIR/config. The key -to each submodule url is "submodule.$name.url". +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 @@ -74,4 +78,4 @@ Written by Lars Hjemli <hjemli@gmail.com> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index e157c6ab5..e1a1d46a9 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -12,7 +12,7 @@ SYNOPSIS DESCRIPTION ----------- git-svn is a simple conduit for changesets between Subversion and git. -It is not to be confused with gitlink:git-svnimport[1], which is +It is not to be confused with linkgit:git-svnimport[1], which is read-only. git-svn was originally designed for an individual developer who wants a @@ -193,6 +193,12 @@ Any other arguments are passed directly to `git log' repository (that has been init-ed with git-svn). The -r<revision> option is required for this. +'info':: + Shows information about a file or directory similar to what + `svn info' provides. Does not currently support a -r/--revision + argument. Use the --url option to output only the value of the + 'URL:' field. + -- OPTIONS @@ -202,7 +208,7 @@ OPTIONS --shared[={false|true|umask|group|all|world|everybody}]:: --template=<template_directory>:: Only used with the 'init' command. - These are passed directly to gitlink:git-init[1]. + These are passed directly to linkgit:git-init[1]. -r <ARG>:: --revision <ARG>:: @@ -255,7 +261,7 @@ config key: svn.edit Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. They are both passed directly to git-diff-tree see -gitlink:git-diff-tree[1] for more information. +linkgit:git-diff-tree[1] for more information. [verse] config key: svn.l @@ -293,7 +299,7 @@ with many revisions. to fetch before repacking. This defaults to repacking every 1000 commits fetched if no argument is specified. ---repack-flags are passed directly to gitlink:git-repack[1]. +--repack-flags are passed directly to linkgit:git-repack[1]. [verse] config key: svn.repack @@ -404,7 +410,7 @@ section because they affect the 'git-svn-id:' metadata line. BASIC EXAMPLES -------------- -Tracking and contributing to a the trunk of a Subversion-managed project: +Tracking and contributing to the trunk of a Subversion-managed project: ------------------------------------------------------------------------ # Clone a repo (like git clone): @@ -555,11 +561,11 @@ however the remote wildcard may be anywhere as long as it's own 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 -gitlink:git-config[1] +linkgit:git-config[1] SEE ALSO -------- -gitlink:git-rebase[1] +linkgit:git-rebase[1] Author ------ diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt deleted file mode 100644 index 71aad8b45..000000000 --- a/Documentation/git-svnimport.txt +++ /dev/null @@ -1,179 +0,0 @@ -git-svnimport(1) -================ -v0.1, July 2005 - -NAME ----- -git-svnimport - Import a SVN repository into git - - -SYNOPSIS --------- -[verse] -'git-svnimport' [ -o <branch-for-HEAD> ] [ -h ] [ -v ] [ -d | -D ] - [ -C <GIT_repository> ] [ -i ] [ -u ] [-l limit_rev] - [ -b branch_subdir ] [ -T trunk_subdir ] [ -t tag_subdir ] - [ -s start_chg ] [ -m ] [ -r ] [ -M regex ] - [ -I <ignorefile_name> ] [ -A <author_file> ] - [ -R <repack_each_revs>] [ -P <path_from_trunk> ] - <SVN_repository_URL> [ <path> ] - - -DESCRIPTION ------------ -Imports a SVN repository into git. It will either create a new -repository, or incrementally import into an existing one. - -SVN access is done by the SVN::Perl module. - -git-svnimport assumes that SVN repositories are organized into one -"trunk" directory where the main development happens, "branches/FOO" -directories for branches, and "/tags/FOO" directories for tags. -Other subdirectories are ignored. - -git-svnimport creates a file ".git/svn2git", which is required for -incremental SVN imports. - -OPTIONS -------- --C <target-dir>:: - The GIT repository to import to. If the directory doesn't - exist, it will be created. Default is the current directory. - --s <start_rev>:: - Start importing at this SVN change number. The default is 1. -+ -When importing incrementally, you might need to edit the .git/svn2git file. - --i:: - Import-only: don't perform a checkout after importing. This option - ensures the working directory and index remain untouched and will - not create them if they do not exist. - --T <trunk_subdir>:: - Name the SVN trunk. Default "trunk". - --t <tag_subdir>:: - Name the SVN subdirectory for tags. Default "tags". - --b <branch_subdir>:: - Name the SVN subdirectory for branches. Default "branches". - --o <branch-for-HEAD>:: - The 'trunk' branch from SVN is imported to the 'origin' branch within - the git repository. Use this option if you want to import into a - different branch. - --r:: - Prepend 'rX: ' to commit messages, where X is the imported - subversion revision. - --u:: - Replace underscores in tag names with periods. - --I <ignorefile_name>:: - Import the svn:ignore directory property to files with this - name in each directory. (The Subversion and GIT ignore - syntaxes are similar enough that using the Subversion patterns - directly with "-I .gitignore" will almost always just work.) - --A <author_file>:: - Read a file with lines on the form -+ ------- - username = User's Full Name <email@addr.es> - ------- -+ -and use "User's Full Name <email@addr.es>" as the GIT -author and committer for Subversion commits made by -"username". If encountering a commit made by a user not in the -list, abort. -+ -For convenience, this data is saved to $GIT_DIR/svn-authors -each time the -A option is provided, and read from that same -file each time git-svnimport is run with an existing GIT -repository without -A. - --m:: - Attempt to detect merges based on the commit message. This option - will enable default regexes that try to capture the name source - branch name from the commit message. - --M <regex>:: - Attempt to detect merges based on the commit message with a custom - regex. It can be used with -m to also see the default regexes. - You must escape forward slashes. - --l <max_rev>:: - Specify a maximum revision number to pull. -+ -Formerly, this option controlled how many revisions to pull, -due to SVN memory leaks. (These have been worked around.) - --R <repack_each_revs>:: - Specify how often git repository should be repacked. -+ -The default value is 1000. git-svnimport will do import in chunks of 1000 -revisions, after each chunk git repository will be repacked. To disable -this behavior specify some big value here which is mote than number of -revisions to import. - --P <path_from_trunk>:: - Partial import of the SVN tree. -+ -By default, the whole tree on the SVN trunk (/trunk) is imported. -'-P my/proj' will import starting only from '/trunk/my/proj'. -This option is useful when you want to import one project from a -svn repo which hosts multiple projects under the same trunk. - --v:: - Verbosity: let 'svnimport' report what it is doing. - --d:: - Use direct HTTP requests if possible. The "<path>" argument is used - only for retrieving the SVN logs; the path to the contents is - included in the SVN log. - --D:: - Use direct HTTP requests if possible. The "<path>" argument is used - for retrieving the logs, as well as for the contents. -+ -There's no safe way to automatically find out which of these options to -use, so you need to try both. Usually, the one that's wrong will die -with a 40x error pretty quickly. - -<SVN_repository_URL>:: - The URL of the SVN module you want to import. For local - repositories, use "file:///absolute/path". -+ -If you're using the "-d" or "-D" option, this is the URL of the SVN -repository itself; it usually ends in "/svn". - -<path>:: - The path to the module you want to check out. - --h:: - Print a short usage message and exit. - -OUTPUT ------- -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 ------- -Written by Matthias Urlichs <smurf@smurf.noris.de>, with help from -various participants of the git-list <git@vger.kernel.org>. - -Based on a cvs2git script by the same author. - -Documentation --------------- -Documentation by Matthias Urlichs <smurf@smurf.noris.de>. - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index a88f72286..a5b40f3e8 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -26,7 +26,7 @@ a regular file whose contents is `ref: refs/heads/master`. OPTIONS ------- --q:: +-q, --quiet:: Do not issue an error message if the <name> is not a symbolic ref but a detached HEAD; instead exit with non-zero status silently. @@ -58,4 +58,4 @@ Written by Junio C Hamano <junkio@cox.net> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 990ae4f94..b62a3d1c5 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -65,7 +65,9 @@ OPTIONS Typing "git tag" without arguments, also lists all tags. -m <msg>:: - Use the given tag message (instead of prompting) + Use the given tag message (instead of prompting). + If multiple `-m` options are given, there values are + concatenated as separate paragraphs. -F <file>:: Take the tag message from the given file. Use '-' to @@ -112,7 +114,7 @@ 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" again, as if you hadn't already published the old one. -However, Git does *not* (and it should not)change tags behind +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 one. @@ -214,6 +216,27 @@ having tracking branches. Again, the heuristic to automatically follow such tags is a good thing. +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 +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_AUTHOR_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". + +An example follows. + +------------ +$ GIT_AUTHOR_DATE="2006-10-02 10:31" git tag -s v1.0.1 +------------ + + Author ------ Written by Linus Torvalds <torvalds@osdl.org>, @@ -225,4 +248,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 434607bfb..65c68176e 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -86,4 +86,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt index 10653ff89..a96403cb8 100644 --- a/Documentation/git-tools.txt +++ b/Documentation/git-tools.txt @@ -22,6 +22,9 @@ Alternative/Augmentative Porcelains providing generally smoother user experience than the "raw" Core GIT itself and indeed many other version control systems. + Cogito is no longer maintained as most of its functionality + is now in core GIT. + - *pg* (http://www.spearce.org/category/projects/scm/pg/) @@ -33,7 +36,7 @@ Alternative/Augmentative Porcelains - *StGit* (http://www.procode.org/stgit/) Stacked GIT provides a quilt-like patch management functionality in the - GIT environment. You can easily manage your patches in the scope of GIT + GIT environment. You can easily manage your patches in the scope of GIT until they get merged upstream. diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt index 20bb6a780..1864d13ed 100644 --- a/Documentation/git-unpack-file.txt +++ b/Documentation/git-unpack-file.txt @@ -32,4 +32,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index d529a43f5..b79be3fd4 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -51,4 +51,4 @@ Documentation by Junio C Hamano GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 0a1953803..66be18ef3 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -27,7 +27,7 @@ Modifies the index or directory cache. Each file mentioned is updated into the index and any 'unmerged' or 'needs updating' state is cleared. -See also gitlink:git-add[1] for a more user-friendly way to do some of +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 @@ -292,14 +292,14 @@ Configuration The command honors `core.filemode` configuration variable. If your repository is on an filesystem whose executable bits are -unreliable, this should be set to 'false' (see gitlink:git-config[1]). +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=`. Quite similarly, if `core.symlinks` configuration variable is set -to 'false' (see gitlink:git-config[1]), symbolic links are checked out +to 'false' (see linkgit:git-config[1]), symbolic links are checked out as plain files, and this command does not modify a recorded file mode from symbolic link to regular file. @@ -309,8 +309,8 @@ The command looks at `core.ignorestat` configuration variable. See See Also -------- -gitlink:git-config[1], -gitlink:git-add[1] +linkgit:git-config[1], +linkgit:git-add[1] Author @@ -323,4 +323,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index f22261659..4dc475992 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -90,4 +90,4 @@ Written by Linus Torvalds <torvalds@osdl.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index e7e82a31e..1cf89fd79 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -54,4 +54,4 @@ Documentation by Junio C Hamano. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt index 403871d7c..c1ef1440b 100644 --- a/Documentation/git-upload-archive.txt +++ b/Documentation/git-upload-archive.txt @@ -34,4 +34,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index fd6519299..2330d1381 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -43,4 +43,4 @@ Documentation by Junio C Hamano. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 813942368..298028390 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -47,9 +47,9 @@ Your sysadmin must hate you!:: See Also -------- -gitlink:git-commit-tree[1] -gitlink:git-tag[1] -gitlink:git-config[1] +linkgit:git-commit-tree[1] +linkgit:git-tag[1] +linkgit:git-config[1] Author ------ @@ -61,4 +61,4 @@ Documentation by Eric Biederman and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index f4c540f39..db019a2b8 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -50,4 +50,4 @@ Documentation by Junio C Hamano GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index ac7fb1915..7e9c1ed15 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -28,4 +28,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 607df48f0..54947b676 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -77,4 +77,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index cb8d6aade..461c813f5 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -46,4 +46,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index a7cd91acc..4ece40d1e 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -28,7 +28,7 @@ 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 -as defined in the configuration file (see gitlink:git-config[1]). +as defined in the configuration file (see linkgit:git-config[1]). Formatted and hyperlinked version of the latest git documentation can be viewed at @@ -43,10 +43,18 @@ 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.3/git.html[documentation for release 1.5.3] +* link:v1.5.3.8/git.html[documentation for release 1.5.3.8] * release notes for - link:RelNotes-1.5.3.1.txt[1.5.3.1]. + 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]. * release notes for link:RelNotes-1.5.2.5.txt[1.5.2.5], @@ -94,9 +102,14 @@ OPTIONS --help:: Prints the synopsis and a list of the most commonly used - commands. If a git command is named this option will bring up - the man-page for that command. If the option '--all' or '-a' is - given then all available commands are printed. + commands. If the option '--all' or '-a' is given then all + available commands are printed. If a git command is named this + option will bring up the manual page for that command. ++ +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 ...'. --exec-path:: Path to wherever your core git programs are installed. @@ -141,6 +154,8 @@ introductions to the underlying git architecture. See also the link:howto-index.html[howto] documents for some useful examples. +The internals are documented link:technical/api-index.html[here]. + GIT COMMANDS ------------ @@ -184,8 +199,8 @@ Low-level commands (plumbing) Although git includes its own porcelain layer, its low-level commands are sufficient to support development of alternative porcelains. Developers of such porcelains -might start by reading about gitlink:git-update-index[1] and -gitlink:git-read-tree[1]. +might start by reading about linkgit:git-update-index[1] and +linkgit:git-read-tree[1]. The interface (input, output, set of options and the semantics) to these low-level commands are meant to be a lot more stable @@ -317,13 +332,13 @@ HEAD:: (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). For a more complete list of ways to spell object names, see -"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. +"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. File/Directory Structure ------------------------ -Please see link:repository-layout.html[repository layout] document. +Please see the link:repository-layout.html[repository layout] document. Read link:hooks.html[hooks] for more details about each hook. @@ -333,7 +348,7 @@ Higher level SCMs may provide and manage additional information in the Terminology ----------- -Please see link:glossary.html[glossary] document. +Please see the link:glossary.html[glossary] document. Environment Variables @@ -385,7 +400,7 @@ git Commits 'GIT_COMMITTER_EMAIL':: 'GIT_COMMITTER_DATE':: 'EMAIL':: - see gitlink:git-commit-tree[1] + see linkgit:git-commit-tree[1] git Diffs ~~~~~~~~~ @@ -425,7 +440,7 @@ other 'GIT_MERGE_VERBOSITY':: A number controlling the amount of output shown by the recursive merge strategy. Overrides merge.verbosity. - See gitlink:git-merge[1] + See linkgit:git-merge[1] 'GIT_PAGER':: This environment variable overrides `$PAGER`. If it is set @@ -433,8 +448,8 @@ other a pager. 'GIT_SSH':: - If this environment variable is set then gitlink:git-fetch[1] - and gitlink:git-push[1] will use this command instead + 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: the 'username@host' (or just 'host') from the URL and the @@ -488,7 +503,7 @@ as tags and branch heads. The object database contains objects of three main types: blobs, which hold file data; trees, which point to blobs and other trees to build up -directory heirarchies; and commits, which each reference a single tree +directory hierarchies; and commits, which each reference a single tree and some number of parent commits. The commit, equivalent to what other systems call a "changeset" or @@ -508,7 +523,7 @@ efficiency may later be compressed together into "pack files". Named pointers called refs mark interesting points in history. A ref may contain the SHA1 name of an object or the name of another ref. Refs with names beginning `ref/head/` contain the SHA1 name of the most -recent commit (or "head") of a branch under developement. SHA1 names of +recent commit (or "head") of a branch under development. SHA1 names of tags of interest are stored under `ref/tags/`. A special ref named `HEAD` contains the name of the currently checked-out branch. @@ -529,7 +544,7 @@ 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 Andres Ericsson <ae@op5.se>. +* The git potty was written by Andreas Ericsson <ae@op5.se>. * General upbringing is handled by the git-list <git@vger.kernel.org>. Documentation @@ -540,4 +555,4 @@ contributors on the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index cf4ee2ebe..35a29fd60 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -238,7 +238,7 @@ When git needs to show you a diff for the path with `diff` attribute set to `jcdiff`, it calls the command you specified with the above configuration, i.e. `j-c-diff`, with 7 parameters, just like `GIT_EXTERNAL_DIFF` program is called. -See gitlink:git[7] for details. +See linkgit:git[7] for details. Defining a custom hunk-header @@ -322,12 +322,43 @@ String:: requested with "binary". +Built-in merge drivers +^^^^^^^^^^^^^^^^^^^^^^ + +There are a few built-in low-level merge drivers defined that +can be asked for via the `merge` attribute. + +text:: + + Usual 3-way file level merge for text files. Conflicted + regions are marked with conflict markers `<<<<<<<`, + `=======` and `>>>>>>>`. The version from your branch + appears before the `=======` marker, and the version + from the merged branch appears after the `=======` + marker. + +binary:: + + Keep the version from your branch in the work tree, but + leave the path in the conflicted state for the user to + sort out. + +union:: + + Run 3-way file level merge for text files, but take + lines from both versions, instead of leaving conflict + markers. This tends to leave the added lines in the + resulting file in random order and the user should + verify the result. Do not use this if you do not + understand the implications. + + Defining a custom merge driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The definition of a merge driver is done in `gitconfig` not -`gitattributes` file, so strictly speaking this manual page is a -wrong place to talk about it. However... +The definition of a merge driver is done in the `.git/config` +file, not in the `gitattributes` file, so strictly speaking this +manual page is a wrong place to talk about it. However... To define a custom merge driver `filfre`, add a section to your `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: @@ -361,6 +392,37 @@ When left unspecified, the driver itself is used for both internal merge and the final merge. +Checking whitespace errors +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`whitespace` +^^^^^^^^^^^^ + +The `core.whitespace` configuration variable allows you to define what +`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. + +Unset:: + + Do not notice anything as error. + +Unspecified:: + + Use the value of `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 + variable. + + EXAMPLE ------- @@ -410,6 +472,23 @@ 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. + + GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt new file mode 100644 index 000000000..7ee5ce386 --- /dev/null +++ b/Documentation/gitcli.txt @@ -0,0 +1,113 @@ +gitcli(5) +========= + +NAME +---- +gitcli - git command line interface and conventions + +SYNOPSIS +-------- +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: + + * it's preferred to use the non dashed form of git commands, which means that + 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). + + * 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"` + 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 + if you happen to have a file called `HEAD` in the work tree. + + +ENHANCED CLI +------------ +From the git 1.5.4 series and further, many git commands (not all of them at the +time of the writing though) come with an enhanced option parser. + +Here is an exhaustive list of the facilities provided by this option parser. + + +Magic Options +~~~~~~~~~~~~~ +Commands which have the enhanced option parser activated all understand a +couple of magic command line options: + +-h:: + gives a pretty printed usage of the command. ++ +--------------------------------------------- +$ git describe -h +usage: git-describe [options] <committish>* + + --contains find the tag that comes after the commit + --debug debug search strategy on stderr + --all use any ref in .git/refs + --tags use any tag in .git/refs/tags + --abbrev [<n>] use <n> digits to display SHA-1s + --candidates <n> consider <n> most recent tags (default: 10) +--------------------------------------------- + +--help-all:: + Some git commands take options that are only used for plumbing or that + are deprecated, and such options are hidden from the default usage. This + option gives the full list of options. + + +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"`. + + +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"`. + + +Separating argument from the option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can write the mandatory option parameter to an option as a separate +word on the command line. That means that all the following uses work: + +---------------------------- +$ git foo --long-opt=Arg +$ git foo --long-opt Arg +$ git foo -oArg +$ git foo -o Arg +---------------------------- + +However, this is *NOT* allowed for switches with an optional value, where the +'sticked' form must be used: +---------------------------- +$ git describe --abbrev HEAD # correct +$ git describe --abbrev=10 HEAD # correct +$ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT +---------------------------- + + +Documentation +------------- +Documentation by Pierre Habouzit. + +GIT +--- +Part of the linkgit:git[7] suite diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index e8b8581f5..08373f52b 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -39,10 +39,10 @@ precedence, the last matching pattern decides the outcome): variable 'core.excludesfile'. The underlying git plumbing tools, such as -gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read +linkgit:git-ls-files[1] and linkgit:git-read-tree[1], read `gitignore` patterns specified by command-line options, or from files specified by command-line options. Higher-level git -tools, such as gitlink:git-status[1] and gitlink:git-add[1], +tools, such as linkgit:git-status[1] and linkgit:git-add[1], use patterns from the sources specified above. Patterns have the following format: @@ -119,4 +119,4 @@ Frank Lichtenheld, and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 8dbfb0d5a..29edafced 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -22,7 +22,7 @@ git repository. OPTIONS ------- To control which revisions to shown, the command takes options applicable to -the gitlink:git-rev-list[1] command. This manual page describes only the most +the linkgit:git-rev-list[1] command. This manual page describes only the most frequently used options. -n <number>, --max-count=<number>:: @@ -48,7 +48,7 @@ frequently used options. the form "'<from>'..'<to>'" to show all revisions between '<from>' and back to '<to>'. Note, more advanced revision selection can be applied. For a more complete list of ways to spell object names, see - "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. + "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. <path>:: @@ -98,4 +98,4 @@ Documentation by Junio C Hamano, Jonas Fonseca, and the git-list GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 035294e20..cc95b69f2 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -15,7 +15,7 @@ DESCRIPTION The `.gitmodules` file, located in the top-level directory of a git working tree, is a text file with a syntax matching the requirements -of gitlink:git-config[1]. +of linkgit:git-config[1]. The file contains one subsection per submodule, and the subsection value is the name of the submodule. Each submodule section also contains the @@ -51,7 +51,7 @@ submodules an url is specified which can be used for cloning the submodules. SEE ALSO -------- -gitlink:git-submodule[1] gitlink:git-config[1] +linkgit:git-submodule[1] linkgit:git-config[1] DOCUMENTATION ------------- @@ -59,4 +59,4 @@ Documentation by Lars Hjemli <hjemli@gmail.com> GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index 3f7b1e42b..ab4caf4e2 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -52,8 +52,8 @@ GIT Glossary [[def_cherry-picking]]cherry-picking:: In <<def_SCM,SCM>> jargon, "cherry pick" means to choose a subset of changes out of a series of changes (typically commits) and record them - as a new series of changes on top of different codebase. In GIT, this is - performed by "git cherry-pick" command to extract the change introduced + as a new series of changes on top of a different codebase. In GIT, this is + performed by the "git cherry-pick" command to extract the change introduced by an existing <<def_commit,commit>> and to record it based on the tip of the current <<def_branch,branch>> as a new commit. @@ -140,7 +140,7 @@ to point at the new commit. branch's <<def_head_ref,head ref>> from a remote <<def_repository,repository>>, to find out which objects are missing from the local <<def_object_database,object database>>, - and to get them, too. See also gitlink:git-fetch[1]. + and to get them, too. See also linkgit:git-fetch[1]. [[def_file_system]]file system:: Linus Torvalds originally designed git to be a user space file system, @@ -164,7 +164,7 @@ to point at the new commit. 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 - gitlink:git-pack-refs[1].) + linkgit:git-pack-refs[1].) [[def_HEAD]]HEAD:: The current <<def_branch,branch>>. In more detail: Your <<def_working_tree, @@ -244,8 +244,7 @@ This commit is referred to as a "merge commit", or sometimes just a The unique identifier of an <<def_object,object>>. The <<def_hash,hash>> of the object's contents using the Secure Hash Algorithm 1 and usually represented by the 40 character hexadecimal encoding of - the <<def_hash,hash>> of the object (possibly followed by - a white space). + the <<def_hash,hash>> of the object. [[def_object_type]]object type:: One of the identifiers @@ -281,9 +280,9 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_pickaxe]]pickaxe:: The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore routines that help select changes that add or delete a given text - string. With the --pickaxe-all option, it can be used to view the full + string. With the `--pickaxe-all` option, it can be used to view the full <<def_changeset,changeset>> that introduced or removed, say, a - particular line of text. See gitlink:git-diff[1]. + particular line of text. See linkgit:git-diff[1]. [[def_plumbing]]plumbing:: Cute name for <<def_core_git,core git>>. @@ -296,13 +295,13 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_pull]]pull:: Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and - <<def_merge,merge>> it. See also gitlink:git-pull[1]. + <<def_merge,merge>> it. See also linkgit:git-pull[1]. [[def_push]]push:: Pushing a <<def_branch,branch>> means to get the branch's <<def_head_ref,head ref>> from a remote <<def_repository,repository>>, - find out if it is an ancestor to the branch's local - head ref is a direct, and in that case, putting all + find out if it is a direct ancestor to the branch's local + head ref, and in that case, putting all objects, which are <<def_reachable,reachable>> from the local head ref, and which are missing from the remote repository, into the remote @@ -334,7 +333,7 @@ This commit is referred to as a "merge commit", or sometimes just a A reflog shows the local "history" of a ref. In other words, it can tell you what the 3rd last revision in _this_ repository was, and what was the current state in _this_ repository, - yesterday 9:14pm. See gitlink:git-reflog[1] for details. + yesterday 9:14pm. See linkgit:git-reflog[1] for details. [[def_refspec]]refspec:: A "refspec" is used by <<def_fetch,fetch>> and @@ -347,7 +346,7 @@ This commit is referred to as a "merge commit", or sometimes just a it as my origin branch head". And `git push $URL refs/heads/master:refs/heads/to-upstream` means "publish my master branch head as to-upstream branch at $URL". See also - gitlink:git-push[1] + linkgit:git-push[1]. [[def_repository]]repository:: A collection of <<def_ref,refs>> together with an @@ -384,15 +383,15 @@ This commit is referred to as a "merge commit", or sometimes just a object>>). This is sometimes useful when you are interested only in the recent history of a project even though the real history recorded in the upstream is much larger. A shallow repository - is created by giving the `--depth` option to gitlink:git-clone[1], and - its history can be later deepened with gitlink:git-fetch[1]. + is created by giving the `--depth` option to linkgit:git-clone[1], and + its history can be later deepened with linkgit:git-fetch[1]. [[def_symref]]symref:: Symbolic reference: instead of containing the <<def_SHA1,SHA1>> id itself, it is of the format 'ref: refs/some/thing' and when referenced, it recursively dereferences to this reference. '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic - references are manipulated with the gitlink:git-symbolic-ref[1] + references are manipulated with the linkgit:git-symbolic-ref[1] command. [[def_tag]]tag:: diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index c39edc57c..f110162b0 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -87,6 +87,33 @@ parameter, and is invoked after a commit is made. This hook is meant primarily for notification, and cannot affect the outcome of `git-commit`. +post-checkout +----------- + +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 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` +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`. + +This hook can be used in conjunction with a corresponding pre-commit hook to +save and restore any form of metadata associated with the working tree +(eg: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl +for an example of how to do this. + [[pre-receive]] pre-receive ----------- diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt new file mode 100644 index 000000000..4357e2691 --- /dev/null +++ b/Documentation/howto/maintain-git.txt @@ -0,0 +1,277 @@ +From: Junio C Hamano <gitster@pobox.com> +Date: Wed, 21 Nov 2007 16:32:55 -0800 +Subject: Addendum to "MaintNotes" +Abstract: Imagine that git development is racing along as usual, when our friendly + neighborhood maintainer is struck down by a wayward bus. Out of the + hordes of suckers (loyal developers), you have been tricked (chosen) to + step up as the new maintainer. This howto will show you "how to" do it. + +The maintainer's git time is spent on three activities. + + - Communication (60%) + + Mailing list discussions on general design, fielding user + questions, diagnosing bug reports; reviewing, commenting on, + suggesting alternatives to, and rejecting patches. + + - Integration (30%) + + Applying new patches from the contributors while spotting and + correcting minor mistakes, shuffling the integration and + testing branches, pushing the results out, cutting the + releases, and making announcements. + + - Own development (10%) + + Scratching my own itch and sending proposed patch series out. + +The policy on Integration is informally mentioned in "A Note +from the maintainer" message, which is periodically posted to +this mailing list after each feature release is made. + +The policy. + + - Feature releases are numbered as vX.Y.Z and are meant to + contain bugfixes and enhancements in any area, including + functionality, performance and usability, without regression. + + - Maintenance releases are numbered as vX.Y.Z.W and are meant + to contain only bugfixes for the corresponding vX.Y.Z feature + release and earlier maintenance releases vX.Y.Z.V (V < W). + + - 'master' branch is used to prepare for the next feature + release. In other words, at some point, the tip of 'master' + branch is tagged with vX.Y.Z. + + - 'maint' branch is used to prepare for the next maintenance + release. After the feature release vX.Y.Z is made, the tip + of 'maint' branch is set to that release, and bugfixes will + accumulate on the branch, and at some point, the tip of the + branch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on. + + - 'next' branch is used to publish changes (both enhancements + and fixes) that (1) have worthwhile goal, (2) are in a fairly + good shape suitable for everyday use, (3) but have not yet + demonstrated to be regression free. New changes are tested + in 'next' before merged to 'master'. + + - 'pu' branch is used to publish other proposed changes that do + 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 + customization on top of them. + + - Usually 'master' contains all of 'maint', 'next' contains all + of 'master' and 'pu' contains all of 'next'. + + - The tip of 'master' is meant to be more stable than any + tagged releases, and the users are encouraged to follow it. + + - The 'next' branch is where new action takes place, and the + users are encouraged to test it so that regressions and bugs + are found before new topics are merged to 'master'. + + +A typical git day for the maintainer implements the above policy +by doing the following: + + - Scan mailing list and #git channel log. Respond with review + comments, suggestions etc. Kibitz. Collect potentially + usable patches from the mailing list. Patches about a single + topic go to one mailbox (I read my mail in Gnus, and type + \C-o to save/append messages in files in mbox format). + + - Review the patches in the saved mailboxes. Edit proposed log + message for typofixes and clarifications, and add Acks + collected from the list. Edit patch to incorporate "Oops, + that should have been like this" fixes from the discussion. + + - Classify the collected patches and handle 'master' and + 'maint' updates: + + - Obviously correct fixes that pertain to the tip of 'maint' + are directly applied to 'maint'. + + - Obviously correct fixes that pertain to the tip of 'master' + are directly applied to 'master'. + + This step is done with "git am". + + $ git checkout master ;# or "git checkout maint" + $ git am -3 -s mailbox + $ make test + + - Merge downwards (maint->master): + + $ git checkout master + $ git merge maint + $ make test + + - Review the last issue of "What's cooking" message, review the + topics scheduled for merging upwards (topic->master and + topic->maint), and merge. + + $ git checkout master ;# or "git checkout maint" + $ git merge ai/topic ;# or "git merge ai/maint-topic" + $ git log -p ORIG_HEAD.. ;# final review + $ git diff ORIG_HEAD.. ;# final review + $ make test ;# final review + $ git branch -d ai/topic ;# or "git branch -d ai/maint-topic" + + - Merge downwards (maint->master) if needed: + + $ git checkout master + $ git merge maint + $ make test + + - Merge downwards (master->next) if needed: + + $ git checkout next + $ git merge master + $ make test + + - Handle the remaining patches: + + - Anything unobvious that is applicable to 'master' (in other + words, does not depend on anything that is still in 'next' + and not in 'master') is applied to a new topic branch that + is forked from the tip of 'master'. This includes both + enhancements and unobvious fixes to 'master'. A topic + branch is named as ai/topic where "ai" is typically + author's initial and "topic" is a descriptive name of the + topic (in other words, "what's the series is about"). + + - An unobvious fix meant for 'maint' is applied to a new + topic branch that is forked from the tip of 'maint'. The + topic is named as ai/maint-topic. + + - Changes that pertain to an existing topic are applied to + the branch, but: + + - obviously correct ones are applied first; + + - questionable ones are discarded or applied to near the tip; + + - Replacement patches to an existing topic are accepted only + for commits not in 'next'. + + The above except the "replacement" are all done with: + + $ git am -3 -s mailbox + + while patch replacement is often done by: + + $ git format-patch ai/topic~$n..ai/topic ;# export existing + + then replace some parts with the new patch, and reapplying: + + $ git reset --hard ai/topic~$n + $ git am -3 -s 000*.txt + + The full test suite is always run for 'maint' and 'master' + after patch application; for topic branches the tests are run + as time permits. + + - 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 + a checkout of the 'todo' branch). + + - Merge topics to 'next'. For each branch whose tip is not + merged to 'next', one of three things can happen: + + - The commits are all next-worthy; merge the topic to next: + + $ git checkout next + $ git merge ai/topic ;# or "git merge ai/maint-topic" + $ make test + + - The new parts are of mixed quality, but earlier ones are + next-worthy; merge the early parts to next: + + $ git checkout next + $ git merge ai/topic~2 ;# the tip two are dubious + $ make test + + - 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. + + $ git rebase master ai/topic + + This step is helped with Meta/git-topic.perl script to + identify which topic is rebaseable. There also is a + 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'. + + $ git checkout pu + $ git reset --hard next + $ git merge ai/topic ;# repeat for all remaining topics + $ make test + + This step is helped with Meta/PU script + + - Push four integration branches to a private repository at + k.org and run "make test" on all of them. + + - Push four integration branches to /pub/scm/git/git.git at + k.org. This triggers its post-update hook which: + + (1) runs "git pull" in $HOME/git-doc/ repository to pull + 'master' just pushed out; + + (2) runs "make doc" in $HOME/git-doc/, install the generated + documentation in staging areas, which are separate + repositories that have html and man branches checked + out. + + (3) runs "git commit" in the staging areas, and run "git + push" back to /pub/scm/git/git.git/ to update the html + and man branches. + + (4) installs generated documentation to /pub/software/scm/git/docs/ + to be viewed from http://www.kernel.org/ + + - Fetch html and man branches back from k.org, and push four + integration branches and the two documentation branches to + repo.or.cz + + +Some observations to be made. + + * Each topic is tested individually, and also together with + other topics cooking in 'next'. Until it matures, none part + of it is merged to 'master'. + + * A topic already in 'next' can get fixes while still in + 'next'. Such a topic will have many merges to 'next' (in + other words, "git log --first-parent next" will show many + "Merge ai/topic to next" for the same topic. + + * An unobvious fix for 'maint' is cooked in 'next' and then + merged to 'master' to make extra sure it is Ok and then + merged to 'maint'. + + * Even when 'next' becomes empty (in other words, all topics + prove stable and are merged to 'master' and "git diff master + next" shows empty), it has tons of merge commits that will + never be in 'master'. + + * In principle, "git log --first-parent master..next" should + show nothing but merges (in practice, there are fixup commits + and reverts that are not merges). + + * Commits near the tip of a topic branch that are not in 'next' + are fair game to be discarded, replaced or rewritten. + Commits already merged to 'next' will not be. + + * Being in the 'next' branch is not a guarantee for a topic to + be included in the next feature release. Being in the + 'master' branch typically is. diff --git a/Documentation/howto/recover-corrupted-blob-object.txt b/Documentation/howto/recover-corrupted-blob-object.txt new file mode 100644 index 000000000..323b513ed --- /dev/null +++ b/Documentation/howto/recover-corrupted-blob-object.txt @@ -0,0 +1,134 @@ +Date: Fri, 9 Nov 2007 08:28:38 -0800 (PST) +From: Linus Torvalds <torvalds@linux-foundation.org> +Subject: corrupt object on git-gc +Abstract: Some tricks to reconstruct blob objects in order to fix + a corrupted repository. + +On Fri, 9 Nov 2007, Yossi Leybovich wrote: +> +> Did not help still the repository look for this object? +> Any one know how can I track this object and understand which file is it + +So exactly *because* the SHA1 hash is cryptographically secure, the hash +itself doesn't actually tell you anything, in order to fix a corrupt +object you basically have to find the "original source" for it. + +The easiest way to do that is almost always to have backups, and find the +same object somewhere else. Backups really are a good idea, and git makes +it pretty easy (if nothing else, just clone the repository somewhere else, +and make sure that you do *not* use a hard-linked clone, and preferably +not the same disk/machine). + +But since you don't seem to have backups right now, the good news is that +especially with a single blob being corrupt, these things *are* somewhat +debuggable. + +First off, move the corrupt object away, and *save* it. The most common +cause of corruption so far has been memory corruption, but even so, there +are people who would be interested in seeing the corruption - but it's +basically impossible to judge the corruption until we can also see the +original object, so right now the corrupt object is useless, but it's very +interesting for the future, in the hope that you can re-create a +non-corrupt version. + +So: + +> ib]$ mv .git/objects/4b/9458b3786228369c63936db65827de3cc06200 ../ + +This is the right thing to do, although it's usually best to save it under +it's full SHA1 name (you just dropped the "4b" from the result ;). + +Let's see what that tells us: + +> ib]$ git-fsck --full +> broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 +> to blob 4b9458b3786228369c63936db65827de3cc06200 +> missing blob 4b9458b3786228369c63936db65827de3cc06200 + +Ok, I removed the "dangling commit" messages, because they are just +messages about the fact that you probably have rebased etc, so they're not +at all interesting. But what remains is still very useful. In particular, +we now know which tree points to it! + +Now you can do + + git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 + +which will show something like + + 100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore + 100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap + 100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING + 100644 blob ee909f2cc49e54f0799a4739d24c4cb9151ae453 CREDITS + 040000 tree 0f5f709c17ad89e72bdbbef6ea221c69807009f6 Documentation + 100644 blob 1570d248ad9237e4fa6e4d079336b9da62d9ba32 Kbuild + 100644 blob 1c7c229a092665b11cd46a25dbd40feeb31661d9 MAINTAINERS + ... + +and you should now have a line that looks like + + 10064 blob 4b9458b3786228369c63936db65827de3cc06200 my-magic-file + +in the output. This already tells you a *lot* it tells you what file the +corrupt blob came from! + +Now, it doesn't tell you quite enough, though: it doesn't tell what +*version* of the file didn't get correctly written! You might be really +lucky, and it may be the version that you already have checked out in your +working tree, in which case fixing this problem is really simple, just do + + git hash-object -w my-magic-file + +again, and if it outputs the missing SHA1 (4b945..) you're now all done! + +But that's the really lucky case, so let's assume that it was some older +version that was broken. How do you tell which version it was? + +The easiest way to do it is to do + + git log --raw --all --full-history -- subdirectory/my-magic-file + +and that will show you the whole log for that file (please realize that +the tree you had may not be the top-level tree, so you need to figure out +which subdirectory it was in on your own), and because you're asking for +raw output, you'll now get something like + + commit abc + Author: + Date: + .. + :100644 100644 4b9458b... newsha... M somedirectory/my-magic-file + + + commit xyz + Author: + Date: + + .. + :100644 100644 oldsha... 4b9458b... M somedirectory/my-magic-file + +and this actually tells you what the *previous* and *subsequent* versions +of that file were! So now you can look at those ("oldsha" and "newsha" +respectively), and hopefully you have done commits often, and can +re-create the missing my-magic-file version by looking at those older and +newer versions! + +If you can do that, you can now recreate the missing object with + + git hash-object -w <recreated-file> + +and your repository is good again! + +(Btw, you could have ignored the fsck, and started with doing a + + git log --raw --all + +and just looked for the sha of the missing object (4b9458b..) in that +whole thing. It's up to you - git does *have* a lot of information, it is +just missing one particular blob version. + +Trying to recreate trees and especially commits is *much* harder. So you +were lucky that it's a blob. It's quite possible that you can recreate the +thing. + + Linus diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index b95f99be6..1e188e6e7 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -22,7 +22,7 @@ does not forbid it. However, there are a few things to keep in mind. . `git-commit-tree` (hence, `git-commit` which uses it) issues - an warning if the commit log message given to it does not look + 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 have i18n.commitencoding in `.git/config` file, like this: diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh index cd3a18eb7..2135a8ee1 100755 --- a/Documentation/install-webdoc.sh +++ b/Documentation/install-webdoc.sh @@ -2,9 +2,16 @@ T="$1" -for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt *.css +for h in \ + *.txt *.html \ + howto/*.txt howto/*.html \ + technical/*.txt technical/*.html \ + RelNotes-*.txt *.css do - if test -f "$T/$h" && + 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" then :; # up to date @@ -16,7 +23,10 @@ do fi done strip_leading=`echo "$T/" | sed -e 's|.|.|g'` -for th in "$T"/*.html "$T"/*.txt "$T"/howto/*.txt "$T"/howto/*.html +for th in \ + "$T"/*.html "$T"/*.txt \ + "$T"/howto/*.txt "$T"/howto/*.html \ + "$T"/technical/*.txt "$T"/technical/*.html do h=`expr "$th" : "$strip_leading"'\(.*\)'` case "$h" in diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index d64c259bb..9f1fc8255 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -10,6 +10,10 @@ 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. + --squash:: Produce the working tree and index state as if a real merge happened, but do not actually make a commit or @@ -19,6 +23,19 @@ 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. + -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. diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 4c92e375f..693913009 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -19,7 +19,7 @@ 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 gitlink:git-clone[1]. +by cloning shallowly. See linkgit:git-clone[1]. . You can be using `objects/info/alternates` mechanism, or `$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow' objects from other object stores. A repository with this kind @@ -89,7 +89,7 @@ refs/remotes/`name`:: packed-refs:: records the same information as refs/heads/, refs/tags/, and friends record in a more efficient way. See - gitlink:git-pack-refs[1]. + linkgit:git-pack-refs[1]. HEAD:: A symref (see glossary) to the `refs/heads/` namespace @@ -106,7 +106,7 @@ 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 gitlink:git-checkout[1] for +identically as normal. See linkgit:git-checkout[1] for details. branches:: @@ -155,7 +155,7 @@ info/exclude:: 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 - at it. See also: gitlink:gitignore[5]. + at it. See also: linkgit:gitignore[5]. remotes:: Stores shorthands to be used to give URL and default @@ -176,4 +176,4 @@ logs/refs/tags/`name`:: shallow:: This is similar to `info/grafts` but is internally used and maintained by shallow clone mechanism. See `--depth` - option to gitlink:git-clone[1] and gitlink:git-fetch[1]. + option to linkgit:git-clone[1] and linkgit:git-fetch[1]. diff --git a/Documentation/technical/.gitignore b/Documentation/technical/.gitignore new file mode 100644 index 000000000..8aa891dae --- /dev/null +++ b/Documentation/technical/.gitignore @@ -0,0 +1 @@ +api-index.txt diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt new file mode 100644 index 000000000..43dbe09f7 --- /dev/null +++ b/Documentation/technical/api-allocation-growing.txt @@ -0,0 +1,34 @@ +allocation growing API +====================== + +Dynamically growing an array using realloc() is error prone and boring. + +Define your array with: + +* a pointer (`ary`) that points at the array, initialized to `NULL`; + +* an integer variable (`alloc`) that keeps track of how big the current + allocation is, initialized to `0`; + +* another integer variable (`nr`) to keep track of how many elements the + array currently has, initialized to `0`. + +Then before adding `n`th element to the array, call `ALLOC_GROW(ary, n, +alloc)`. This ensures that the array can hold at least `n` elements by +calling `realloc(3)` and adjusting `alloc` variable. + +------------ +sometype *ary; +size_t nr; +size_t alloc + +for (i = 0; i < nr; i++) + if (we like ary[i] already) + return; + +/* we did not like any existing one, so add one */ +ALLOC_GROW(ary, nr + 1, alloc); +ary[nr++] = value you like; +------------ + +You are responsible for updating the `nr` variable. diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt new file mode 100644 index 000000000..52cdb4c52 --- /dev/null +++ b/Documentation/technical/api-builtin.txt @@ -0,0 +1,63 @@ +builtin API +=========== + +Adding a new built-in +--------------------- + +There are 4 things to do to add a bulit-in command implementation to +git: + +. Define the implementation of the built-in command `foo` with + signature: + + int cmd_foo(int argc, const char **argv, const char *prefix); + +. Add the external declaration for the function to `builtin.h`. + +. Add the command to `commands[]` table in `handle_internal_command()`, + defined in `git.c`. The entry should look like: + + { "foo", cmd_foo, <options> }, + + where options is the bitwise-or of: + +`RUN_SETUP`:: + + Make sure there is a git directory to work on, and if there is a + work tree, chdir to the top of it if the command was invoked + in a subdirectory. If there is no work tree, no chdir() is + done. + +`USE_PAGER`:: + + If the standard output is connected to a tty, spawn a pager and + feed our output to it. + +. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. + +Additionally, if `foo` is a new command, there are 3 more things to do: + +. Add tests to `t/` directory. + +. Write documentation in `Documentation/git-foo.txt`. + +. Add an entry for `git-foo` to the list at the end of + `Documentation/cmd-list.perl`. + + +How a built-in is called +------------------------ + +The implementation `cmd_foo()` takes three parameters, `argc`, `argv, +and `prefix`. The first two are similar to what `main()` of a +standalone command would be called with. + +When `RUN_SETUP` is specified in the `commands[]` table, and when you +were started from a subdirectory of the work tree, `cmd_foo()` is called +after chdir(2) to the top of the work tree, and `prefix` gets the path +to the subdirectory the command started from. This allows you to +convert a user-supplied pathname (typically relative to that directory) +to a pathname relative to the top of the work tree. + +The return value from `cmd_foo()` becomes the exit status of the +command. diff --git a/Documentation/technical/api-decorate.txt b/Documentation/technical/api-decorate.txt new file mode 100644 index 000000000..1d52a6ce1 --- /dev/null +++ b/Documentation/technical/api-decorate.txt @@ -0,0 +1,6 @@ +decorate API +============ + +Talk about <decorate.h> + +(Linus) diff --git a/Documentation/technical/api-diff.txt b/Documentation/technical/api-diff.txt new file mode 100644 index 000000000..83b007e70 --- /dev/null +++ b/Documentation/technical/api-diff.txt @@ -0,0 +1,166 @@ +diff API +======== + +The diff API is for programs that compare two sets of files (e.g. two +trees, one tree and the index) and present the found difference in +various ways. The calling program is responsible for feeding the API +pairs of files, one from the "old" set and the corresponding one from +"new" set, that are different. The library called through this API is +called diffcore, and is responsible for two things. + +* finding total rewrites (`-B`), renames (`-M`) and copies (`-C`), and + changes that touch a string (`-S`), as specified by the caller. + +* outputting the differences in various formats, as specified by the + caller. + +Calling sequence +---------------- + +* Prepare `struct diff_options` to record the set of diff options, and + then call `diff_setup()` to initialize this structure. This sets up + the vanilla default. + +* Fill in the options structure to specify desired output format, rename + detection, etc. `diff_opt_parse()` can be used to parse options given + from the command line in a way consistent with existing git-diff + family of programs. + +* Call `diff_setup_done()`; this inspects the options set up so far for + internal consistency and make necessary tweaking to it (e.g. if + textual patch output was asked, recursive behaviour is turned on). + +* 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 + API. These are thin wrappers to a lower-level `diff_queue()` function + that is flexible enough to record any of these kinds of changes. + +* Once you finish feeding the pairs of files, call `diffcore_std()`. + This will tell the diffcore library to go ahead and do its work. + +* Calling `diffcore_flush()` will produce the output. + + +Data structures +--------------- + +* `struct diff_filespec` + +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 +feed `diff_queue()` function with. + +* `struct diff_filepair` + +This records a pair of `struct diff_filespec`; the filespec for a file +in the "old" set (i.e. preimage) is called `one`, and the filespec for a +file in the "new" set (i.e. postimage) is called `two`. A change that +represents file creation has NULL in `one`, and file deletion has NULL +in `two`. + +A `filepair` starts pointing at `one` and `two` that are from the same +filename, but `diffcore_std()` can break pairs and match component +filespecs with other filespecs from a different filepair to form new +filepair. This is called 'rename detection'. + +* `struct diff_queue` + +This is a collection of filepairs. Notable members are: + +`queue`:: + + An array of pointers to `struct diff_filepair`. This + dynamically grows as you add filepairs; + +`alloc`:: + + The allocated size of the `queue` array; + +`nr`:: + + The number of elements in the `queue` array. + + +* `struct diff_options` + +This describes the set of options the calling program wants to affect +the operation of diffcore library with. + +Notable members are: + +`output_format`:: + The output format used when `diff_flush()` is run. + +`context`:: + Number of context lines to generate in patch output. + +`break_opt`, `detect_rename`, `rename-score`, `rename_limit`:: + Affects the way detection logic for complete rewrites, renames + and copies. + +`abbrev`:: + Number of hexdigits to abbreviate raw format output to. + +`pickaxe`:: + A constant string (can and typically does contain newlines to + look for a block of text, not just a single line) to filter out + the filepairs that do not change the number of strings contained + in its preimage and postimage of the diff_queue. + +`flags`:: + This is mostly a collection of boolean options that affects the + operation, but some do not have anything to do with the diffcore + library. + +BINARY, TEXT;; + Affects the way how a file that is seemingly binary is treated. + +FULL_INDEX;; + Tells the patch output format not to use abbreviated object + names on the "index" lines. + +FIND_COPIES_HARDER;; + Tells the diffcore library that the caller is feeding unchanged + filepairs to allow copies from unmodified files be detected. + +COLOR_DIFF;; + Output should be colored. + +COLOR_DIFF_WORDS;; + Output is a colored word-diff. + +NO_INDEX;; + Tells diff-files that the input is not tracked files but files + in random locations on the filesystem. + +ALLOW_EXTERNAL;; + Tells output routine that it is Ok to call user specified patch + output routine. Plumbing disables this to ensure stable output. + +QUIET;; + Do not show any output. + +REVERSE_DIFF;; + Tells the library that the calling program is feeding the + filepairs reversed; `one` is two, and `two` is one. + +EXIT_WITH_STATUS;; + For communication between the calling program and the options + parser; tell the calling program to signal the presence of + difference using program exit code. + +HAS_CHANGES;; + Internal; used for optimization to see if there is any change. + +SILENT_ON_REMOVE;; + Affects if diff-files shows removed files. + +RECURSIVE, TREE_IN_RECURSIVE;; + Tells if tree traversal done by tree-diff should recursively + descend into a tree object pair that are different in preimage + and postimage set. + +(JC) diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt new file mode 100644 index 000000000..5bbd18f02 --- /dev/null +++ b/Documentation/technical/api-directory-listing.txt @@ -0,0 +1,76 @@ +directory listing API +===================== + +The directory listing API is used to enumerate paths in the work tree, +optionally taking `.git/info/exclude` and `.gitignore` files per +directory into account. + +Data structure +-------------- + +`struct dir_struct` structure is used to pass directory traversal +options to the library and to record the paths discovered. The notable +options are: + +`exclude_per_dir`:: + + The name of the file to be read in each directory for excluded + files (typically `.gitignore`). + +`collect_ignored`:: + + Include paths that are to be excluded in the result. + +`show_ignored`:: + + The traversal is for finding just ignored files, not unignored + files. + +`show_other_directories`:: + + Include a directory that is not tracked. + +`hide_empty_directories`:: + + Do not include a directory that is not tracked and is empty. + +`no_gitlinks`:: + + If set, recurse into a directory that looks like a git + directory. Otherwise it is shown as a directory. + +The result of the enumeration is left in these fields:: + +`entries[]`:: + + An array of `struct dir_entry`, each element of which describes + a path. + +`nr`:: + + The number of members in `entries[]` array. + +`alloc`:: + + Internal use; keeps track of allocation of `entries[]` array. + + +Calling sequence +---------------- + +* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, + sizeof(dir))`. + +* Call `add_exclude()` to add single exclude pattern, + `add_excludes_from_file()` to add patterns from a file + (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A + short-hand function `setup_standard_excludes()` can be used to set up + the standard set of exclude settings. + +* Set options described in the Data Structure section above. + +* Call `read_directory()`. + +* Use `dir.entries[]`. + +(JC) diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt new file mode 100644 index 000000000..9d97eaa9d --- /dev/null +++ b/Documentation/technical/api-gitattributes.txt @@ -0,0 +1,111 @@ +gitattributes API +================= + +gitattributes mechanism gives a uniform way to associate various +attributes to set of paths. + + +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. + +`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. + + +Attribute Values +---------------- + +An attribute for a path can be in one of four states: Set, Unset, +Unspecified or set to a string, and `.value` member of `struct +git_attr_check` records it. There are three macros to check these: + +`ATTR_TRUE()`:: + + Returns true if the attribute is Set for the path. + +`ATTR_FALSE()`:: + + Returns true if the attribute is Unset for the path. + +`ATTR_UNSET()`:: + + Returns true if the attribute is Unspecified for the path. + +If none of the above returns true, `.value` member points at a string +value of the attribute for the path. + + +Example +------- + +To see how attributes "crlf" and "indent" are set for different paths. + +. Prepare an array of `struct git_attr_check` with two elements (because + we are checking two attributes). Initialize their `attr` member with + pointers to `struct git_attr` obtained by calling `git_attr()`: + +------------ +static struct git_attr_check check[2]; +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); +} +------------ + +. Call `git_checkattr()` with the prepared array of `struct git_attr_check`: + +------------ + const char *path; + + setup_check(); + git_checkattr(path, ARRAY_SIZE(check), check); +------------ + +. Act on `.value` member of the result, left in `check[]`: + +------------ + const char *value = check[0].value; + + if (ATTR_TRUE(value)) { + The attribute is Set, by listing only the name of the + attribute in the gitattributes file for the path. + } else if (ATTR_FALSE(value)) { + The attribute is Unset, by listing the name of the + attribute prefixed with a dash - for the path. + } else if (ATTR_UNSET(value)) { + The attribute is not set nor unset for the path. + } else if (!strcmp(value, "input")) { + If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is + true, the value is a string set in the gitattributes + file for the path by saying "attr=value". + } else if (... other check using value as string ...) { + ... + } +------------ + +(JC) diff --git a/Documentation/technical/api-grep.txt b/Documentation/technical/api-grep.txt new file mode 100644 index 000000000..a69cc8964 --- /dev/null +++ b/Documentation/technical/api-grep.txt @@ -0,0 +1,8 @@ +grep API +======== + +Talk about <grep.h>, things like: + +* grep_buffer() + +(JC) diff --git a/Documentation/technical/api-hash.txt b/Documentation/technical/api-hash.txt new file mode 100644 index 000000000..c784d3edc --- /dev/null +++ b/Documentation/technical/api-hash.txt @@ -0,0 +1,6 @@ +hash API +======== + +Talk about <hash.h> + +(Linus) diff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt new file mode 100644 index 000000000..adbdbf5d7 --- /dev/null +++ b/Documentation/technical/api-in-core-index.txt @@ -0,0 +1,21 @@ +in-core index API +================= + +Talk about <read-cache.c> and <cache-tree.c>, things like: + +* cache -> the_index macros +* read_index() +* write_index() +* ie_match_stat() and ie_modified(); how they are different and when to + use which. +* index_name_pos() +* remove_index_entry_at() +* remove_file_from_index() +* add_file_to_index() +* add_index_entry() +* refresh_index() +* discard_index() +* cache_tree_invalidate_path() +* cache_tree_update() + +(JC, Linus) diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt new file mode 100644 index 000000000..af7cc2e39 --- /dev/null +++ b/Documentation/technical/api-index-skel.txt @@ -0,0 +1,15 @@ +GIT API Documents +================= + +GIT has grown a set of internal API over time. This collection +documents them. + +//////////////////////////////////////////////////////////////// +// table of contents begin +//////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////// +// table of contents end +//////////////////////////////////////////////////////////////// + +2007-11-24 diff --git a/Documentation/technical/api-index.sh b/Documentation/technical/api-index.sh new file mode 100755 index 000000000..9c3f4131b --- /dev/null +++ b/Documentation/technical/api-index.sh @@ -0,0 +1,28 @@ +#!/bin/sh + +( + c=//////////////////////////////////////////////////////////////// + skel=api-index-skel.txt + sed -e '/^\/\/ table of contents begin/q' "$skel" + echo "$c" + + ls api-*.txt | + while read filename + do + case "$filename" in + api-index-skel.txt | api-index.txt) continue ;; + esac + title=$(sed -e 1q "$filename") + html=${filename%.txt}.html + echo "* link:$html[$title]" + done + echo "$c" + sed -n -e '/^\/\/ table of contents end/,$p' "$skel" +) >api-index.txt+ + +if test -f api-index.txt && cmp api-index.txt api-index.txt+ >/dev/null +then + rm -f api-index.txt+ +else + mv api-index.txt+ api-index.txt +fi diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt new file mode 100644 index 000000000..73ac1025f --- /dev/null +++ b/Documentation/technical/api-lockfile.txt @@ -0,0 +1,12 @@ +lockfile API +============ + +Talk about <lockfile.c>, things like: + +* lockfile lifetime -- atexit(3) looks at them, do not put them on the + stack; +* hold_lock_file_for_update() +* commit_lock_file() +* rollback_rock_file() + +(JC, Dscho, Shawn) diff --git a/Documentation/technical/api-object-access.txt b/Documentation/technical/api-object-access.txt new file mode 100644 index 000000000..03bb0e950 --- /dev/null +++ b/Documentation/technical/api-object-access.txt @@ -0,0 +1,15 @@ +object access API +================= + +Talk about <sha1_file.c> and <object.h> family, things like + +* read_sha1_file() +* read_object_with_reference() +* has_sha1_file() +* write_sha1_file() +* pretend_sha1_file() +* lookup_{object,commit,tag,blob,tree} +* parse_{object,commit,tag,blob,tree} +* Use of object flags + +(JC, Shawn, Daniel, Dscho, Linus) diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt new file mode 100644 index 000000000..b7cda94f5 --- /dev/null +++ b/Documentation/technical/api-parse-options.txt @@ -0,0 +1,6 @@ +parse-options API +================= + +Talk about <parse-options.h> + +(Pierre) diff --git a/Documentation/technical/api-path-list.txt b/Documentation/technical/api-path-list.txt new file mode 100644 index 000000000..d07768317 --- /dev/null +++ b/Documentation/technical/api-path-list.txt @@ -0,0 +1,9 @@ +path-list API +============= + +Talk about <path-list.h>, things like + +* it is not just paths but strings in general; +* the calling sequence. + +(Dscho) diff --git a/Documentation/technical/api-quote.txt b/Documentation/technical/api-quote.txt new file mode 100644 index 000000000..e8a1bce94 --- /dev/null +++ b/Documentation/technical/api-quote.txt @@ -0,0 +1,10 @@ +quote API +========= + +Talk about <quote.h>, things like + +* sq_quote and unquote +* c_style quote and unquote +* quoting for foreign languages + +(JC) diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt new file mode 100644 index 000000000..01a24551a --- /dev/null +++ b/Documentation/technical/api-revision-walking.txt @@ -0,0 +1,9 @@ +revision walking API +==================== + +Talk about <revision.h>, things like: + +* two diff_options, one for path limiting, another for output; +* calling sequence: init_revisions(), setup_revsions(), get_revision(); + +(Linus, JC, Dscho) diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt new file mode 100644 index 000000000..19d2f64f7 --- /dev/null +++ b/Documentation/technical/api-run-command.txt @@ -0,0 +1,10 @@ +run-command API +=============== + +Talk about <run-command.h>, and things like: + +* Environment the command runs with (e.g. GIT_DIR); +* File descriptors and pipes; +* Exit status; + +(Hannes, Dscho, Shawn) diff --git a/Documentation/technical/api-setup.txt b/Documentation/technical/api-setup.txt new file mode 100644 index 000000000..4f63a04d7 --- /dev/null +++ b/Documentation/technical/api-setup.txt @@ -0,0 +1,13 @@ +setup API +========= + +Talk about + +* setup_git_directory() +* setup_git_directory_gently() +* is_inside_git_dir() +* is_inside_work_tree() +* setup_work_tree() +* get_pathspec() + +(Dscho) diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt new file mode 100644 index 000000000..a52e4f36d --- /dev/null +++ b/Documentation/technical/api-strbuf.txt @@ -0,0 +1,6 @@ +strbuf API +========== + +Talk about <strbuf.h> + +(Pierre, JC) diff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt new file mode 100644 index 000000000..e3ddf9128 --- /dev/null +++ b/Documentation/technical/api-tree-walking.txt @@ -0,0 +1,12 @@ +tree walking API +================ + +Talk about <tree-walk.h>, things like + +* struct tree_desc +* init_tree_desc +* tree_entry_extract +* update_tree_entry +* get_tree_entry + +(JC, Linus) diff --git a/Documentation/technical/api-xdiff-interface.txt b/Documentation/technical/api-xdiff-interface.txt new file mode 100644 index 000000000..6296ecad1 --- /dev/null +++ b/Documentation/technical/api-xdiff-interface.txt @@ -0,0 +1,7 @@ +xdiff interface API +=================== + +Talk about our calling convention to xdiff library, including +xdiff_emit_consume_fn. + +(Dscho, JC) diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index e5b31c81f..aa87756a5 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -1,9 +1,9 @@ GIT pack format =============== -= pack-*.pack file has the following format: += pack-*.pack files have the following format: - - The header appears at the beginning and consists of the following: + - A header appears at the beginning and consists of the following: 4-byte signature: The signature is: {'P', 'A', 'C', 'K'} @@ -34,18 +34,14 @@ GIT pack format - The trailer records 20-byte SHA1 checksum of all of the above. -= pack-*.idx file has the following format: += Original (version 1) pack-*.idx files have the following format: - The header consists of 256 4-byte network byte order integers. N-th entry of this table records the number of objects in the corresponding pack, the first byte of whose - object name are smaller than N. This is called the + object name is less than or equal to N. This is called the 'first-level fan-out' table. - Observation: we would need to extend this to an array of - 8-byte integers to go beyond 4G objects per pack, but it is - not strictly necessary. - - The header is followed by sorted 24-byte entries, one entry per object in the pack. Each entry is: @@ -55,10 +51,6 @@ GIT pack format 20-byte object name. - Observation: we would definitely need to extend this to - 8-byte integer plus 20-byte object name to handle a packfile - that is larger than 4GB. - - The file is concluded with a trailer: A copy of the 20-byte SHA1 checksum at the end of @@ -68,31 +60,30 @@ GIT pack format Pack Idx file: - idx - +--------------------------------+ - | fanout[0] = 2 |-. - +--------------------------------+ | + -- +--------------------------------+ +fanout | fanout[0] = 2 (for example) |-. +table +--------------------------------+ | | fanout[1] | | +--------------------------------+ | | fanout[2] | | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | - | fanout[255] | | - +--------------------------------+ | -main | offset | | -index | object name 00XXXXXXXXXXXXXXXX | | -table +--------------------------------+ | - | offset | | - | object name 00XXXXXXXXXXXXXXXX | | - +--------------------------------+ | - .-| offset |<+ - | | object name 01XXXXXXXXXXXXXXXX | - | +--------------------------------+ - | | offset | - | | object name 01XXXXXXXXXXXXXXXX | - | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | | offset | - | | object name FFXXXXXXXXXXXXXXXX | - | +--------------------------------+ + | fanout[255] = total objects |---. + -- +--------------------------------+ | | +main | offset | | | +index | object name 00XXXXXXXXXXXXXXXX | | | +table +--------------------------------+ | | + | offset | | | + | object name 00XXXXXXXXXXXXXXXX | | | + +--------------------------------+<+ | + .-| offset | | + | | object name 01XXXXXXXXXXXXXXXX | | + | +--------------------------------+ | + | | offset | | + | | object name 01XXXXXXXXXXXXXXXX | | + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | + | | offset | | + | | object name FFXXXXXXXXXXXXXXXX | | + --| +--------------------------------+<--+ trailer | | packfile checksum | | +--------------------------------+ | | idxfile checksum | @@ -116,3 +107,40 @@ Pack file entry: <+ 20-byte base object name SHA1 (the size above is the size of the delta data that follows). delta data, deflated. + + += Version 2 pack-*.idx files support packs larger than 4 GiB, and + have some other reorganizations. They have the format: + + - A 4-byte magic number '\377tOc' which is an unreasonable + fanout[0] value. + + - A 4-byte version number (= 2) + + - A 256-entry fan-out table just like v1. + + - A table of sorted 20-byte SHA1 object names. These are + packed together without offset values to reduce the cache + footprint of the binary search for a specific object name. + + - A table of 4-byte CRC32 values of the packed object data. + This is new in v2 so compressed data can be copied directly + from pack to pack during repacking without undetected + data corruption. + + - A table of 4-byte offset values (in network byte order). + These are usually 31-bit pack file offsets, but large + offsets are encoded as an index into the next table with + the msbit set. + + - A table of 8-byte offset entries (empty for pack files less + than 2 GiB). Pack files are organized with heavily used + objects toward the front, so most object references should + not need to refer to this table. + + - The same trailer as a v1 pack file: + + A copy of the 20-byte SHA1 checksum at the end of + corresponding packfile. + + 20-byte SHA1-checksum of all of the above. diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt index 5c39a165f..7fac47de8 100644 --- a/Documentation/tutorial-2.txt +++ b/Documentation/tutorial-2.txt @@ -172,7 +172,7 @@ merge, with the parent references pointing to the heads of the merged branches. Besides blobs, trees, and commits, the only remaining type of object -is a "tag", which we won't discuss here; refer to gitlink:git-tag[1] +is a "tag", which we won't discuss here; refer to linkgit:git-tag[1] for details. So now we know how git uses the object database to represent a diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index fff1068c5..e2bbda53f 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -47,7 +47,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 gitlink:git-add[1]: +current directory (note the '.'), with linkgit:git-add[1]: ------------------------------------------------ $ git add . @@ -55,7 +55,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 gitlink:git-commit[1]: +repository with linkgit:git-commit[1]: ------------------------------------------------ $ git commit @@ -74,15 +74,15 @@ $ git add file1 file2 file3 ------------------------------------------------ You are now ready to commit. You can see what is about to be committed -using gitlink:git-diff[1] with the --cached option: +using linkgit:git-diff[1] with the --cached option: ------------------------------------------------ $ git diff --cached ------------------------------------------------ -(Without --cached, gitlink:git-diff[1] will show you any changes that +(Without --cached, linkgit:git-diff[1] 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 gitlink:git-status[1]: +summary of the situation with linkgit:git-status[1]: ------------------------------------------------ $ git status @@ -358,7 +358,7 @@ $ git config --get remote.origin.url ------------------------------------- (The complete configuration created by git-clone is visible using -"git config -l", and the gitlink:git-config[1] man page +"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 @@ -377,10 +377,10 @@ $ git clone alice.org:/home/alice/project myrepo ------------------------------------- Alternatively, git has a native protocol, or can use rsync or http; -see gitlink:git-pull[1] for details. +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 gitlink:git-push[1] and +that various users push changes to; see linkgit:git-push[1] and link:cvs-migration.html[git for CVS users]. Exploring history @@ -442,7 +442,7 @@ $ git-tag v2.5 1b2e1d63ff you can refer to 1b2e1d63ff by the name "v2.5". If you intend to share this name with other people (for example, to identify a release version), you should create a "tag" object, and perhaps sign it; see -gitlink:git-tag[1] for details. +linkgit:git-tag[1] for details. Any git command that needs to know a commit can take any of these names. For example: @@ -461,7 +461,7 @@ this branch. If this branch is the only branch containing those 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 gitlink:git-revert[1] +If you need to undo changes that you have pushed, use linkgit:git-revert[1] instead. The git grep command can search for strings in any version of your @@ -567,12 +567,12 @@ need to make the most of git. If you don't want to continue with that right away, a few other digressions that may be interesting at this point are: - * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert + * 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 on emailed patches. - * gitlink:git-bisect[1]: When there is a regression in your + * linkgit:git-bisect[1]: When there is a regression in your project, one way to track down the bug is by searching through the history to find the exact commit that's to blame. Git bisect can help you perform a binary search for that commit. It is diff --git a/Documentation/urls.txt b/Documentation/urls.txt index e67f9140a..81ac17f32 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -36,5 +36,11 @@ To sync with a local directory, you can use: - file:///path/to/repo.git/ =============================================================== +ifndef::git-clone[] They are mostly equivalent, except when cloning. See -gitlink:git-clone[1] for details. +linkgit:git-clone[1] for details. +endif::git-clone[] + +ifdef::git-clone[] +They are equivalent, except the former implies --local option. +endif::git-clone[] diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf index 92b01ecf7..339b30919 100644 --- a/Documentation/user-manual.conf +++ b/Documentation/user-manual.conf @@ -7,7 +7,7 @@ startsb=[ endsb=] tilde=~ -[gitlink-inlinemacro] +[linkgit-inlinemacro] <ulink url="{target}.html">{target}{0?({0})}</ulink> ifdef::backend-docbook[] diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 159de30e1..40b0de087 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -42,7 +42,7 @@ How to get a git repository It will be useful to have a git repository to experiment with as you read this manual. -The best way to get one is by using the gitlink:git-clone[1] command to +The best way to get one is by using the linkgit:git-clone[1] command to download a copy of an existing repository. If you don't already have a project in mind, here are some interesting examples: @@ -74,12 +74,12 @@ version is called a <<def_commit,commit>>. Those snapshots aren't necessarily all arranged in a single line from oldest to newest; instead, work may simultaneously proceed along -parallel lines of development, called <def_branch,branches>>, which may +parallel lines of development, called <<def_branch,branches>>, which may merge and diverge. A single git repository can track development on multiple branches. It does this by keeping a list of <<def_head,heads>> which reference the -latest commit on each branch; the gitlink:git-branch[1] command shows +latest commit on each branch; the linkgit:git-branch[1] command shows you the list of branch heads: ------------------------------------------------ @@ -93,7 +93,7 @@ the project referred to by that branch head. Most projects also use <<def_tag,tags>>. Tags, like heads, are references into the project's history, and can be listed using the -gitlink:git-tag[1] command: +linkgit:git-tag[1] command: ------------------------------------------------ $ git tag -l @@ -113,14 +113,14 @@ Tags are expected to always point at the same version of a project, while heads are expected to advance as development progresses. Create a new branch head pointing to one of these versions and check it -out using gitlink:git-checkout[1]: +out using linkgit:git-checkout[1]: ------------------------------------------------ $ git checkout -b new v2.6.13 ------------------------------------------------ The working directory then reflects the contents that the project had -when it was tagged v2.6.13, and gitlink:git-branch[1] shows two +when it was tagged v2.6.13, and linkgit:git-branch[1] shows two branches, with an asterisk marking the currently checked-out branch: ------------------------------------------------ @@ -146,7 +146,7 @@ Understanding History: Commits ------------------------------ Every change in the history of a project is represented by a commit. -The gitlink:git-show[1] command shows the most recent commit on the +The linkgit:git-show[1] command shows the most recent commit on the current branch: ------------------------------------------------ @@ -208,7 +208,7 @@ representing a merge can therefore have more than one parent, with each parent representing the most recent commit on one of the lines of development leading to that point. -The best way to see how this works is using the gitlink:gitk[1] +The best way to see how this works is using the linkgit:gitk[1] command; running gitk now on a git repository and looking for merge commits will help understand how the git organizes history. @@ -335,7 +335,7 @@ 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 -can view using the "-r" option to gitlink:git-branch[1]: +can view using the "-r" option to linkgit:git-branch[1]: ------------------------------------------------ $ git branch -r @@ -378,7 +378,7 @@ exists a tag and a branch with the same name. (Newly created refs are actually stored in the .git/refs directory, under the path given by their name. However, for efficiency reasons they may also be packed together in a single file; see -gitlink:git-pack-refs[1]). +linkgit:git-pack-refs[1]). As another useful shortcut, the "HEAD" of a repository can be referred to just using the name of that repository. So, for example, "origin" @@ -387,7 +387,7 @@ is usually a shortcut for the HEAD branch in the repository "origin". For the complete list of paths which git checks for references, and the order it uses to decide which to choose when there are multiple references with the same shorthand name, see the "SPECIFYING -REVISIONS" section of gitlink:git-rev-parse[1]. +REVISIONS" section of linkgit:git-rev-parse[1]. [[Updating-a-repository-with-git-fetch]] Updating a repository with git fetch @@ -407,7 +407,7 @@ Fetching branches from other repositories ----------------------------------------- You can also track branches from repositories other than the one you -cloned from, using gitlink:git-remote[1]: +cloned from, using linkgit:git-remote[1]: ------------------------------------------------- $ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git @@ -443,7 +443,7 @@ $ cat .git/config This is what causes git to track the remote's branches; you may modify or delete these configuration options by editing .git/config with a text editor. (See the "CONFIGURATION FILE" section of -gitlink:git-config[1] for details.) +linkgit:git-config[1] for details.) [[exploring-git-history]] Exploring git history @@ -468,7 +468,7 @@ Suppose version 2.6.18 of your project worked, but the version at "master" crashes. Sometimes the best way to find the cause of such a regression is to perform a brute-force search through the project's history to find the particular commit that caused the problem. The -gitlink:git-bisect[1] command can help you do this: +linkgit:git-bisect[1] command can help you do this: ------------------------------------------------- $ git bisect start @@ -481,7 +481,7 @@ 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 -v2.6.19 but not from v2.6.18. Compile and test it, and see whether +"master" but not from v2.6.18. Compile and test it, and see whether it crashes. Assume it does crash. Then: ------------------------------------------------- @@ -497,7 +497,7 @@ half each time. After about 13 tests (in this case), it will output the commit id of the guilty commit. You can then examine the commit with -gitlink:git-show[1], find out who wrote it, and mail them your bug +linkgit:git-show[1], find out who wrote it, and mail them your bug report with the commit id. Finally, run ------------------------------------------------- @@ -543,7 +543,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 -gitlink:git-rev-parse[1] man page for the complete list of ways to +linkgit:git-rev-parse[1] man page for the complete list of ways to name revisions. Some examples: ------------------------------------------------- @@ -584,7 +584,7 @@ When we discuss merges we'll also see the special name MERGE_HEAD, which refers to the other branch that we're merging in to the current branch. -The gitlink:git-rev-parse[1] command is a low-level command that is +The linkgit:git-rev-parse[1] command is a low-level command that is occasionally useful for translating some name for a commit to the object name for that commit: @@ -608,14 +608,14 @@ You can use stable-1 to refer to the commit 1b2e1d63ff. This creates a "lightweight" tag. If you would also like to include a comment with the tag, and possibly sign it cryptographically, then you -should create a tag object instead; see the gitlink:git-tag[1] man page +should create a tag object instead; see the linkgit:git-tag[1] man page for details. [[browsing-revisions]] Browsing revisions ------------------ -The gitlink:git-log[1] command can show lists of commits. On its +The linkgit:git-log[1] command can show lists of commits. On its own, it shows all commits reachable from the parent commit; but you can also make more specific requests: @@ -645,7 +645,7 @@ You can also ask git log to show patches: $ git log -p ------------------------------------------------- -See the "--pretty" option in the gitlink:git-log[1] man page for more +See the "--pretty" option in the linkgit:git-log[1] man page for more display options. Note that git log starts with the most recent commit and works @@ -658,7 +658,7 @@ Generating diffs ---------------- You can generate diffs between any two versions using -gitlink:git-diff[1]: +linkgit:git-diff[1]: ------------------------------------------------- $ git diff master..test @@ -673,7 +673,7 @@ $ git diff master...test ------------------------------------------------- Sometimes what you want instead is a set of patches; for this you can -use gitlink:git-format-patch[1]: +use linkgit:git-format-patch[1]: ------------------------------------------------- $ git format-patch master..test @@ -714,7 +714,7 @@ $ git log --pretty=oneline origin..mybranch | wc -l ------------------------------------------------- Alternatively, you may often see this sort of thing done with the -lower-level command gitlink:git-rev-list[1], which just lists the SHA1's +lower-level command linkgit:git-rev-list[1], which just lists the SHA1's of all the given commits: ------------------------------------------------- @@ -772,7 +772,7 @@ You could just visually inspect the commits since e05db0fd: $ gitk e05db0fd.. ------------------------------------------------- -Or you can use gitlink:git-name-rev[1], which will give the commit a +Or you can use linkgit:git-name-rev[1], which will give the commit a name based on any tag it finds pointing to one of the commit's descendants: @@ -781,7 +781,7 @@ $ git name-rev --tags e05db0fd e05db0fd tags/v1.5.0-rc1^0~23 ------------------------------------------------- -The gitlink:git-describe[1] command does the opposite, naming the +The linkgit:git-describe[1] command does the opposite, naming the revision using a tag on which the given commit is based: ------------------------------------------------- @@ -793,7 +793,7 @@ but that may sometimes help you guess which tags might come after the given commit. If you just want to verify whether a given tagged version contains a -given commit, you could use gitlink:git-merge-base[1]: +given commit, you could use linkgit:git-merge-base[1]: ------------------------------------------------- $ git merge-base e05db0fd v1.5.0-rc1 @@ -814,7 +814,7 @@ $ git log v1.5.0-rc1..e05db0fd will produce empty output if and only if v1.5.0-rc1 includes e05db0fd, because it outputs only commits that are not reachable from v1.5.0-rc1. -As yet another alternative, the gitlink:git-show-branch[1] command lists +As yet another alternative, the linkgit:git-show-branch[1] command lists the commits reachable from its arguments with a display on the left-hand side that indicates which arguments that commit is reachable from. So, you can run something like @@ -847,7 +847,7 @@ Suppose you would like to see all the commits reachable from the branch head named "master" but not from any other head in your repository. We can list all the heads in this repository with -gitlink:git-show-ref[1]: +linkgit:git-show-ref[1]: ------------------------------------------------- $ git show-ref --heads @@ -884,14 +884,14 @@ commits reachable from some head but not from any tag in the repository: $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) ------------------------------------------------- -(See gitlink:git-rev-parse[1] for explanations of commit-selecting +(See linkgit:git-rev-parse[1] for explanations of commit-selecting syntax such as `--not`.) [[making-a-release]] Creating a changelog and tarball for a software release ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The gitlink:git-archive[1] command can create a tar or zip archive from +The linkgit:git-archive[1] command can create a tar or zip archive from any version of a project; for example: ------------------------------------------------- @@ -939,13 +939,13 @@ file such that it contained the given content either before or after the commit. You can find out with this: ------------------------------------------------- -$ git log --raw --abbrev=40 --pretty=oneline -- filename | +$ git log --raw --abbrev=40 --pretty=oneline | grep -B 1 `git hash-object filename` ------------------------------------------------- Figuring out why this works is left as an exercise to the (advanced) -student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and -gitlink:git-hash-object[1] man pages may prove helpful. +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 @@ -965,7 +965,7 @@ file named .gitconfig in your home directory: email = you@yourdomain.example.com ------------------------------------------------ -(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for +(See the "CONFIGURATION FILE" section of linkgit:git-config[1] for details on the configuration file.) @@ -1088,7 +1088,7 @@ $ git diff HEAD # difference between HEAD and working tree; what $ git status # a brief per-file summary of the above. ------------------------------------------------- -You can also use gitlink:git-gui[1] to create commits, view changes in +You can also use linkgit:git-gui[1] to create commits, view changes in the index and the working tree files, and individually select diff hunks for inclusion in the index (by right-clicking on the diff hunk and choosing "Stage Hunk For Commit"). @@ -1131,7 +1131,7 @@ foo.txt *.[oa] ------------------------------------------------- -See gitlink:gitignore[5] for a detailed explanation of the syntax. You can +See linkgit:gitignore[5] for a detailed explanation of the syntax. You can also place .gitignore files in other directories in your working tree, and they will apply to those directories and their subdirectories. The `.gitignore` files can be added to your repository like any other files (just run `git add @@ -1144,14 +1144,14 @@ If you wish the exclude patterns to affect only certain repositories them in a file in your repository named .git/info/exclude, or in any file specified by the `core.excludesfile` configuration variable. Some git commands can also take exclude patterns directly on the command line. -See gitlink:gitignore[5] for the details. +See linkgit:gitignore[5] for the details. [[how-to-merge]] How to merge ------------ You can rejoin two diverging branches of development using -gitlink:git-merge[1]: +linkgit:git-merge[1]: ------------------------------------------------- $ git merge branchname @@ -1188,7 +1188,7 @@ the working tree in a special state that gives you all the information you need to help resolve the merge. Files with conflicts are marked specially in the index, so until you -resolve the problem and update the index, gitlink:git-commit[1] will +resolve the problem and update the index, linkgit:git-commit[1] will fail: ------------------------------------------------- @@ -1196,7 +1196,7 @@ $ git commit file.txt: needs merge ------------------------------------------------- -Also, gitlink:git-status[1] will list those files as "unmerged", and the +Also, linkgit:git-status[1] will list those files as "unmerged", and the files with conflicts will have conflict markers added, like this: ------------------------------------------------- @@ -1227,7 +1227,7 @@ Getting conflict-resolution help during a merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All of the changes that git was able to merge automatically are -already added to the index file, so gitlink:git-diff[1] shows only +already added to the index file, so linkgit:git-diff[1] shows only the conflicts. It uses an unusual syntax: ------------------------------------------------- @@ -1262,7 +1262,7 @@ $ git show :3:file.txt # the version from MERGE_HEAD, but including any Since the stage 2 and stage 3 versions have already been updated with nonconflicting changes, the only remaining differences between them are -the important ones; thus gitlink:git-diff[1] can use the information in +the important ones; thus linkgit:git-diff[1] can use the information in the index to show only those conflicts. The diff above shows the differences between the working-tree version of @@ -1271,7 +1271,7 @@ each line by a single "+" or "-", it now uses two columns: the first column is used for differences between the first parent and the working directory copy, and the second for differences between the second parent and the working directory copy. (See the "COMBINED DIFF FORMAT" section -of gitlink:git-diff-files[1] for a details of the format.) +of linkgit:git-diff-files[1] for a details of the format.) After resolving the conflict in the obvious way (but before updating the index), the diff will look like: @@ -1304,7 +1304,7 @@ $ git diff -3 file.txt # diff against stage 3 $ git diff --theirs file.txt # same as the above. ------------------------------------------------- -The gitlink:git-log[1] and gitk[1] commands also provide special help +The linkgit:git-log[1] and gitk[1] commands also provide special help for merges: ------------------------------------------------- @@ -1315,7 +1315,7 @@ $ gitk --merge These will display all commits which exist only on HEAD or on MERGE_HEAD, and which touch an unmerged file. -You may also use gitlink:git-mergetool[1], which lets you merge the +You may also use linkgit:git-mergetool[1], which lets you merge the unmerged files using external tools such as emacs or kdiff3. Each time you resolve the conflicts in a file and update the index: @@ -1380,7 +1380,7 @@ If you make a commit that you later wish you hadn't, there are two fundamentally different ways to fix the problem: 1. You can create a new commit that undoes whatever was done - by the previous commit. This is the correct thing if your + by the old commit. This is the correct thing if your mistake has already been made public. 2. You can go back and modify the old commit. You should @@ -1394,7 +1394,7 @@ Fixing a mistake with a new commit ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Creating a new commit that reverts an earlier change is very easy; -just pass the gitlink:git-revert[1] command a reference to the bad +just pass the linkgit:git-revert[1] command a reference to the bad commit; for example, to revert the most recent commit: ------------------------------------------------- @@ -1437,7 +1437,7 @@ which will replace the old commit by a new commit incorporating your changes, giving you a chance to edit the old commit message first. Again, you should never do this to a commit that may already have -been merged into another branch; use gitlink:git-revert[1] instead in +been merged into another branch; use linkgit:git-revert[1] instead in that case. It is also possible to replace commits further back in the history, but @@ -1450,7 +1450,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 -gitlink: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 @@ -1463,7 +1463,7 @@ also updates the index to match. It does not change branches. If you just want to look at an old version of the file, without modifying the working directory, you can do that with -gitlink:git-show[1]: +linkgit:git-show[1]: ------------------------------------------------- $ git show HEAD^:path/to/file @@ -1477,7 +1477,7 @@ Temporarily setting aside work in progress While you are in the middle of working on something complicated, you find an unrelated but obvious and trivial bug. You would like to fix it -before continuing. You can use gitlink:git-stash[1] to save the current +before continuing. You can use linkgit:git-stash[1] to save the current state of your work, and after fixing the bug (or, optionally after doing so on a different branch and then coming back), unstash the work-in-progress changes. @@ -1508,10 +1508,10 @@ Ensuring good performance ------------------------- On large repositories, git depends on compression to keep the history -information from taking up to much space on disk or in memory. +information from taking up too much space on disk or in memory. This compression is not performed automatically. Therefore you -should occasionally run gitlink:git-gc[1]: +should occasionally run linkgit:git-gc[1]: ------------------------------------------------- $ git gc @@ -1529,7 +1529,7 @@ Ensuring reliability Checking the repository for corruption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The gitlink:git-fsck[1] command runs a number of self-consistency checks +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: @@ -1549,8 +1549,8 @@ 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. However, if -you wish, you can remove them with gitlink:git-prune[1] or the --prune -option to gitlink:git-gc[1]: +you wish, you can remove them with linkgit:git-prune[1] or the `--prune` +option to linkgit:git-gc[1]: ------------------------------------------------- $ git gc --prune @@ -1560,7 +1560,7 @@ This may be time-consuming. Unlike most other git operations (including git-gc when run without any options), it is not safe to prune while other git operations are in progress in the same repository. -If gitlink:git-fsck[1] complains about sha1 mismatches or missing +If linkgit:git-fsck[1] complains about sha1 mismatches or missing objects, you may have a much more serious problem; your best option is probably restoring from backups. See <<recovering-from-repository-corruption>> for a detailed discussion. @@ -1573,7 +1573,7 @@ Recovering lost changes Reflogs ^^^^^^^ -Say you modify a branch with gitlink: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. @@ -1585,9 +1585,9 @@ old history using, for example, $ git log master@{1} ------------------------------------------------- -This lists the commits reachable from the previous version of the head. -This syntax can be used to with any git command that accepts a commit, -not just with git log. Some other examples: +This lists the commits reachable from the previous version of the +"master" branch head. This syntax can be used with any git command +that accepts a commit, not just with git log. Some other examples: ------------------------------------------------- $ git show master@{2} # See where the branch pointed 2, @@ -1608,9 +1608,9 @@ pointed to one week ago. This allows you to see the history of what you've checked out. The reflogs are kept by default for 30 days, after which they may be -pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn +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 gitlink:git-rev-parse[1] for details. +section of linkgit:git-rev-parse[1] for details. Note that the reflog history is very different from normal git history. While normal history is shared by every repository that works on the @@ -1675,7 +1675,7 @@ may wish to check the original repository for updates and merge them into your own work. We have already seen <<Updating-a-repository-with-git-fetch,how to -keep remote tracking branches up to date>> with gitlink:git-fetch[1], +keep remote tracking branches up to date>> with linkgit:git-fetch[1], and how to merge two branches. So you can merge in changes from the original repository's master branch with: @@ -1684,7 +1684,7 @@ $ git fetch $ git merge origin/master ------------------------------------------------- -However, the gitlink:git-pull[1] command provides a way to do this in +However, the linkgit:git-pull[1] command provides a way to do this in one step: ------------------------------------------------- @@ -1702,8 +1702,8 @@ $ git pull More generally, a branch that is created from a remote branch will pull by default from that branch. See the descriptions of the branch.<name>.remote and branch.<name>.merge options in -gitlink:git-config[1], and the discussion of the --track option in -gitlink:git-checkout[1], to learn how to control these defaults. +linkgit:git-config[1], and the discussion of the `--track` option in +linkgit:git-checkout[1], to learn how to control these defaults. In addition to saving you keystrokes, "git pull" also helps you by producing a default commit message documenting the branch and @@ -1731,7 +1731,7 @@ Submitting patches to a project If you just have a few changes, the simplest way to submit them may just be to send them as patches in email: -First, use gitlink:git-format-patch[1]; for example: +First, use linkgit:git-format-patch[1]; for example: ------------------------------------------------- $ git format-patch origin @@ -1742,7 +1742,7 @@ for each patch in the current branch but not in origin/HEAD. You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to -use the gitlink:git-send-email[1] script to automate the process. +use the linkgit:git-send-email[1] script to automate the process. Consult the mailing list for your project first to determine how they prefer such patches be handled. @@ -1750,7 +1750,7 @@ prefer such patches be handled. Importing patches to a project ------------------------------ -Git also provides a tool called gitlink:git-am[1] (am stands for +Git also provides a tool called linkgit:git-am[1] (am stands for "apply mailbox"), for importing such an emailed series of patches. Just save all of the patch-containing messages, in order, into a single mailbox file, say "patches.mbox", then run @@ -1785,7 +1785,7 @@ 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 -gitlink:git-pull[1]. In the section "<<getting-updates-with-git-pull, +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. @@ -1800,7 +1800,7 @@ $ git clone /path/to/repository $ git pull /path/to/other/repository ------------------------------------------------- -or an ssh url: +or an ssh URL: ------------------------------------------------- $ git clone ssh://yourhost/~you/repository @@ -1861,19 +1861,19 @@ Exporting a git repository via the git protocol This is the preferred method. If someone else administers the server, they should tell you what -directory to put the repository in, and what git:// url it will appear +directory to put the repository in, and what git:// URL it will appear at. You can then skip to the section "<<pushing-changes-to-a-public-repository,Pushing changes to a public repository>>", below. -Otherwise, all you need to do is start gitlink:git-daemon[1]; it will +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 arguments will further restrict the exports to those paths. You can also run git-daemon as an inetd service; see the -gitlink:git-daemon[1] man page for details. (See especially the +linkgit:git-daemon[1] man page for details. (See especially the examples section.) [[exporting-via-http]] @@ -1895,11 +1895,11 @@ $ chmod a+x hooks/post-update ------------------------------------------------- (For an explanation of the last two lines, see -gitlink:git-update-server-info[1], and the documentation +linkgit:git-update-server-info[1], and the documentation link:hooks.html[Hooks used by git].) -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: +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: ------------------------------------------------- $ git clone http://yourserver.com/~you/proj.git @@ -1920,7 +1920,7 @@ maintainers to fetch your latest changes, but they do not allow write access, which you will need to update the public repository with the latest changes created in your private repository. -The simplest way to do this is using gitlink:git-push[1] and ssh; to +The simplest way to do this is using linkgit:git-push[1] and ssh; to update the remote branch named "master" with the latest state of your branch named "master", run @@ -1961,7 +1961,7 @@ $ git push public-repo master ------------------------------------------------- See the explanations of the remote.<name>.url, branch.<name>.remote, -and remote.<name>.push options in gitlink:git-config[1] for +and remote.<name>.push options in linkgit:git-config[1] for details. [[forcing-push]] @@ -1994,7 +1994,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 descendent of the commit that it pointed to +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>>.) @@ -2083,14 +2083,14 @@ $ cd work ------------------------------------------------- Linus's tree will be stored in the remote branch named origin/master, -and can be updated using gitlink:git-fetch[1]; you can track other -public trees using gitlink:git-remote[1] to set up a "remote" and -gitlink:git-fetch[1] to keep them up-to-date; see +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 <<repositories-and-branches>>. Now create the branches in which you are going to work; these start out at the current tip of origin/master branch, and should be set up (using -the --track option to gitlink:git-branch[1]) to merge changes in from +the --track option to linkgit:git-branch[1]) to merge changes in from Linus by default. ------------------------------------------------- @@ -2098,7 +2098,7 @@ $ git branch --track test origin/master $ git branch --track release origin/master ------------------------------------------------- -These can be easily kept up to date using gitlink:git-pull[1] +These can be easily kept up to date using linkgit:git-pull[1]. ------------------------------------------------- $ git checkout test && git pull @@ -2113,7 +2113,7 @@ doing this capriciously in the "release" branch, as these noisy commits will become part of the permanent history when you ask Linus to pull from the release branch. -A few configuration variables (see gitlink:git-config[1]) can +A few configuration variables (see linkgit:git-config[1]) can make it easy to push both branches to your public tree. (See <<setting-up-a-public-repository>>.) @@ -2127,7 +2127,7 @@ EOF ------------------------------------------------- Then you can push both the test and release trees using -gitlink:git-push[1]: +linkgit:git-push[1]: ------------------------------------------------- $ git push mytree @@ -2190,7 +2190,7 @@ changes are in a specific branch, use: $ git log linux..branchname | git-shortlog ------------------------------------------------- -To see whether it has already been merged into the test or release branches +To see whether it has already been merged into the test or release branches, use: ------------------------------------------------- @@ -2203,12 +2203,12 @@ or $ git log release..branchname ------------------------------------------------- -(If this branch has not yet been merged you will see some log entries. +(If this branch has not yet been merged, you will see some log entries. If it has been merged, then there will be no output.) Once a patch completes the great cycle (moving from test to release, then pulled by Linus, and finally coming back into your local -"origin/master" branch) the branch for this change is no longer needed. +"origin/master" branch), the branch for this change is no longer needed. You detect this when the output from: ------------------------------------------------- @@ -2440,7 +2440,7 @@ the result would create a new merge commit, like this: However, if you prefer to keep the history in mywork a simple series of commits without any merges, you may instead choose to use -gitlink:git-rebase[1]: +linkgit:git-rebase[1]: ------------------------------------------------- $ git checkout mywork @@ -2470,7 +2470,7 @@ $ git rebase --continue and git will continue applying the rest of the patches. -At any point you may use the --abort option to abort this process and +At any point you may use the `--abort` option to abort this process and return mywork to the state it had before you started the rebase: ------------------------------------------------- @@ -2491,7 +2491,7 @@ $ git commit --amend which will replace the old commit by a new commit incorporating your changes, giving you a chance to edit the old commit message first. -You can also use a combination of this and gitlink:git-rebase[1] to +You can also use a combination of this and linkgit:git-rebase[1] to replace a commit further back in your history and recreate the intervening changes on top of it. First, tag the problematic commit with @@ -2529,7 +2529,7 @@ new commits having new object names. Reordering or selecting from a patch series ------------------------------------------- -Given one existing commit, the gitlink:git-cherry-pick[1] command +Given one existing commit, the linkgit:git-cherry-pick[1] command allows you to apply the change introduced by that commit and create a new commit that records it. So, for example, if "mywork" points to a series of patches on top of "origin", you might do something like: @@ -2539,10 +2539,10 @@ $ git checkout -b mywork-new origin $ gitk origin..mywork & ------------------------------------------------- -And browse through the list of patches in the mywork branch using gitk, +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. -The gitlink:git-gui[1] command may also help as it allows you to +cherry-pick, and possibly modifying them as you go using `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"). @@ -2555,7 +2555,7 @@ $ git reset --hard origin ------------------------------------------------- Then modify, reorder, or eliminate patches as preferred before applying -them again with gitlink:git-am[1]. +them again with linkgit:git-am[1]. [[patch-series-tools]] Other tools @@ -2618,7 +2618,7 @@ published branches should never be rewritten. Why bisecting merge commits can be harder than bisecting linear history ----------------------------------------------------------------------- -The gitlink:git-bisect[1] command correctly handles history that +The linkgit:git-bisect[1] command correctly handles history that includes merge commits. However, when the commit that it finds is a merge commit, the user may need to work harder than usual to figure out why that commit introduced a problem. @@ -2651,7 +2651,7 @@ Nevertheless, the code at C is broken, because the callers added on the lower line of development have not been converted to the new semantics introduced on the upper line of development. So if all you know is that D is bad, that Z is good, and that -gitlink:git-bisect[1] identifies C as the culprit, how will you +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 @@ -2688,7 +2688,7 @@ Advanced branch management Fetching individual branches ---------------------------- -Instead of using gitlink:git-remote[1], you can also choose just +Instead of using linkgit:git-remote[1], you can also choose just to update one branch at a time, and to store it locally under an arbitrary name: @@ -2779,7 +2779,7 @@ Configuring remote branches We saw above that "origin" is just a shortcut to refer to the repository that you originally cloned from. This information is stored in git configuration variables, which you can see using -gitlink:git-config[1]: +linkgit:git-config[1]: ------------------------------------------------- $ git config -l @@ -2832,9 +2832,9 @@ throwing away commits on mybranch. Also note that all of the above configuration can be performed by directly editing the file .git/config instead of using -gitlink:git-config[1]. +linkgit:git-config[1]. -See gitlink:git-config[1] for more details on the configuration +See linkgit:git-config[1] for more details on the configuration options mentioned above. @@ -2865,7 +2865,7 @@ others: - Git can quickly determine whether two objects are identical or not, just by comparing names. -- Since object names are computed the same way in ever repository, the +- Since object names are computed the same way in every repository, the 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 @@ -2882,7 +2882,7 @@ There are four different types of objects: "blob", "tree", "commit", and "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 - together into a <<def_DAG,directed acyclic graph>> of revisions - each + together into a <<def_DAG,directed acyclic graph>> of revisions--each commit contains the object name of exactly one tree designating the directory hierarchy at the time of the commit. In addition, a commit refers to "parent" commit objects that describe the history of how we @@ -2900,7 +2900,7 @@ Commit Object The "commit" object links a physical state of a tree with a description of how we got there and why. Use the --pretty=raw option to -gitlink:git-show[1] or gitlink:git-log[1] to examine your favorite +linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite commit: ------------------------------------------------ @@ -2921,7 +2921,7 @@ As you can see, a commit is defined by: - a tree: The SHA1 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 - immediately prevoius step(s) in the history of the project. 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 represents the initial revision of a project. Each project must have @@ -2941,9 +2941,9 @@ of the tree referred to by this commit with the trees associated with its parents. In particular, git does not attempt to record file renames explicitly, though it can identify cases where the existence of the same file data at changing paths suggests a rename. (See, for example, the --M option to gitlink:git-diff[1]). +-M option to linkgit:git-diff[1]). -A commit is usually created by gitlink:git-commit[1], which creates a +A commit is usually created by linkgit:git-commit[1], which creates a commit whose parent is normally the current HEAD, and whose tree is taken from the content currently stored in the index. @@ -2951,8 +2951,8 @@ taken from the content currently stored in the index. Tree Object ~~~~~~~~~~~ -The ever-versatile gitlink:git-show[1] command can also be used to -examine tree objects, but gitlink:git-ls-tree[1] will give you more +The ever-versatile linkgit:git-show[1] command can also be used to +examine tree objects, but linkgit:git-ls-tree[1] will give you more details: ------------------------------------------------ @@ -2991,7 +2991,7 @@ attention to the executable bit. Blob Object ~~~~~~~~~~~ -You can use gitlink:git-show[1] to examine the contents of a blob; take, +You can use linkgit:git-show[1] to examine the contents of a blob; take, for example, the blob in the entry for "COPYING" from the tree above: ------------------------------------------------ @@ -3013,7 +3013,7 @@ is totally independent of its location in the directory tree, and renaming a file does not change the object that file is associated with. Note that any tree or blob object can be examined using -gitlink:git-show[1] with the <revision>:<path> syntax. This can +linkgit:git-show[1] with the <revision>:<path> syntax. This can sometimes be useful for browsing the contents of a tree that is not currently checked out. @@ -3053,7 +3053,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 gitlink:git-cat-file[1]: +a signature, as can be seen using the linkgit:git-cat-file[1]: ------------------------------------------------ $ git cat-file tag v1.5.0 @@ -3072,8 +3072,8 @@ nLE/L9aUXdWeTFPron96DLA= -----END PGP SIGNATURE----- ------------------------------------------------ -See the gitlink:git-tag[1] command to learn how to create and verify tag -objects. (Note that gitlink:git-tag[1] can also be used to create +See the linkgit:git-tag[1] command to learn how to create and verify tag +objects. (Note that linkgit:git-tag[1] can also be used to create "lightweight tags", which are not tag objects at all, but just simple references whose names begin with "refs/tags/"). @@ -3135,14 +3135,14 @@ $ git count-objects Although the object files are gone, any commands that refer to those objects will work exactly as they did before. -The gitlink:git-gc[1] command performs packing, pruning, and more for +The linkgit:git-gc[1] command performs packing, pruning, and more for you, so is normally the only high-level command you need. [[dangling-objects]] Dangling objects ~~~~~~~~~~~~~~~~ -The gitlink:git-fsck[1] command will sometimes complain about dangling +The linkgit:git-fsck[1] command will sometimes complain about dangling objects. They are not a problem. The most common cause of dangling objects is that you've rebased a @@ -3155,7 +3155,7 @@ There are also other situations that cause dangling objects. For example, a "dangling blob" may arise because you did a "git add" of a file, but then, before you actually committed it and made it part of the bigger picture, you changed something else in that file and committed -that *updated* thing - the old state that you added originally ends up +that *updated* thing--the old state that you added originally ends up not being pointed to by any commit or tree, so it's now a dangling blob object. @@ -3170,7 +3170,7 @@ up pointing to them, so they end up "dangling" in your repository. Generally, dangling objects aren't anything to worry about. They can even be very useful: if you screw something up, the dangling objects can be how you recover your old tree (say, you did a rebase, and realized -that you really didn't want to - you can look at what dangling objects +that you really didn't want to--you can look at what dangling objects you have, and decide to reset your head to some old dangling state). For commits, you can just use: @@ -3214,10 +3214,10 @@ $ git prune ------------------------------------------------ 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 +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 +(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 @@ -3242,11 +3242,11 @@ to replace them by hand. Back up your repository before attempting this in case you corrupt things even more in the process. We'll assume that the problem is a single missing or corrupted blob, -which is sometimes a solveable problem. (Recovering missing trees and +which is sometimes a solvable problem. (Recovering missing trees and especially commits is *much* harder). Before starting, verify that there is corruption, and figure out where -it is with gitlink:git-fsck[1]; this may be time-consuming. +it is with linkgit:git-fsck[1]; this may be time-consuming. Assume the output looks like this: @@ -3264,7 +3264,7 @@ 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 .git/objects/4b/9458b3... and be done. Suppose you can't. You can -still examine the tree that pointed to it with gitlink:git-ls-tree[1], +still examine the tree that pointed to it with linkgit:git-ls-tree[1], which might output something like: ------------------------------------------------ @@ -3282,7 +3282,7 @@ So now you know that the missing blob was the data for a file named say it's in "somedirectory". If you're lucky the missing copy might be the same as the copy you have checked out in your working tree at "somedirectory/myfile"; you can test whether that's right with -gitlink:git-hash-object[1]: +linkgit:git-hash-object[1]: ------------------------------------------------ $ git hash-object -w somedirectory/myfile @@ -3336,14 +3336,14 @@ $ git hash-object -w <recreated-file> and your repository is good again! -(Btw, you could have ignored the fsck, and started with doing a +(Btw, you could have ignored the fsck, and started with doing a ------------------------------------------------ $ git log --raw --all ------------------------------------------------ -and just looked for the sha of the missing object (4b9458b..) in that -whole thing. It's up to you - git does *have* a lot of information, it is +and just looked for the sha of the missing object (4b9458b..) in that +whole thing. It's up to you - git does *have* a lot of information, it is just missing one particular blob version. [[the-index]] @@ -3352,7 +3352,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 -object; gitlink:git-ls-files[1] can show you the contents of the index: +object; linkgit:git-ls-files[1] can show you the contents of the index: ------------------------------------------------- $ git ls-files --stage @@ -3374,7 +3374,7 @@ properties: 1. The index contains all the information necessary to generate a single (uniquely determined) tree object. + -For example, running gitlink:git-commit[1] generates this tree object +For example, running linkgit:git-commit[1] generates this tree object from the index, stores it in the object database, and uses it as the tree object associated with the new commit. @@ -3395,7 +3395,7 @@ you can create a three-way merge between them. + We saw in <<conflict-resolution>> that during a merge the index can store multiple versions of a single file (called "stages"). The third -column in the gitlink:git-ls-files[1] output above is the stage +column in the linkgit:git-ls-files[1] output above is the stage number, and will take on values other than 0 for files with merge conflicts. @@ -3444,7 +3444,7 @@ commit ID, so other developers who clone the containing project Partial checkouts of the superproject are possible: you can tell Git to clone none, some or all of the submodules. -The gitlink:git-submodule[1] command is available since Git 1.5.3. Users +The linkgit:git-submodule[1] command is available since Git 1.5.3. Users with Git 1.5.2 can look up the submodule commits in the repository and manually check them out; earlier versions won't recognize the submodules at all. @@ -3492,7 +3492,7 @@ The `git submodule add` command does a couple of things: - It clones the submodule under the current directory and by default checks out the master branch. -- It adds the submodule's clone path to the gitlink:gitmodules[5] file and +- 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 committed. @@ -3653,28 +3653,29 @@ understand its inner workings. Object access and manipulation ------------------------------ -The gitlink:git-cat-file[1] command can show the contents of any object, -though the higher-level gitlink:git-show[1] is usually more useful. +The linkgit:git-cat-file[1] command can show the contents of any object, +though the higher-level linkgit:git-show[1] is usually more useful. -The gitlink:git-commit-tree[1] command allows constructing commits with +The linkgit:git-commit-tree[1] command allows constructing commits with arbitrary parents and trees. -A tree can be created with gitlink:git-write-tree[1] and its data can be -accessed by gitlink:git-ls-tree[1]. Two trees can be compared with -gitlink:git-diff-tree[1]. +A tree can be created with linkgit:git-write-tree[1] and its data can be +accessed by linkgit:git-ls-tree[1]. Two trees can be compared with +linkgit:git-diff-tree[1]. -A tag is created with gitlink:git-mktag[1], and the signature can be -verified by gitlink:git-verify-tag[1], though it is normally simpler to -use gitlink:git-tag[1] for both. +A tag is created with linkgit:git-mktag[1], and the signature can be +verified by linkgit:git-verify-tag[1], though it is normally simpler to +use linkgit:git-tag[1] for both. [[the-workflow]] The Workflow ------------ -High-level operations such as gitlink:git-commit[1], -gitlink:git-checkout[1] and git-reset[1] work by moving data between the -working tree, the index, and the object database. Git provides -low-level operations which perform each of these steps individually. +High-level operations such as linkgit:git-commit[1], +linkgit:git-checkout[1] and linkgit:git-reset[1] work by moving data +between the working tree, the index, and the object database. Git +provides low-level operations which perform each of these steps +individually. Generally, all "git" operations work on the index file. Some operations work *purely* on the index file (showing the current state of the @@ -3686,7 +3687,7 @@ combinations: working directory -> index ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The gitlink:git-update-index[1] command updates the index with +The linkgit:git-update-index[1] command updates the index with information from the working directory. You generally update the index information by just specifying the filename you want to update, like so: @@ -3716,8 +3717,8 @@ stat information. It will 'not' update the object status itself, and it will only update the fields that are used to quickly test whether an object still matches its old backing store object. -The previously introduced gitlink:git-add[1] is just a wrapper for -gitlink:git-update-index[1]. +The previously introduced linkgit:git-add[1] is just a wrapper for +linkgit:git-update-index[1]. [[index-to-object-database]] index -> object database @@ -3729,7 +3730,7 @@ You write your current index file to a "tree" object with the program $ git write-tree ------------------------------------------------- -that doesn't come with any options - it will just write out the +that doesn't come with any options--it will just write out the current index into the set of tree objects that describe that state, and it will return the name of the resulting top-level tree. You can use that tree to re-generate the index at any time by going in the @@ -3740,7 +3741,7 @@ object database -> index ~~~~~~~~~~~~~~~~~~~~~~~~ You read a "tree" file from the object database, and use that to -populate (and overwrite - don't do this if your index contains any +populate (and overwrite--don't do this if your index contains any unsaved state that you might want to restore later!) your current index. Normal operation is just @@ -3788,7 +3789,7 @@ Tying it all together 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 +behind it--most notably the "parent" commits that preceded it in history. Normally a "commit" has one parent: the previous state of the tree @@ -3864,7 +3865,7 @@ Examining the data You can examine the data represented in the object database and the index with various helper tools. For every object, you can use -gitlink:git-cat-file[1] to examine details about the +linkgit:git-cat-file[1] to examine details about the object: ------------------------------------------------- @@ -3931,7 +3932,7 @@ Once you know the three trees you are going to merge (the one "original" tree, aka the common tree, and the two "result" trees, aka the branches you want to merge), you do a "merge" read into the index. This will complain if it has to throw away your old index contents, so you should -make sure that you've committed those - in fact you would normally +make sure that you've committed those--in fact you would normally always do a merge against your last commit (which should thus match what you have in your current index anyway). @@ -3951,7 +3952,7 @@ Merging multiple trees, continued --------------------------------- Sadly, many merges aren't trivial. If there are files that have -been added.moved or removed, or if both branches have modified the +been added, moved or removed, or if both branches have modified the same file, you will be left with an index tree that contains "merge 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 @@ -4203,7 +4204,7 @@ Two things are interesting here: - `get_sha1()` returns 0 on _success_. This might surprise some new Git hackers, but there is a long tradition in UNIX to return different - negative numbers in case of different errors -- and 0 on success. + 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 @@ -4308,7 +4309,7 @@ $ git branch new # create branch "new" starting at current HEAD $ git branch -d new # delete branch "new" ----------------------------------------------- -Instead of basing new branch on current HEAD (the default), use: +Instead of basing a new branch on current HEAD (the default), use: ----------------------------------------------- $ git branch new test # branch named "test" @@ -4527,7 +4528,7 @@ Scan Documentation/ for other stuff left out; in particular: - howto's - some of technical/? - hooks -- list of commands in gitlink:git[1] +- list of commands in linkgit:git[1] Scan email archives for other stuff left out |