diff options
Diffstat (limited to 'Documentation')
192 files changed, 6878 insertions, 902 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 1c3a9fead5..d62aebd848 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -3,6 +3,7 @@ *.[1-8] *.made *.texi +*.pdf git.info gitman.info howto-index.txt diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index fe1c1e5bc2..483008699f 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -81,6 +81,10 @@ For shell scripts specifically (not exhaustive): are ERE elements not BRE (note that \? and \+ are not even part of BRE -- making them accessible from BRE is a GNU extension). + - Use Git's gettext wrappers in git-sh-i18n to make the user + interface translatable. See "Marking strings for translation" in + po/README. + For C programs: - We use tabs to indent, and interpret tabs as taking up to @@ -144,6 +148,9 @@ For C programs: - When we pass <string, length> pair to functions, we should try to pass them in that order. + - Use Git's gettext wrappers to make the user interface + translatable. See "Marking strings for translation" in po/README. + Writing Documentation: Every user-visible change should be reflected in the documentation. diff --git a/Documentation/Makefile b/Documentation/Makefile index 36989b7f65..d40e211f22 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,12 +1,13 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ - gitk.txt git.txt + gitk.txt gitweb.txt git.txt MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ - gitrepository-layout.txt + gitrepository-layout.txt gitweb.conf.txt MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \ gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \ - gitdiffcore.txt gitrevisions.txt gitworkflows.txt + gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt +MAN7_TXT += gitcredentials.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) @@ -19,7 +20,10 @@ ARTICLES += everyday ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. -SP_ARTICLES = howto/revert-branch-rebase howto/using-merge-subtree user-manual +SP_ARTICLES = user-manual +SP_ARTICLES += howto/revert-branch-rebase +SP_ARTICLES += howto/using-merge-subtree +SP_ARTICLES += howto/using-signed-tag-in-pull-request API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) SP_ARTICLES += technical/api-index @@ -46,8 +50,8 @@ MANPAGE_XSL = manpage-normal.xsl XMLTO_EXTRA = INSTALL?=install RM ?= rm -f -DOC_REF = origin/man -HTML_REF = origin/html +MAN_REPO = ../../git-manpages +HTML_REPO = ../../git-htmldocs infodir?=$(prefix)/share/info MAKEINFO=makeinfo @@ -232,6 +236,7 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) clean: $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 $(RM) *.texi *.texi+ *.texi++ git.info gitman.info + $(RM) *.pdf $(RM) howto-index.txt howto/*.html doc.dep $(RM) technical/api-*.html technical/api-index.txt $(RM) $(cmds_txt) *.made @@ -326,12 +331,23 @@ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt install-webdoc : html '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST) +# You must have a clone of git-htmldocs and git-manpages repositories +# next to the git repository itself for the following to work. + quick-install: quick-install-man -quick-install-man: - '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(DOC_REF) $(DESTDIR)$(mandir) +require-manrepo:: + @if test ! -d $(MAN_REPO); \ + then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi + +quick-install-man: require-manrepo + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) + +require-htmlrepo:: + @if test ! -d $(HTML_REPO); \ + then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi -quick-install-html: - '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir) +quick-install-html: require-htmlrepo + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) .PHONY: FORCE diff --git a/Documentation/RelNotes/1.7.5.1.txt b/Documentation/RelNotes/1.7.5.1.txt new file mode 100644 index 0000000000..c6ebd76d19 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.1.txt @@ -0,0 +1,47 @@ +Git v1.7.5.1 Release Notes +========================== + +Fixes since v1.7.5 +------------------ + + * When an object "$tree:$path" does not exist, if $path does exist in the + subtree of $tree that corresponds to the subdirectory the user is in, + git now suggests using "$tree:./$path" in addition to the advice to use + the full path from the root of the working tree. + + * The "--date=relative" output format used to say "X years, 12 months" + when it should have said "X+1 years". + + * The smart-HTTP transfer was broken in 1.7.5 when the client needs + to issue a small POST (which uses content-length) and then a large + POST (which uses chunked) back to back. + + * "git clean" used to fail on an empty directory that is not readable, + even though rmdir(2) could remove such a directory. Now we attempt it + as the last resort. + + * The "--dirstat" option of "diff" family of commands used to totally + ignore a change that only rearranged lines within a file. Such a + change now counts as at least a minimum but non zero change. + + * The "--dirstat" option of "diff" family of commands used to use the + pathname in the original, instead of the pathname in the result, + when renames are involved. + + * "git pack-object" did not take core.bigfilethreashold into account + (unlike fast-import); now it does. + + * "git reflog" ignored options like "--format=.." on the command line. + + * "git stash apply" used to refuse to work if there was any change in + the working tree, even when the change did not overlap with the change + the stash recorded. + + * "git stash apply @{99999}" was not diagnosed as an error, even when you + did not have that many stash entries. + + * An error message from "git send-email" to diagnose a broken SMTP + connection configuration lacked a space between "hello=<smtp-domain>" + and "port=<smtp-server-port>". + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.2.txt b/Documentation/RelNotes/1.7.5.2.txt new file mode 100644 index 0000000000..951eb7cb08 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.2.txt @@ -0,0 +1,57 @@ +Git v1.7.5.2 Release Notes +========================== + +The release notes to 1.7.5.1 forgot to mention: + + * "git stash -p --no-keep-index" and "git stash --no-keep-index -p" now + mean the same thing. + + * "git upload-pack" (hence "git push" over git native protocol) had a + subtle race condition that could lead to a deadlock. + +Fixes since v1.7.5.1 +-------------------- + + * "git add -p" did not work correctly when a hunk is split and then + one of them was given to the editor. + + * "git add -u" did not resolve a conflict where our history deleted and + their history modified the same file, and the working tree resolved to + keep a file. + + * "git cvsimport" did not know that CVSNT stores its password file in a + location different from the traditional CVS. + + * "git diff-files" did not show the mode information from the working + tree side of an unmerged path correctly. + + * "git diff -M --cached" used to use unmerged path as a possible rename + source candidate, which made no sense. + + * The option name parser in "git fast-import" used prefix matches for + some options where it shouldn't, and accepted non-existent options, + e.g. "--relative-marksmith" or "--forceps". + + * "git format-patch" did not quote RFC822 special characters in the + email address (e.g From: Junio C. Hamano <jch@example.com>, not + From: "Junio C. Hamano" <jch@example.com>). + + * "git format-patch" when run with "--quiet" option used to produce a + nonsense result that consists of alternating empty output. + + * In "git merge", per-branch branch.<name>.mergeoptions configuration + variables did not override the fallback default merge.<option> + configuration variables such as merge.ff, merge.log, etc. + + * "git merge-one-file" did not honor GIT_WORK_TREE settings when + handling a "both sides added, differently" conflict. + + * "git mergetool" did not handle conflicted submoudules gracefully. + + * "git-p4" (in contrib) used a wrong base image while merge a file that + was added on both branches differently. + + * "git rebase -i -p" failed to preserve the history when there is a + redundant merge created with the --no-ff option. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.3.txt b/Documentation/RelNotes/1.7.5.3.txt new file mode 100644 index 0000000000..9c03353af2 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.3.txt @@ -0,0 +1,32 @@ +Git v1.7.5.3 Release Notes +========================== + +Fixes since v1.7.5.2 +-------------------- + + * The bash completion scripts should correctly work using zsh's bash + completion emulation layer now. + + * Setting $(prefix) in config.mak did not affect where etc/gitconfig + file is read from, even though passing it from the command line of + $(MAKE) did. + + * The logic to handle "&" (expand to UNIX username) in GECOS field + miscounted the length of the name it formatted. + + * "git cherry-pick -s resolve" failed to cherry-pick a root commit. + + * "git diff --word-diff" misbehaved when diff.suppress-blank-empty was + in effect. + + * "git log --stdin path" with an input that has additional pathspec + used to corrupt memory. + + * "git send-pack" (hence "git push") over smalt-HTTP protocol could + deadlock when the client side pack-object died early. + + * Compressed tarball gitweb generates used to be made with the timestamp + of the tarball generation; this was bad because snapshot from the same + tree should result in a same tarball. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.4.txt b/Documentation/RelNotes/1.7.5.4.txt new file mode 100644 index 0000000000..cf3f455ced --- /dev/null +++ b/Documentation/RelNotes/1.7.5.4.txt @@ -0,0 +1,21 @@ +Git v1.7.5.4 Release Notes +========================== + +Fixes since v1.7.5.3 +-------------------- + + * The single-key mode of "git add -p" was easily fooled into thinking + that it was told to add everthing ('a') when up-arrow was pressed by + mistake. + + * Setting a git command that uses custom configuration via "-c var=val" + as an alias caused a crash due to a realloc(3) failure. + + * "git diff -C -C" used to disable the rename detection entirely when + there are too many copy candidate paths in the tree; now it falls + back to "-C" when doing so would keep the copy candidate paths + under the rename detection limit. + + * "git rerere" did not diagnose a corrupt MERGE_RR file in some cases. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.1.txt b/Documentation/RelNotes/1.7.6.1.txt new file mode 100644 index 0000000000..42e46ab17f --- /dev/null +++ b/Documentation/RelNotes/1.7.6.1.txt @@ -0,0 +1,63 @@ +Git v1.7.6.1 Release Notes +========================== + +Fixes since v1.7.6 +------------------ + + * Various codepaths that invoked zlib deflate/inflate assumed that these + functions can compress or uncompress more than 4GB data in one call on + platforms with 64-bit long, which has been corrected. + + * "git unexecutable" reported that "unexecutable" was not found, even + though the actual error was that "unexecutable" was found but did + not have a proper she-bang line to be executed. + + * Error exits from $PAGER were silently ignored. + + * "git checkout -b <branch>" was confused when attempting to create a + branch whose name ends with "-g" followed by hexadecimal digits, + and refused to work. + + * "git checkout -b <branch>" sometimes wrote a bogus reflog entry, + causing later "git checkout -" to fail. + + * "git diff --cc" learned to correctly ignore binary files. + + * "git diff -c/--cc" mishandled a deletion that resolves a conflict, and + looked in the working tree instead. + + * "git fast-export" forgot to quote pathnames with unsafe characters + in its output. + + * "git fetch" over smart-http transport used to abort when the + repository was updated between the initial connection and the + subsequent object transfer. + + * "git fetch" did not recurse into submodules in subdirectories. + + * "git ls-tree" did not error out when asked to show a corrupt tree. + + * "git pull" without any argument left an extra whitespace after the + command name in its reflog. + + * "git push --quiet" was not really quiet. + + * "git rebase -i -p" incorrectly dropped commits from side branches. + + * "git reset [<commit>] paths..." did not reset the index entry correctly + for unmerged paths. + + * "git submodule add" did not allow a relative repository path when + the superproject did not have any default remote url. + + * "git submodule foreach" failed to correctly give the standard input to + the user-supplied command it invoked. + + * submodules that the user has never showed interest in by running + "git submodule init" was incorrectly marked as interesting by "git + submodule sync". + + * "git submodule update --quiet" was not really quiet. + + * "git tag -l <glob>..." did not take multiple glob patterns from the + command line. diff --git a/Documentation/RelNotes/1.7.6.2.txt b/Documentation/RelNotes/1.7.6.2.txt new file mode 100644 index 0000000000..67ae414965 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.2.txt @@ -0,0 +1,8 @@ +Git v1.7.6.2 Release Notes +========================== + +Fixes since v1.7.6.1 +-------------------- + + * v1.7.6.1 broke "git push --quiet"; it used to be a no-op against an old + version of Git running on the other end, but v1.7.6.1 made it abort. diff --git a/Documentation/RelNotes/1.7.6.3.txt b/Documentation/RelNotes/1.7.6.3.txt new file mode 100644 index 0000000000..95971831b9 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.3.txt @@ -0,0 +1,24 @@ +Git v1.7.6.3 Release Notes +========================== + +Fixes since v1.7.6.2 +-------------------- + + * "git -c var=value subcmd" misparsed the custom configuration when + value contained an equal sign. + + * "git fetch" had a major performance regression, wasting many + needless cycles in a repository where there is no submodules + present. This was especially bad, when there were many refs. + + * "git reflog $refname" did not default to the "show" subcommand as + the documentation advertised the command to do. + + * "git reset" did not leave meaningful log message in the reflog. + + * "git status --ignored" did not show ignored items when there is no + untracked items. + + * "git tag --contains $commit" was unnecessarily inefficient. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.4.txt b/Documentation/RelNotes/1.7.6.4.txt new file mode 100644 index 0000000000..e19acac2da --- /dev/null +++ b/Documentation/RelNotes/1.7.6.4.txt @@ -0,0 +1,32 @@ +Git v1.7.6.4 Release Notes +========================== + +Fixes since v1.7.6.3 +-------------------- + + * The error reporting logic of "git am" when the command is fed a file + whose mail-storage format is unknown was fixed. + + * "git branch --set-upstream @{-1} foo" did not expand @{-1} correctly. + + * "git check-ref-format --print" used to parrot a candidate string that + began with a slash (e.g. /refs/heads/master) without stripping it, to make + the result a suitably normalized string the caller can append to "$GIT_DIR/". + + * "git clone" failed to clone locally from a ".git" file that itself + is not a directory but is a pointer to one. + + * "git clone" from a local repository that borrows from another + object store using a relative path in its objects/info/alternates + file did not adjust the alternates in the resulting repository. + + * "git describe --dirty" did not refresh the index before checking the + state of the working tree files. + + * "git ls-files ../$path" that is run from a subdirectory reported errors + incorrectly when there is no such path that matches the given pathspec. + + * "git mergetool" could loop forever prompting when nothing can be read + from the standard input. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.5.txt b/Documentation/RelNotes/1.7.6.5.txt new file mode 100644 index 0000000000..6713132a9e --- /dev/null +++ b/Documentation/RelNotes/1.7.6.5.txt @@ -0,0 +1,26 @@ +Git v1.7.6.5 Release Notes +========================== + +Fixes since v1.7.6.4 +-------------------- + + * The date parser did not accept timezone designators that lack minutes + part and also has a colon between "hh:mm". + + * After fetching from a remote that has very long refname, the reporting + output could have corrupted by overrunning a static buffer. + + * "git mergetool" did not use its arguments as pathspec, but as a path to + the file that may not even have any conflict. + + * "git name-rev --all" tried to name all _objects_, naturally failing to + describe many blobs and trees, instead of showing only commits as + advertised in its documentation. + + * "git remote rename $a $b" were not careful to match the remote name + against $a (i.e. source side of the remote nickname). + + * "gitweb" used to produce a non-working link while showing the contents + of a blob, when JavaScript actions are enabled. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.6.txt b/Documentation/RelNotes/1.7.6.6.txt new file mode 100644 index 0000000000..5343e00400 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.6.txt @@ -0,0 +1,16 @@ +Git v1.7.6.6 Release Notes +========================== + +Fixes since v1.7.6.5 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.txt b/Documentation/RelNotes/1.7.6.txt new file mode 100644 index 0000000000..9ec498ea39 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.txt @@ -0,0 +1,136 @@ +Git v1.7.6 Release Notes +======================== + +Updates since v1.7.5 +-------------------- + + * Various git-svn updates. + + * Updates the way content tags are handled in gitweb. Also adds + a UI to choose common timezone for displaying the dates. + + * Similar to branch names, tagnames that begin with "-" are now + disallowed. + + * Clean-up of the C part of i18n (but not l10n---please wait) + continues. + + * The scripting part of the codebase is getting prepared for i18n/l10n. + + * Pushing and pulling from a repository with large number of refs that + point to identical commits are optimized by not listing the same commit + during the common ancestor negotiation exchange with the other side. + + * Adding a file larger than core.bigfilethreshold (defaults to 1/2 Gig) + using "git add" will send the contents straight to a packfile without + having to hold it and its compressed representation both at the same + time in memory. + + * Processes spawned by "[alias] <name> = !process" in the configuration + can inspect GIT_PREFIX environment variable to learn where in the + working tree the original command was invoked. + + * A magic pathspec ":/" tells a command that limits its operation to + the current directory when ran from a subdirectory to work on the + entire working tree. In general, ":/path/to/file" would be relative + to the root of the working tree hierarchy. + + After "git reset --hard; edit Makefile; cd t/", "git add -u" would + be a no-op, but "git add -u :/" would add the updated contents of + the Makefile at the top level. If you want to name a path in the + current subdirectory whose unusual name begins with ":/", you can + name it by "./:/that/path" or by "\:/that/path". + + * "git blame" learned "--abbrev[=<n>]" option to control the minimum + number of hexdigits shown for commit object names. + + * "git blame" learned "--line-porcelain" that is less efficient but is + easier to parse. + + * Aborting "git commit --interactive" discards updates to the index + made during the interactive session. + + * "git commit" learned a "--patch" option to directly jump to the + per-hunk selection UI of the interactive mode. + + * "git diff" and its family of commands learned --dirstat=0 to show + directories that contribute less than 0.1% of changes. + + * "git diff" and its family of commands learned --dirstat=lines mode to + assess damage to the directory based on number of lines in the patch + output, not based on the similarity numbers. + + * "git format-patch" learned "--quiet" option to suppress the output of + the names of generated files. + + * "git format-patch" quotes people's names when it has RFC822 special + characters in it, e.g. "Junio C. Hamano" <jch@example.com>. Earlier + it was up to the user to do this when using its output. + + * "git format-patch" can take an empty --subject-prefix now. + + * "git grep" learned the "-P" option to take pcre regular expressions. + + * "git log" and friends learned a new "--notes" option to replace the + "--show-notes" option. Unlike "--show-notes", "--notes=<ref>" does + not imply showing the default notes. + + * They also learned a log.abbrevCommit configuration variable to augment + the --abbrev-commit command line option. + + * "git ls-remote" learned "--exit-code" option to consider it a + different kind of error when no remote ref to be shown. + + * "git merge" learned "-" as a short-hand for "the previous branch", just + like the way "git checkout -" works. + + * "git merge" uses "merge.ff" configuration variable to decide to always + create a merge commit (i.e. --no-ff, aka merge.ff=no), refuse to create + a merge commit (i.e. --ff-only, aka merge.ff=only). Setting merge.ff=yes + (or not setting it at all) restores the default behaviour of allowing + fast-forward to happen when possible. + + * p4-import (from contrib) learned a new option --preserve-user. + + * "git read-tree -m" learned "--dry-run" option that reports if a merge + would fail without touching the index nor the working tree. + + * "git rebase" that does not specify on top of which branch to rebase + the current branch now uses @{upstream} of the current branch. + + * "git rebase" finished either normally or with --abort did not + update the reflog for HEAD to record the event to come back to + where it started from. + + * "git remote add -t only-this-branch --mirror=fetch" is now allowed. Earlier + a fetch-mode mirror meant mirror everything, but now it only means refs are + not renamed. + + * "git rev-list --count" used with "--cherry-mark" counts the cherry-picked + commits separately, producing more a useful output. + + * "git submodule update" learned "--force" option to get rid of local + changes in submodules and replace them with the up-to-date version. + + * "git status" and friends ignore .gitmodules file while the file is + still in a conflicted state during a merge, to avoid using information + that is not final and possibly corrupt with conflict markers. + +Also contains various documentation updates and minor miscellaneous +changes. + + +Fixes since v1.7.5 +------------------ + +Unless otherwise noted, all the fixes in 1.7.5.X maintenance track are +included in this release. + + * "git config" used to choke with an insanely long line. + (merge ef/maint-strbuf-init later) + + * "git diff --quiet" did not work well with --diff-filter. + (merge jk/diff-not-so-quick later) + + * "git status -z" did not default to --porcelain output format. + (merge bc/maint-status-z-to-use-porcelain later) diff --git a/Documentation/RelNotes/1.7.7.1.txt b/Documentation/RelNotes/1.7.7.1.txt new file mode 100644 index 0000000000..ac9b838e25 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.1.txt @@ -0,0 +1,60 @@ +Git v1.7.7.1 Release Notes +========================== + +Fixes since v1.7.7 +------------------ + + * On some BSD systems, adding +s bit on directories is detrimental + (it is not necessary on BSD to begin with). "git init --shared" + has been updated to take this into account without extra makefile + settings on platforms the Makefile knows about. + + * After incorrectly written third-party tools store a tag object in + HEAD, git diagnosed it as a repository corruption and refused to + proceed in order to avoid spreading the damage. We now gracefully + recover from such a situation by pretending as if the commit that + is pointed at by the tag were in HEAD. + + * "git apply --whitespace=error" did not bother to report the exact + line number in the patch that introduced new blank lines at the end + of the file. + + * "git apply --index" did not check corrupted patch. + + * "git checkout $tree $directory/" resurrected paths locally removed or + modified only in the working tree in $directory/ that did not appear + in $directory of the given $tree. They should have been kept intact. + + * "git diff $tree $path" used to apply the pathspec at the output stage, + reading the whole tree, wasting resources. + + * The code to check for updated submodules during a "git fetch" of the + superproject had an unnecessary quadratic loop. + + * "git fetch" from a large bundle did not enable the progress output. + + * When "git fsck --lost-and-found" found that an empty blob object in the + object store is unreachable, it incorrectly reported an error after + writing the lost blob out successfully. + + * "git filter-branch" did not refresh the index before checking that the + working tree was clean. + + * "git grep $tree" when run with multiple threads had an unsafe access to + the object database that should have been protected with mutex. + + * The "--ancestry-path" option to "git log" and friends misbehaved in a + history with complex criss-cross merges and showed an uninteresting + side history as well. + + * Test t1304 assumed LOGNAME is always set, which may not be true on + some systems. + + * Tests with --valgrind failed to find "mergetool" scriptlets. + + * "git patch-id" miscomputed the patch-id in a patch that has a line longer + than 1kB. + + * When an "exec" insn failed after modifying the index and/or the working + tree during "rebase -i", we now check and warn that the changes need to + be cleaned up. diff --git a/Documentation/RelNotes/1.7.7.2.txt b/Documentation/RelNotes/1.7.7.2.txt new file mode 100644 index 0000000000..e6bbef2f01 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.2.txt @@ -0,0 +1,44 @@ +Git v1.7.7.2 Release Notes +========================== + +Fixes since v1.7.7.1 +-------------------- + + * We used to drop error messages from libcurl on certain kinds of + errors. + + * Error report from smart HTTP transport, when the connection was + broken in the middle of a transfer, showed a useless message on + a corrupt packet. + + * "git fetch --prune" was unsafe when used with refspecs from the + command line. + + * The attribute mechanism did not use case insensitive match when + core.ignorecase was set. + + * "git bisect" did not notice when it failed to update the working tree + to the next commit to be tested. + + * "git config --bool --get-regexp" failed to separate the variable name + and its value "true" when the variable is defined without "= true". + + * "git remote rename $a $b" were not careful to match the remote name + against $a (i.e. source side of the remote nickname). + + * "git mergetool" did not use its arguments as pathspec, but as a path to + the file that may not even have any conflict. + + * "git diff --[num]stat" used to use the number of lines of context + different from the default, potentially giving different results from + "git diff | diffstat" and confusing the users. + + * "git pull" and "git rebase" did not work well even when GIT_WORK_TREE is + set correctly with GIT_DIR if the current directory is outside the working + tree. + + * "git send-email" did not honor the configured hostname when restarting + the HELO/EHLO exchange after switching TLS on. + + * "gitweb" used to produce a non-working link while showing the contents + of a blob, when JavaScript actions are enabled. diff --git a/Documentation/RelNotes/1.7.7.3.txt b/Documentation/RelNotes/1.7.7.3.txt new file mode 100644 index 0000000000..09301f0957 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.3.txt @@ -0,0 +1,19 @@ +Git v1.7.7.3 Release Notes +========================== + +Fixes since v1.7.7.2 +-------------------- + + * Adjust the "quick-install-doc" procedures as preformatted + html/manpage are no longer in the source repository. + + * The logic to optimize the locality of the data in a pack introduced in + 1.7.7 was grossly inefficient. + + * The logic to filter out forked projects in the project list in + "gitweb" was broken for some time. + + * "git branch -m/-M" advertised to update RENAME_REF ref in the + commit log message that introduced the feature but not anywhere in + the documentation, and never did update such a ref anyway. This + undocumented misfeature that did not exist has been excised. diff --git a/Documentation/RelNotes/1.7.7.4.txt b/Documentation/RelNotes/1.7.7.4.txt new file mode 100644 index 0000000000..e5234485e7 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.4.txt @@ -0,0 +1,14 @@ +Git v1.7.7.4 Release Notes +========================== + +Fixes since v1.7.7.3 +-------------------- + + * A few header dependencies were missing from the Makefile. + + * Some newer parts of the code used C99 __VA_ARGS__ while we still + try to cater to older compilers. + + * "git name-rev --all" tried to name all _objects_, naturally failing to + describe many blobs and trees, instead of showing only commits as + advertised in its documentation. diff --git a/Documentation/RelNotes/1.7.7.5.txt b/Documentation/RelNotes/1.7.7.5.txt new file mode 100644 index 0000000000..7b0931987b --- /dev/null +++ b/Documentation/RelNotes/1.7.7.5.txt @@ -0,0 +1,14 @@ +Git v1.7.7.5 Release Notes +========================== + +Fixes since v1.7.7.4 +-------------------- + + * After fetching from a remote that has very long refname, the reporting + output could have corrupted by overrunning a static buffer. + + * "git checkout" and "git merge" treated in-tree .gitignore and exclude + file in $GIT_DIR/info/ directory inconsistently when deciding which + untracked files are ignored and expendable. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.7.6.txt b/Documentation/RelNotes/1.7.7.6.txt new file mode 100644 index 0000000000..8df606d452 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.6.txt @@ -0,0 +1,20 @@ +Git v1.7.7.6 Release Notes +========================== + +Fixes since v1.7.7.5 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * A wildcard that matches deeper hierarchy given to the "diff-index" command, + e.g. "git diff-index HEAD -- '*.txt'", incorrectly reported additions of + matching files even when there is no change. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.7.txt b/Documentation/RelNotes/1.7.7.txt new file mode 100644 index 0000000000..7655cccfaa --- /dev/null +++ b/Documentation/RelNotes/1.7.7.txt @@ -0,0 +1,134 @@ +Git v1.7.7 Release Notes +======================== + +Updates since v1.7.6 +-------------------- + + * The scripting part of the codebase is getting prepared for i18n/l10n. + + * Interix, Cygwin and Minix ports got updated. + + * Various updates to git-p4 (in contrib/), fast-import, and git-svn. + + * Gitweb learned to read from /etc/gitweb-common.conf when it exists, + before reading from gitweb_config.perl or from /etc/gitweb.conf + (this last one is read only when per-repository gitweb_config.perl + does not exist). + + * Various codepaths that invoked zlib deflate/inflate assumed that these + functions can compress or uncompress more than 4GB data in one call on + platforms with 64-bit long, which has been corrected. + + * Git now recognizes loose objects written by other implementations that + use a non-standard window size for zlib deflation (e.g. Agit running on + Android with 4kb window). We used to reject anything that was not + deflated with 32kb window. + + * Interaction between the use of pager and coloring of the output has + been improved, especially when a command that is not built-in was + involved. + + * "git am" learned to pass the "--exclude=<path>" option through to underlying + "git apply". + + * You can now feed many empty lines before feeding an mbox file to + "git am". + + * "git archive" can be told to pass the output to gzip compression and + produce "archive.tar.gz". + + * "git bisect" can be used in a bare repository (provided that the test + you perform per each iteration does not need a working tree, of + course). + + * The length of abbreviated object names in "git branch -v" output + now honors the core.abbrev configuration variable. + + * "git check-attr" can take relative paths from the command line. + + * "git check-attr" learned an "--all" option to list the attributes for a + given path. + + * "git checkout" (both the code to update the files upon checking out a + different branch and the code to checkout a specific set of files) learned + to stream the data from object store when possible, without having to + read the entire contents of a file into memory first. An earlier round + of this code that is not in any released version had a large leak but + now it has been plugged. + + * "git clone" can now take a "--config key=value" option to set the + repository configuration options that affect the initial checkout. + + * "git commit <paths>..." now lets you feed relative pathspecs that + refer to outside your current subdirectory. + + * "git diff --stat" learned a --stat-count option to limit the output of + a diffstat report. + + * "git diff" learned a "--histogram" option to use a different diff + generation machinery stolen from jgit, which might give better + performance. + + * "git diff" had a weird worst case behaviour that can be triggered + when comparing files with potentially many places that could match. + + * "git fetch", "git push" and friends no longer show connection + errors for addresses that couldn't be connected to when at least one + address succeeds (this is arguably a regression but a deliberate + one). + + * "git grep" learned "--break" and "--heading" options, to let users mimic + the output format of "ack". + + * "git grep" learned a "-W" option that shows wider context using the same + logic used by "git diff" to determine the hunk header. + + * Invoking the low-level "git http-fetch" without "-a" option (which + git itself never did---normal users should not have to worry about + this) is now deprecated. + + * The "--decorate" option to "git log" and its family learned to + highlight grafted and replaced commits. + + * "git rebase master topci" no longer spews usage hints after giving + the "fatal: no such branch: topci" error message. + + * The recursive merge strategy implementation got a fairly large + fix for many corner cases that may rarely happen in real world + projects (it has been verified that none of the 16000+ merges in + the Linux kernel history back to v2.6.12 is affected with the + corner case bugs this update fixes). + + * "git stash" learned an "--include-untracked option". + + * "git submodule update" used to stop at the first error updating a + submodule; it now goes on to update other submodules that can be + updated, and reports the ones with errors at the end. + + * "git push" can be told with the "--recurse-submodules=check" option to + refuse pushing of the supermodule, if any of its submodules' + commits hasn't been pushed out to their remotes. + + * "git upload-pack" and "git receive-pack" learned to pretend that only a + subset of the refs exist in a repository. This may help a site to + put many tiny repositories into one repository (this would not be + useful for larger repositories as repacking would be problematic). + + * "git verify-pack" has been rewritten to use the "index-pack" machinery + that is more efficient in reading objects in packfiles. + + * test scripts for gitweb tried to run even when CGI-related perl modules + are not installed; they now exit early when the latter are unavailable. + +Also contains various documentation updates and minor miscellaneous +changes. + + +Fixes since v1.7.6 +------------------ + +Unless otherwise noted, all fixes in the 1.7.6.X maintenance track are +included in this release. + + * "git branch -m" and "git checkout -b" incorrectly allowed the tip + of the branch that is currently checked out updated. diff --git a/Documentation/RelNotes/1.7.8.1.txt b/Documentation/RelNotes/1.7.8.1.txt new file mode 100644 index 0000000000..33dc948b94 --- /dev/null +++ b/Documentation/RelNotes/1.7.8.1.txt @@ -0,0 +1,38 @@ +Git v1.7.8.1 Release Notes +========================== + +Fixes since v1.7.8 +------------------ + + * In some codepaths (notably, checkout and merge), the ignore patterns + recorded in $GIT_DIR/info/exclude were not honored. They now are. + + * "git apply --check" did not error out when given an empty input + without any patch. + + * "git archive" mistakenly allowed remote clients to ask for commits + that are not at the tip of any ref. + + * "git checkout" and "git merge" treated in-tree .gitignore and exclude + file in $GIT_DIR/info/ directory inconsistently when deciding which + untracked files are ignored and expendable. + + * LF-to-CRLF streaming filter used when checking out a large-ish blob + fell into an infinite loop with a rare input. + + * The function header pattern for files with "diff=cpp" attribute did + not consider "type *funcname(type param1,..." as the beginning of a + function. + + * The error message from "git diff" and "git status" when they fail + to inspect changes in submodules did not report which submodule they + had trouble with. + + * After fetching from a remote that has very long refname, the reporting + output could have corrupted by overrunning a static buffer. + + * "git pack-objects" avoids creating cyclic dependencies among deltas + when seeing a broken packfile that records the same object in both + the deflated form and as a delta. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.2.txt b/Documentation/RelNotes/1.7.8.2.txt new file mode 100644 index 0000000000..e74f4ef1ef --- /dev/null +++ b/Documentation/RelNotes/1.7.8.2.txt @@ -0,0 +1,71 @@ +Git v1.7.8.2 Release Notes +========================== + +Fixes since v1.7.8.1 +-------------------- + + * Porcelain commands like "git reset" did not distinguish deletions + and type-changes from ordinary modification, and reported them with + the same 'M' moniker. They now use 'D' (for deletion) and 'T' (for + type-change) to match "git status -s" and "git diff --name-status". + + * The configuration file parser used for sizes (e.g. bigFileThreshold) + did not correctly interpret 'g' suffix. + + * The replacement implemention for snprintf used on platforms with + native snprintf that is broken did not use va_copy correctly. + + * LF-to-CRLF streaming filter replaced all LF with CRLF, which might + be techinically correct but not friendly to people who are trying + to recover from earlier mistakes of using CRLF in the repository + data in the first place. It now refrains from doing so for LF that + follows a CR. + + * git native connection going over TCP (not over SSH) did not set + SO_KEEPALIVE option which failed to receive link layer errors. + + * "git branch -m <current branch> HEAD" is an obvious no-op but was not + allowed. + + * "git checkout -m" did not recreate the conflicted state in a "both + sides added, without any common ancestor version" conflict + situation. + + * "git cherry-pick $commit" (not a range) created an unnecessary + sequencer state and interfered with valid workflow to use the + command during a session to cherry-pick multiple commits. + + * You could make "git commit" segfault by giving the "--no-message" + option. + + * "fast-import" did not correctly update an existing notes tree, + possibly corrupting the fan-out. + + * "git fetch-pack" accepted unqualified refs that do not begin with + refs/ by mistake and compensated it by matching the refspec with + tail-match, which was doubly wrong. This broke fetching from a + repository with a funny named ref "refs/foo/refs/heads/master" and a + 'master' branch with "git fetch-pack refs/heads/master", as the + command incorrectly considered the former a "match". + + * "git log --follow" did not honor the rename threshold score given + with the -M option (e.g. "-M50%"). + + * "git mv" gave suboptimal error/warning messages when it overwrites + target files. It also did not pay attention to "-v" option. + + * Authenticated "git push" over dumb HTTP were broken with a recent + change and failed without asking for password when username is + given. + + * "git push" to an empty repository over HTTP were broken with a + recent change to the ref handling. + + * "git push -v" forgot how to be verbose by mistake. It now properly + becomes verbose when asked to. + + * When a "reword" action in "git rebase -i" failed to run "commit --amend", + we did not give the control back to the user to resolve the situation, and + instead kept the original commit log message. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.3.txt b/Documentation/RelNotes/1.7.8.3.txt new file mode 100644 index 0000000000..a92714c14b --- /dev/null +++ b/Documentation/RelNotes/1.7.8.3.txt @@ -0,0 +1,16 @@ +Git v1.7.8.3 Release Notes +========================== + +Fixes since v1.7.8.2 +-------------------- + + * Attempt to fetch from an empty file pretending it to be a bundle did + not error out correctly. + + * gitweb did not correctly fall back to configured $fallback_encoding + that is not 'latin1'. + + * "git clone --depth $n" did not catch a non-number given as $n as an + error. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.4.txt b/Documentation/RelNotes/1.7.8.4.txt new file mode 100644 index 0000000000..9bebdbf13d --- /dev/null +++ b/Documentation/RelNotes/1.7.8.4.txt @@ -0,0 +1,23 @@ +Git v1.7.8.4 Release Notes +========================== + +Fixes since v1.7.8.3 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * A wildcard that matches deeper hierarchy given to the "diff-index" command, + e.g. "git diff-index HEAD -- '*.txt'", incorrectly reported additions of + matching files even when there is no change. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + + * "git send-email" did not properly treat sendemail.multiedit as a + boolean (e.g. setting it to "false" did not turn it off). + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.txt b/Documentation/RelNotes/1.7.8.txt new file mode 100644 index 0000000000..b4d90bba0f --- /dev/null +++ b/Documentation/RelNotes/1.7.8.txt @@ -0,0 +1,161 @@ +Git v1.7.8 Release Notes +======================== + +Updates since v1.7.7 +-------------------- + + * Some git-svn, git-gui, git-p4 (in contrib) and msysgit updates. + + * Updates to bash completion scripts. + + * The build procedure has been taught to take advantage of computed + dependency automatically when the complier supports it. + + * The date parser now accepts timezone designators that lack minutes + part and also has a colon between "hh:mm". + + * The contents of the /etc/mailname file, if exists, is used as the + default value of the hostname part of the committer/author e-mail. + + * "git am" learned how to read from patches generated by Hg. + + * "git archive" talking with a remote repository can report errors + from the remote side in a more informative way. + + * "git branch" learned an explicit --list option to ask for branches + listed, optionally with a glob matching pattern to limit its output. + + * "git check-attr" learned "--cached" option to look at .gitattributes + files from the index, not from the working tree. + + * Variants of "git cherry-pick" and "git revert" that take multiple + commits learned to "--continue" and "--abort". + + * "git daemon" gives more human readble error messages to clients + using ERR packets when appropriate. + + * Errors at the network layer is logged by "git daemon". + + * "git diff" learned "--minimal" option to spend extra cycles to come + up with a minimal patch output. + + * "git diff" learned "--function-context" option to show the whole + function as context that was affected by a change. + + * "git difftool" can be told to skip launching the tool for a path by + answering 'n' to its prompt. + + * "git fetch" learned to honor transfer.fsckobjects configuration to + validate the objects that were received from the other end, just like + "git receive-pack" (the receiving end of "git push") does. + + * "git fetch" makes sure that the set of objects it received from the + other end actually completes the history before updating the refs. + "git receive-pack" (the receiving end of "git push") learned to do the + same. + + * "git fetch" learned that fetching/cloning from a regular file on the + filesystem is not necessarily a request to unpack a bundle file; the + file could be ".git" with "gitdir: <path>" in it. + + * "git for-each-ref" learned "%(contents:subject)", "%(contents:body)" + and "%(contents:signature)". The last one is useful for signed tags. + + * "git grep" used to incorrectly pay attention to .gitignore files + scattered in the directory it was working in even when "--no-index" + option was used. It no longer does this. The "--exclude-standard" + option needs to be given to explicitly activate the ignore + mechanism. + + * "git grep" learned "--untracked" option, where given patterns are + searched in untracked (but not ignored) files as well as tracked + files in the working tree, so that matches in new but not yet + added files do not get missed. + + * The recursive merge backend no longer looks for meaningless + existing merges in submodules unless in the outermost merge. + + * "git log" and friends learned "--children" option. + + * "git ls-remote" learned to respond to "-h"(elp) requests. + + * "mediawiki" remote helper can interact with (surprise!) MediaWiki + with "git fetch" & "git push". + + * "git merge" learned the "--edit" option to allow users to edit the + merge commit log message. + + * "git rebase -i" can be told to use special purpose editor suitable + only for its insn sheet via sequence.editor configuration variable. + + * "git send-email" learned to respond to "-h"(elp) requests. + + * "git send-email" allows the value given to sendemail.aliasfile to begin + with "~/" to refer to the $HOME directory. + + * "git send-email" forces use of Authen::SASL::Perl to work around + issues between Authen::SASL::Cyrus and AUTH PLAIN/LOGIN. + + * "git stash" learned "--include-untracked" option to stash away + untracked/ignored cruft from the working tree. + + * "git submodule clone" does not leak an error message to the UI + level unnecessarily anymore. + + * "git submodule update" learned to honor "none" as the value for + submodule.<name>.update to specify that the named submodule should + not be checked out by default. + + * When populating a new submodule directory with "git submodule init", + the $GIT_DIR metainformation directory for submodules is created inside + $GIT_DIR/modules/<name>/ directory of the superproject and referenced + via the gitfile mechanism. This is to make it possible to switch + between commits in the superproject that has and does not have the + submodule in the tree without re-cloning. + + * "gitweb" leaked unescaped control characters from syntax hiliter + outputs. + + * "gitweb" can be told to give custom string at the end of the HTML + HEAD element. + + * "gitweb" now has its own manual pages. + + +Also contains other documentation updates and minor code cleanups. + + +Fixes since v1.7.7 +------------------ + +Unless otherwise noted, all fixes in the 1.7.7.X maintenance track are +included in this release. + + * HTTP transport did not use pushurl correctly, and also did not tell + what host it is trying to authenticate with when asking for + credentials. + (merge deba493 jk/http-auth later to maint). + + * "git blame" was aborted if started from an uncommitted content and + the path had the textconv filter in effect. + (merge 8518088 ss/blame-textconv-fake-working-tree later to maint). + + * Adding many refs to the local repository in one go (e.g. "git fetch" + that fetches many tags) and looking up a ref by name in a repository + with too many refs were unnecessarily slow. + (merge 17d68a54d jp/get-ref-dir-unsorted later to maint). + + * Report from "git commit" on untracked files was confused under + core.ignorecase option. + (merge 395c7356 jk/name-hash-dirent later to maint). + + * "git merge" did not understand ":/<pattern>" as a way to name a commit. + + " "git push" on the receiving end used to call post-receive and post-update + hooks for attempted removal of non-existing refs. + (merge 160b81ed ph/push-to-delete-nothing later to maint). + + * Help text for "git remote set-url" and "git remote set-branches" + were misspelled. + (merge c49904e fc/remote-seturl-usage-fix later to maint). + (merge 656cdf0 jc/remote-setbranches-usage-fix later to maint). diff --git a/Documentation/RelNotes/1.7.9.txt b/Documentation/RelNotes/1.7.9.txt new file mode 100644 index 0000000000..f1294b458b --- /dev/null +++ b/Documentation/RelNotes/1.7.9.txt @@ -0,0 +1,111 @@ +Git v1.7.9 Release Notes +======================== + +Updates since v1.7.8 +-------------------- + + * gitk updates accumulated since early 2011. + + * git-gui updated to 0.16.0. + + * git-p4 (in contrib/) updates. + + * Git uses gettext to translate its most common interface messages + into the user's language if translations are available and the + locale is appropriately set. Distributors can drop in new PO files + in po/ to add new translations. + + * The code to handle username/password for HTTP transaction used in + "git push" & "git fetch" learned to talk "credential API" to + external programs to cache or store them, to allow integration with + platform native keychain mechanisms. + + * The prompted input in the terminal use our own getpass() replacement + when possible. HTTP transactions used to ask username without echoing + back what was typed, but with this change you will see it as you type. + + * The internal of "revert/cherry-pick" has been tweaked to prepare + building more generic "sequencer" on top of the implementation that + drives them. + + * "git rev-parse FETCH_HEAD" after "git fetch" without specifying + what to fetch from the command line will now show the commit that + would be merged if the command were "git pull". + + * "git add" learned to stream large files directly into a packfile + instead of writing them into individual loose object files. + + * "git checkout -B <current branch> <elsewhere>" is a more intuitive + way to spell "git reset --keep <elsewhere>". + + * "git checkout" and "git merge" learned "--no-overwrite-ignore" option + to tell Git that untracked and ignored files are not expendable. + + * "git commit --amend" learned "--no-edit" option to say that the + user is amending the tree being recorded, without updating the + commit log message. + + * "git commit" and "git reset" re-learned the optimization to prime + the cache-tree information in the index, which makes it faster to + write a tree object out after the index entries are updated. + + * "git commit" detects and rejects an attempt to stuff NUL byte in + the commit log message. + + * "git commit" learned "-S" to GPG-sign the commit; this can be shown + with the "--show-signature" option to "git log". + + * fsck and prune are relatively lengthy operations that still go + silent while making the end-user wait. They learned to give progress + output like other slow operations. + + * The set of built-in function-header patterns for various languages + knows MATLAB. + + * "git log --format='<format>'" learned new %g[nNeE] specifiers to + show information from the reflog entries when walking the reflog + (i.e. with "-g"). + + * "git pull" can be used to fetch and merge an annotated/signed tag, + instead of the tip of a topic branch. The GPG signature from the + signed tag is recorded in the resulting merge commit for later + auditing. + + * "git log" learned "--show-signature" option to show the signed tag + that was merged that is embedded in the merge commit. It also can + show the signature made on the commit with "git commit -S". + + * "git branch --edit-description" can be used to add descriptive text + to explain what a topic branch is about. + + * "git fmt-merge-msg" learned to take the branch description into + account when preparing a merge summary that "git merge" records + when merging a local branch. + + * "git request-pull" has been updated to convey more information + useful for integrators to decide if a topic is worth merging and + what is pulled is indeed what the requestor asked to pull, + including: + + - the tip of the branch being requested to be merged; + - the branch description describing what the topic is about; + - the contents of the annotated tag, when requesting to pull a tag. + + * "git pull" learned to notice 'pull.rebase' configuration variable, + which serves as a global fallback for setting 'branch.<name>.rebase' + configuration variable per branch. + + * "git tag" learned "--cleanup" option to control how the whitespaces + and empty lines in tag message are cleaned up. + + * "gitweb" learned to show side-by-side diff. + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.8 +------------------ + +Unless otherwise noted, all the fixes since v1.7.8 in the maintenance +releases are contained in this release (see release notes to them for +details). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c6a5032912..0dbf2c9843 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -134,8 +134,7 @@ Another thing: NULL pointers shall be written as NULL, not as 0. (2) Generate your patch using git tools out of your commits. -git based diff tools (git, Cogito, and StGIT included) generate -unidiff which is the preferred format. +git based diff tools generate unidiff which is the preferred format. You do not have to be afraid to use -M option to "git diff" or "git format-patch", if your patch involves file renames. The @@ -344,50 +343,20 @@ MUA specific hints Some of patches I receive or pick up from the list share common patterns of breakage. Please make sure your MUA is set up -properly not to corrupt whitespaces. Here are two common ones -I have seen: +properly not to corrupt whitespaces. -* Empty context lines that do not have _any_ whitespace. +See the DISCUSSION section of git-format-patch(1) for hints on +checking your patch by mailing it to yourself and applying with +git-am(1). -* Non empty context lines that have one extra whitespace at the - beginning. - -One test you could do yourself if your MUA is set up correctly is: - -* Send the patch to yourself, exactly the way you would, except - To: and Cc: lines, which would not contain the list and - maintainer address. - -* Save that patch to a file in UNIX mailbox format. Call it say - a.patch. - -* Try to apply to the tip of the "master" branch from the - git.git public repository: - - $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply - $ git checkout test-apply - $ git reset --hard - $ git am a.patch - -If it does not apply correctly, there can be various reasons. - -* Your patch itself does not apply cleanly. That is _bad_ but - does not have much to do with your MUA. Please rebase the - patch appropriately. - -* Your MUA corrupted your patch; "am" would complain that - the patch does not apply. Look at .git/rebase-apply/ subdirectory and - see what 'patch' file contains and check for the common - corruption patterns mentioned above. - -* While you are at it, check what are in 'info' and - 'final-commit' files as well. If what is in 'final-commit' is - not exactly what you would want to see in the commit log - message, it is very likely that your maintainer would end up - hand editing the log message when he applies your patch. - Things like "Hi, this is my first patch.\n", if you really - want to put in the patch e-mail, should come after the - three-dash line that signals the end of the commit message. +While you are at it, check the resulting commit log message from +a trial run of applying the patch. If what is in the resulting +commit is not exactly what you would want to see, it is very +likely that your maintainer would end up hand editing the log +message when he applies your patch. Things like "Hi, this is my +first patch.\n", if you really want to put in the patch e-mail, +should come after the three-dash line that signals the end of the +commit message. Pine @@ -443,89 +412,10 @@ that or Gentoo did it.) So you need to set the it. -Thunderbird ------------ - -(A Large Angry SCM) - -By default, Thunderbird will both wrap emails as well as flag them as -being 'format=flowed', both of which will make the resulting email unusable -by git. - -Here are some hints on how to successfully submit patches inline using -Thunderbird. - -There are two different approaches. One approach is to configure -Thunderbird to not mangle patches. The second approach is to use -an external editor to keep Thunderbird from mangling the patches. - -Approach #1 (configuration): - -This recipe is current as of Thunderbird 2.0.0.19. Three steps: - 1. Configure your mail server composition as plain text - Edit...Account Settings...Composition & Addressing, - uncheck 'Compose Messages in HTML'. - 2. Configure your general composition window to not wrap - Edit..Preferences..Composition, wrap plain text messages at 0 - 3. Disable the use of format=flowed - Edit..Preferences..Advanced..Config Editor. Search for: - mailnews.send_plaintext_flowed - toggle it to make sure it is set to 'false'. - -After that is done, you should be able to compose email as you -otherwise would (cut + paste, git-format-patch | git-imap-send, etc), -and the patches should not be mangled. - -Approach #2 (external editor): - -This recipe appears to work with the current [*1*] Thunderbird from Suse. - -The following Thunderbird extensions are needed: - AboutConfig 0.5 - http://aboutconfig.mozdev.org/ - External Editor 0.7.2 - http://globs.org/articles.php?lng=en&pg=8 - -1) Prepare the patch as a text file using your method of choice. - -2) Before opening a compose window, use Edit->Account Settings to -uncheck the "Compose messages in HTML format" setting in the -"Composition & Addressing" panel of the account to be used to send the -patch. [*2*] - -3) In the main Thunderbird window, _before_ you open the compose window -for the patch, use Tools->about:config to set the following to the -indicated values: - mailnews.send_plaintext_flowed => false - mailnews.wraplength => 0 - -4) Open a compose window and click the external editor icon. - -5) In the external editor window, read in the patch file and exit the -editor normally. - -6) Back in the compose window: Add whatever other text you wish to the -message, complete the addressing and subject fields, and press send. - -7) Optionally, undo the about:config/account settings changes made in -steps 2 & 3. +Thunderbird, KMail, GMail +------------------------- - -[Footnotes] -*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse -9.3 professional updates. - -*2* It may be possible to do this with about:config and the following -settings but I haven't tried, yet. - mail.html_compose => false - mail.identity.default.compose_html => false - mail.identity.id?.compose_html => false - -(Lukas Sandström) - -There is a script in contrib/thunderbird-patch-inline which can help -you include patches with Thunderbird in an easy way. To use it, do the -steps above and then use the script as the external editor. +See the MUA-SPECIFIC HINTS section of git-format-patch(1). Gnus ---- @@ -540,71 +430,3 @@ characters (most notably in people's names), and also whitespaces (fatal in patches). Running 'C-u g' to display the message in raw form before using '|' to run the pipe can work this problem around. - - -KMail ------ - -This should help you to submit patches inline using KMail. - -1) Prepare the patch as a text file. - -2) Click on New Mail. - -3) Go under "Options" in the Composer window and be sure that -"Word wrap" is not set. - -4) Use Message -> Insert file... and insert the patch. - -5) Back in the compose window: add whatever other text you wish to the -message, complete the addressing and subject fields, and press send. - - -Gmail ------ - -GMail does not appear to have any way to turn off line wrapping in the web -interface, so this will mangle any emails that you send. You can however -use "git send-email" and send your patches through the GMail SMTP server, or -use any IMAP email client to connect to the google IMAP server and forward -the emails through that. - -To use "git send-email" and send your patches through the GMail SMTP server, -edit ~/.gitconfig to specify your account settings: - -[sendemail] - smtpencryption = tls - smtpserver = smtp.gmail.com - smtpuser = user@gmail.com - smtppass = p4ssw0rd - smtpserverport = 587 - -Once your commits are ready to be sent to the mailing list, run the -following commands: - - $ git format-patch --cover-letter -M origin/master -o outgoing/ - $ edit outgoing/0000-* - $ git send-email outgoing/* - -To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your -account settings: - -[imap] - folder = "[Gmail]/Drafts" - host = imaps://imap.gmail.com - user = user@gmail.com - pass = p4ssw0rd - port = 993 - sslverify = false - -You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error -that the "Folder doesn't exist". - -Once your commits are ready to be sent to the mailing list, run the -following commands: - - $ git format-patch --cover-letter -M --stdout origin/master | git imap-send - -Just make sure to disable line wrapping in the email client (GMail web -interface will line wrap no matter what, so you need to use a real -IMAP client). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 16e3c68576..d4a51da464 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -52,6 +52,11 @@ of lines before or after the line given by <start>. --porcelain:: Show in a format designed for machine consumption. +--line-porcelain:: + Show the porcelain format, but output commit information for + each line, not just the first time a commit is referenced. + Implies --porcelain. + --incremental:: Show the result incrementally in a format designed for machine consumption. @@ -112,5 +117,4 @@ commit. And the default value is 40. If there are more than one take effect. -h:: ---help:: Show help message. diff --git a/Documentation/config.txt b/Documentation/config.txt index 750c86d4f5..abeb82b2c6 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -45,9 +45,10 @@ lines. Variables may belong directly to a section or to a given subsection. You can have `[section]` if you have `[section "subsection"]`, but you don't need to. -There is also a case insensitive alternative `[section.subsection]` syntax. -In this syntax, subsection names follow the same restrictions as for section -names. +There is also a deprecated `[section.subsection]` syntax. With this +syntax, the subsection name is converted to lower-case and is also +compared case sensitively. These subsection names follow the same +restrictions as section names. All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form @@ -114,40 +115,37 @@ in the appropriate manual page. You will find a description of non-core porcelain configuration variables in the respective porcelain documentation. advice.*:: - When set to 'true', display the given optional help message. - When set to 'false', do not display. The configuration variables - are: + These variables control various optional help messages designed to + aid new users. All 'advice.*' variables default to 'true', and you + can tell Git that you do not need help by setting these to 'false': + -- pushNonFastForward:: Advice shown when linkgit:git-push[1] refuses - non-fast-forward refs. Default: true. + non-fast-forward refs. statusHints:: Directions on how to stage/unstage/add shown in the output of linkgit:git-status[1] and the template shown - when writing commit messages. Default: true. + when writing commit messages. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to merge to avoid overwriting local changes. - Default: true. resolveConflict:: Advices shown by various commands when conflicts prevent the operation from being performed. - Default: true. implicitIdentity:: Advice on how to set your identity configuration when your information is guessed from the system username and - domain name. Default: true. - + domain name. detachedHead:: - Advice shown when you used linkgit::git-checkout[1] to + Advice shown when you used linkgit:git-checkout[1] to move to the detach HEAD state, to instruct how to create - a local branch after the fact. Default: true. + a local branch after the fact. -- core.fileMode:: If false, the executable bit differences between the index and - the working copy are ignored; useful on broken filesystems like FAT. + the working tree are ignored; useful on broken filesystems like FAT. See linkgit:git-update-index[1]. + The default is true, except linkgit:git-clone[1] or linkgit:git-init[1] @@ -179,7 +177,7 @@ is created. core.trustctime:: If false, the ctime differences between the index and the - working copy are ignored; useful when the inode change time + working tree are ignored; useful when the inode change time is regularly modified by something outside Git (file system crawlers and some backup systems). See linkgit:git-update-index[1]. True by default. @@ -292,7 +290,7 @@ core.ignoreStat:: If true, commands which modify both the working tree and the index will mark the updated paths with the "assume unchanged" bit in the index. These marked files are then assumed to stay unchanged in the - working copy, until you mark them otherwise manually - Git will not + working tree, until you mark them otherwise manually - Git will not detect the file changes by lstat() calls. This is useful on systems where those are very slow, such as Microsoft Windows. See linkgit:git-update-index[1]. @@ -344,7 +342,9 @@ core.logAllRefUpdates:: SHA1, the date/time and the reason of the update, but only when the file exists. If this configuration variable is set to true, missing "$GIT_DIR/logs/<ref>" - file is automatically created for branch heads. + file is automatically created for branch heads (i.e. under + refs/heads/), remote refs (i.e. under refs/remotes/), + note refs (i.e. under refs/notes/), and the symbolic ref HEAD. + This information can be used to determine what commit was the tip of a branch "2 days ago". @@ -442,8 +442,6 @@ for most projects as source code and other text files can still be delta compressed, but larger binary media files won't be. + Common unit suffixes of 'k', 'm', or 'g' are supported. -+ -Currently only linkgit:git-fast-import[1] honors this setting. core.excludesfile:: In addition to '.gitignore' (per-directory) and @@ -473,6 +471,12 @@ core.editor:: variable when it is set, and the environment variable `GIT_EDITOR` is not set. See linkgit:git-var[1]. +sequence.editor:: + Text editor used by `git rebase -i` for editing the rebase insn file. + The value is meant to be interpreted by the shell when it is used. + It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable. + When not configured the default commit message editor is used instead. + core.pager:: The command that git will use to paginate output. Can be overridden with the `GIT_PAGER` environment @@ -589,6 +593,8 @@ it will be treated as a shell command. For example, defining "gitk --all --not ORIG_HEAD". Note that shell commands will be executed from the top-level directory of a repository, which may not necessarily be the current directory. +'GIT_PREFIX' is set as returned by running 'git rev-parse --show-prefix' +from the original current directory. See linkgit:git-rev-parse[1]. am.keepcr:: If true, git-am will call git-mailsplit for patches in mbox format @@ -643,7 +649,7 @@ branch.<name>.remote:: branch.<name>.merge:: Defines, together with branch.<name>.remote, the upstream branch - for the given branch. It tells 'git fetch'/'git pull' which + for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which branch to merge and can also affect 'git push' (see push.default). When in branch <name>, it tells 'git fetch' the default refspec to be marked for merging in FETCH_HEAD. The value is @@ -668,15 +674,17 @@ branch.<name>.mergeoptions:: branch.<name>.rebase:: When true, rebase the branch <name> on top of the fetched branch, instead of merging the default branch from the default remote when - "git pull" is run. - *NOTE*: this is a possibly dangerous operation; do *not* use - it unless you understand the implications (see linkgit:git-rebase[1] - for details). + "git pull" is run. See "pull.rebase" for doing this in a non + branch-specific manner. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand the implications (see linkgit:git-rebase[1] +for details). browser.<tool>.cmd:: Specify the command to invoke the specified browser. The specified command is evaluated in shell with the URLs passed - as arguments. (See linkgit:git-web--browse[1].) + as arguments. (See linkgit:git-web{litdd}browse[1].) browser.<tool>.path:: Override the path for the given tool that may be used to @@ -708,9 +716,16 @@ second is the background. The position of the attribute, if any, doesn't matter. color.diff:: - When set to `always`, always use colors in patch. - When false (or `never`), never. When set to `true` or `auto`, use - colors only when the output is to the terminal. Defaults to false. + Whether to use ANSI escape sequences to add color to patches. + If this is set to `always`, linkgit:git-diff[1], + linkgit:git-log[1], and linkgit:git-show[1] will use color + for all patches. If it is set to `true` or `auto`, those + commands will only use color when output is to the terminal. + Defaults to false. ++ +This does not affect linkgit:git-format-patch[1] nor the +'git-diff-{asterisk}' plumbing commands. Can be overridden on the +command line with the `--color[=<when>]` option. color.diff.<slot>:: Use customized color for diff colorization. `<slot>` specifies @@ -796,11 +811,15 @@ color.status.<slot>:: color.branch.<slot>. color.ui:: - When set to `always`, always use colors in all git commands which - are capable of colored output. When false (or `never`), never. When - set to `true` or `auto`, use colors only when the output is to the - terminal. When more specific variables of color.* are set, they always - take precedence over this setting. Defaults to false. + This variable determines the default value for variables such + as `color.diff` and `color.grep` that control the use of color + per command family. Its scope will expand as more commands learn + configuration to set a default for the `--color` option. Set it + to `always` if you want all output not intended for machine + consumption to use color, to `true` or `auto` if you want such + output to use color when written to the terminal, or to `false` or + `never` if you prefer git commands not to use color unless enabled + explicitly with some other configuration or the `--color` option. commit.status:: A boolean to enable/disable inclusion of status information in the @@ -812,68 +831,30 @@ commit.template:: "{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the specified user's home directory. -diff.autorefreshindex:: - When using 'git diff' to compare with work tree - files, do not consider stat-only change as changed. - Instead, silently run `git update-index --refresh` to - update the cached stat information for paths whose - contents in the work tree match the contents in the - index. This option defaults to true. Note that this - affects only 'git diff' Porcelain, and not lower level - 'diff' commands such as 'git diff-files'. - -diff.external:: - If this config variable is set, diff generation is not - performed using the internal diff machinery, but using the - given command. Can be overridden with the `GIT_EXTERNAL_DIFF' - environment variable. The command is called with parameters - as described under "git Diffs" in linkgit:git[1]. Note: if - you want to use an external diff program only on a subset of - your files, you might want to use linkgit:gitattributes[5] instead. - -diff.mnemonicprefix:: - If set, 'git diff' uses a prefix pair that is different from the - standard "a/" and "b/" depending on what is being compared. When - this configuration is in effect, reverse diff output also swaps - the order of the prefixes: -`git diff`;; - compares the (i)ndex and the (w)ork tree; -`git diff HEAD`;; - compares a (c)ommit and the (w)ork tree; -`git diff --cached`;; - compares a (c)ommit and the (i)ndex; -`git diff HEAD:file1 file2`;; - compares an (o)bject and a (w)ork tree entity; -`git diff --no-index a b`;; - compares two non-git things (1) and (2). - -diff.noprefix:: - If set, 'git diff' does not show any source or destination prefix. - -diff.renameLimit:: - The number of files to consider when performing the copy/rename - detection; equivalent to the 'git diff' option '-l'. - -diff.renames:: - Tells git to detect renames. If set to any boolean value, it - will enable basic rename detection. If set to "copies" or - "copy", it will detect copies, as well. - -diff.ignoreSubmodules:: - Sets the default value of --ignore-submodules. Note that this - affects only 'git diff' Porcelain, and not lower level 'diff' - commands such as 'git diff-files'. 'git checkout' also honors - this setting when reporting uncommitted changes. - -diff.suppressBlankEmpty:: - A boolean to inhibit the standard behavior of printing a space - before each empty output line. Defaults to false. - -diff.tool:: - Controls which diff tool is used. `diff.tool` overrides - `merge.tool` when used by linkgit:git-difftool[1] and has - the same valid values as `merge.tool` minus "tortoisemerge" - and plus "kompare". +credential.helper:: + Specify an external helper to be called when a username or + password credential is needed; the helper may consult external + storage to avoid prompting the user for the credentials. See + linkgit:gitcredentials[7] for details. + +credential.useHttpPath:: + When acquiring credentials, consider the "path" component of an http + or https URL to be important. Defaults to false. See + linkgit:gitcredentials[7] for more information. + +credential.username:: + If no username is set for a network authentication, use this username + by default. See credential.<context>.* below, and + linkgit:gitcredentials[7]. + +credential.<url>.*:: + Any of the credential.* options above can be applied selectively to + some credentials. For example "credential.https://example.com.username" + would set the default username only for https connections to + example.com. See linkgit:gitcredentials[7] for details on how URLs are + matched. + +include::diff-config.txt[] difftool.<tool>.path:: Override the path for the given tool. This is useful in case @@ -905,6 +886,13 @@ fetch.recurseSubmodules:: when its superproject retrieves a commit that updates the submodule's reference. +fetch.fsckObjects:: + If it is set to true, git-fetch-pack will check all fetched + objects. It will abort in the case of a malformed object or a + broken link. The result of an abort are only dangling objects. + Defaults to false. If not set, the value of `transfer.fsckObjects` + is used instead. + fetch.unpackLimit:: If the number of objects fetched over the git native transfer is below this @@ -977,6 +965,16 @@ format.signoff:: the rights to submit this work under the same open source license. Please see the 'SubmittingPatches' document for further discussion. +filter.<driver>.clean:: + The command which is used to convert the content of a worktree + file to a blob upon checkin. See linkgit:gitattributes[5] for + details. + +filter.<driver>.smudge:: + The command which is used to convert the content of a blob + object to a worktree file upon checkout. See + linkgit:gitattributes[5] for details. + gc.aggressiveWindow:: The window size parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults @@ -1102,12 +1100,40 @@ All gitcvs variables except for 'gitcvs.usecrlfattr' and is one of "ext" and "pserver") to make them apply only for the given access method. +gitweb.category:: +gitweb.description:: +gitweb.owner:: +gitweb.url:: + See linkgit:gitweb[1] for description. + +gitweb.avatar:: +gitweb.blame:: +gitweb.grep:: +gitweb.highlight:: +gitweb.patches:: +gitweb.pickaxe:: +gitweb.remote_heads:: +gitweb.showsizes:: +gitweb.snapshot:: + See linkgit:gitweb.conf[5] for description. + grep.lineNumber:: If set to true, enable '-n' option by default. grep.extendedRegexp:: If set to true, enable '--extended-regexp' option by default. +gpg.program:: + Use this custom program instead of "gpg" found on $PATH when + making or verifying a PGP signature. The program must support the + same command line interface as GPG, namely, to verify a detached + signature, "gpg --verify $file - <$signature" is run, and the + program is expected to signal a good signature by exiting with + code 0, and to generate an ascii-armored detached signature, the + standard input of "gpg -bsau $key" is fed with the contents to be + signed, and the program is expected to send the result to its + standard output. + gui.commitmsgwidth:: Defines how wide the commit message window is in the linkgit:git-gui[1]. "75" is the default. @@ -1236,6 +1262,14 @@ http.proxy:: environment variable (see linkgit:curl[1]). This can be overridden on a per-remote basis; see remote.<name>.proxy +http.cookiefile:: + File containing previously stored cookie lines which should be used + in the git http session, if they match the server. The file format + of the file to read cookies from should be plain HTTP headers or + the Netscape/Mozilla cookie file format (see linkgit:curl[1]). + NOTE that the file specified with http.cookiefile is only used as + input. No cookies will be stored in the file. + http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment @@ -1349,9 +1383,16 @@ instaweb.port:: interactive.singlekey:: In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). - Currently this is used only by the `\--patch` mode of - linkgit:git-add[1]. Note that this setting is silently - ignored if portable keystroke input is not available. + Currently this is used by the `\--patch` mode of + linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1], + linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this + setting is silently ignored if portable keystroke input + is not available. + +log.abbrevCommit:: + If true, makes linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] assume `\--abbrev-commit`. You may + override this option with `\--no-abbrev-commit`. log.date:: Set the default date-time mode for the 'log' command. @@ -1476,7 +1517,8 @@ notes.rewriteRef:: You may also specify this configuration several times. + Does not have a default value; you must configure this variable to -enable note rewriting. +enable note rewriting. Set it to `refs/notes/commits` to enable +rewriting for the default commit notes. + This setting can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable, which must be a colon separated list of refs or @@ -1581,6 +1623,16 @@ pretty.<name>:: Note that an alias with the same name as a built-in format will be silently ignored. +pull.rebase:: + When true, rebase branches on top of the fetched branch, instead + of merging the default branch from the default remote when "git + pull" is run. See "branch.<name>.rebase" for setting this on a + per-branch basis. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand the implications (see linkgit:git-rebase[1] +for details). + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. @@ -1618,7 +1670,8 @@ receive.fsckObjects:: If it is set to true, git-receive-pack will check all received objects. It will abort in the case of a malformed object or a broken link. The result of an abort are only dangling objects. - Defaults to false. + Defaults to false. If not set, the value of `transfer.fsckObjects` + is used instead. receive.unpackLimit:: If the number of objects received in a push is below this @@ -1730,10 +1783,11 @@ rerere.autoupdate:: rerere.enabled:: Activate recording of resolved conflicts, so that identical - conflict hunks can be resolved automatically, should they - be encountered again. linkgit:git-rerere[1] command is by - default enabled if you create `rr-cache` directory under - `$GIT_DIR`, but can be disabled by setting this option to false. + conflict hunks can be resolved automatically, should they be + encountered again. By default, linkgit:git-rerere[1] is + enabled if there is an `rr-cache` directory under the + `$GIT_DIR`, e.g. if "rerere" was previously used in the + repository. sendemail.identity:: A configuration identity. When given, causes values in the @@ -1853,6 +1907,11 @@ tar.umask:: archiving user's umask will be used instead. See umask(2) and linkgit:git-archive[1]. +transfer.fsckObjects:: + When `fetch.fsckObjects` or `receive.fsckObjects` are + not set, the value of this variable is used instead. + Defaults to false. + transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are not set, the value of this variable is used instead. diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt new file mode 100644 index 0000000000..1aed79e7dc --- /dev/null +++ b/Documentation/diff-config.txt @@ -0,0 +1,136 @@ +diff.autorefreshindex:: + When using 'git diff' to compare with work tree + files, do not consider stat-only change as changed. + Instead, silently run `git update-index --refresh` to + update the cached stat information for paths whose + contents in the work tree match the contents in the + index. This option defaults to true. Note that this + affects only 'git diff' Porcelain, and not lower level + 'diff' commands such as 'git diff-files'. + +diff.dirstat:: + A comma separated list of `--dirstat` parameters specifying the + default behavior of the `--dirstat` option to linkgit:git-diff[1]` + and friends. The defaults can be overridden on the command line + (using `--dirstat=<param1,param2,...>`). The fallback defaults + (when not changed by `diff.dirstat`) are `changes,noncumulative,3`. + The following parameters are available: ++ +-- +`changes`;; + Compute the dirstat numbers by counting the lines that have been + removed from the source, or added to the destination. This ignores + the amount of pure code movements within a file. In other words, + rearranging lines in a file is not counted as much as other changes. + This is the default behavior when no parameter is given. +`lines`;; + Compute the dirstat numbers by doing the regular line-based diff + analysis, and summing the removed/added line counts. (For binary + files, count 64-byte chunks instead, since binary files have no + natural concept of lines). This is a more expensive `--dirstat` + behavior than the `changes` behavior, but it does count rearranged + lines within a file as much as other changes. The resulting output + is consistent with what you get from the other `--*stat` options. +`files`;; + Compute the dirstat numbers by counting the number of files changed. + Each changed file counts equally in the dirstat analysis. This is + the computationally cheapest `--dirstat` behavior, since it does + not have to look at the file contents at all. +`cumulative`;; + Count changes in a child directory for the parent directory as well. + Note that when using `cumulative`, the sum of the percentages + reported may exceed 100%. The default (non-cumulative) behavior can + be specified with the `noncumulative` parameter. +<limit>;; + An integer parameter specifies a cut-off percent (3% by default). + Directories contributing less than this percentage of the changes + are not shown in the output. +-- ++ +Example: The following will count changed files, while ignoring +directories with less than 10% of the total amount of changed files, +and accumulating child directory counts in the parent directories: +`files,10,cumulative`. + +diff.external:: + If this config variable is set, diff generation is not + performed using the internal diff machinery, but using the + given command. Can be overridden with the `GIT_EXTERNAL_DIFF' + environment variable. The command is called with parameters + as described under "git Diffs" in linkgit:git[1]. Note: if + you want to use an external diff program only on a subset of + your files, you might want to use linkgit:gitattributes[5] instead. + +diff.ignoreSubmodules:: + Sets the default value of --ignore-submodules. Note that this + affects only 'git diff' Porcelain, and not lower level 'diff' + commands such as 'git diff-files'. 'git checkout' also honors + this setting when reporting uncommitted changes. + +diff.mnemonicprefix:: + If set, 'git diff' uses a prefix pair that is different from the + standard "a/" and "b/" depending on what is being compared. When + this configuration is in effect, reverse diff output also swaps + the order of the prefixes: +`git diff`;; + compares the (i)ndex and the (w)ork tree; +`git diff HEAD`;; + compares a (c)ommit and the (w)ork tree; +`git diff --cached`;; + compares a (c)ommit and the (i)ndex; +`git diff HEAD:file1 file2`;; + compares an (o)bject and a (w)ork tree entity; +`git diff --no-index a b`;; + compares two non-git things (1) and (2). + +diff.noprefix:: + If set, 'git diff' does not show any source or destination prefix. + +diff.renameLimit:: + The number of files to consider when performing the copy/rename + detection; equivalent to the 'git diff' option '-l'. + +diff.renames:: + Tells git to detect renames. If set to any boolean value, it + will enable basic rename detection. If set to "copies" or + "copy", it will detect copies, as well. + +diff.suppressBlankEmpty:: + A boolean to inhibit the standard behavior of printing a space + before each empty output line. Defaults to false. + +diff.<driver>.command:: + The custom diff driver command. See linkgit:gitattributes[5] + for details. + +diff.<driver>.xfuncname:: + The regular expression that the diff driver should use to + recognize the hunk header. A built-in pattern may also be used. + See linkgit:gitattributes[5] for details. + +diff.<driver>.binary:: + Set this option to true to make the diff driver treat files as + binary. See linkgit:gitattributes[5] for details. + +diff.<driver>.textconv:: + The command that the diff driver should call to generate the + text-converted version of a file. The result of the + conversion is used to generate a human-readable diff. See + linkgit:gitattributes[5] for details. + +diff.<driver>.wordregex:: + The regular expression that the diff driver should use to + split words in a line. See linkgit:gitattributes[5] for + details. + +diff.<driver>.cachetextconv:: + Set this option to true to make the diff driver cache the text + conversion outputs. See linkgit:gitattributes[5] for details. + +diff.tool:: + The diff tool to be used by linkgit:git-difftool[1]. This + option overrides `merge.tool`, and has the same valid built-in + values as `merge.tool` minus "tortoisemerge" and plus + "kompare". Any other value is treated as a custom diff tool, + and there must be a corresponding `difftool.<tool>.cmd` + option. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index c93124be79..9f7cba2be6 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -45,14 +45,24 @@ ifndef::git-format-patch[] Synonym for `-p --raw`. endif::git-format-patch[] +--minimal:: + Spend extra time to make sure the smallest possible + diff is produced. + --patience:: Generate a diff using the "patience diff" algorithm. ---stat[=<width>[,<name-width>]]:: +--stat[=<width>[,<name-width>[,<count>]]]:: Generate a diffstat. You can override the default output width for 80-column terminal by `--stat=<width>`. The width of the filename part can be controlled by giving another width to it separated by a comma. + By giving a third parameter `<count>`, you can limit the + output to the first `<count>` lines, followed by + `...` if there are more. ++ +These parameters can also be set individually with `--stat-width=<width>`, +`--stat-name-width=<name-width>` and `--stat-count=<count>`. --numstat:: Similar to `\--stat`, but shows number of added and @@ -66,15 +76,49 @@ endif::git-format-patch[] number of modified files, as well as number of added and deleted lines. ---dirstat[=<limit>]:: - Output the distribution of relative amount of changes (number of lines added or - removed) for each sub-directory. Directories with changes below - a cut-off percent (3% by default) are not shown. The cut-off percent - can be set with `--dirstat=<limit>`. Changes in a child directory are not - counted for the parent directory, unless `--cumulative` is used. - ---dirstat-by-file[=<limit>]:: - Same as `--dirstat`, but counts changed files instead of lines. +--dirstat[=<param1,param2,...>]:: + Output the distribution of relative amount of changes for each + sub-directory. The behavior of `--dirstat` can be customized by + passing it a comma separated list of parameters. + The defaults are controlled by the `diff.dirstat` configuration + variable (see linkgit:git-config[1]). + The following parameters are available: ++ +-- +`changes`;; + Compute the dirstat numbers by counting the lines that have been + removed from the source, or added to the destination. This ignores + the amount of pure code movements within a file. In other words, + rearranging lines in a file is not counted as much as other changes. + This is the default behavior when no parameter is given. +`lines`;; + Compute the dirstat numbers by doing the regular line-based diff + analysis, and summing the removed/added line counts. (For binary + files, count 64-byte chunks instead, since binary files have no + natural concept of lines). This is a more expensive `--dirstat` + behavior than the `changes` behavior, but it does count rearranged + lines within a file as much as other changes. The resulting output + is consistent with what you get from the other `--*stat` options. +`files`;; + Compute the dirstat numbers by counting the number of files changed. + Each changed file counts equally in the dirstat analysis. This is + the computationally cheapest `--dirstat` behavior, since it does + not have to look at the file contents at all. +`cumulative`;; + Count changes in a child directory for the parent directory as well. + Note that when using `cumulative`, the sum of the percentages + reported may exceed 100%. The default (non-cumulative) behavior can + be specified with the `noncumulative` parameter. +<limit>;; + An integer parameter specifies a cut-off percent (3% by default). + Directories contributing less than this percentage of the changes + are not shown in the output. +-- ++ +Example: The following will count changed files, while ignoring +directories with less than 10% of the total amount of changed files, +and accumulating child directory counts in the parent directories: +`--dirstat=files,10,cumulative`. --summary:: Output a condensed summary of extended header information @@ -120,12 +164,19 @@ any of those replacements occurred. --color[=<when>]:: Show colored diff. - The value must be always (the default), never, or auto. + The value must be `always` (the default for `<when>`), `never`, or `auto`. + The default value is `never`. +ifdef::git-diff[] + It can be changed by the `color.ui` and `color.diff` + configuration settings. +endif::git-diff[] --no-color:: - Turn off colored diff, even when the configuration file - gives the default to color output. - Same as `--color=never`. + Turn off colored diff. +ifdef::git-diff[] + This can be used to override configuration settings. +endif::git-diff[] + It is the same as `--color=never`. --word-diff[=<mode>]:: Show a word diff, using the <mode> to delimit changed words. @@ -183,10 +234,14 @@ endif::git-format-patch[] ifndef::git-format-patch[] --check:: - Warn if changes introduce trailing whitespace - or an indent that uses a space before a tab. Exits with - non-zero status if problems are found. Not compatible with - --exit-code. + Warn if changes introduce whitespace errors. What are + considered whitespace errors is controlled by `core.whitespace` + configuration. By default, trailing whitespaces (including + lines that solely consist of whitespaces) and a space character + that is immediately followed by a tab character inside the + initial indent of the line are considered whitespace errors. + Exits with non-zero status if problems are found. Not compatible + with --exit-code. endif::git-format-patch[] --full-index:: @@ -239,7 +294,7 @@ ifdef::git-log[] For following files across renames while traversing history, see `--follow`. endif::git-log[] - If `n` is specified, it is a is a threshold on the similarity + If `n` is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the file's size). For example, `-M90%` means git should consider a delete/add pair to be a rename if more than 90% of the file @@ -259,6 +314,19 @@ endif::git-log[] projects, so use it with caution. Giving more than one `-C` option has the same effect. +-D:: +--irreversible-delete:: + Omit the preimage for deletes, i.e. print only the header but not + the diff between the preimage and `/dev/null`. The resulting patch + is not meant to be applied with `patch` nor `git apply`; this is + solely for people who want to just concentrate on reviewing the + text after the change. In addition, the output obviously lack + enough information to apply such a patch in reverse, even manually, + hence the name of the option. ++ +When used together with `-B`, omit also the preimage in the deletion part +of a delete/create pair. + -l<num>:: The `-M` and `-C` options require O(n^2) processing time where n is the number of potential rename/copy targets. This @@ -340,7 +408,12 @@ endif::git-format-patch[] Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other. +-W:: +--function-context:: + Show whole surrounding functions of changes. + ifndef::git-format-patch[] +ifndef::git-log[] --exit-code:: Make the program exit with codes similar to diff(1). That is, it exits with 1 if there were differences and @@ -348,6 +421,7 @@ ifndef::git-format-patch[] --quiet:: Disable all output of the program. Implies `--exit-code`. +endif::git-log[] endif::git-format-patch[] --ext-diff:: @@ -358,6 +432,17 @@ endif::git-format-patch[] --no-ext-diff:: Disallow external diff drivers. +--textconv:: +--no-textconv:: + Allow (or disallow) external text conversion filters to be run + when comparing binary files. See linkgit:gitattributes[5] for + details. Because textconv filters are typically a one-way + conversion, the resulting diff is suitable for human + consumption, but cannot be applied. For this reason, textconv + filters are enabled by default only for linkgit:git-diff[1] and + linkgit:git-log[1], but not for linkgit:git-format-patch[1] or + diff plumbing commands. + --ignore-submodules[=<when>]:: Ignore changes to submodules in the diff generation. <when> can be either "none", "untracked", "dirty" or "all", which is the default diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 7eebbefe7b..9c1d395722 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -134,6 +134,8 @@ subdirectories. If some files could not be added because of errors indexing them, do not abort the operation, but continue adding the others. The command shall still exit with non-zero status. + The configuration variable `add.ignoreErrors` can be set to + true to make this the default behaviour. --ignore-missing:: This option can only be used together with --dry-run. By using @@ -272,7 +274,8 @@ patch:: This lets you choose one path out of a 'status' like selection. After choosing the path, it presents the diff between the index and the working tree file and asks you if you want to stage - the change of each hunk. You can say: + the change of each hunk. You can select one of the following + options and type return: y - stage this hunk n - do not stage this hunk @@ -291,6 +294,9 @@ patch:: + After deciding the fate for all hunks, if there is any hunk that was chosen, the index is updated with the selected hunks. ++ +You can omit having to type return here, by setting the configuration +variable `interactive.singlekey` to `true`. diff:: diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 6b1b5af64e..887466d777 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -13,7 +13,8 @@ SYNOPSIS [--3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] - [--reject] [-q | --quiet] [--scissors | --no-scissors] + [--exclude=<path>] [--reject] [-q | --quiet] + [--scissors | --no-scissors] [(<mbox> | <Maildir>)...] 'git am' (--continue | --skip | --abort) @@ -87,6 +88,7 @@ default. You can use `--no-utf8` to override this. -C<n>:: -p<n>:: --directory=<dir>:: +--exclude=<path>:: --reject:: These flags are passed to the 'git apply' (see linkgit:git-apply[1]) program that applies diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index 9eb75c37da..05fd482b74 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -7,6 +7,7 @@ git-annotate - Annotate file lines with commit information SYNOPSIS -------- +[verse] 'git annotate' [options] file [revision] DESCRIPTION diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 9c750e2444..ac7006e640 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -101,6 +101,25 @@ tar.umask:: details. If `--remote` is used then only the configuration of the remote repository takes effect. +tar.<format>.command:: + This variable specifies a shell command through which the tar + output generated by `git archive` should be piped. The command + is executed using the shell with the generated tar file on its + standard input, and should produce the final output on its + standard output. Any compression-level options will be passed + to the command (e.g., "-9"). An output file with the same + extension as `<format>` will be use this format if no other + format is given. ++ +The "tar.gz" and "tgz" formats are defined automatically and default to +`gzip -cn`. You may override them with custom commands. + +tar.<format>.remote:: + If true, enable `<format>` for use by remote clients via + linkgit:git-upload-archive[1]. Defaults to false for + user-defined formats, but true for the "tar.gz" and "tgz" + formats. + ATTRIBUTES ---------- @@ -123,32 +142,46 @@ while archiving any tree in your `$GIT_DIR/info/attributes` file. EXAMPLES -------- -git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -):: +`git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)`:: Create a tar archive that contains the contents of the latest commit on the current branch, and extract it in the `/var/tmp/junk` directory. -git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz:: +`git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a compressed tarball for v1.4.0 release. -git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz:: +`git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz`:: + + Same as above, but using the builtin tar.gz handling. + +`git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0`:: + + Same as above, but the format is inferred from the output file. + +`git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz`:: Create a compressed tarball for v1.4.0 release, but without a global extended pax header. -git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip:: +`git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip`:: Put everything in the current head's Documentation/ directory into 'git-1.4.0-docs.zip', with the prefix 'git-docs/'. -git archive -o latest.zip HEAD:: +`git archive -o latest.zip HEAD`:: Create a Zip archive that contains the contents of the latest commit on the current branch. Note that the output format is inferred by the extension of the output file. +`git config tar.tar.xz.command "xz -c"`:: + + Configure a "tar.xz" format for making LZMA-compressed tarfiles. + You can use it specifying `--format=tar.xz`, or by creating an + output file like `-o foo.tar.xz`. + SEE ALSO -------- diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 7b7bafba0c..e4f46bc18d 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -8,6 +8,7 @@ git-bisect - Find by binary search the change that introduced a bug SYNOPSIS -------- +[verse] 'git bisect' <subcommand> <options> DESCRIPTION @@ -16,7 +17,7 @@ The command takes various subcommands, and different options depending on the subcommand: git bisect help - git bisect start [<bad> [<good>...]] [--] [<paths>...] + git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] git bisect bad [<rev>] git bisect good [<rev>...] git bisect skip [(<rev>|<range>)...] @@ -262,6 +263,19 @@ rewind the tree to the pristine state. Finally the script should exit with the status of the real test to let the "git bisect run" command loop determine the eventual outcome of the bisect session. +OPTIONS +------- +--no-checkout:: ++ +Do not checkout the new working tree at each iteration of the bisection +process. Instead just update a special reference named 'BISECT_HEAD' to make +it point to the commit that should be tested. ++ +This option may be useful when the test you would perform in each step +does not require a checked out tree. ++ +If the repository is bare, `--no-checkout` is assumed. + EXAMPLES -------- @@ -342,6 +356,25 @@ $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" This shows that you can do without a run script if you write the test on a single line. +* Locate a good region of the object graph in a damaged repository ++ +------------ +$ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout +$ git bisect run sh -c ' + GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) && + git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ && + git pack-objects --stdout >/dev/null <tmp.$$ + rc=$? + rm -f tmp.$$ + test $rc = 0' + +------------ ++ +In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that +has at least one parent whose reachable graph is fully traversable in the sense +required by 'git pack objects'. + + SEE ALSO -------- link:git-bisect-lk2009.html[Fighting regressions with git bisect], diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index c4d1ff86c9..9516914236 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L n,m] - [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] + [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file> DESCRIPTION @@ -73,6 +73,11 @@ include::blame-options.txt[] Ignore whitespace when comparing the parent's version and the child's to find where the lines came from. +--abbrev=<n>:: + Instead of using the default 7+1 hexadecimal digits as the + abbreviated object name, use <n>+1 digits. Note that 1 column + is used for a caret to mark the boundary commit. + THE PORCELAIN FORMAT -------------------- @@ -100,6 +105,19 @@ The contents of the actual line is output after the above header, prefixed by a TAB. This is to allow adding more header elements later. +The porcelain format generally suppresses commit information that has +already been seen. For example, two lines that are blamed to the same +commit will both be shown, but the details for that commit will be shown +only once. This is more efficient, but may require more state be kept by +the reader. The `--line-porcelain` option can be used to output full +commit information for each line, allowing simpler (but less efficient) +usage like: + + # count the number of lines attributed to each author + git blame --line-porcelain file | + sed -n 's/^author //p' | + sort | uniq -c | sort -rn + SPECIFYING RANGES ----------------- diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index c50f189827..0427e80a35 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -9,18 +9,23 @@ SYNOPSIS -------- [verse] 'git branch' [--color[=<when>] | --no-color] [-r | -a] - [-v [--abbrev=<length> | --no-abbrev]] - [(--merged | --no-merged | --contains) [<commit>]] + [--list] [-v [--abbrev=<length> | --no-abbrev]] + [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> 'git branch' (-d | -D) [-r] <branchname>... +'git branch' --edit-description [<branchname>] DESCRIPTION ----------- With no arguments, existing branches are listed and the current branch will be highlighted with an asterisk. Option `-r` causes the remote-tracking -branches to be listed, and option `-a` shows both. +branches to be listed, and option `-a` shows both. This list mode is also +activated by the `--list` option (see below). +<pattern> restricts the output to matching branches, the pattern is a shell +wildcard (i.e., matched using fnmatch(3)) +Multiple patterns may be given; if any of them matches, the tag is shown. With `--contains`, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the @@ -64,6 +69,7 @@ way to clean up all obsolete remote-tracking branches. OPTIONS ------- -d:: +--delete:: Delete a branch. The branch must be fully merged in its upstream branch, or in `HEAD` if no upstream was set with `--track` or `--set-upstream`. @@ -72,6 +78,7 @@ OPTIONS Delete a branch irrespective of its merged status. -l:: +--create-reflog:: Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@\{yesterday}". @@ -84,6 +91,7 @@ OPTIONS already. Without `-f` 'git branch' refuses to change an existing branch. -m:: +--move:: Move/rename a branch and the corresponding reflog. -M:: @@ -100,20 +108,28 @@ OPTIONS Same as `--color=never`. -r:: +--remotes:: List or delete (if used with -d) the remote-tracking branches. -a:: +--all:: List both remote-tracking branches and local branches. +--list:: + Activate the list mode. `git branch <pattern>` would try to create a branch, + use `git branch --list <pattern>` to list matching branches. + -v:: --verbose:: - Show sha1 and commit subject line for each head, along with + When in list mode, + show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print the name of the upstream branch, as well. --abbrev=<length>:: Alter the sha1's minimum display length in the output listing. - The default value is 7. + The default value is 7 and can be overridden by the `core.abbrev` + config option. --no-abbrev:: Display the full sha1s in the output listing rather than abbreviating them. @@ -143,6 +159,10 @@ start-point is either a local or remote-tracking branch. like '--track' would when creating the branch, except that where branch points to is not changed. +--edit-description:: + Open an editor and edit the text to explain what the branch is + for, to be used by various other commands (e.g. `request-pull`). + --contains <commit>:: Only list branches which contain the specified commit. diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 30eca6cee6..5abdbaa51c 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -9,8 +9,8 @@ git-check-attr - Display gitattributes information SYNOPSIS -------- [verse] -'git check-attr' attr... [--] pathname... -'git check-attr' --stdin [-z] attr... < <list-of-paths> +'git check-attr' [-a | --all | attr...] [--] pathname... +'git check-attr' --stdin [-z] [-a | --all | attr...] < <list-of-paths> DESCRIPTION ----------- @@ -19,6 +19,14 @@ For every pathname, this command will list if each attribute is 'unspecified', OPTIONS ------- +-a, --all:: + List all attributes that are associated with the specified + paths. If this option is used, then 'unspecified' attributes + will not be included in the output. + +--cached:: + Consider `.gitattributes` in the index only, ignoring the working tree. + --stdin:: Read file names from stdin instead of from the command-line. @@ -28,8 +36,11 @@ OPTIONS \--:: Interpret all preceding arguments as attributes and all following - arguments as path names. If not supplied, only the first argument will - be treated as an attribute. + arguments as path names. + +If none of `--stdin`, `--all`, or `--` is used, the first argument +will be treated as an attribute and the rest of the arguments as +pathnames. OUTPUT ------ @@ -69,6 +80,13 @@ org/example/MyClass.java: diff: java org/example/MyClass.java: myAttr: set --------------- +* Listing all attributes for a file: +--------------- +$ git check-attr --all -- org/example/MyClass.java +org/example/MyClass.java: diff: java +org/example/MyClass.java: myAttr: set +--------------- + * Listing an attribute for multiple files: --------------- $ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 205d83dd0b..103e7b128d 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -8,8 +8,9 @@ git-check-ref-format - Ensures that a reference name is well formed SYNOPSIS -------- [verse] -'git check-ref-format' <refname> -'git check-ref-format' --print <refname> +'git check-ref-format' [--normalize] + [--[no-]allow-onelevel] [--refspec-pattern] + <refname> 'git check-ref-format' --branch <branchname-shorthand> DESCRIPTION @@ -18,29 +19,38 @@ Checks if a given 'refname' is acceptable, and exits with a non-zero status if it is not. A reference is used in git to specify branches and tags. A -branch head is stored under the `$GIT_DIR/refs/heads` directory, and -a tag is stored under the `$GIT_DIR/refs/tags` directory (or, if refs -are packed by `git gc`, as entries in the `$GIT_DIR/packed-refs` file). +branch head is stored in the `refs/heads` hierarchy, while +a tag is stored in the `refs/tags` hierarchy of the ref namespace +(typically in `$GIT_DIR/refs/heads` and `$GIT_DIR/refs/tags` +directories or, as entries in file `$GIT_DIR/packed-refs` +if refs are packed by `git gc`). + git imposes the following rules on how references are named: . They can include slash `/` for hierarchical (directory) grouping, but no slash-separated component can begin with a - dot `.`. + dot `.` or end with the sequence `.lock`. . They must contain at least one `/`. This enforces the presence of a category like `heads/`, `tags/` etc. but the actual names are not - restricted. + restricted. If the `--allow-onelevel` option is used, this rule + is waived. . They cannot have two consecutive dots `..` anywhere. . They cannot have ASCII control characters (i.e. bytes whose values are lower than \040, or \177 `DEL`), space, tilde `~`, - caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`, - or open bracket `[` anywhere. + caret `{caret}`, or colon `:` anywhere. + +. They cannot have question-mark `?`, asterisk `{asterisk}`, or open + bracket `[` anywhere. See the `--refspec-pattern` option below for + an exception to this rule. -. They cannot end with a slash `/` nor a dot `.`. +. They cannot begin or end with a slash `/` or contain multiple + consecutive slashes (see the `--normalize` option below for an + exception to this rule) -. They cannot end with the sequence `.lock`. +. They cannot end with a dot `.`. . They cannot contain a sequence `@{`. @@ -65,16 +75,36 @@ reference name expressions (see linkgit:gitrevisions[7]): . at-open-brace `@{` is used as a notation to access a reflog entry. -With the `--print` option, if 'refname' is acceptable, it prints the -canonicalized name of a hypothetical reference with that name. That is, -it prints 'refname' with any extra `/` characters removed. - With the `--branch` option, it expands the ``previous branch syntax'' `@{-n}`. For example, `@{-1}` is a way to refer the last branch you were on. This option should be used by porcelains to accept this syntax anywhere a branch name is expected, so they can act as if you typed the branch name. +OPTIONS +------- +--allow-onelevel:: +--no-allow-onelevel:: + Controls whether one-level refnames are accepted (i.e., + refnames that do not contain multiple `/`-separated + components). The default is `--no-allow-onelevel`. + +--refspec-pattern:: + Interpret <refname> as a reference name pattern for a refspec + (as used with remote repositories). If this option is + enabled, <refname> is allowed to contain a single `{asterisk}` + in place of a one full pathname component (e.g., + `foo/{asterisk}/bar` but not `foo/bar{asterisk}`). + +--normalize:: + Normalize 'refname' by removing any leading slash (`/`) + characters and collapsing runs of adjacent slashes between + name components into a single slash. Iff the normalized + refname is valid then print it to standard output and exit + with a status of 0. (`--print` is a deprecated way to spell + `--normalize`.) + + EXAMPLES -------- @@ -87,7 +117,7 @@ $ git check-ref-format --branch @{-1} * Determine the reference name to use for a new branch: + ------------ -$ ref=$(git check-ref-format --print "refs/heads/$newbranch") || +$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") || die "we do not like '$newbranch' as a branch name." ------------ diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 1063f69023..c0a96e6c1e 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git checkout' [-q] [-f] [-m] [--detach] [<commit>] 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... -'git checkout' --patch [<tree-ish>] [--] [<paths>...] +'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...] DESCRIPTION ----------- @@ -45,7 +45,7 @@ $ git checkout <branch> that is to say, the branch is not reset/created unless "git checkout" is successful. -'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...:: +'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...:: When <paths> or `--patch` are given, 'git checkout' does *not* switch branches. It updates the named paths in the working tree @@ -183,7 +183,8 @@ the conflicted merge in the specified paths. working tree (and if a <tree-ish> was specified, the index). + This means that you can use `git checkout -p` to selectively discard -edits from your current working tree. +edits from your current working tree. See the ``Interactive Mode'' +section of linkgit:git-add[1] to learn how to operate the `\--patch` mode. <branch>:: Branch to checkout; if it refers to a branch (i.e., a name that, diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 01db83039f..fed5097e00 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -7,7 +7,11 @@ git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS -------- +[verse] 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>... +'git cherry-pick' --continue +'git cherry-pick' --quit +'git cherry-pick' --abort DESCRIPTION ----------- @@ -51,9 +55,10 @@ OPTIONS message prior to committing. -x:: - When recording the commit, append to the original commit - message a note that indicates which commit this change - was cherry-picked from. Append the note only for cherry + When recording the commit, append a line that says + "(cherry picked from commit ...)" to the original commit + message in order to indicate which commit this change was + cherry-picked from. This is done only for cherry picks without conflicts. Do not use this option if you are cherry-picking from your private branch because the information is useless to the recipient. If on the @@ -108,33 +113,37 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. +SEQUENCER SUBCOMMANDS +--------------------- +include::sequencer.txt[] + EXAMPLES -------- -git cherry-pick master:: +`git cherry-pick master`:: Apply the change introduced by the commit at the tip of the master branch and create a new commit with this change. -git cherry-pick ..master:: -git cherry-pick ^HEAD master:: +`git cherry-pick ..master`:: +`git cherry-pick ^HEAD master`:: Apply the changes introduced by all commits that are ancestors of master but not of HEAD to produce new commits. -git cherry-pick master{tilde}4 master{tilde}2:: +`git cherry-pick master{tilde}4 master{tilde}2`:: Apply the changes introduced by the fifth and third last commits pointed to by master and create 2 new commits with these changes. -git cherry-pick -n master~1 next:: +`git cherry-pick -n master~1 next`:: Apply to the working tree and the index the changes introduced by the second last commit pointed to by master and by the last commit pointed to by next, but do not create any commit with these changes. -git cherry-pick --ff ..next:: +`git cherry-pick --ff ..next`:: If history is linear and HEAD is an ancestor of next, update the working tree and advance the HEAD pointer to match next. @@ -142,7 +151,7 @@ git cherry-pick --ff ..next:: are in next but not HEAD to the current branch, creating a new commit for each new change. -git rev-list --reverse master \-- README | git cherry-pick -n --stdin:: +`git rev-list --reverse master \-- README | git cherry-pick -n --stdin`:: Apply the changes introduced by all commits on the master branch that touched README to the working tree and index, diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 79448c505b..f6c19c734d 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -7,6 +7,7 @@ git-cherry - Find commits not merged upstream SYNOPSIS -------- +[verse] 'git cherry' [-v] [<upstream> [<head> [<limit>]]] DESCRIPTION diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.txt index 6e5c8126f5..c7a11c36c1 100644 --- a/Documentation/git-citool.txt +++ b/Documentation/git-citool.txt @@ -7,6 +7,7 @@ git-citool - Graphical alternative to git-commit SYNOPSIS -------- +[verse] 'git citool' DESCRIPTION diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 974e04ef1a..79fb984144 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -47,12 +47,14 @@ OPTIONS -e <pattern>:: --exclude=<pattern>:: - Specify special exceptions to not be cleaned. Each <pattern> is - the same form as in $GIT_DIR/info/excludes and this option can be - given multiple times. + In addition to those found in .gitignore (per directory) and + $GIT_DIR/info/exclude, also consider these patterns to be in the + set of the ignore rules in effect. -x:: - Don't use the ignore rules. This allows removing all untracked + Don't use the standard ignore rules read from .gitignore (per + directory) and $GIT_DIR/info/exclude, but do still use the ignore + rules given with `-e` options. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with 'git reset') to create a pristine working directory to test a clean build. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 86eb4c9368..4b8b26b75e 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] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] - [--separate-git-dir|-L <git dir>] + [--separate-git-dir <git dir>] [--depth <depth>] [--recursive|--recurse-submodules] [--] <repository> [<directory>] @@ -159,6 +159,17 @@ objects from the source repository into a pack in the cloned repository. Specify the directory from which templates will be used; (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) +--config <key>=<value>:: +-c <key>=<value>:: + Set a configuration variable in the newly-created repository; + this takes effect immediately after the repository is + initialized, but before the remote history is fetched or any + files checked out. The key is in the same format as expected by + linkgit:git-config[1] (e.g., `core.eol=true`). If multiple + values are given for the same key, each value will be written to + the config file. This makes it safe, for example, to add + additional fetch refspecs to the origin remote. + --depth <depth>:: Create a 'shallow' clone with a history truncated to the specified number of revisions. A shallow repository has a @@ -177,7 +188,6 @@ objects from the source repository into a pack in the cloned repository. repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) --L=<git dir>:: --separate-git-dir=<git dir>:: Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index f524d76019..cfb9906bb5 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -8,7 +8,9 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- -'git commit-tree' <tree> [(-p <parent commit>)...] < changelog +[verse] +'git commit-tree' <tree> [(-p <parent>)...] < changelog +'git commit-tree' [(-p <parent>)...] [(-m <message>)...] [(-F <file>)...] <tree> DESCRIPTION ----------- @@ -16,7 +18,8 @@ This is usually not what an end user wants to run directly. See linkgit:git-commit[1] instead. Creates a new commit object based on the provided tree object and -emits the new commit object id on stdout. +emits the new commit object id on stdout. The log message is read +from the standard input, unless `-m` or `-F` options are given. A commit object may have any number of parents. With exactly one parent, it is an ordinary commit. Having more than one parent makes @@ -38,9 +41,17 @@ OPTIONS <tree>:: An existing tree object --p <parent commit>:: +-p <parent>:: Each '-p' indicates the id of a parent commit object. +-m <message>:: + A paragraph in the commig log message. This can be given more than + once and each <message> becomes its own paragraph. + +-F <file>:: + Read the commit log message from the given file. Use `-` to read + from the standard input. + Commit Information ------------------ @@ -67,7 +78,9 @@ if set: In case (some of) these environment variables are not set, the information is taken from the configuration items user.name and user.email, or, if not -present, system user name and fully qualified hostname. +present, system user name and the hostname used for outgoing mail (taken +from `/etc/mailname` and falling back to the fully qualified hostname when +that file does not exist). A commit comment is read from stdin. If a changelog entry is not provided via "<" redirection, 'git commit-tree' will just wait @@ -89,6 +102,10 @@ Discussion include::i18n.txt[] +FILES +----- +/etc/mailname + SEE ALSO -------- linkgit:git-write-tree[1] diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index d0534b8c05..5cc84a1391 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,11 +8,12 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] [--dry-run] - [(-c | -C | --fixup | --squash) <commit>] [-F <file> | -m <msg>] - [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] - [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] - [--status | --no-status] [-i | -o] [--] [<file>...] +'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] + [--dry-run] [(-c | -C | --fixup | --squash) <commit>] + [-F <file> | -m <msg>] [--reset-author] [--allow-empty] + [--allow-empty-message] [--no-verify] [-e] [--author=<author>] + [--date=<date>] [--cleanup=<mode>] [--status | --no-status] + [-i | -o] [--] [<file>...] DESCRIPTION ----------- @@ -39,9 +40,10 @@ The content to be added can be specified in several ways: that have been removed from the working tree, and then perform the actual commit; -5. by using the --interactive switch with the 'commit' command to decide one - by one which files should be part of the commit, before finalizing the - operation. Currently, this is done by invoking 'git add --interactive'. +5. by using the --interactive or --patch switches with the 'commit' command + to decide one by one which files or hunks should be part of the commit, + before finalizing the operation. See the ``Interactive Mode`` section of + linkgit:git-add[1] to learn how to operate these modes. The `--dry-run` option can be used to obtain a summary of what is included by any of the above for the next @@ -59,6 +61,12 @@ OPTIONS been modified and deleted, but new files you have not told git about are not affected. +-p:: +--patch:: + Use the interactive patch selection interface to chose + which changes to commit. See linkgit:git-add[1] for + details. + -C <commit>:: --reuse-message=<commit>:: Take an existing commit object, and reuse the log message @@ -276,7 +284,7 @@ When recording your own work, the contents of modified files in your working tree are temporarily stored to a staging area called the "index" with 'git add'. A file can be reverted back, only in the index but not in the working tree, -to that of the last commit with `git reset HEAD -- <file>`, +to that of the last commit with `git reset HEAD \-- <file>`, which effectively reverts 'git add' and prevents the changes to this file from participating in the next commit. After building the state to be committed incrementally with these commands, diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 8804de327f..e7ecf5d803 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -50,16 +50,18 @@ The default is to assume the config file of the current repository, .git/config unless defined otherwise with GIT_DIR and GIT_CONFIG (see <<FILES>>). -This command will fail if: - -. The config file is invalid, -. Can not write to the config file, -. no section was provided, -. the section or key is invalid, -. you try to unset an option which does not exist, -. you try to unset/set an option for which multiple lines match, or -. you use '--global' option without $HOME being properly set. - +This command will fail (with exit code ret) if: + +. The config file is invalid (ret=3), +. can not write to the config file (ret=4), +. no section or name was provided (ret=2), +. the section or key is invalid (ret=1), +. you try to unset an option which does not exist (ret=5), +. you try to unset/set an option for which multiple lines match (ret=5), +. you try to use an invalid regexp (ret=6), or +. you use '--global' option without $HOME being properly set (ret=128). + +On success, the command returns the exit code 0. OPTIONS ------- diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index a73933a931..23c80cea64 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -7,6 +7,7 @@ git-count-objects - Count unpacked number of objects and their disk consumption SYNOPSIS -------- +[verse] 'git count-objects' [-v] DESCRIPTION diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt new file mode 100644 index 0000000000..11edc5a173 --- /dev/null +++ b/Documentation/git-credential-cache--daemon.txt @@ -0,0 +1,26 @@ +git-credential-cache--daemon(1) +=============================== + +NAME +---- +git-credential-cache--daemon - temporarily store user credentials in memory + +SYNOPSIS +-------- +[verse] +git credential-cache--daemon <socket> + +DESCRIPTION +----------- + +NOTE: You probably don't want to invoke this command yourself; it is +started automatically when you use linkgit:git-credential-cache[1]. + +This command listens on the Unix domain socket specified by `<socket>` +for `git-credential-cache` clients. Clients may store and retrieve +credentials. Each credential is held for a timeout specified by the +client; once no credentials are held, the daemon exits. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt new file mode 100644 index 0000000000..f3d09c5d51 --- /dev/null +++ b/Documentation/git-credential-cache.txt @@ -0,0 +1,77 @@ +git-credential-cache(1) +======================= + +NAME +---- +git-credential-cache - helper to temporarily store passwords in memory + +SYNOPSIS +-------- +----------------------------- +git config credential.helper 'cache [options]' +----------------------------- + +DESCRIPTION +----------- + +This command caches credentials in memory for use by future git +programs. The stored credentials never touch the disk, and are forgotten +after a configurable timeout. The cache is accessible over a Unix +domain socket, restricted to the current user by filesystem permissions. + +You probably don't want to invoke this command directly; it is meant to +be used as a credential helper by other parts of git. See +linkgit:gitcredentials[7] or `EXAMPLES` below. + +OPTIONS +------- + +--timeout <seconds>:: + + Number of seconds to cache credentials (default: 900). + +--socket <path>:: + + Use `<path>` to contact a running cache daemon (or start a new + cache daemon if one is not started). Defaults to + `~/.git-credential-cache/socket`. If your home directory is on a + network-mounted filesystem, you may need to change this to a + local filesystem. + +CONTROLLING THE DAEMON +---------------------- + +If you would like the daemon to exit early, forgetting all cached +credentials before their timeout, you can issue an `exit` action: + +-------------------------------------- +git credential-cache exit +-------------------------------------- + +EXAMPLES +-------- + +The point of this helper is to reduce the number of times you must type +your username or password. For example: + +------------------------------------ +$ git config credential.helper cache +$ git push http://example.com/repo.git +Username: <type your username> +Password: <type your password> + +[work for 5 more minutes] +$ git push http://example.com/repo.git +[your credentials are used automatically] +------------------------------------ + +You can provide options via the credential.helper configuration +variable (this example drops the cache time to 5 minutes): + +------------------------------------------------------- +$ git config credential.helper 'cache --timeout=300' +------------------------------------------------------- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt new file mode 100644 index 0000000000..31093467d1 --- /dev/null +++ b/Documentation/git-credential-store.txt @@ -0,0 +1,75 @@ +git-credential-store(1) +======================= + +NAME +---- +git-credential-store - helper to store credentials on disk + +SYNOPSIS +-------- +------------------- +git config credential.helper 'store [options]' +------------------- + +DESCRIPTION +----------- + +NOTE: Using this helper will store your passwords unencrypted on disk, +protected only by filesystem permissions. If this is not an acceptable +security tradeoff, try linkgit:git-credential-cache[1], or find a helper +that integrates with secure storage provided by your operating system. + +This command stores credentials indefinitely on disk for use by future +git programs. + +You probably don't want to invoke this command directly; it is meant to +be used as a credential helper by other parts of git. See +linkgit:gitcredentials[7] or `EXAMPLES` below. + +OPTIONS +------- + +--store=<path>:: + + Use `<path>` to store credentials. The file will have its + filesystem permissions set to prevent other users on the system + from reading it, but will not be encrypted or otherwise + protected. Defaults to `~/.git-credentials`. + +EXAMPLES +-------- + +The point of this helper is to reduce the number of times you must type +your username or password. For example: + +------------------------------------------ +$ git config credential.helper store +$ git push http://example.com/repo.git +Username: <type your username> +Password: <type your password> + +[several days later] +$ git push http://example.com/repo.git +[your credentials are used automatically] +------------------------------------------ + +STORAGE FORMAT +-------------- + +The `.git-credentials` file is stored in plaintext. Each credential is +stored on its own line as a URL like: + +------------------------------ +https://user:pass@example.com +------------------------------ + +When git needs authentication for a particular URL context, +credential-store will consider that context a pattern to match against +each entry in the credentials file. If the protocol, hostname, and +username (if we already have one) match, then the password is returned +to git. See the discussion of configuration in linkgit:gitcredentials[7] +for more information. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index ad93a3e84e..7f79cec3f8 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,6 +8,7 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- +[verse] 'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 88d814af0e..827bc988ed 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -252,7 +252,7 @@ Configuring database backend 'git-cvsserver' uses the Perl DBI module. Please also read its documentation if changing these variables, especially -about `DBI->connect()`. +about `DBI\->connect()`. gitcvs.dbname:: Database name. The exact meaning depends on the diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index ebd13be72e..31b28fc29f 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -93,14 +93,14 @@ OPTIONS Listen on an alternative port. Incompatible with '--inetd' option. --init-timeout=<n>:: - Timeout between the moment the connection is established and the - client request is received (typically a rather low value, since + Timeout (in seconds) between the moment the connection is established + and the client request is received (typically a rather low value, since that should be basically immediate). --timeout=<n>:: - Timeout for specific client sub-requests. This includes the time - it takes for the server to process the sub-request and the time spent - waiting for the next client's request. + Timeout (in seconds) for specific client sub-requests. This includes + the time it takes for the server to process the sub-request and the + time spent waiting for the next client's request. --max-connections=<n>:: Maximum number of concurrent clients, defaults to 32. Set it to @@ -161,6 +161,16 @@ the facility of inet daemon to achieve the same before spawning repository configuration. By default, all the services are overridable. +--informative-errors:: +--no-informative-errors:: + When informative errors are turned on, git-daemon will report + more verbose errors to the client, differentiating conditions + like "no such repository" from "repository not exported". This + is more convenient for clients, but may leak information about + the existence of unexported repositories. When informative + errors are not enabled, all errors report "access denied" to the + client. The default is --no-informative-errors. + <directory>:: A directory to add to the whitelist of allowed directories. Unless --strict-paths is specified this will also include subdirectories diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 8d481948bd..906774f0f7 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -8,6 +8,7 @@ git-diff-files - Compares files in the working tree and the index SYNOPSIS -------- +[verse] 'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] DESCRIPTION diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 6d18486402..c0b7c581ad 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -8,6 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi SYNOPSIS -------- +[verse] 'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] DESCRIPTION @@ -96,8 +97,8 @@ show that. So let's say that you have edited `kernel/sched.c`, but have not actually done a 'git update-index' on it yet - there is no "object" associated with the new state, and you get: - torvalds@ppc970:~/v2.6/linux> git diff-index HEAD - *100644->100664 blob 7476bb......->000000...... kernel/sched.c + torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD + :100644 100664 7476bb... 000000... kernel/sched.c i.e., it shows that the tree has changed, and that `kernel/sched.c` has is not up-to-date and may contain new stuff. The all-zero sha1 means that to diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 4e5f127efa..1439486e40 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -138,8 +138,8 @@ so it can be used to name subdirectories. An example of normal usage is: - torvalds@ppc970:~/git> git diff-tree 5319e4...... - *100664->100664 blob ac348b.......->a01513....... git-fsck-objects.c + torvalds@ppc970:~/git> git diff-tree --abbrev 5319e4 + :100664 100664 ac348b... a01513... git-fsck-objects.c which tells you that the last commit changed just one file (it's from this one: diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 590f410abf..19d473c070 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -7,6 +7,7 @@ git-difftool - Show changes using common diff tools SYNOPSIS -------- +[verse] 'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...] DESCRIPTION @@ -30,7 +31,7 @@ OPTIONS -t <tool>:: --tool=<tool>:: Use the diff tool specified by <tool>. - Valid merge tools are: + Valid diff tools are: araxis, bc3, diffuse, emerge, ecmerge, gvimdiff, kdiff3, kompare, meld, opendiff, p4merge, tkdiff, vimdiff and xxdiff. + diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 781bd6edc3..f37eada63a 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -8,6 +8,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- +[verse] 'git fast-export [options]' | 'git fast-import' DESCRIPTION @@ -82,6 +83,10 @@ marks the same across runs. allow that. So fake a tagger to be able to fast-import the output. +--use-done-feature:: + Start the stream with a 'feature done' stanza, and terminate + it with a 'done' command. + --no-data:: Skip output of blob objects and instead refer to blobs via their original SHA-1 hash. This is useful when rewriting the diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 2c2ea12c5c..ec6ef31197 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -8,6 +8,7 @@ git-fast-import - Backend for fast Git data importers SYNOPSIS -------- +[verse] frontend | 'git fast-import' [options] DESCRIPTION @@ -83,7 +84,7 @@ OPTIONS skips the file if it does not exist. --relative-marks:: - After specifying --relative-marks= the paths specified + After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. In git-fast-import this means that the paths are relative @@ -93,7 +94,7 @@ OPTIONS --no-relative-marks:: Negates a previous --relative-marks. Allows for combining relative and non-relative marks by interweaving - --(no-)-relative-marks= with the --(import|export)-marks= + --(no-)-relative-marks with the --(import|export)-marks= options. --cat-blob-fd=<fd>:: @@ -101,6 +102,12 @@ OPTIONS when the `cat-blob` command is encountered in the stream. The default behaviour is to write to `stdout`. +--done:: + Require a `done` command at the end of the stream. + This option might be useful for detecting errors that + cause the frontend to terminate before it has started to + write a stream. + --export-pack-edges=<file>:: After creating a packfile, print a line of data to <file> listing the filename of the packfile and the last @@ -330,6 +337,11 @@ and control the current import process. More detailed discussion standard output. This command is optional and is not needed to perform an import. +`done`:: + Marks the end of the stream. This command is optional + unless the `done` feature was requested using the + `--done` command line option or `feature done` command. + `cat-blob`:: Causes fast-import to print a blob in 'cat-file --batch' format to the file descriptor set with `--cat-blob-fd` or @@ -413,8 +425,8 @@ Here `<name>` is the person's display name (for example (``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) and greater-than (\x3e) symbols. These are required to delimit the email address from the other fields in the line. Note that -`<name>` is free-form and may contain any sequence of bytes, except -`LT` and `LF`. It is typically UTF-8 encoded. +`<name>` and `<email>` are free-form and may contain any sequence +of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded. The time of the change is specified by `<when>` using the date format that was selected by the \--date-format=<fmt> command line option. @@ -648,9 +660,14 @@ paths for a commit are encouraged to do so. `notemodify` ^^^^^^^^^^^^ -Included in a `commit` command to add a new note (annotating a given -commit) or change the content of an existing note. This command has -two different means of specifying the content of the note. +Included in a `commit` `<notes_ref>` command to add a new note +annotating a `<committish>` or change this annotation contents. +Internally it is similar to filemodify 100644 on `<committish>` +path (maybe split into subdirectories). It's not advised to +use any other commands to write to the `<notes_ref>` tree except +`filedeleteall` to delete all existing notes in this tree. +This command has two different means of specifying the content +of the note. External data format:: The data content for the note was already supplied by a prior @@ -995,10 +1012,14 @@ force:: (see OPTIONS, above). import-marks:: +import-marks-if-exists:: Like --import-marks except in two respects: first, only one - "feature import-marks" command is allowed per stream; - second, an --import-marks= command-line option overrides - any "feature import-marks" command in the stream. + "feature import-marks" or "feature import-marks-if-exists" + command is allowed per stream; second, an --import-marks= + or --import-marks-if-exists command-line option overrides + any of these "feature" commands in the stream; third, + "feature import-marks-if-exists" like a corresponding + command-line option silently skips a nonexistent file. cat-blob:: ls:: @@ -1015,6 +1036,11 @@ notes:: Versions of fast-import not supporting notes will exit with a message indicating so. +done:: + Error out if the stream ends without a 'done' command. + Without this feature, errors causing the frontend to end + abruptly at a convenient point in the stream can go + undetected. `option` ~~~~~~~~ @@ -1044,6 +1070,15 @@ not be passed as option: * cat-blob-fd * force +`done` +~~~~~~ +If the `done` feature is not in use, treated as if EOF was read. +This can be used to tell fast-import to finish early. + +If the `--done` command line option or `feature done` command is +in use, the `done` command is mandatory and marks the end of the +stream. + Crash Reports ------------- If fast-import is supplied invalid input it will terminate with a diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 48d4bf6d68..ed1bdaacd1 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -8,6 +8,7 @@ git-fetch-pack - Receive missing objects from another repository SYNOPSIS -------- +[verse] 'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...] DESCRIPTION diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 60ac8d26eb..b41d7c1de1 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -8,12 +8,10 @@ git-fetch - Download objects and refs from another repository SYNOPSIS -------- +[verse] 'git fetch' [<options>] [<repository> [<refspec>...]] - 'git fetch' [<options>] <group> - 'git fetch' --multiple [<options>] [(<repository> | <group>)...] - 'git fetch' --all [<options>] diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 9dc1f2a947..0f2f117383 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,8 +32,9 @@ changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. -*NOTE*: This command honors `.git/info/grafts`. If you have any grafts -defined, running this command will make them permanent. +*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +If you have any grafts or replacement refs defined, running this command +will make them permanent. *WARNING*! The rewritten history will have different object names for all the objects and will not converge with the original branch. You will not diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 152e695c81..c872b883ba 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -101,9 +101,10 @@ Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. -The first line of the message in a commit and tag object is -`subject`, the remaining lines are `body`. The whole message -is `contents`. +The complete message in a commit and tag object is `contents`. +Its first line is `contents:subject`, the remaining lines +are `contents:body` and the optional GPG signature +is `contents:signature`. For sorting purposes, fields with numeric values sort in numeric order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index a5525e9aa8..6ea9be775c 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -20,7 +20,7 @@ SYNOPSIS [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] [--to=<email>] [--cc=<email>] - [--cover-letter] + [--cover-letter] [--quiet] [<common diff options>] [ <since> | <revision range> ] @@ -166,15 +166,22 @@ will want to ensure that threading is disabled for `git send-email`. --to=<email>:: Add a `To:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. + The negated form `--no-to` discards all `To:` headers added so + far (from config or command line). --cc=<email>:: Add a `Cc:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. + The negated form `--no-cc` discards all `Cc:` headers added so + far (from config or command line). --add-header=<header>:: Add an arbitrary header to the email headers. This is in addition to any configured headers, and may be used multiple times. - For example, `--add-header="Organization: git-foo"` + For example, `--add-header="Organization: git-foo"`. + The negated form `--no-add-header` discards *all* (`To:`, + `Cc:`, and custom) headers added so far from config or command + line. --cover-letter:: In addition to the patches, generate a cover letter file @@ -196,6 +203,9 @@ will want to ensure that threading is disabled for `git send-email`. Note that the leading character does not have to be a dot; for example, you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. +--quiet:: + Do not print the names of the generated files to standard output. + --no-binary:: Do not output contents of changes in binary files, instead display a notice that those files changed. Patches generated @@ -229,6 +239,233 @@ attachments, and sign off patches with configuration variables. ------------ +DISCUSSION +---------- + +The patch produced by 'git format-patch' is in UNIX mailbox format, +with a fixed "magic" time stamp to indicate that the file is output +from format-patch rather than a real mailbox, like so: + +------------ +From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001 +From: Tony Luck <tony.luck@intel.com> +Date: Tue, 13 Jul 2010 11:42:54 -0700 +Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?= + =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?= +MIME-Version: 1.0 +Content-Type: text/plain; charset=UTF-8 +Content-Transfer-Encoding: 8bit + +arch/arm config files were slimmed down using a python script +(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment) + +Do the same for ia64 so we can have sleek & trim looking +... +------------ + +Typically it will be placed in a MUA's drafts folder, edited to add +timely commentary that should not go in the changelog after the three +dashes, and then sent as a message whose body, in our example, starts +with "arch/arm config files were...". On the receiving end, readers +can save interesting patches in a UNIX mailbox and apply them with +linkgit:git-am[1]. + +When a patch is part of an ongoing discussion, the patch generated by +'git format-patch' can be tweaked to take advantage of the 'git am +--scissors' feature. After your response to the discussion comes a +line that consists solely of "`-- >8 --`" (scissors and perforation), +followed by the patch with unnecessary header fields removed: + +------------ +... +> So we should do such-and-such. + +Makes sense to me. How about this patch? + +-- >8 -- +Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet + +arch/arm config files were slimmed down using a python script +... +------------ + +When sending a patch this way, most often you are sending your own +patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you +should omit `From:` and `Date:` lines from the patch file. The patch +title is likely to be different from the subject of the discussion the +patch is in response to, so it is likely that you would want to keep +the Subject: line, like the example above. + +Checking for patch corruption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Many mailers if not set up properly will corrupt whitespace. Here are +two common types of corruption: + +* Empty context lines that do not have _any_ whitespace. + +* Non-empty context lines that have one extra whitespace at the + beginning. + +One way to test if your MUA is set up correctly is: + +* Send the patch to yourself, exactly the way you would, except + with To: and Cc: lines that do not contain the list and + maintainer address. + +* Save that patch to a file in UNIX mailbox format. Call it a.patch, + say. + +* Apply it: + + $ git fetch <project> master:test-apply + $ git checkout test-apply + $ git reset --hard + $ git am a.patch + +If it does not apply correctly, there can be various reasons. + +* The patch itself does not apply cleanly. That is _bad_ but + does not have much to do with your MUA. You might want to rebase + the patch with linkgit:git-rebase[1] before regenerating it in + this case. + +* The MUA corrupted your patch; "am" would complain that + the patch does not apply. Look in the .git/rebase-apply/ subdirectory and + see what 'patch' file contains and check for the common + corruption patterns mentioned above. + +* While at it, check the 'info' and 'final-commit' files as well. + If what is in 'final-commit' is not exactly what you would want to + see in the commit log message, it is very likely that the + receiver would end up hand editing the log message when applying + your patch. Things like "Hi, this is my first patch.\n" in the + patch e-mail should come after the three-dash line that signals + the end of the commit message. + +MUA-SPECIFIC HINTS +------------------ +Here are some hints on how to successfully submit patches inline using +various mailers. + +GMail +~~~~~ +GMail does not have any way to turn off line wrapping in the web +interface, so it will mangle any emails that you send. You can however +use "git send-email" and send your patches through the GMail SMTP server, or +use any IMAP email client to connect to the google IMAP server and forward +the emails through that. + +For hints on using 'git send-email' to send your patches through the +GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1]. + +For hints on submission using the IMAP interface, see the EXAMPLE +section of linkgit:git-imap-send[1]. + +Thunderbird +~~~~~~~~~~~ +By default, Thunderbird will both wrap emails as well as flag +them as being 'format=flowed', both of which will make the +resulting email unusable by git. + +There are three different approaches: use an add-on to turn off line wraps, +configure Thunderbird to not mangle patches, or use +an external editor to keep Thunderbird from mangling the patches. + +Approach #1 (add-on) +^^^^^^^^^^^^^^^^^^^^ + +Install the Toggle Word Wrap add-on that is available from +https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ +It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu +that you can tick off. Now you can compose the message as you otherwise do +(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to +insert line breaks manually in any text that you type. + +Approach #2 (configuration) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Three steps: + +1. Configure your mail server composition as plain text: + Edit...Account Settings...Composition & Addressing, + uncheck "Compose Messages in HTML". + +2. Configure your general composition window to not wrap. ++ +In Thunderbird 2: +Edit..Preferences..Composition, wrap plain text messages at 0 ++ +In Thunderbird 3: +Edit..Preferences..Advanced..Config Editor. Search for +"mail.wrap_long_lines". +Toggle it to make sure it is set to `false`. + +3. Disable the use of format=flowed: +Edit..Preferences..Advanced..Config Editor. Search for +"mailnews.send_plaintext_flowed". +Toggle it to make sure it is set to `false`. + +After that is done, you should be able to compose email as you +otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc), +and the patches will not be mangled. + +Approach #3 (external editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following Thunderbird extensions are needed: +AboutConfig from http://aboutconfig.mozdev.org/ and +External Editor from http://globs.org/articles.php?lng=en&pg=8 + +1. Prepare the patch as a text file using your method of choice. + +2. Before opening a compose window, use Edit->Account Settings to + uncheck the "Compose messages in HTML format" setting in the + "Composition & Addressing" panel of the account to be used to + send the patch. + +3. In the main Thunderbird window, 'before' you open the compose + window for the patch, use Tools->about:config to set the + following to the indicated values: ++ +---------- + mailnews.send_plaintext_flowed => false + mailnews.wraplength => 0 +---------- + +4. Open a compose window and click the external editor icon. + +5. In the external editor window, read in the patch file and exit + the editor normally. + +Side note: it may be possible to do step 2 with +about:config and the following settings but no one's tried yet. + +---------- + mail.html_compose => false + mail.identity.default.compose_html => false + mail.identity.id?.compose_html => false +---------- + +There is a script in contrib/thunderbird-patch-inline which can help +you include patches with Thunderbird in an easy way. To use it, do the +steps above and then use the script as the external editor. + +KMail +~~~~~ +This should help you to submit patches inline using KMail. + +1. Prepare the patch as a text file. + +2. Click on New Mail. + +3. Go under "Options" in the Composer window and be sure that + "Word wrap" is not set. + +4. Use Message -> Insert file... and insert the patch. + +5. Back in the compose window: add whatever other text you wish to the + message, complete the addressing and subject fields, and press send. + + EXAMPLES -------- diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt index 90ebb8a594..eec4bdb600 100644 --- a/Documentation/git-fsck-objects.txt +++ b/Documentation/git-fsck-objects.txt @@ -8,6 +8,7 @@ git-fsck-objects - Verifies the connectivity and validity of the objects in the SYNOPSIS -------- +[verse] 'git fsck-objects' ... DESCRIPTION diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index c9ede794b0..6c47395ad2 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -10,7 +10,8 @@ SYNOPSIS -------- [verse] 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] - [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>*] + [--[no-]full] [--strict] [--verbose] [--lost-found] + [--[no-]progress] [<object>*] DESCRIPTION ----------- @@ -26,7 +27,7 @@ index file, all SHA1 references in .git/refs/*, and all reflogs (unless --no-reflogs is given) as heads. --unreachable:: - Print out objects that exist but that aren't readable from any + Print out objects that exist but that aren't reachable from any of the reference nodes. --root:: @@ -72,30 +73,28 @@ index file, all SHA1 references in .git/refs/*, and all reflogs (unless a blob, the contents are written into the file, rather than its object name. -It tests SHA1 and general object sanity, and it does full tracking of -the resulting reachability and everything else. It prints out any -corruption it finds (missing or bad objects), and if you use the -'--unreachable' flag it will also print out objects that exist but -that aren't readable from any of the specified head nodes. - -So for example +--progress:: +--no-progress:: + Progress status is reported on the standard error stream by + default when it is attached to a terminal, unless + --no-progress or --verbose is specified. --progress forces + progress status even if the standard error stream is not + directed to a terminal. - git fsck --unreachable HEAD \ - $(git for-each-ref --format="%(objectname)" refs/heads) +DISCUSSION +---------- -will do quite a _lot_ of verification on the tree. There are a few -extra validity tests to be added (make sure that tree objects are -sorted properly etc), but on the whole if 'git fsck' is happy, you -do have a valid tree. +git-fsck tests SHA1 and general object sanity, and it does full tracking +of the resulting reachability and everything else. It prints out any +corruption it finds (missing or bad objects), and if you use the +'--unreachable' flag it will also print out objects that exist but that +aren't reachable from any of the specified head nodes (or the default +set, as mentioned above). Any corrupt objects you will have to find in backups or other archives (i.e., you can just remove them and do an 'rsync' with some other site in the hopes that somebody else has the object you have corrupted). -Of course, "valid tree" doesn't mean that it wasn't generated by some -evil person, and the end result might be crap. git is a revision -tracking system, not a quality assurance system ;) - Extracted Diagnostics --------------------- diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 4966cb5784..815afcb922 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -8,6 +8,7 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- +[verse] 'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] DESCRIPTION diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 8035736c96..1e2a20dd26 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -8,6 +8,7 @@ git-get-tar-commit-id - Extract commit ID from an archive created using git-arch SYNOPSIS -------- +[verse] 'git get-tar-commit-id' < <tarfile> diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index d7523b3e45..6a8b1e3a7d 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -12,7 +12,8 @@ SYNOPSIS 'git grep' [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp] [-v | --invert-match] [-h|-H] [--full-name] [-E | --extended-regexp] [-G | --basic-regexp] - [-F | --fixed-strings] [-n] + [-P | --perl-regexp] + [-F | --fixed-strings] [-n | --line-number] [-l | --files-with-matches] [-L | --files-without-match] [(-O | --open-files-in-pager) [<pager>]] [-z | --null] @@ -22,7 +23,7 @@ SYNOPSIS [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] - [--cached | --no-index | <tree>...] + [ [--exclude-standard] [--cached | --no-index | --untracked] | <tree>...] [--] [<pathspec>...] DESCRIPTION @@ -48,7 +49,20 @@ OPTIONS blobs registered in the index file. --no-index:: - Search files in the current directory, not just those tracked by git. + Search files in the current directory that is not managed by git. + +--untracked:: + In addition to searching in the tracked files in the working + tree, search also in untracked files. + +--no-exclude-standard:: + Also search in ignored files by not honoring the `.gitignore` + mechanism. Only useful with `--untracked`. + +--exclude-standard:: + Do not pay attention to ignored files specified via the `.gitignore` + mechanism. Only useful when searching files in the current directory + with `--no-index`. -a:: --text:: @@ -65,6 +79,9 @@ OPTIONS --max-depth <depth>:: For each <pathspec> given on command line, descend at most <depth> levels of directories. A negative value means no limit. + This option is ignored if <pathspec> contains active wildcards. + In other words if "a*" matches a directory named "a*", + "*" is matched literally so --max-depth is still effective. -w:: --word-regexp:: @@ -97,6 +114,11 @@ OPTIONS Use POSIX extended/basic regexp for patterns. Default is to use basic regexp. +-P:: +--perl-regexp:: + Use Perl-compatible regexp for patterns. Requires libpcre to be + compiled in. + -F:: --fixed-strings:: Use fixed strings for patterns (don't interpret pattern @@ -142,14 +164,12 @@ OPTIONS gives the default to color output. Same as `--color=never`. --[ABC] <context>:: - Show `context` trailing (`A` -- after), or leading (`B` - -- before), or both (`C` -- context) lines, and place a - line containing `--` between contiguous groups of - matches. +--break:: + Print an empty line between matches from different files. --<num>:: - A shortcut for specifying `-C<num>`. +--heading:: + Show the filename above the matches in that file instead of + at the start of each shown line. -p:: --show-function:: @@ -159,6 +179,29 @@ OPTIONS patch hunk headers (see 'Defining a custom hunk-header' in linkgit:gitattributes[5]). +-<num>:: +-C <num>:: +--context <num>:: + Show <num> leading and trailing lines, and place a line + containing `--` between contiguous groups of matches. + +-A <num>:: +--after-context <num>:: + Show <num> trailing lines, and place a line containing + `--` between contiguous groups of matches. + +-B <num>:: +--before-context <num>:: + Show <num> leading lines, and place a line containing + `--` between contiguous groups of matches. + +-W:: +--function-context:: + Show the surrounding text from the previous line containing a + function name up to the one before the next function name, + effectively showing the whole function in which the match was + found. + -f <file>:: Read patterns from <file>, one per line. @@ -202,15 +245,15 @@ OPTIONS Examples -------- -git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}:: +`git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}`:: Looks for `time_t` in all tracked .c and .h files in the working directory and its subdirectories. -git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \):: +`git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \)`:: Looks for a line that has `#define` and either `MAX_PATH` or `PATH_MAX`. -git grep --all-match -e NODE -e Unexpected:: +`git grep --all-match -e NODE -e Unexpected`:: Looks for a line that has `NODE` or `Unexpected` in files that have lines that match both. diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index 32a833e0ae..0041994443 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -7,6 +7,7 @@ git-gui - A portable graphical interface to Git SYNOPSIS -------- +[verse] 'git gui' [<command>] [arguments] DESCRIPTION @@ -49,7 +50,7 @@ version:: Examples -------- -git gui blame Makefile:: +`git gui blame Makefile`:: Show the contents of the file 'Makefile' in the current working directory, and provide annotations for both the @@ -58,41 +59,41 @@ git gui blame Makefile:: uncommitted changes (if any) are explicitly attributed to 'Not Yet Committed'. -git gui blame v0.99.8 Makefile:: +`git gui blame v0.99.8 Makefile`:: Show the contents of 'Makefile' in revision 'v0.99.8' and provide annotations for each line. Unlike the above example the file is read from the object database and not the working directory. -git gui blame --line=100 Makefile:: +`git gui blame --line=100 Makefile`:: Loads annotations as described above and automatically scrolls the view to center on line '100'. -git gui citool:: +`git gui citool`:: Make one commit and return to the shell when it is complete. This command returns a non-zero exit code if the window was closed in any way other than by making a commit. -git gui citool --amend:: +`git gui citool --amend`:: Automatically enter the 'Amend Last Commit' mode of the interface. -git gui citool --nocommit:: +`git gui citool --nocommit`:: Behave as normal citool, but instead of making a commit simply terminate with a zero exit code. It still checks that the index does not contain any unmerged entries, so you can use it as a GUI version of linkgit:git-mergetool[1] -git citool:: +`git citool`:: Same as `git gui citool` (above). -git gui browser maint:: +`git gui browser maint`:: Show a browser for the tree of the 'maint' branch. Files selected in the browser can be viewed with the internal diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 42aa2b0c01..9e0b3f6811 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -7,6 +7,7 @@ git-help - display help information about git SYNOPSIS -------- +[verse] 'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND] DESCRIPTION diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index 277d9e141b..f4e0741c11 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -119,6 +119,14 @@ ScriptAliasMatch \ ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ ---------------------------------------------------------------- ++ +To serve multiple repositories from different linkgit:gitnamespaces[7] in a +single repository: ++ +---------------------------------------------------------------- +SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1 +ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1 +---------------------------------------------------------------- Accelerated static Apache 2.x:: Similar to the above, but Apache can be used to return static diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index fefa752198..070cd1e6ed 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -8,12 +8,16 @@ git-http-fetch - Download from a remote git repository via HTTP SYNOPSIS -------- +[verse] 'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url> DESCRIPTION ----------- Downloads a remote git repository via HTTP. +*NOTE*: use of this command without -a is deprecated. The -a +behaviour will become the default in a future release. + OPTIONS ------- commit-id:: diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index 82ae34b9b8..2e67362bd4 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -8,6 +8,7 @@ git-http-push - Push objects over HTTP/DAV to another repository SYNOPSIS -------- +[verse] 'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] DESCRIPTION diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index d3013d6a29..875d2831a5 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -8,6 +8,7 @@ git-imap-send - Send a collection of patches from stdin to an IMAP folder SYNOPSIS -------- +[verse] 'git imap-send' @@ -111,6 +112,31 @@ Using direct mode with SSL: .......................... +EXAMPLE +------- +To submit patches using GMail's IMAP interface, first, edit your ~/.gitconfig +to specify your account settings: + +--------- +[imap] + folder = "[Gmail]/Drafts" + host = imaps://imap.gmail.com + user = user@gmail.com + port = 993 + sslverify = false +--------- + +You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error +that the "Folder doesn't exist". + +Once the commits are ready to be sent, run the following command: + + $ git format-patch --cover-letter -M --stdout origin/master | git imap-send + +Just make sure to disable line wrapping in the email client (GMail's web +interface will wrap lines no matter what, so you need to use a real +IMAP client). + CAUTION ------- It is still your responsibility to make sure that the email message @@ -124,6 +150,10 @@ Thunderbird in particular is known to be problematic. Thunderbird users may wish to visit this web page for more information: http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email +SEE ALSO +-------- +linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5) + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 2c4c716f33..a21e346789 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -8,7 +8,8 @@ git-init-db - Creates an empty git repository SYNOPSIS -------- -'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--shared[=<permissions>]] +[verse] +'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]] DESCRIPTION diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 58cd01145a..9ac2bbaa56 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -8,8 +8,9 @@ git-init - Create an empty git repository or reinitialize an existing one SYNOPSIS -------- +[verse] 'git init' [-q | --quiet] [--bare] [--template=<template_directory>] - [--separate-git-dir|-L <git dir>] + [--separate-git-dir <git dir>] [--shared[=<permissions>]] [directory] @@ -54,7 +55,6 @@ current working directory. Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) --L=<git dir>:: --separate-git-dir=<git dir>:: Instead of initializing the repository where it is supposed to be, diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 08f85ba046..f3eef510f2 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -51,8 +51,8 @@ OPTIONS start:: --start:: - Start the httpd instance and exit. This does not generate - any of the configuration files for spawning a new instance. + Start the httpd instance and exit. Regenerate configuration files + as necessary for spawning a new instance. stop:: --stop:: @@ -62,8 +62,8 @@ stop:: restart:: --restart:: - Restart the httpd instance and exit. This does not generate - any of the configuration files for spawning a new instance. + Restart the httpd instance and exit. Regenerate configuration files + as necessary for spawning a new instance. CONFIGURATION ------------- @@ -84,6 +84,10 @@ If the configuration variable 'instaweb.browser' is not set, 'web.browser' will be used instead if it is defined. See linkgit:git-web{litdd}browse[1] for more information about this. +SEE ALSO +-------- +linkgit:gitweb[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 2c84028838..249fc878ec 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -8,6 +8,7 @@ git-log - Show commit logs SYNOPSIS -------- +[verse] 'git log' [<options>] [<since>..<until>] [[\--] <path>...] DESCRIPTION @@ -68,10 +69,13 @@ produced by --stat etc. its size is not included. [\--] <path>...:: - Show only commits that affect any of the specified paths. To - prevent confusion with options and branch names, paths may need - to be prefixed with "\-- " to separate them from options or - refnames. + Show only commits that are enough to explain how the files + that match the specified paths came to be. See "History + Simplification" below for details and other simplification + modes. ++ +To prevent confusion with options and branch names, paths may need to +be prefixed with "\-- " to separate them from options or refnames. include::rev-list-options.txt[] @@ -87,45 +91,45 @@ include::diff-generate-patch.txt[] Examples -------- -git log --no-merges:: +`git log --no-merges`:: Show the whole commit history, but skip any merges -git log v2.6.12.. include/scsi drivers/scsi:: +`git log v2.6.12.. include/scsi drivers/scsi`:: Show all commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -git log --since="2 weeks ago" \-- gitk:: +`git log --since="2 weeks ago" \-- gitk`:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named 'gitk' -git log --name-status release..test:: +`git log --name-status release..test`:: Show the commits that are in the "test" branch but not yet in the "release" branch, along with the list of paths each commit modifies. -git log --follow builtin-rev-list.c:: +`git log --follow builtin-rev-list.c`:: Shows the commits that changed builtin-rev-list.c, including those commits that occurred before the file was given its present name. -git log --branches --not --remotes=origin:: +`git log --branches --not --remotes=origin`:: Shows all commits that are in any of local branches but not in any of remote-tracking branches for 'origin' (what you have that origin doesn't). -git log master --not --remotes=*/master:: +`git log master --not --remotes=*/master`:: Shows all commits that are in local master but not in any remote repository master branches. -git log -p -m --first-parent:: +`git log -p -m --first-parent`:: Shows the history including change diffs, but only from the "main branch" perspective, skipping commits that come from merged @@ -178,9 +182,9 @@ May be an unabbreviated ref name or a glob and may be specified multiple times. A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored. + -This setting can be disabled by the `--no-standard-notes` option, +This setting can be disabled by the `--no-notes` option, overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, -and supplemented by the `--show-notes` option. +and overridden by the `--notes=<ref>` option. GIT --- diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index adf7e1c055..c406a11001 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -7,6 +7,7 @@ git-lost-found - Recover lost refs that luckily have not yet been pruned SYNOPSIS -------- +[verse] 'git lost-found' DESCRIPTION diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index c3df8c0ebe..7a9b86a58a 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] - <repository> [<refs>...] + [--exit-code] <repository> [<refs>...] DESCRIPTION ----------- @@ -36,6 +36,12 @@ OPTIONS SSH and where the SSH daemon does not use the PATH configured by the user. +--exit-code:: + Exit with status "2" when no matching refs are found in the remote + repository. Usually the command exits with status "0" to indicate + it successfully talked with the remote repository, whether it + found any matching refs. + <repository>:: Location of the repository. The shorthand defined in $GIT_DIR/branches/ can be used. Use "." (dot) to list references in diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index ed45662cc9..97e7a8e9e7 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -8,6 +8,7 @@ git-mailinfo - Extracts patch and authorship from a single e-mail message SYNOPSIS -------- +[verse] 'git mailinfo' [-k|-b] [-u | --encoding=<encoding> | -n] [--scissors] <msg> <patch> @@ -24,13 +25,24 @@ command directly. See linkgit:git-am[1] instead. OPTIONS ------- -k:: - Usually the program 'cleans up' the Subject: header line - to extract the title line for the commit log message, - among which (1) remove 'Re:' or 're:', (2) leading - whitespaces, (3) '[' up to ']', typically '[PATCH]', and - then prepends "[PATCH] ". This flag forbids this - munging, and is most useful when used to read back - 'git format-patch -k' output. + Usually the program removes email cruft from the Subject: + header line to extract the title line for the commit log + message. This option prevents this munging, and is most + useful when used to read back 'git format-patch -k' output. ++ +Specifically, the following are removed until none of them remain: ++ +-- +* Leading and trailing whitespace. + +* Leading `Re:`, `re:`, and `:`. + +* Leading bracketed strings (between `[` and `]`, usually + `[PATCH]`). +-- ++ +Finally, runs of whitespace are normalized to a single ASCII space +character. -b:: When -k is not in effect, all leading strings bracketed with '[' diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index 9b2049d674..4d1b871d96 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -7,6 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program SYNOPSIS -------- +[verse] 'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...] DESCRIPTION diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index ba36ec04f4..b295bf8330 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -9,7 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- [verse] -'git merge-base' [-a|--all] [--octopus] <commit> <commit>... +'git merge-base' [-a|--all] <commit> <commit>... +'git merge-base' [-a|--all] --octopus <commit>... 'git merge-base' --independent <commit>... DESCRIPTION @@ -22,23 +23,21 @@ that does not have any better common ancestor is a 'best common ancestor', i.e. a 'merge base'. Note that there can be more than one merge base for a pair of commits. -Unless `--octopus` is given, among the two commits to compute the merge -base from, one is specified by the first commit argument on the command -line; the other commit is a (possibly hypothetical) commit that is a merge -across all the remaining commits on the command line. As the most common -special case, specifying only two commits on the command line means -computing the merge base between the given two commits. +OPERATION MODE +-------------- + +As the most common special case, specifying only two commits on the +command line means computing the merge base between the given two commits. + +More generally, among the two commits to compute the merge base from, +one is specified by the first commit argument on the command line; +the other commit is a (possibly hypothetical) commit that is a merge +across all the remaining commits on the command line. As a consequence, the 'merge base' is not necessarily contained in each of the commit arguments if more than two commits are specified. This is different from linkgit:git-show-branch[1] when used with the `--merge-base` option. -OPTIONS -------- --a:: ---all:: - Output all merge bases for the commits, instead of just one. - --octopus:: Compute the best common ancestors of all supplied commits, in preparation for an n-way merge. This mimics the behavior @@ -51,6 +50,12 @@ OPTIONS from any other. This mimics the behavior of 'git show-branch --independent'. +OPTIONS +------- +-a:: +--all:: + Output all merge bases for the commits, instead of just one. + DISCUSSION ---------- @@ -89,6 +94,9 @@ and the result of `git merge-base A M` is '1'. Commit '2' is also a common ancestor between 'A' and 'M', but '1' is a better common ancestor, because '2' is an ancestor of '1'. Hence, '2' is not a merge base. +The result of `git merge-base --octopus A B C` is '2', because '2' is +the best common ancestor of all commits. + When the history involves criss-cross merges, there can be more than one 'best' common ancestor for two commits. For example, with this topology: diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 635c66956e..d7db2a3737 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -76,12 +76,12 @@ OPTIONS EXAMPLES -------- -git merge-file README.my README README.upstream:: +`git merge-file README.my README README.upstream`:: combines the changes of README.my and README.upstream since README, tries to merge them and writes the result into README.my. -git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345:: +`git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345`:: merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels `a` and `c` instead of `tmp/a123` and `tmp/c345`. diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 6ce54673b0..e0df1b3340 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,6 +8,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- +[verse] 'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) DESCRIPTION diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt index ee059def79..04e803d5d3 100644 --- a/Documentation/git-merge-one-file.txt +++ b/Documentation/git-merge-one-file.txt @@ -8,6 +8,7 @@ git-merge-one-file - The standard helper program to use with git-merge-index SYNOPSIS -------- +[verse] 'git merge-one-file' DESCRIPTION diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index 3bfa7b4220..c5f84b6495 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -8,6 +8,7 @@ git-merge-tree - Show three-way merge without touching index SYNOPSIS -------- +[verse] 'git merge-tree' <base-tree> <branch1> <branch2> DESCRIPTION diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt index 63ededec1d..f98a41b87c 100644 --- a/Documentation/git-mergetool--lib.txt +++ b/Documentation/git-mergetool--lib.txt @@ -7,7 +7,8 @@ git-mergetool--lib - Common git merge tool shell scriptlets SYNOPSIS -------- -'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool--lib"' +[verse] +'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool{litdd}lib"' DESCRIPTION ----------- diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 8c79ae8d2a..2a49de7cfe 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -7,6 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts SYNOPSIS -------- +[verse] 'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...] DESCRIPTION @@ -16,9 +17,10 @@ Use `git mergetool` to run one of several merge utilities to resolve merge conflicts. It is typically run after 'git merge'. If one or more <file> parameters are given, the merge tool program will -be run to resolve differences on each file. If no <file> names are -specified, 'git mergetool' will run the merge tool program on every file -with merge conflicts. +be run to resolve differences on each file (skipping those without +conflicts). Specifying a directory will include all unresolved files in +that path. If no <file> names are specified, 'git mergetool' will run +the merge tool program on every file with merge conflicts. OPTIONS ------- diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 037ab1045d..65e167a5c5 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -8,6 +8,7 @@ git-mktag - Creates a tag object SYNOPSIS -------- +[verse] 'git mktag' < signature_file DESCRIPTION diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index afe21be64d..5c6ebdfad9 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -8,6 +8,7 @@ git-mktree - Build a tree-object from ls-tree formatted text SYNOPSIS -------- +[verse] 'git mktree' [-z] [--missing] [--batch] DESCRIPTION diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index db0e030d69..e3c8448614 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -8,14 +8,15 @@ git-mv - Move or rename a file, a directory, or a symlink SYNOPSIS -------- +[verse] 'git mv' <options>... <args>... DESCRIPTION ----------- This script is used to move or rename a file, directory or symlink. - git mv [-f] [-n] <source> <destination> - git mv [-f] [-n] [-k] <source> ... <destination directory> + git mv [-v] [-f] [-n] [-k] <source> <destination> + git mv [-v] [-f] [-n] [-k] <source> ... <destination directory> In the first form, it renames <source>, which must exist and be either a file, symlink or directory, to <destination>. @@ -39,6 +40,10 @@ OPTIONS --dry-run:: Do nothing; only show what would happen +-v:: +--verbose:: + Report the names of files as they are moved. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 296f314eae..e8319eac69 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -17,7 +17,7 @@ SYNOPSIS 'git notes' merge [-v | -q] [-s <strategy> ] <notes_ref> 'git notes' merge --commit [-v | -q] 'git notes' merge --abort [-v | -q] -'git notes' remove [<object>] +'git notes' remove [--ignore-missing] [--stdin] [<object>...] 'git notes' prune [-n | -v] 'git notes' get-ref @@ -57,8 +57,11 @@ list:: add:: Add notes for a given object (defaults to HEAD). Abort if the - object already has notes (use `-f` to overwrite an - existing note). + object already has notes (use `-f` to overwrite existing notes). + However, if you're using `add` interactively (using an editor + to supply the notes contents), then - instead of aborting - + the existing notes will be opened in the editor (like the `edit` + subcommand). copy:: Copy the notes for the first object onto the second object. @@ -103,8 +106,9 @@ When done, the user can either finalize the merge with 'git notes merge --abort'. remove:: - Remove the notes for a given object (defaults to HEAD). - This is equivalent to specifying an empty note message to + Remove the notes for given objects (defaults to HEAD). When + giving zero or one object from the command line, this is + equivalent to specifying an empty note message to the `edit` subcommand. prune:: @@ -138,8 +142,9 @@ OPTIONS -C <object>:: --reuse-message=<object>:: - Take the note message from the given blob object (for - example, another note). + Take the given blob object (for example, another note) as the + note message. (Use `git notes copy <object>` instead to + copy notes between objects.) -c <object>:: --reedit-message=<object>:: @@ -151,6 +156,15 @@ OPTIONS 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref is taken to be in `refs/notes/` if it is not qualified. +--ignore-missing:: + Do not consider it an error to request removing notes from an + object that does not have notes attached to it. + +--stdin:: + Also read the object names to remove notes from from the standard + input (there is no reason you cannot combine this with object + names from the command line). + -n:: --dry-run:: Do not remove anything; just report the object names whose notes @@ -272,6 +286,8 @@ $ blob=$(git hash-object -w a.out) $ git notes --ref=built add -C "$blob" HEAD ------------ +(You cannot simply use `git notes --ref=built add -F a.out HEAD` +because that is not binary-safe.) Of course, it doesn't make much sense to display non-text-format notes with 'git log', so if you use such notes, you'll probably need to write some special-purpose tools to do something useful with them. diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt new file mode 100644 index 0000000000..78938b2930 --- /dev/null +++ b/Documentation/git-p4.txt @@ -0,0 +1,493 @@ +git-p4(1) +========= + +NAME +---- +git-p4 - Import from and submit to Perforce repositories + + +SYNOPSIS +-------- +[verse] +'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... +'git p4 sync' [<sync options>] [<p4 depot path>...] +'git p4 rebase' +'git p4 submit' [<submit options>] [<master branch name>] + + +DESCRIPTION +----------- +This command provides a way to interact with p4 repositories +using git. + +Create a new git repository from an existing p4 repository using +'git p4 clone', giving it one or more p4 depot paths. Incorporate +new commits from p4 changes with 'git p4 sync'. The 'sync' command +is also used to include new branches from other p4 depot paths. +Submit git changes back to p4 using 'git p4 submit'. The command +'git p4 rebase' does a sync plus rebases the current branch onto +the updated p4 remote branch. + + +EXAMPLE +------- +* Create an alias for 'git p4', using the full path to the 'git-p4' + script if needed: ++ +------------ +$ git config --global alias.p4 '!git-p4' +------------ + +* Clone a repository: ++ +------------ +$ git p4 clone //depot/path/project +------------ + +* Do some work in the newly created git repository: ++ +------------ +$ cd project +$ vi foo.h +$ git commit -a -m "edited foo.h" +------------ + +* Update the git repository with recent changes from p4, rebasing your + work on top: ++ +------------ +$ git p4 rebase +------------ + +* Submit your commits back to p4: ++ +------------ +$ git p4 submit +------------ + + +COMMANDS +-------- + +Clone +~~~~~ +Generally, 'git p4 clone' is used to create a new git directory +from an existing p4 repository: +------------ +$ git p4 clone //depot/path/project +------------ +This: + +1. Creates an empty git repository in a subdirectory called 'project'. ++ +2. Imports the full contents of the head revision from the given p4 +depot path into a single commit in the git branch 'refs/remotes/p4/master'. ++ +3. Creates a local branch, 'master' from this remote and checks it out. + +To reproduce the entire p4 history in git, use the '@all' modifier on +the depot path: +------------ +$ git p4 clone //depot/path/project@all +------------ + + +Sync +~~~~ +As development continues in the p4 repository, those changes can +be included in the git repository using: +------------ +$ git p4 sync +------------ +This command finds new changes in p4 and imports them as git commits. + +P4 repositories can be added to an existing git repository using +'git p4 sync' too: +------------ +$ mkdir repo-git +$ cd repo-git +$ git init +$ git p4 sync //path/in/your/perforce/depot +------------ +This imports the specified depot into +'refs/remotes/p4/master' in an existing git repository. The +'--branch' option can be used to specify a different branch to +be used for the p4 content. + +If a git repository includes branches 'refs/remotes/origin/p4', these +will be fetched and consulted first during a 'git p4 sync'. Since +importing directly from p4 is considerably slower than pulling changes +from a git remote, this can be useful in a multi-developer environment. + + +Rebase +~~~~~~ +A common working pattern is to fetch the latest changes from the p4 depot +and merge them with local uncommitted changes. Often, the p4 repository +is the ultimate location for all code, thus a rebase workflow makes +sense. This command does 'git p4 sync' followed by 'git rebase' to move +local commits on top of updated p4 changes. +------------ +$ git p4 rebase +------------ + + +Submit +~~~~~~ +Submitting changes from a git repository back to the p4 repository +requires a separate p4 client workspace. This should be specified +using the 'P4CLIENT' environment variable or the git configuration +variable 'git-p4.client'. The p4 client must exist, but the client root +will be created and populated if it does not already exist. + +To submit all changes that are in the current git branch but not in +the 'p4/master' branch, use: +------------ +$ git p4 submit +------------ + +To specify a branch other than the current one, use: +------------ +$ git p4 submit topicbranch +------------ + +The upstream reference is generally 'refs/remotes/p4/master', but can +be overridden using the '--origin=' command-line option. + +The p4 changes will be created as the user invoking 'git p4 submit'. The +'--preserve-user' option will cause ownership to be modified +according to the author of the git commit. This option requires admin +privileges in p4, which can be granted using 'p4 protect'. + + +OPTIONS +------- + +General options +~~~~~~~~~~~~~~~ +All commands except clone accept this option. + +--git-dir <dir>:: + Set the 'GIT_DIR' environment variable. See linkgit:git[1]. + +Sync options +~~~~~~~~~~~~ +These options can be used in the initial 'clone' as well as in +subsequent 'sync' operations. + +--branch <branch>:: + Import changes into given branch. If the branch starts with + 'refs/', it will be used as is, otherwise the path 'refs/heads/' + will be prepended. The default branch is 'master'. If used + with an initial clone, no HEAD will be checked out. ++ +This example imports a new remote "p4/proj2" into an existing +git repository: +---- + $ git init + $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 +---- + +--detect-branches:: + Use the branch detection algorithm to find new paths in p4. It is + documented below in "BRANCH DETECTION". + +--changesfile <file>:: + Import exactly the p4 change numbers listed in 'file', one per + line. Normally, 'git p4' inspects the current p4 repository + state and detects the changes it should import. + +--silent:: + Do not print any progress information. + +--verbose:: + Provide more progress information. + +--detect-labels:: + Query p4 for labels associated with the depot paths, and add + them as tags in git. + +--import-local:: + By default, p4 branches are stored in 'refs/remotes/p4/', + where they will be treated as remote-tracking branches by + linkgit:git-branch[1] and other commands. This option instead + puts p4 branches in 'refs/heads/p4/'. Note that future + sync operations must specify '--import-local' as well so that + they can find the p4 branches in refs/heads. + +--max-changes <n>:: + Limit the number of imported changes to 'n'. Useful to + limit the amount of history when using the '@all' p4 revision + specifier. + +--keep-path:: + The mapping of file names from the p4 depot path to git, by + default, involves removing the entire depot path. With this + option, the full p4 depot path is retained in git. For example, + path '//depot/main/foo/bar.c', when imported from + '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the + git path is instead 'depot/main/foo/bar.c'. + +--use-client-spec:: + Use a client spec to find the list of interesting files in p4. + See the "CLIENT SPEC" section below. + +Clone options +~~~~~~~~~~~~~ +These options can be used in an initial 'clone', along with the 'sync' +options described above. + +--destination <directory>:: + Where to create the git repository. If not provided, the last + component in the p4 depot path is used to create a new + directory. + +--bare:: + Perform a bare clone. See linkgit:git-clone[1]. + +-/ <path>:: + Exclude selected depot paths when cloning. + +Submit options +~~~~~~~~~~~~~~ +These options can be used to modify 'git p4 submit' behavior. + +--verbose:: + Provide more progress information. + +--origin <commit>:: + Upstream location from which commits are identified to submit to + p4. By default, this is the most recent p4 commit reachable + from 'HEAD'. + +-M[<n>]:: + Detect renames. See linkgit:git-diff[1]. Renames will be + represented in p4 using explicit 'move' operations. There + is no corresponding option to detect copies, but there are + variables for both moves and copies. + +--preserve-user:: + Re-author p4 changes before submitting to p4. This option + requires p4 admin privileges. + + +DEPOT PATH SYNTAX +----------------- +The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can +be one or more space-separated p4 depot paths, with an optional +p4 revision specifier on the end: + +"//depot/my/project":: + Import one commit with all files in the '#head' change under that tree. + +"//depot/my/project@all":: + Import one commit for each change in the history of that depot path. + +"//depot/my/project@1,6":: + Import only changes 1 through 6. + +"//depot/proj1@all //depot/proj2@all":: + Import all changes from both named depot paths into a single + repository. Only files below these directories are included. + There is not a subdirectory in git for each "proj1" and "proj2". + You must use the '--destination' option when specifying more + than one depot path. The revision specifier must be specified + identically on each depot path. If there are files in the + depot paths with the same name, the path with the most recently + updated version of the file is the one that appears in git. + +See 'p4 help revisions' for the full syntax of p4 revision specifiers. + + +CLIENT SPEC +----------- +The p4 client specification is maintained with the 'p4 client' command +and contains among other fields, a View that specifies how the depot +is mapped into the client repository. Git-p4 can consult the client +spec when given the '--use-client-spec' option or useClientSpec +variable. + +The full syntax for a p4 view is documented in 'p4 help views'. Git-p4 +knows only a subset of the view syntax. It understands multi-line +mappings, overlays with '+', exclusions with '-' and double-quotes +around whitespace. Of the possible wildcards, git-p4 only handles +'...', and only when it is at the end of the path. Git-p4 will complain +if it encounters an unhandled wildcard. + +The name of the client can be given to git-p4 in multiple ways. The +variable 'git-p4.client' takes precedence if it exists. Otherwise, +normal p4 mechanisms of determining the client are used: environment +variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. + + +BRANCH DETECTION +---------------- +P4 does not have the same concept of a branch as git. Instead, +p4 organizes its content as a directory tree, where by convention +different logical branches are in different locations in the tree. +The 'p4 branch' command is used to maintain mappings between +different areas in the tree, and indicate related content. 'git p4' +can use these mappings to determine branch relationships. + +If you have a repository where all the branches of interest exist as +subdirectories of a single depot path, you can use '--detect-branches' +when cloning or syncing to have 'git p4' automatically find +subdirectories in p4, and to generate these as branches in git. + +For example, if the P4 repository structure is: +---- +//depot/main/... +//depot/branch1/... +---- + +And "p4 branch -o branch1" shows a View line that looks like: +---- +//depot/main/... //depot/branch1/... +---- + +Then this 'git p4 clone' command: +---- +git p4 clone --detect-branches //depot@all +---- +produces a separate branch in 'refs/remotes/p4/' for //depot/main, +called 'master', and one for //depot/branch1 called 'depot/branch1'. + +However, it is not necessary to create branches in p4 to be able to use +them like branches. Because it is difficult to infer branch +relationships automatically, a git configuration setting +'git-p4.branchList' can be used to explicitly identify branch +relationships. It is a list of "source:destination" pairs, like a +simple p4 branch specification, where the "source" and "destination" are +the path elements in the p4 repository. The example above relied on the +presence of the p4 branch. Without p4 branches, the same result will +occur with: +---- +git config git-p4.branchList main:branch1 +git p4 clone --detect-branches //depot@all +---- + + +PERFORMANCE +----------- +The fast-import mechanism used by 'git p4' creates one pack file for +each invocation of 'git p4 sync'. Normally, git garbage compression +(linkgit:git-gc[1]) automatically compresses these to fewer pack files, +but explicit invocation of 'git repack -adf' may improve performance. + + +CONFIGURATION VARIABLES +----------------------- +The following config settings can be used to modify 'git p4' behavior. +They all are in the 'git-p4' section. + +General variables +~~~~~~~~~~~~~~~~~ +git-p4.user:: + User specified as an option to all p4 commands, with '-u <user>'. + The environment variable 'P4USER' can be used instead. + +git-p4.password:: + Password specified as an option to all p4 commands, with + '-P <password>'. + The environment variable 'P4PASS' can be used instead. + +git-p4.port:: + Port specified as an option to all p4 commands, with + '-p <port>'. + The environment variable 'P4PORT' can be used instead. + +git-p4.host:: + Host specified as an option to all p4 commands, with + '-h <host>'. + The environment variable 'P4HOST' can be used instead. + +git-p4.client:: + Client specified as an option to all p4 commands, with + '-c <client>', including the client spec. + +Clone and sync variables +~~~~~~~~~~~~~~~~~~~~~~~~ +git-p4.syncFromOrigin:: + Because importing commits from other git repositories is much faster + than importing them from p4, a mechanism exists to find p4 changes + first in git remotes. If branches exist under 'refs/remote/origin/p4', + those will be fetched and used when syncing from p4. This + variable can be set to 'false' to disable this behavior. + +git-p4.branchUser:: + One phase in branch detection involves looking at p4 branches + to find new ones to import. By default, all branches are + inspected. This option limits the search to just those owned + by the single user named in the variable. + +git-p4.branchList:: + List of branches to be imported when branch detection is + enabled. Each entry should be a pair of branch names separated + by a colon (:). This example declares that both branchA and + branchB were created from main: +------------- +git config git-p4.branchList main:branchA +git config --add git-p4.branchList main:branchB +------------- + +git-p4.useClientSpec:: + Specify that the p4 client spec should be used to identify p4 + depot paths of interest. This is equivalent to specifying the + option '--use-client-spec'. See the "CLIENT SPEC" section above. + This variable is a boolean, not the name of a p4 client. + +Submit variables +~~~~~~~~~~~~~~~~ +git-p4.detectRenames:: + Detect renames. See linkgit:git-diff[1]. + +git-p4.detectCopies:: + Detect copies. See linkgit:git-diff[1]. + +git-p4.detectCopiesHarder:: + Detect copies harder. See linkgit:git-diff[1]. + +git-p4.preserveUser:: + On submit, re-author changes to reflect the git author, + regardless of who invokes 'git p4 submit'. + +git-p4.allowMissingP4Users:: + When 'preserveUser' is true, 'git p4' normally dies if it + cannot find an author in the p4 user map. This setting + submits the change regardless. + +git-p4.skipSubmitEdit:: + The submit process invokes the editor before each p4 change + is submitted. If this setting is true, though, the editing + step is skipped. + +git-p4.skipSubmitEditCheck:: + After editing the p4 change message, 'git p4' makes sure that + the description really was changed by looking at the file + modification time. This option disables that test. + +git-p4.allowSubmit:: + By default, any branch can be used as the source for a 'git p4 + submit' operation. This configuration variable, if set, permits only + the named branches to be used as submit sources. Branch names + must be the short names (no "refs/heads/"), and should be + separated by commas (","), with no spaces. + +git-p4.skipUserNameCheck:: + If the user running 'git p4 submit' does not exist in the p4 + user map, 'git p4' exits. This option can be used to force + submission regardless. + + +IMPLEMENTATION DETAILS +---------------------- +* Changesets from p4 are imported using git fast-import. +* Cloning or syncing does not require a p4 client; file contents are + collected using 'p4 print'. +* Submitting requires a p4 client, which is not in the same location + as the git repository. Patches are applied, one at a time, to + this p4 client and submitted from there. +* Each commit imported by 'git p4' has a line at the end of the log + message indicating the p4 depot location and change number. This + line is used by later 'git p4 sync' operations to know which p4 + changes are new. diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index db9f0f7055..f2869da572 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -8,6 +8,7 @@ git-pack-redundant - Find redundant pack files SYNOPSIS -------- +[verse] 'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > DESCRIPTION diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 54b92534ce..a3c6677bfa 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -7,6 +7,7 @@ git-pack-refs - Pack heads and tags for efficient repository access SYNOPSIS -------- +[verse] 'git pack-refs' [--all] [--no-prune] DESCRIPTION diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt index 02217f6ba2..a45ea1ece8 100644 --- a/Documentation/git-parse-remote.txt +++ b/Documentation/git-parse-remote.txt @@ -8,6 +8,7 @@ git-parse-remote - Routines to help parsing remote repository access parameters SYNOPSIS -------- +[verse] '. "$(git --exec-path)/git-parse-remote"' DESCRIPTION diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 50e26f43c1..90268f02e7 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -7,6 +7,7 @@ git-patch-id - Compute unique ID for a patch SYNOPSIS -------- +[verse] 'git patch-id' < <patch> DESCRIPTION diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index a34d62f0da..87ea3fb054 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -8,6 +8,7 @@ git-peek-remote - List the references in a remote repository SYNOPSIS -------- +[verse] 'git peek-remote' [--upload-pack=<git-upload-pack>] [<host>:]<directory> DESCRIPTION diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 9e6202cdff..80dc022ede 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -8,6 +8,7 @@ git-prune-packed - Remove extra objects that are already in pack files SYNOPSIS -------- +[verse] 'git prune-packed' [-n|--dry-run] [-q|--quiet] diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index f616a739ef..80d01b0571 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -8,6 +8,7 @@ git-prune - Prune all unreachable objects from the object database SYNOPSIS -------- +[verse] 'git prune' [-n] [-v] [--expire <expire>] [--] [<head>...] DESCRIPTION diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 14609cbd4d..0f18ec891a 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -8,6 +8,7 @@ git-pull - Fetch from and merge with another repository or a local branch SYNOPSIS -------- +[verse] 'git pull' [options] [<repository> [<refspec>...]] @@ -107,7 +108,7 @@ include::merge-options.txt[] fetched, the rebase uses that information to avoid rebasing non-local changes. + -See `branch.<name>.rebase` and `branch.autosetuprebase` in +See `pull.rebase`, `branch.<name>.rebase` and `branch.autosetuprebase` in linkgit:git-config[1] if you want to make `git pull` always use `{litdd}rebase` instead of merging. + diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 88acfcd4cc..aede48877f 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -162,6 +162,12 @@ useful if you write an alias or script around 'git push'. is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. +--recurse-submodules=check:: + Check whether all submodule commits used by the revisions to be + pushed are available on a remote tracking branch. Otherwise the + push will be aborted and the command will exit with non-zero status. + + include::urls-remotes.txt[] OUTPUT @@ -327,12 +333,12 @@ a case where you do mean to lose history. Examples -------- -git push:: +`git push`:: Works like `git push <remote>`, where <remote> is the current branch's remote (or `origin`, if no remote is configured for the current branch). -git push origin:: +`git push origin`:: Without additional configuration, works like `git push origin :`. + @@ -344,45 +350,45 @@ use `git config remote.origin.push HEAD`. Any valid <refspec> (like the ones in the examples below) can be configured as the default for `git push origin`. -git push origin ::: +`git push origin :`:: Push "matching" branches to `origin`. See <refspec> in the <<OPTIONS,OPTIONS>> section above for a description of "matching" branches. -git push origin master:: +`git push origin master`:: Find a ref that matches `master` in the source repository (most likely, it would find `refs/heads/master`), and update the same ref (e.g. `refs/heads/master`) in `origin` repository with it. If `master` did not exist remotely, it would be created. -git push origin HEAD:: +`git push origin HEAD`:: A handy way to push the current branch to the same name on the remote. -git push origin master:satellite/master dev:satellite/dev:: +`git push origin master:satellite/master dev:satellite/dev`:: Use the source ref that matches `master` (e.g. `refs/heads/master`) to update the ref that matches `satellite/master` (most probably `refs/remotes/satellite/master`) in the `origin` repository, then do the same for `dev` and `satellite/dev`. -git push origin HEAD:master:: +`git push origin HEAD:master`:: Push the current branch to the remote ref matching `master` in the `origin` repository. This form is convenient to push the current branch without thinking about its local name. -git push origin master:refs/heads/experimental:: +`git push origin master:refs/heads/experimental`:: Create the branch `experimental` in the `origin` repository by copying the current `master` branch. This form is only needed to create a new branch or tag in the remote repository when the local name and the remote name are different; otherwise, the ref name on its own will work. -git push origin :experimental:: +`git push origin :experimental`:: Find a ref that matches `experimental` in the `origin` repository (e.g. `refs/heads/experimental`), and delete it. -git push origin {plus}dev:master:: +`git push origin {plus}dev:master`:: Update the origin repository's master branch with the dev branch, allowing non-fast-forward updates. *This can leave unreferenced commits dangling in the origin repository.* Consider the diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 26fdadc642..c4bde6509e 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,6 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- +[verse] 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--index-output=<file>] [--no-sparse-checkout] @@ -46,13 +47,18 @@ OPTIONS -i:: Usually a merge requires the index file as well as the - files in the working tree are up to date with the + files in the working tree to be up to date with the current head commit, in order not to lose local changes. This flag disables the check with the working tree and is meant to be used when creating a merge of trees that are not directly related to the current working tree status into a temporary index file. +-n:: +--dry-run:: + Check if the command would error out, without updating the index + nor the files in the working tree for real. + -v:: Show the progress of checking files out. @@ -65,23 +71,22 @@ OPTIONS --aggressive:: Usually a three-way merge by 'git read-tree' resolves the merge for really trivial cases and leaves other - cases unresolved in the index, so that Porcelains can + cases unresolved in the index, so that porcelains can implement different merge policies. This flag makes the - command to resolve a few more cases internally: + command resolve a few more cases internally: + * when one side removes a path and the other side leaves the path unmodified. The resolution is to remove that path. * when both sides remove a path. The resolution is to remove that path. -* when both sides adds a path identically. The resolution +* when both sides add a path identically. The resolution is to add that path. --prefix=<prefix>/:: Keep the current index contents, and read the contents - of named tree-ish under directory at `<prefix>`. The - original index file cannot have anything at the path - `<prefix>` itself, and have nothing in `<prefix>/` - directory. Note that the `<prefix>/` value must end - with a slash. + of the named tree-ish under the directory at `<prefix>`. + The command will refuse to overwrite entries that already + existed in the original index file. Note that the `<prefix>/` + value must end with a slash. --exclude-per-directory=<gitignore>:: When running the command with `-u` and `-m` options, the @@ -336,7 +341,7 @@ since you pulled from him: ---------------- $ git fetch git://.... linus -$ LT=`cat .git/FETCH_HEAD` +$ LT=`git rev-parse FETCH_HEAD` ---------------- Your work tree is still based on your HEAD ($JC), but you have @@ -373,45 +378,45 @@ have finished your work-in-progress), attempt the merge again. Sparse checkout --------------- -"Sparse checkout" allows to sparsely populate working directory. -It uses skip-worktree bit (see linkgit:git-update-index[1]) to tell -Git whether a file on working directory is worth looking at. +"Sparse checkout" allows populating the working directory sparsely. +It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell +Git whether a file in the working directory is worth looking at. -"git read-tree" and other merge-based commands ("git merge", "git -checkout"...) can help maintaining skip-worktree bitmap and working +'git read-tree' and other merge-based commands ('git merge', 'git +checkout'...) can help maintaining the skip-worktree bitmap and working directory update. `$GIT_DIR/info/sparse-checkout` is used to -define the skip-worktree reference bitmap. When "git read-tree" needs -to update working directory, it will reset skip-worktree bit in index +define the skip-worktree reference bitmap. When 'git read-tree' needs +to update the working directory, it resets the skip-worktree bit in the index based on this file, which uses the same syntax as .gitignore files. -If an entry matches a pattern in this file, skip-worktree will be -set on that entry. Otherwise, skip-worktree will be unset. +If an entry matches a pattern in this file, skip-worktree will not be +set on that entry. Otherwise, skip-worktree will be set. Then it compares the new skip-worktree value with the previous one. If -skip-worktree turns from unset to set, it will add the corresponding -file back. If it turns from set to unset, that file will be removed. +skip-worktree turns from set to unset, it will add the corresponding +file back. If it turns from unset to set, that file will be removed. While `$GIT_DIR/info/sparse-checkout` is usually used to specify what -files are in. You can also specify what files are _not_ in, using -negate patterns. For example, to remove file "unwanted": +files are in, you can also specify what files are _not_ in, using +negate patterns. For example, to remove the file `unwanted`: ---------------- -* +/* !unwanted ---------------- -Another tricky thing is fully repopulating working directory when you +Another tricky thing is fully repopulating the working directory when you no longer want sparse checkout. You cannot just disable "sparse -checkout" because skip-worktree are still in the index and you working -directory is still sparsely populated. You should re-populate working +checkout" because skip-worktree bits are still in the index and your working +directory is still sparsely populated. You should re-populate the working directory with the `$GIT_DIR/info/sparse-checkout` file content as follows: ---------------- -* +/* ---------------- -Then you can disable sparse checkout. Sparse checkout support in "git -read-tree" and similar commands is disabled by default. You need to +Then you can disable sparse checkout. Sparse checkout support in 'git +read-tree' and similar commands is disabled by default. You need to turn `core.sparseCheckout` on in order to have sparse checkout support. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 620d50e71f..504945c691 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -9,10 +9,9 @@ SYNOPSIS -------- [verse] 'git rebase' [-i | --interactive] [options] [--onto <newbase>] - <upstream> [<branch>] + [<upstream>] [<branch>] 'git rebase' [-i | --interactive] [options] --onto <newbase> --root [<branch>] - 'git rebase' --continue | --skip | --abort DESCRIPTION @@ -21,6 +20,12 @@ If <branch> is specified, 'git rebase' will perform an automatic `git checkout <branch>` before doing anything else. Otherwise it remains on the current branch. +If <upstream> is not specified, the upstream configured in +branch.<name>.remote and branch.<name>.merge options will be used; see +linkgit:git-config[1] for details. If you are currently not on any +branch or if the current branch does not have a configured upstream, +the rebase will abort. + All changes made by commits in the current branch but that are not in <upstream> are saved to a temporary area. This is the same set of commits that would be shown by `git log <upstream>..HEAD` (or @@ -40,7 +45,7 @@ with a different commit message or timestamp will be skipped). It is possible that a merge failure will prevent this process from being completely automatic. You will have to resolve any such merge failure and run `git rebase --continue`. Another option is to bypass the commit -that caused the merge failure with `git rebase --skip`. To restore the +that caused the merge failure with `git rebase --skip`. To check out the original <branch> and remove the .git/rebase-apply working files, use the command `git rebase --abort` instead. @@ -217,7 +222,8 @@ leave out at most one of A and B, in which case it defaults to HEAD. <upstream>:: Upstream branch to compare against. May be any valid commit, - not just an existing branch name. + not just an existing branch name. Defaults to the configured + upstream for the current branch. <branch>:: Working branch; defaults to HEAD. @@ -226,7 +232,11 @@ leave out at most one of A and B, in which case it defaults to HEAD. Restart the rebasing process after having resolved a merge conflict. --abort:: - Restore the original branch and abort the rebase operation. + Abort the rebase operation and reset HEAD to the original + branch. If <branch> was provided when the rebase operation was + started, then HEAD will be reset to <branch>. Otherwise HEAD + will be reset to where it was when the rebase operation was + started. --skip:: Restart the rebasing process by skipping the current patch. diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index f34e0ae1bd..b1f7dc643a 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -8,6 +8,7 @@ git-receive-pack - Receive what is pushed into the repository SYNOPSIS -------- +[verse] 'git-receive-pack' <directory> DESCRIPTION @@ -149,7 +150,7 @@ if the repository is packed and is served via a dumb transport. SEE ALSO -------- -linkgit:git-send-pack[1] +linkgit:git-send-pack[1], linkgit:gitnamespaces[7] GIT --- diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 09057bf90c..976dc14937 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -8,6 +8,7 @@ git-reflog - Manage reflog information SYNOPSIS -------- +[verse] 'git reflog' <subcommand> <options> DESCRIPTION diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index 9893376487..3b33c99510 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -7,6 +7,7 @@ git-relink - Hardlink common objects in local repositories SYNOPSIS -------- +[verse] 'git relink' [--safe] <dir>... <master_dir> DESCRIPTION diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 68263a6a53..8a8e1d775d 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -7,6 +7,7 @@ git-remote-ext - Bridge smart transport to external command. SYNOPSIS -------- +[verse] git remote add <nick> "ext::<command>[ <arguments>...]" DESCRIPTION diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index 4aecd4d187..f095d57d09 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -35,19 +35,19 @@ GIT_TRANSLOOP_DEBUG:: EXAMPLES -------- -git fetch fd::17 master:: +`git fetch fd::17 master`:: Fetch master, using file descriptor #17 to communicate with git-upload-pack. -git fetch fd::17/foo master:: +`git fetch fd::17/foo master`:: Same as above. -git push fd::7,8 master (as URL):: +`git push fd::7,8 master (as URL)`:: Push master, using file descriptor #7 to read data from git-receive-pack and file descriptor #8 to write data to same service. -git push fd::7,8/bar master:: +`git push fd::7,8/bar master`:: Same as above. Documentation diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 87cd11f2c4..674797cd83 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -7,6 +7,7 @@ git-remote-helpers - Helper programs to interact with remote repositories SYNOPSIS -------- +[verse] 'git remote-<transport>' <repository> [<URL>] DESCRIPTION @@ -23,22 +24,141 @@ output. Because a remote helper runs as an independent process from git, there is no need to re-link git to add a new helper, nor any need to link the helper with the implementation of git. -Every helper must support the "capabilities" command, which git will -use to determine what other commands the helper will accept. Other -commands generally concern facilities like discovering and updating -remote refs, transporting objects between the object database and -the remote repository, and updating the local object store. - -Helpers supporting the 'fetch' capability can discover refs from the -remote repository and transfer objects reachable from those refs to -the local object store. Helpers supporting the 'push' capability can -transfer local objects to the remote repository and update remote refs. +Every helper must support the "capabilities" command, which git +uses to determine what other commands the helper will accept. Those +other commands can be used to discover and update remote refs, +transport objects between the object database and the remote repository, +and update the local object store. Git comes with a "curl" family of remote helpers, that handle various transport protocols, such as 'git-remote-http', 'git-remote-https', 'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities 'fetch', 'option', and 'push'. +INPUT FORMAT +------------ + +Git sends the remote helper a list of commands on standard input, one +per line. The first command is always the 'capabilities' command, in +response to which the remote helper must print a list of the +capabilities it supports (see below) followed by a blank line. The +response to the capabilities command determines what commands Git uses +in the remainder of the command stream. + +The command stream is terminated by a blank line. In some cases +(indicated in the documentation of the relevant commands), this blank +line is followed by a payload in some other protocol (e.g., the pack +protocol), while in others it indicates the end of input. + +Capabilities +~~~~~~~~~~~~ + +Each remote helper is expected to support only a subset of commands. +The operations a helper supports are declared to git in the response +to the `capabilities` command (see COMMANDS, below). + +'option':: + For specifying settings like `verbosity` (how much output to + write to stderr) and `depth` (how much history is wanted in the + case of a shallow clone) that affect how other commands are + carried out. + +'connect':: + For fetching and pushing using git's native packfile protocol + that requires a bidirectional, full-duplex connection. + +'push':: + For listing remote refs and pushing specified objects from the + local object store to remote refs. + +'fetch':: + For listing remote refs and fetching the associated history to + the local object store. + +'import':: + For listing remote refs and fetching the associated history as + a fast-import stream. + +'refspec' <refspec>:: + This modifies the 'import' capability, allowing the produced + fast-import stream to modify refs in a private namespace + instead of writing to refs/heads or refs/remotes directly. + It is recommended that all importers providing the 'import' + capability use this. ++ +A helper advertising the capability +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}` +is saying that, when it is asked to `import refs/heads/topic`, the +stream it outputs will update the `refs/svn/origin/branches/topic` +ref. ++ +This capability can be advertised multiple times. The first +applicable refspec takes precedence. The left-hand of refspecs +advertised with this capability must cover all refs reported by +the list command. If no 'refspec' capability is advertised, +there is an implied `refspec {asterisk}:{asterisk}`. + +Capabilities for Pushing +~~~~~~~~~~~~~~~~~~~~~~~~ +'connect':: + Can attempt to connect to 'git receive-pack' (for pushing), + 'git upload-pack', etc for communication using the + packfile protocol. ++ +Supported commands: 'connect'. + +'push':: + Can discover remote refs and push local commits and the + history leading up to them to new or existing remote refs. ++ +Supported commands: 'list for-push', 'push'. + +If a helper advertises both 'connect' and 'push', git will use +'connect' if possible and fall back to 'push' if the helper requests +so when connecting (see the 'connect' command under COMMANDS). + +Capabilities for Fetching +~~~~~~~~~~~~~~~~~~~~~~~~~ +'connect':: + Can try to connect to 'git upload-pack' (for fetching), + 'git receive-pack', etc for communication using the + packfile protocol. ++ +Supported commands: 'connect'. + +'fetch':: + Can discover remote refs and transfer objects reachable from + them to the local object store. ++ +Supported commands: 'list', 'fetch'. + +'import':: + Can discover remote refs and output objects reachable from + them as a stream in fast-import format. ++ +Supported commands: 'list', 'import'. + +If a helper advertises 'connect', git will use it if possible and +fall back to another capability if the helper requests so when +connecting (see the 'connect' command under COMMANDS). +When choosing between 'fetch' and 'import', git prefers 'fetch'. +Other frontends may have some other order of preference. + +'refspec' <refspec>:: + This modifies the 'import' capability. ++ +A helper advertising +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}` +in its capabilities is saying that, when it handles +`import refs/heads/topic`, the stream it outputs will update the +`refs/svn/origin/branches/topic` ref. ++ +This capability can be advertised multiple times. The first +applicable refspec takes precedence. The left-hand of refspecs +advertised with this capability must cover all refs reported by +the list command. If no 'refspec' capability is advertised, +there is an implied `refspec {asterisk}:{asterisk}`. + INVOCATION ---------- @@ -47,6 +167,9 @@ arguments. The first argument specifies a remote repository as in git; it is either the name of a configured remote or a URL. The second argument specifies a URL; it is usually of the form '<transport>://<address>', but any arbitrary string is possible. +The 'GIT_DIR' environment variable is set up for the remote helper +and can be used to determine where to store additional data or from +which directory to invoke auxiliary git commands. When git encounters a URL of the form '<transport>://<address>', where '<transport>' is a protocol that it cannot handle natively, it @@ -118,7 +241,22 @@ Supported if the helper has the "fetch" capability. 'push' +<src>:<dst>:: Pushes the given local <src> commit or branch to the remote branch described by <dst>. A batch sequence of - one or more push commands is terminated with a blank line. + one or more 'push' commands is terminated with a blank line + (if there is only one reference to push, a single 'push' command + is followed by a blank line). For example, the following would + be two batches of 'push', the first asking the remote-helper + to push the local ref 'master' to the remote ref 'master' and + the local 'HEAD' to the remote 'branch', and the second + asking to push ref 'foo' to ref 'bar' (forced update requested + by the '+'). ++ +------------ +push refs/heads/master:refs/heads/master +push HEAD:refs/heads/branch +\n +push +refs/heads/foo:refs/heads/bar +\n +------------ + Zero or more protocol options may be entered after the last 'push' command, before the batch's terminating blank line. @@ -143,6 +281,11 @@ Supported if the helper has the "push" capability. Especially useful for interoperability with a foreign versioning system. + +Just like 'push', a batch sequence of one or more 'import' is +terminated with a blank line. For each batch of 'import', the remote +helper should produce a fast-import stream terminated by a 'done' +command. ++ Supported if the helper has the "import" capability. 'connect' <service>:: @@ -167,26 +310,6 @@ completing a valid response for the current command. Additional commands may be supported, as may be determined from capabilities reported by the helper. -CAPABILITIES ------------- - -'fetch':: -'option':: -'push':: -'import':: -'connect':: - This helper supports the corresponding command with the same name. - -'refspec' 'spec':: - When using the import command, expect the source ref to have - been written to the destination ref. The earliest applicable - refspec takes precedence. For example - "refs/heads/*:refs/svn/origin/branches/*" means that, after an - "import refs/heads/name", the script has written to - refs/svn/origin/branches/name. If this capability is used at - all, it must cover all refs reported by the list command; if - it is not used, it is effectively "*:*" - REF LIST ATTRIBUTES ------------------- @@ -239,6 +362,8 @@ SEE ALSO -------- linkgit:git-remote[1] +linkgit:git-remote-testgit[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt new file mode 100644 index 0000000000..2a67d456a3 --- /dev/null +++ b/Documentation/git-remote-testgit.txt @@ -0,0 +1,30 @@ +git-remote-testgit(1) +===================== + +NAME +---- +git-remote-testgit - Example remote-helper + + +SYNOPSIS +-------- +[verse] +git clone testgit::<source-repo> [<destination>] + +DESCRIPTION +----------- + +This command is a simple remote-helper, that is used both as a +testcase for the remote-helper functionality, and as an example to +show remote-helper authors one possible implementation. + +The best way to learn more is to read the comments and source code in +'git-remote-testgit.py'. + +SEE ALSO +-------- +linkgit:git-remote-helpers[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 528f34a131..5a8c5061f3 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -60,11 +60,11 @@ the remote repository. + With `-t <branch>` option, instead of the default glob refspec for the remote to track all branches under -`$GIT_DIR/remotes/<name>/`, a refspec to track only `<branch>` +the `refs/remotes/<name>/` namespace, a refspec to track only `<branch>` is created. You can give more than one `-t <branch>` to track multiple branches without grabbing all branches. + -With `-m <master>` option, `$GIT_DIR/remotes/<name>/HEAD` is set +With `-m <master>` option, a symbolic-ref `refs/remotes/<name>/HEAD` is set up to point at remote's `<master>` branch. See also the set-head command. + When a fetch mirror is created with `\--mirror=fetch`, the refs will not @@ -92,24 +92,25 @@ configuration settings for the remote are removed. 'set-head':: -Sets or deletes the default branch (`$GIT_DIR/remotes/<name>/HEAD`) for +Sets or deletes the default branch (i.e. the target of the +symbolic-ref `refs/remotes/<name>/HEAD`) for the named remote. Having a default branch for a remote is not required, but allows the name of the remote to be specified in lieu of a specific branch. For example, if the default branch for `origin` is set to `master`, then `origin` may be specified wherever you would normally specify `origin/master`. + -With `-d`, `$GIT_DIR/remotes/<name>/HEAD` is deleted. +With `-d`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted. + -With `-a`, the remote is queried to determine its `HEAD`, then -`$GIT_DIR/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote +With `-a`, the remote is queried to determine its `HEAD`, then the +symbolic-ref `refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote `HEAD` is pointed at `next`, "`git remote set-head origin -a`" will set -`$GIT_DIR/refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will +the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will only work if `refs/remotes/origin/next` already exists; if not it must be fetched first. + -Use `<branch>` to set `$GIT_DIR/remotes/<name>/HEAD` explicitly. e.g., "git -remote set-head origin master" will set `$GIT_DIR/refs/remotes/origin/HEAD` to +Use `<branch>` to set the symbolic-ref `refs/remotes/<name>/HEAD` explicitly. e.g., "git +remote set-head origin master" will set the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/master`. This will only work if `refs/remotes/origin/master` already exists; if not it must be fetched first. + diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 0decee240b..40af321153 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -8,6 +8,7 @@ git-repack - Pack unpacked objects in a repository SYNOPSIS -------- +[verse] 'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>] DESCRIPTION diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index a0d1fa6594..9ec115b9e0 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -8,6 +8,7 @@ git-repo-config - Get and set repository or global options SYNOPSIS -------- +[verse] 'git repo-config' ... diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 3521d8e3c8..b99681ce85 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -7,6 +7,7 @@ git-request-pull - Generates a summary of pending changes SYNOPSIS -------- +[verse] 'git request-pull' [-p] <start> <url> [<end>] DESCRIPTION diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 52db1d80cf..a6253ba617 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -7,6 +7,7 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- +[verse] 'git rerere' ['clear'|'forget' <pathspec>|'diff'|'status'|'gc'] DESCRIPTION diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 8481f9db74..b674866e6d 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -9,8 +9,8 @@ SYNOPSIS -------- [verse] 'git reset' [-q] [<commit>] [--] <paths>... -'git reset' --patch [<commit>] [--] [<paths>...] -'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] +'git reset' (--patch | -p) [<commit>] [--] [<paths>...] +'git reset' (--soft | --mixed | --hard | --merge | --keep) [-q] [<commit>] DESCRIPTION ----------- @@ -34,15 +34,16 @@ Alternatively, using linkgit:git-checkout[1] and specifying a commit, you can copy the contents of a path out of a commit to the index and to the working tree in one go. -'git reset' --patch|-p [<commit>] [--] [<paths>...]:: +'git reset' (--patch | -p) [<commit>] [--] [<paths>...]:: Interactively select hunks in the difference between the index and <commit> (defaults to HEAD). The chosen hunks are applied in reverse to the index. + -This means that `git reset -p` is the opposite of `git add -p` (see -linkgit:git-add[1]). +This means that `git reset -p` is the opposite of `git add -p`, i.e. +you can use it to selectively reset hunks. See the ``Interactive Mode'' +section of linkgit:git-add[1] to learn how to operate the `\--patch` mode. -'git reset' [--<mode>] [<commit>]:: +'git reset' --<mode> [<commit>]:: This form resets the current branch head to <commit> and possibly updates the index (resetting it to the tree of <commit>) and the working tree depending on <mode>, which diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 415f4f0b30..38fafcaa6b 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -29,6 +29,7 @@ SYNOPSIS [ \--tags[=<pattern>] ] [ \--remotes[=<pattern>] ] [ \--glob=<glob-pattern> ] + [ \--ignore-missing ] [ \--stdin ] [ \--quiet ] [ \--topo-order ] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 02c44c999f..8023dc086d 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -8,6 +8,7 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- +[verse] 'git rev-parse' [ --option ] <args>... DESCRIPTION @@ -179,6 +180,10 @@ print a message to stderr and exit with nonzero status. <args>...:: Flags and parameters to be parsed. +--resolve-git-dir <path>:: + Check if <path> is a valid git-dir or a git-file pointing to a valid + git-dir. If <path> is a valid git-dir the resolved path to git-dir will + be printed. include::revisions.txt[] diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index ac10cfbb14..b699a3458e 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -7,7 +7,11 @@ git-revert - Revert some existing commits SYNOPSIS -------- +[verse] 'git revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit>... +'git revert' --continue +'git revert' --quit +'git revert' --abort DESCRIPTION ----------- @@ -23,7 +27,7 @@ throw away all uncommitted changes in your working directory, you should see linkgit:git-reset[1], particularly the '--hard' option. If you want to extract specific files as they were in another commit, you should see linkgit:git-checkout[1], specifically the `git checkout -<commit> -- <filename>` syntax. Take care with these alternatives as +<commit> \-- <filename>` syntax. Take care with these alternatives as both will discard uncommitted changes in your working directory. OPTIONS @@ -90,14 +94,18 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. +SEQUENCER SUBCOMMANDS +--------------------- +include::sequencer.txt[] + EXAMPLES -------- -git revert HEAD~3:: +`git revert HEAD~3`:: Revert the changes specified by the fourth last commit in HEAD and create a new commit with the reverted changes. -git revert -n master{tilde}5..master{tilde}2:: +`git revert -n master{tilde}5..master{tilde}2`:: Revert the changes done by commits from the fifth last commit in master (included) to the third last commit in master diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 8c0554f971..665ad4ddab 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -7,6 +7,7 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- +[verse] 'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... DESCRIPTION @@ -136,7 +137,7 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached EXAMPLES -------- -git rm Documentation/\*.txt:: +`git rm Documentation/\*.txt`:: Removes all `*.txt` files from the index that are under the `Documentation` directory and any of its subdirectories. + @@ -144,7 +145,7 @@ Note that the asterisk `*` is quoted from the shell in this example; this lets git, and not the shell, expand the pathnames of files and subdirectories under the `Documentation/` directory. -git rm -f git-*.sh:: +`git rm -f git-*.sh`:: Because this example lets the shell expand the asterisk (i.e. you are listing the files explicitly), it does not remove `subdir/git-foo.sh`. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index ee14f74fd3..327233c85b 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -8,6 +8,7 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- +[verse] 'git send-email' [options] <file|directory|rev-list options>... @@ -348,10 +349,12 @@ sendemail.confirm:: one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm' in the previous section for the meaning of these values. +EXAMPLE +------- Use gmail as the smtp server ----------------------------- - -Add the following section to the config file: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To use 'git send-email' to send your patches through the GMail SMTP server, +edit ~/.gitconfig to specify your account settings: [sendemail] smtpencryption = tls @@ -359,9 +362,20 @@ Add the following section to the config file: smtpuser = yourname@gmail.com smtpserverport = 587 +Once your commits are ready to be sent to the mailing list, run the +following commands: + + $ git format-patch --cover-letter -M origin/master -o outgoing/ + $ edit outgoing/0000-* + $ git send-email outgoing/* + Note: the following perl modules are required Net::SMTP::SSL, MIME::Base64 and Authen::SASL +SEE ALSO +-------- +linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5) + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 17f8f55526..bd3eaa69bf 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -8,6 +8,7 @@ git-send-pack - Push objects over git protocol to another repository SYNOPSIS -------- +[verse] 'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] DESCRIPTION diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt new file mode 100644 index 0000000000..5c3ec327bb --- /dev/null +++ b/Documentation/git-sh-i18n--envsubst.txt @@ -0,0 +1,36 @@ +git-sh-i18n{litdd}envsubst(1) +============================= + +NAME +---- +git-sh-i18n--envsubst - Git's own envsubst(1) for i18n fallbacks + +SYNOPSIS +-------- +[verse] +eval_gettext () { + printf "%s" "$1" | ( + export PATH $('git sh-i18n{litdd}envsubst' --variables "$1"); + 'git sh-i18n{litdd}envsubst' "$1" + ) +} + +DESCRIPTION +----------- + +This is not a command the end user would want to run. Ever. +This documentation is meant for people who are studying the +plumbing scripts and/or are writing new ones. + +'git sh-i18n{litdd}envsubst' is Git's stripped-down copy of the GNU +`envsubst(1)` program that comes with the GNU gettext package. It's +used internally by linkgit:git-sh-i18n[1] to interpolate the variables +passed to the the `eval_gettext` function. + +No promises are made about the interface, or that this +program won't disappear without warning in the next version +of Git. Don't use it. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-sh-i18n.txt b/Documentation/git-sh-i18n.txt new file mode 100644 index 0000000000..60cf49cb2a --- /dev/null +++ b/Documentation/git-sh-i18n.txt @@ -0,0 +1,43 @@ +git-sh-i18n(1) +============== + +NAME +---- +git-sh-i18n - Git's i18n setup code for shell scripts + +SYNOPSIS +-------- +[verse] +'. "$(git --exec-path)/git-sh-i18n"' + +DESCRIPTION +----------- + +This is not a command the end user would want to run. Ever. +This documentation is meant for people who are studying the +Porcelain-ish scripts and/or are writing new ones. + +The 'git sh-i18n scriptlet is designed to be sourced (using +`.`) by Git's porcelain programs implemented in shell +script. It provides wrappers for the GNU `gettext` and +`eval_gettext` functions accessible through the `gettext.sh` +script, and provides pass-through fallbacks on systems +without GNU gettext. + +FUNCTIONS +--------- + +gettext:: + Currently a dummy fall-through function implemented as a wrapper + around `printf(1)`. Will be replaced by a real gettext + implementation in a later version. + +eval_gettext:: + Currently a dummy fall-through function implemented as a wrapper + around `printf(1)` with variables expanded by the + linkgit:git-sh-i18n{litdd}envsubst[1] helper. Will be replaced by a + real gettext implementation in a later version. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 053df505bc..5e5f1c8964 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -7,6 +7,7 @@ git-sh-setup - Common git shell script setup code SYNOPSIS -------- +[verse] '. "$(git --exec-path)/git-sh-setup"' DESCRIPTION @@ -58,9 +59,24 @@ cd_to_toplevel:: runs chdir to the toplevel of the working tree. require_work_tree:: - checks if the repository is a bare repository, and dies - if so. Used by scripts that require working tree - (e.g. `checkout`). + checks if the current directory is within the working tree + of the repository, and otherwise dies. + +require_work_tree_exists:: + checks if the working tree associated with the repository + exists, and otherwise dies. Often done before calling + cd_to_toplevel, which is impossible to do if there is no + working tree. + +require_clean_work_tree <action> [<hint>]:: + checks that the working tree and index associated with the + repository have no uncommitted changes to tracked files. + Otherwise it emits an error message of the form `Cannot + <action>: <reason>. <hint>`, and dies. Example: ++ +---------------- +require_clean_work_tree rebase "Please commit or stash them." +---------------- get_author_ident_from_commit:: outputs code for use with eval to set the GIT_AUTHOR_NAME, diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index d7d4b92894..9b9250600f 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -8,6 +8,7 @@ git-shell - Restricted login shell for Git-only SSH access SYNOPSIS -------- +[verse] 'git shell' [-c <command> <argument>] DESCRIPTION diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index ee4559b6f2..a8e77b5350 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -13,7 +13,6 @@ SYNOPSIS [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...] - 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index c4d99f1028..2dcbbb2454 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -8,6 +8,7 @@ git-show-index - Show packed archive index SYNOPSIS -------- +[verse] 'git show-index' < idx-file diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 3c45895299..fcee0008a9 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -44,7 +44,7 @@ OPTIONS -d:: --dereference:: - Dereference tags into object IDs as well. They will be shown with "^{}" + Dereference tags into object IDs as well. They will be shown with "{caret}{}" appended. -s:: @@ -73,9 +73,9 @@ OPTIONS --exclude-existing[=<pattern>]:: Make 'git show-ref' act as a filter that reads refs from stdin of the - form "^(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$" + form "`{caret}(?:<anything>\s)?<refname>(?:{backslash}{caret}{})?$`" and performs the following actions on each: - (1) strip "^{}" at the end of line if any; + (1) strip "{caret}{}" at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; (4) ignore if refname is a ref that exists in the local repository; diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 7f075e84f5..1e38819e67 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -8,6 +8,7 @@ git-show - Show various types of objects SYNOPSIS -------- +[verse] 'git show' [options] <object>... DESCRIPTION @@ -47,23 +48,23 @@ include::pretty-formats.txt[] EXAMPLES -------- -git show v1.0.0:: +`git show v1.0.0`:: Shows the tag `v1.0.0`, along with the object the tags points at. -git show v1.0.0^\{tree\}:: +`git show v1.0.0^\{tree\}`:: Shows the tree pointed to by the tag `v1.0.0`. -git show -s --format=%s v1.0.0^\{commit\}:: +`git show -s --format=%s v1.0.0^\{commit\}`:: Shows the subject of the commit pointed to by the tag `v1.0.0`. -git show next~10:Documentation/README:: +`git show next~10:Documentation/README`:: Shows the contents of the file `Documentation/README` as they were current in the 10th last commit of the branch `next`. -git show master:Makefile master:t/Makefile:: +`git show master:Makefile master:t/Makefile`:: Concatenates the contents of said Makefiles in the head of the branch `master`. diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 79abc38e50..43af38aa4b 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -13,7 +13,8 @@ SYNOPSIS 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] [<message>]] +'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] + [-u|--include-untracked] [-a|--all] [<message>]] 'git stash' clear 'git stash' create @@ -42,7 +43,7 @@ is also possible). OPTIONS ------- -save [--patch] [--[no-]keep-index] [-q|--quiet] [<message>]:: +save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: Save your local modifications to a new 'stash', and run `git reset --hard` to revert them. The <message> part is optional and gives @@ -54,12 +55,18 @@ save [--patch] [--[no-]keep-index] [-q|--quiet] [<message>]:: If the `--keep-index` option is used, all changes already added to the index are left intact. + -With `--patch`, you can interactively select hunks from in the diff +If the `--include-untracked` option is used, all untracked files are also +stashed and then cleaned up with `git clean`, leaving the working directory +in a very clean state. If the `--all` option is used instead then the +ignored files are stashed and cleaned in addition to the untracked files. ++ +With `--patch`, you can interactively select hunks from the diff between HEAD and the working tree to be stashed. The stash entry is constructed such that its index state is the same as the index state of your repository, and its worktree contains only the changes you selected interactively. The selected changes are then rolled back -from your worktree. +from your worktree. See the ``Interactive Mode'' section of +linkgit:git-add[1] to learn how to operate the `\--patch` mode. + The `--patch` option implies `--keep-index`. You can use `--no-keep-index` to override this. diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 00b699fef7..3d51717bbe 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -8,6 +8,7 @@ git-status - Show the working tree status SYNOPSIS -------- +[verse] 'git status' [<options>...] [--] [<pathspec>...] DESCRIPTION @@ -32,9 +33,10 @@ OPTIONS Show the branch and tracking info even in short-format. --porcelain:: - Give the output in a stable, easy-to-parse format for scripts. - Currently this is identical to --short output, but is guaranteed - not to change in the future, making it safe for scripts. + Give the output in an easy-to-parse format for scripts. + This is similar to the short output, but will remain stable + across git versions and regardless of user configuration. See + below for details. -u[<mode>]:: --untracked-files[=<mode>]:: @@ -68,6 +70,9 @@ configuration variable documented in linkgit:git-config[1]. (and suppresses the output of submodule summaries when the config option `status.submodulesummary` is set). +--ignored:: + Show ignored files as well. + -z:: Terminate entries with NUL, instead of LF. This implies the `--porcelain` output format if no other format is given. @@ -78,23 +83,27 @@ OUTPUT The output from this command is designed to be used as a commit template comment, and all the output lines are prefixed with '#'. The default, long format, is designed to be human readable, -verbose and descriptive. They are subject to change in any time. +verbose and descriptive. Its contents and format are subject to change +at any time. The paths mentioned in the output, unlike many other git commands, are made relative to the current directory if you are working in a subdirectory (this is on purpose, to help cutting and pasting). See the status.relativePaths config option below. -In short-format, the status of each path is shown as +Short Format +~~~~~~~~~~~~ + +In the short-format, the status of each path is shown as XY PATH1 -> PATH2 -where `PATH1` is the path in the `HEAD`, and ` -> PATH2` part is +where `PATH1` is the path in the `HEAD`, and the ` \-> PATH2` part is shown only when `PATH1` corresponds to a different path in the index/worktree (i.e. the file is renamed). The 'XY' is a two-letter status code. -The fields (including the `->`) are separated from each other by a +The fields (including the `\->`) are separated from each other by a single space. If a filename contains whitespace or other nonprintable characters, that field will be quoted in the manner of a C string literal: surrounded by ASCII double quote (34) characters, and with @@ -114,7 +123,8 @@ codes can be interpreted as follows: * 'C' = copied * 'U' = updated but unmerged -Ignored files are not listed. +Ignored files are not listed, unless `--ignored` option is in effect, +in which case `XY` are `!!`. X Y Meaning ------------------------------------------------- @@ -137,16 +147,32 @@ Ignored files are not listed. U U unmerged, both modified ------------------------------------------------- ? ? untracked + ! ! ignored ------------------------------------------------- If -b is used the short-format status is preceded by a line ## branchname tracking info -There is an alternate -z format recommended for machine parsing. In +Porcelain Format +~~~~~~~~~~~~~~~~ + +The porcelain format is similar to the short format, but is guaranteed +not to change in a backwards-incompatible way between git versions or +based on user configuration. This makes it ideal for parsing by scripts. +The description of the short format above also describes the porcelain +format, with a few exceptions: + +1. The user's color.status configuration is not respected; color will + always be off. + +2. The user's status.relativePaths configuration is not respected; paths + shown will always be relative to the repository root. + +There is also an alternate -z format recommended for machine parsing. In that format, the status field is the same, but some other things -change. First, the '->' is omitted from rename entries and the field -order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL +change. First, the '\->' is omitted from rename entries and the field +order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL (ASCII 0) follows each filename, replacing space as a field separator and the terminating newline (but a space still separates the status field from the first filename). Third, filenames containing special diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 10509cc450..a80d94650d 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -3,25 +3,83 @@ git-stripspace(1) NAME ---- -git-stripspace - Filter out empty lines +git-stripspace - Remove unnecessary whitespace SYNOPSIS -------- -'git stripspace' [-s | --strip-comments] < <stream> +[verse] +'git stripspace' [-s | --strip-comments] < input DESCRIPTION ----------- -Remove multiple empty lines, and empty lines at beginning and end. + +Clean the input in the manner used by 'git' for text such as commit +messages, notes, tags and branch descriptions. + +With no arguments, this will: + +- remove trailing whitespace from all lines +- collapse multiple consecutive empty lines into one empty line +- remove empty lines from the beginning and end of the input +- add a missing '\n' to the last line if necessary. + +In the case where the input consists entirely of whitespace characters, no +output will be produced. + +*NOTE*: This is intended for cleaning metadata, prefer the `--whitespace=fix` +mode of linkgit:git-apply[1] for correcting whitespace of patches or files in +the repository. OPTIONS ------- -s:: --strip-comments:: - In addition to empty lines, also strip lines starting with '#'. + Skip and remove all lines starting with '#'. + +EXAMPLES +-------- + +Given the following noisy input with '$' indicating the end of a line: -<stream>:: - Byte stream to act on. +-------- +|A brief introduction $ +| $ +|$ +|A new paragraph$ +|# with a commented-out line $ +|explaining lots of stuff.$ +|$ +|# An old paragraph, also commented-out. $ +| $ +|The end.$ +| $ +--------- + +Use 'git stripspace' with no arguments to obtain: + +-------- +|A brief introduction$ +|$ +|A new paragraph$ +|# with a commented-out line$ +|explaining lots of stuff.$ +|$ +|# An old paragraph, also commented-out.$ +|$ +|The end.$ +--------- + +Use 'git stripspace --strip-comments' to obtain: + +-------- +|A brief introduction$ +|$ +|A new paragraph$ +|explaining lots of stuff.$ +|$ +|The end.$ +--------- GIT --- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 1a16ff6044..b72964947a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -15,7 +15,8 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...] -'git submodule' [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...] +'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] + [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> 'git submodule' [--quiet] sync [--] [<path>...] @@ -78,7 +79,14 @@ to exist in the superproject. If <path> is not given, the <repository> is the URL of the new submodule's origin repository. This may be either an absolute URL, or (if it begins with ./ or ../), the location relative to the superproject's origin -repository. +repository (Please note that to specify a repository 'foo.git' +which is located right next to a superproject 'bar.git', you'll +have to use '../foo.git' instead of './foo.git' - as one might expect +when following the rules for relative URLs - because the evaluation +of relative URLs in Git is identical to that of relative directories). +If the superproject doesn't have an origin configured +the superproject is its own authoritative upstream and the current +working directory is used instead. + <path> is the relative location for the cloned submodule to exist in the superproject. If <path> does not exist, then the @@ -106,12 +114,19 @@ status:: repository and `U` if the submodule has merge conflicts. This command is the default command for 'git submodule'. + -If '--recursive' is specified, this command will recurse into nested +If `--recursive` is specified, this command will recurse into nested submodules, and show their status as well. ++ +If you are only interested in changes of the currently initialized +submodules with respect to the commit recorded in the index or the HEAD, +linkgit:git-status[1] and linkgit:git-diff[1] will provide that information +too (and can also report changes to a submodule's work tree). init:: Initialize the submodules, i.e. register each submodule name and url found in .gitmodules into .git/config. + It will also copy the value of `submodule.$name.update` into + .git/config. The key used in .git/config is `submodule.$name.url`. This command does not alter existing information in .git/config. You can then customize the submodule clone URLs in .git/config @@ -123,26 +138,33 @@ init:: update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. - This will make the submodules HEAD be detached unless '--rebase' or - '--merge' is specified or the key `submodule.$name.update` is set to - `rebase` or `merge`. + This will make the submodules HEAD be detached unless `--rebase` or + `--merge` is specified or the key `submodule.$name.update` is set to + `rebase`, `merge` or `none`. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the -submodule with the --init option. +submodule with the `--init` option. + -If '--recursive' is specified, this command will recurse into the +If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. ++ +If the configuration key `submodule.$name.update` is set to `none` the +submodule with name `$name` will not be updated by default. This can be +overriden by adding `--checkout` to the command. summary:: Show commit summary between the given commit (defaults to HEAD) and working tree/index. For a submodule in question, a series of commits in the submodule between the given super project commit and the - index or working tree (switched by --cached) are shown. If the option - --files is given, show the series of commits in the submodule between + index or working tree (switched by `--cached`) are shown. If the option + `--files` is given, show the series of commits in the submodule between the index of the super project and the working tree of the submodule - (this option doesn't allow to use the --cached option or to provide an + (this option doesn't allow to use the `--cached` option or to provide an explicit commit). ++ +Using the `--submodule=log` option with linkgit:git-diff[1] will provide that +information too. foreach:: Evaluates an arbitrary shell command in each checked out submodule. @@ -153,9 +175,9 @@ foreach:: superproject, $sha1 is the commit as recorded in the superproject, and $toplevel is the absolute path to the top-level of the superproject. Any submodules defined in the superproject but not checked out are - ignored by this command. Unless given --quiet, foreach prints the name + ignored by this command. Unless given `--quiet`, foreach prints the name of each submodule before evaluating the command. - If --recursive is given, submodules are traversed recursively (i.e. + If `--recursive` is given, submodules are traversed recursively (i.e. the given shell command is evaluated in nested submodules as well). A non-zero return from the command in any submodule causes the processing to terminate. This can be overridden by adding '|| :' @@ -167,12 +189,14 @@ commit for each submodule. sync:: Synchronizes submodules' remote URL configuration setting - to the value specified in .gitmodules. This is useful when + to the value specified in .gitmodules. It will only affect those + submodules which already have an url entry in .git/config (that is the + case when they are initialized or freshly added). This is useful when submodule URLs change upstream and you need to update your local repositories accordingly. + "git submodule sync" synchronizes all submodules while -"git submodule sync -- A" synchronizes submodule "A" only. +"git submodule sync \-- A" synchronizes submodule "A" only. OPTIONS ------- @@ -186,8 +210,10 @@ OPTIONS -f:: --force:: - This option is only valid for the add command. - Allow adding an otherwise ignored submodule path. + This option is only valid for add and update commands. + When running add, allow adding an otherwise ignored submodule path. + When running update, throw away local changes in submodules when + switching to a different commit. --cached:: This option is only valid for status and summary commands. These @@ -231,13 +257,18 @@ OPTIONS If the key `submodule.$name.update` is set to `rebase`, this option is implicit. +--init:: + This option is only valid for the update command. + Initialize all submodules for which "git submodule init" has not been + called so far before updating. + --reference <repository>:: This option is only valid for add and update commands. These commands sometimes need to clone a remote repository. In this case, this option will be passed to the linkgit:git-clone[1] command. + *NOTE*: Do *not* use this option unless you have read the note -for linkgit:git-clone[1]'s --reference and --shared options carefully. +for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. --recursive:: This option is only valid for foreach, update and status commands. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 30a67486d2..34ee785064 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -7,6 +7,7 @@ git-svn - Bidirectional operation between a Subversion repository and git SYNOPSIS -------- +[verse] 'git svn' <command> [options] [arguments] DESCRIPTION @@ -145,17 +146,6 @@ Skip "branches" and "tags" of first level directories;; ------------------------------------------------------------------------ -- ---use-log-author;; - When retrieving svn commits into git (as part of fetch, rebase, or - dcommit operations), look for the first From: or Signed-off-by: line - in the log message and use that as the author string. ---add-author-from;; - When committing to svn from git (as part of commit or dcommit - operations), if the existing log message doesn't already have a - From: or Signed-off-by: line, append a From: line based on the - git commit's author string. If you use this, then --use-log-author - will retrieve a valid author string for all commits. - 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; @@ -167,6 +157,17 @@ Skip "branches" and "tags" of first level directories;; affecting the working tree; and the 'rebase' command will be able to update the working tree with the latest changes. +--preserve-empty-dirs;; + Create a placeholder file in the local Git repository for each + empty directory fetched from Subversion. This includes directories + that become empty by removing all entries in the Subversion + repository (but not the directory itself). The placeholder files + are also tracked and removed when no longer necessary. + +--placeholder-filename=<filename>;; + Set the name of placeholder files created by --preserve-empty-dirs. + Default: ".gitignore" + 'rebase':: This fetches revisions from the SVN parent of the current HEAD and rebases the current (uncommitted to SVN) work against it. @@ -221,8 +222,25 @@ discouraged. Add the given merge information during the dcommit (e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can store this information (as a property), and svn clients starting from - version 1.5 can make use of it. 'git svn' currently does not use it - and does not set it automatically. + version 1.5 can make use of it. To specify merge information from multiple + branches, use a single space character between the branches + (`--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"`) ++ +[verse] +config key: svn.pushmergeinfo ++ +This option will cause git-svn to attempt to automatically populate the +svn:mergeinfo property in the SVN repository when possible. Currently, this can +only be done when dcommitting non-fast-forward merges where all parents but the +first have already been pushed into SVN. + +--interactive;; + Ask the user to confirm that a patch set should actually be sent to SVN. + For each patch, one may answer "yes" (accept this patch), "no" (discard this + patch), "all" (accept all patches), or "quit". + + + 'git svn dcommit' returns immediately if answer if "no" or "quit", without + commiting anything to SVN. 'branch':: Create a branch in the SVN repository. @@ -308,7 +326,7 @@ Any other arguments are passed directly to 'git log' Show what revision and author last modified each line of a file. The output of this mode is format-compatible with the output of `svn blame' by default. Like the SVN blame command, - local uncommitted changes in the working copy are ignored; + local uncommitted changes in the working tree are ignored; the version of the file in the HEAD revision is annotated. Unknown arguments are passed directly to 'git blame'. + @@ -350,6 +368,8 @@ Any other arguments are passed directly to 'git log' Empty directories are automatically recreated when using "git svn clone" and "git svn rebase", so "mkdirs" is intended for use after commands like "git checkout" or "git reset". + (See the svn-remote.<name>.automkdirs config file option for + more information.) 'commit-diff':: Commits the diff of two tree-ish arguments from the @@ -572,6 +592,17 @@ repository that will be fetched from. For 'branch' and 'tag', display the urls that will be used for copying when creating the branch or tag. +--use-log-author:: + When retrieving svn commits into git (as part of 'fetch', 'rebase', or + 'dcommit' operations), look for the first `From:` or `Signed-off-by:` line + in the log message and use that as the author string. +--add-author-from:: + When committing to svn from git (as part of 'commit-diff', 'set-tree' or 'dcommit' + operations), if the existing log message doesn't already have a + `From:` or `Signed-off-by:` line, append a `From:` line based on the + git commit's author string. If you use this, then `--use-log-author` + will retrieve a valid author string for all commits. + ADVANCED OPTIONS ---------------- @@ -680,6 +711,14 @@ svn.pathnameencoding:: locales to avoid corrupted file names with non-ASCII characters. Valid encodings are the ones supported by Perl's Encode module. +svn-remote.<name>.automkdirs:: + Normally, the "git svn clone" and "git svn rebase" commands + attempt to recreate empty directories that are in the + Subversion repository. If this option is set to "false", then + empty directories will only be created if the "git svn mkdirs" + command is run explicitly. If unset, 'git svn' assumes this + option to be "true". + Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps options all affect the metadata generated and used by 'git svn'; they *must* be set in the configuration file before any history is imported @@ -774,10 +813,9 @@ use `git svn rebase` to update your work branch instead of `git pull` or when committing into SVN, which can lead to merge commits reversing previous commits in SVN. -DESIGN PHILOSOPHY ------------------ -Merge tracking in Subversion is lacking and doing branched development -with Subversion can be cumbersome as a result. While 'git svn' can track +MERGE TRACKING +-------------- +While 'git svn' can track copy history (including branches and tags) for repositories adopting a standard layout, it cannot yet represent merge history that happened inside git back upstream to SVN users. Therefore it is advised that @@ -787,16 +825,15 @@ compatibility with SVN (see the CAVEATS section below). CAVEATS ------- -For the sake of simplicity and interoperating with a less-capable system -(SVN), it is recommended that all 'git svn' users clone, fetch and dcommit +For the sake of simplicity and interoperating with Subversion, +it is recommended that all 'git svn' users clone, fetch and dcommit directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push' operations between git repositories and branches. The recommended method of exchanging code between git branches and users is 'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository. Running 'git merge' or 'git pull' is NOT recommended on a branch you -plan to 'dcommit' from. Subversion does not represent merges in any -reasonable or useful fashion; so users using Subversion cannot see any +plan to 'dcommit' from because Subversion users cannot see any merges you've made. Furthermore, if you merge or pull from a git branch that is a mirror of an SVN branch, 'dcommit' may commit to the wrong branch. @@ -846,7 +883,7 @@ Renamed and copied directories are not detected by git and hence not tracked when committing to SVN. I do not plan on adding support for this as it's quite difficult and time-consuming to get working for all the possible corner cases (git doesn't do it, either). Committing -renamed and copied files are fully supported if they're similar enough +renamed and copied files is fully supported if they're similar enough for git to detect them. CONFIGURATION diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index d7795ed657..a45d4c4f29 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -7,6 +7,7 @@ git-symbolic-ref - Read and modify symbolic refs SYNOPSIS -------- +[verse] 'git symbolic-ref' [-q] [-m <reason>] <name> [<ref>] DESCRIPTION @@ -42,12 +43,9 @@ In the past, `.git/HEAD` was a symbolic link pointing at `refs/heads/master`. When we wanted to switch to another branch, we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we wanted to find out which branch we are on, we did `readlink .git/HEAD`. -This was fine, and internally that is what still happens by -default, but on platforms that do not have working symlinks, -or that do not have the `readlink(1)` command, this was a bit -cumbersome. On some platforms, `ln -sf` does not even work as -advertised (horrors). Therefore symbolic links are now deprecated -and symbolic refs are used by default. +But symbolic links are not entirely portable, so they are now +deprecated and symbolic refs (as described above) are used by +default. 'git symbolic-ref' will exit with status 0 if the contents of the symbolic ref were printed correctly, with status 1 if the requested diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index d82f62120a..53ff5f6cf7 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... -'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>] +'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION @@ -38,27 +38,34 @@ created (i.e. a lightweight tag). A GnuPG signed tag object will be created when `-s` or `-u <key-id>` is used. When `-u <key-id>` is not used, the committer identity for the current user is used to find the -GnuPG key for signing. +GnuPG key for signing. The configuration variable `gpg.program` +is used to specify custom GnuPG binary. + OPTIONS ------- -a:: +--annotate:: Make an unsigned, annotated tag object -s:: - Make a GPG-signed tag, using the default e-mail address's key +--sign:: + Make a GPG-signed tag, using the default e-mail address's key. -u <key-id>:: - Make a GPG-signed tag, using the given key +--local-user=<key-id>:: + Make a GPG-signed tag, using the given key. -f:: --force:: Replace an existing tag with the given name (instead of failing) -d:: +--delete:: Delete existing tags with the given names. -v:: +--verify:: Verify the gpg signature of the given tag names. -n<num>:: @@ -69,13 +76,18 @@ OPTIONS If the tag is not annotated, the commit message is displayed instead. -l <pattern>:: - List tags with names that match the given pattern (or all if no pattern is given). - Typing "git tag" without arguments, also lists all tags. +--list <pattern>:: + List tags with names that match the given pattern (or all if no + pattern is given). Running "git tag" without arguments also + lists all tags. The pattern is a shell wildcard (i.e., matched + using fnmatch(3)). Multiple patterns may be given; if any of + them matches, the tag is shown. --contains <commit>:: Only list tags which contain the specified commit. -m <msg>:: +--message=<msg>:: Use the given tag message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. @@ -83,11 +95,19 @@ OPTIONS is given. -F <file>:: +--file=<file>:: Take the tag message from the given file. Use '-' to read the message from the standard input. Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. +--cleanup=<mode>:: + This option sets how the tag message is cleaned up. + The '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'. The + 'strip' mode is default. The 'verbatim' mode does not change message at + all, 'whitespace' removes just leading/trailing whitespace lines and + 'strip' removes both whitespace and commentary. + <tagname>:: The name of the tag to create, delete, or describe. The new tag name must pass all checks defined by diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 5f15754257..346e7a2079 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -8,6 +8,7 @@ git-tar-tree - Create a tar archive of the files in the named tree object SYNOPSIS -------- +[verse] 'git tar-tree' [--remote=<repo>] <tree-ish> [ <base> ] DESCRIPTION @@ -52,26 +53,26 @@ tar.umask:: EXAMPLES -------- -git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -):: +`git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)`:: Create a tar archive that contains the contents of the latest commit on the current branch, and extracts it in `/var/tmp/junk` directory. -git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz:: +`git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a tarball for v1.4.0 release. -git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz:: +`git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a tarball for v1.4.0 release, but without a global extended pax header. -git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar:: +`git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar`:: Get a tarball v1.4.0 from example.com. -git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar:: +`git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar`:: Put everything in the current head's Documentation/ directory into 'git-1.4.0-docs.tar', with the prefix 'git-docs/'. diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt index c49d727f74..e9f148a00d 100644 --- a/Documentation/git-unpack-file.txt +++ b/Documentation/git-unpack-file.txt @@ -9,6 +9,7 @@ git-unpack-file - Creates a temporary file with a blob's contents SYNOPSIS -------- +[verse] 'git unpack-file' <blob> DESCRIPTION diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index dd7799095b..ff23494e70 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -8,6 +8,7 @@ git-unpack-objects - Unpack objects from a packed archive SYNOPSIS -------- +[verse] 'git unpack-objects' [-n] [-q] [-r] [--strict] <pack-file diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index d3931294d1..a3081f4e23 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -264,7 +264,9 @@ tree files, you have to explicitly tell git about it by dropping "assume unchanged" bit, either before or after you modify them. In order to set "assume unchanged" bit, use `--assume-unchanged` -option. To unset, use `--no-assume-unchanged`. +option. To unset, use `--no-assume-unchanged`. To see which files +have the "assume unchanged" bit set, use `git ls-files -v` +(see linkgit:git-ls-files[1]). The command looks at `core.ignorestat` configuration variable. When this is true, paths updated with `git update-index paths...` and @@ -363,7 +365,8 @@ ctime for marking files processed) (see linkgit:git-config[1]). SEE ALSO -------- linkgit:git-config[1], -linkgit:git-add[1] +linkgit:git-add[1], +linkgit:git-ls-files[1] GIT --- diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index e25a65a80f..d377a35243 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -7,6 +7,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- +[verse] 'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>]) DESCRIPTION @@ -60,8 +61,9 @@ still contains <oldvalue>. Logging Updates --------------- -If config parameter "core.logAllRefUpdates" is true or the file -"$GIT_DIR/logs/<ref>" exists then `git update-ref` will append +If config parameter "core.logAllRefUpdates" is true and the ref is one under +"refs/heads/", "refs/remotes/", "refs/notes/", or the symbolic ref HEAD; or +the file "$GIT_DIR/logs/<ref>" exists then `git update-ref` will append a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating the log name) describing the change in ref value. Log lines are formatted as: diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 775024da3e..bd0e36492f 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -8,6 +8,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers SYNOPSIS -------- +[verse] 'git update-server-info' [--force] DESCRIPTION diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt index acbf634f85..4d52d3833a 100644 --- a/Documentation/git-upload-archive.txt +++ b/Documentation/git-upload-archive.txt @@ -8,6 +8,7 @@ git-upload-archive - Send archive back to git-archive SYNOPSIS -------- +[verse] 'git upload-archive' <directory> DESCRIPTION diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 4c0ca9ded2..71f16083d6 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -8,6 +8,7 @@ git-upload-pack - Send objects packed back to git-fetch-pack SYNOPSIS -------- +[verse] 'git-upload-pack' [--strict] [--timeout=<n>] <directory> DESCRIPTION @@ -33,6 +34,10 @@ OPTIONS <directory>:: The repository to sync from. +SEE ALSO +-------- +linkgit:gitnamespaces[7] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 6498f7cb69..5317cc2474 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -8,6 +8,7 @@ git-var - Show a git logical variable SYNOPSIS -------- +[verse] 'git var' ( -l | <variable> ) DESCRIPTION diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 7c2428d569..cd230769fd 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -8,6 +8,7 @@ git-verify-pack - Validate packed git archive files SYNOPSIS -------- +[verse] 'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index 8c9a71865b..5ff76e892a 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -7,6 +7,7 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- +[verse] 'git verify-tag' <tag>... DESCRIPTION diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 69d92fa00e..c2bc87bc61 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -7,6 +7,7 @@ git-web--browse - git helper script to launch a web browser SYNOPSIS -------- +[verse] 'git web{litdd}browse' [OPTIONS] URL/FILE ... DESCRIPTION @@ -68,7 +69,7 @@ browser.<tool>.path You can explicitly provide a full path to your preferred browser by setting the configuration variable 'browser.<tool>.path'. For example, you can configure the absolute path to firefox by setting -'browser.firefox.path'. Otherwise, 'git web--browse' assumes the tool +'browser.firefox.path'. Otherwise, 'git web{litdd}browse' assumes the tool is available in PATH. browser.<tool>.cmd diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 31f3663ae7..76c7f7eec5 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -8,6 +8,7 @@ git-whatchanged - Show logs with difference each commit introduces SYNOPSIS -------- +[verse] 'git whatchanged' <option>... DESCRIPTION @@ -52,12 +53,12 @@ include::pretty-formats.txt[] Examples -------- -git whatchanged -p v2.6.12.. include/scsi drivers/scsi:: +`git whatchanged -p v2.6.12.. include/scsi drivers/scsi`:: Show as patches the commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -git whatchanged --since="2 weeks ago" \-- gitk:: +`git whatchanged --since="2 weeks ago" \-- gitk`:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index e8c94c1352..f22041a9dc 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -8,6 +8,7 @@ git-write-tree - Create a tree object from the current index SYNOPSIS -------- +[verse] 'git write-tree' [--missing-ok] [--prefix=<prefix>/] DESCRIPTION diff --git a/Documentation/git.txt b/Documentation/git.txt index 9d5949229a..db5d5570cf 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -9,9 +9,9 @@ git - the stupid content tracker SYNOPSIS -------- [verse] -'git' [--version] [--exec-path[=<path>]] [--html-path] - [-p|--paginate|--no-pager] [--no-replace-objects] - [--bare] [--git-dir=<path>] [--work-tree=<path>] +'git' [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] + [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] + [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] [-c <name>=<value>] [--help] <command> [<args>] @@ -44,9 +44,43 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.7.5/git.html[documentation for release 1.7.5] +* link:v1.7.8.4/git.html[documentation for release 1.7.8.4] * release notes for + link:RelNotes/1.7.8.4.txt[1.7.8.4], + link:RelNotes/1.7.8.3.txt[1.7.8.3], + link:RelNotes/1.7.8.2.txt[1.7.8.2], + link:RelNotes/1.7.8.1.txt[1.7.8.1], + link:RelNotes/1.7.8.txt[1.7.8]. + +* link:v1.7.7.6/git.html[documentation for release 1.7.7.6] + +* release notes for + link:RelNotes/1.7.7.6.txt[1.7.7.6], + link:RelNotes/1.7.7.5.txt[1.7.7.5], + link:RelNotes/1.7.7.4.txt[1.7.7.4], + link:RelNotes/1.7.7.3.txt[1.7.7.3], + link:RelNotes/1.7.7.2.txt[1.7.7.2], + link:RelNotes/1.7.7.1.txt[1.7.7.1], + link:RelNotes/1.7.7.txt[1.7.7]. + +* link:v1.7.6.5/git.html[documentation for release 1.7.6.5] + +* release notes for + link:RelNotes/1.7.6.5.txt[1.7.6.5], + link:RelNotes/1.7.6.4.txt[1.7.6.4], + link:RelNotes/1.7.6.3.txt[1.7.6.3], + link:RelNotes/1.7.6.2.txt[1.7.6.2], + link:RelNotes/1.7.6.1.txt[1.7.6.1], + link:RelNotes/1.7.6.txt[1.7.6]. + +* link:v1.7.5.4/git.html[documentation for release 1.7.5.4] + +* release notes for + link:RelNotes/1.7.5.4.txt[1.7.5.4], + link:RelNotes/1.7.5.3.txt[1.7.5.3], + link:RelNotes/1.7.5.2.txt[1.7.5.2], + link:RelNotes/1.7.5.1.txt[1.7.5.1], link:RelNotes/1.7.5.txt[1.7.5]. * link:v1.7.4.5/git.html[documentation for release 1.7.4.5] @@ -287,8 +321,16 @@ help ...`. the current setting and then exit. --html-path:: - Print the path to wherever your git HTML documentation is installed - and exit. + Print the path, without trailing slash, where git's HTML + documentation is installed and exit. + +--man-path:: + Print the manpath (see `man(1)`) for the man pages for + this version of git and exit. + +--info-path:: + Print the path where the Info files documenting this + version of git are installed and exit. -p:: --paginate:: @@ -313,6 +355,11 @@ help ...`. variable (see core.worktree in linkgit:git-config[1] for a more detailed discussion). +--namespace=<path>:: + Set the git namespace. See linkgit:gitnamespaces[7] for more + details. Equivalent to setting the `GIT_NAMESPACE` environment + variable. + --bare:: Treat the repository as a bare repository. If GIT_DIR environment is not set, it is set to the current working @@ -506,16 +553,15 @@ Any git command accepting any <object> can also use the following symbolic notation: HEAD:: - indicates the head of the current branch (i.e. the - contents of `$GIT_DIR/HEAD`). + indicates the head of the current branch. <tag>:: a valid tag 'name' - (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). + (i.e. a `refs/tags/<tag>` reference). <head>:: a valid head 'name' - (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). + (i.e. a `refs/heads/<head>` reference). For a more complete list of ways to spell object names, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. @@ -577,6 +623,10 @@ git so take care if using Cogito etc. This can also be controlled by the '--work-tree' command line option and the core.worktree configuration variable. +'GIT_NAMESPACE':: + Set the git namespace; see linkgit:gitnamespaces[7] for details. + The '--namespace' command-line option also sets this value. + 'GIT_CEILING_DIRECTORIES':: This should be a colon-separated list of absolute paths. If set, it is a list of directories that git should not chdir diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 15aebc6062..a85b187e04 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -79,7 +79,7 @@ Attributes for all users on a system should be placed in the `$(prefix)/etc/gitattributes` file. Sometimes you would need to override an setting of an attribute -for a path to `unspecified` state. This can be done by listing +for a path to `Unspecified` state. This can be done by listing the name of the attribute prefixed with an exclamation point `!`. @@ -500,6 +500,8 @@ patterns are available: - `java` suitable for source code in the Java language. +- `matlab` suitable for source code in the MATLAB language. + - `objc` suitable for source code in the Objective-C language. - `pascal` suitable for source code in the Pascal/Delphi language. @@ -593,6 +595,37 @@ and now produces better output), you can remove the cache manually with `git update-ref -d refs/notes/textconv/jpg` (where "jpg" is the name of the diff driver, as in the example above). +Choosing textconv versus external diff +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to show differences between binary or specially-formatted +blobs in your repository, you can choose to use either an external diff +command, or to use textconv to convert them to a diff-able text format. +Which method you choose depends on your exact situation. + +The advantage of using an external diff command is flexibility. You are +not bound to find line-oriented changes, nor is it necessary for the +output to resemble unified diff. You are free to locate and report +changes in the most appropriate way for your data format. + +A textconv, by comparison, is much more limiting. You provide a +transformation of the data into a line-oriented text format, and git +uses its regular diff tools to generate the output. There are several +advantages to choosing this method: + +1. Ease of use. It is often much simpler to write a binary to text + transformation than it is to perform your own diff. In many cases, + existing programs can be used as textconv filters (e.g., exif, + odt2txt). + +2. Git diff features. By performing only the transformation step + yourself, you can still utilize many of git's diff features, + including colorization, word-diff, and combined diffs for merges. + +3. Caching. Textconv caching can speed up repeated diffs, such as those + you might trigger by running `git log -p`. + + Marking files as binary ^^^^^^^^^^^^^^^^^^^^^^^ @@ -837,7 +870,7 @@ If this attribute is not set or has an invalid value, the value of the (See linkgit:git-config[1]). -USING ATTRIBUTE MACROS +USING MACRO ATTRIBUTES ---------------------- You do not want any end-of-line conversions applied to, nor textual diffs @@ -848,24 +881,27 @@ produced for, any binary file you track. You would need to specify e.g. ------------ but that may become cumbersome, when you have many attributes. Using -attribute macros, you can specify groups of attributes set or unset at -the same time. The system knows a built-in attribute macro, `binary`: +macro attributes, you can define an attribute that, when set, also +sets or unsets a number of other attributes at the same time. The +system knows a built-in macro attribute, `binary`: ------------ *.jpg binary ------------ -which is equivalent to the above. Note that the attribute macros can only -be "Set" (see the above example that sets "binary" macro as if it were an -ordinary attribute --- setting it in turn unsets "text" and "diff"). +Setting the "binary" attribute also unsets the "text" and "diff" +attributes as above. Note that macro attributes can only be "Set", +though setting one might have the effect of setting or unsetting other +attributes or even returning other attributes to the "Unspecified" +state. -DEFINING ATTRIBUTE MACROS +DEFINING MACRO ATTRIBUTES ------------------------- -Custom attribute macros can be defined only in the `.gitattributes` file -at the toplevel (i.e. not in any subdirectory). The built-in attribute -macro "binary" is equivalent to: +Custom macro attributes can be defined only in the `.gitattributes` +file at the toplevel (i.e. not in any subdirectory). The built-in +macro attribute "binary" is equivalent to: ------------ [attr]binary -diff -text @@ -921,6 +957,9 @@ frotz unspecified ---------------------------------------------------------------- +SEE ALSO +-------- +linkgit:git-check-attr[1]. GIT --- diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt new file mode 100644 index 0000000000..066f825f2e --- /dev/null +++ b/Documentation/gitcredentials.txt @@ -0,0 +1,183 @@ +gitcredentials(7) +================= + +NAME +---- +gitcredentials - providing usernames and passwords to git + +SYNOPSIS +-------- +------------------ +git config credential.https://example.com.username myusername +git config credential.helper "$helper $options" +------------------ + +DESCRIPTION +----------- + +Git will sometimes need credentials from the user in order to perform +operations; for example, it may need to ask for a username and password +in order to access a remote repository over HTTP. This manual describes +the mechanisms git uses to request these credentials, as well as some +features to avoid inputting these credentials repeatedly. + +REQUESTING CREDENTIALS +---------------------- + +Without any credential helpers defined, git will try the following +strategies to ask the user for usernames and passwords: + +1. If the `GIT_ASKPASS` environment variable is set, the program + specified by the variable is invoked. A suitable prompt is provided + to the program on the command line, and the user's input is read + from its standard output. + +2. Otherwise, if the `core.askpass` configuration variable is set, its + value is used as above. + +3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its + value is used as above. + +4. Otherwise, the user is prompted on the terminal. + +AVOIDING REPETITION +------------------- + +It can be cumbersome to input the same credentials over and over. Git +provides two methods to reduce this annoyance: + +1. Static configuration of usernames for a given authentication context. + +2. Credential helpers to cache or store passwords, or to interact with + a system password wallet or keychain. + +The first is simple and appropriate if you do not have secure storage available +for a password. It is generally configured by adding this to your config: + +--------------------------------------- +[credential "https://example.com"] + username = me +--------------------------------------- + +Credential helpers, on the other hand, are external programs from which git can +request both usernames and passwords; they typically interface with secure +storage provided by the OS or other programs. + +To use a helper, you must first select one to use. Git currently +includes the following helpers: + +cache:: + + Cache credentials in memory for a short period of time. See + linkgit:git-credential-cache[1] for details. + +store:: + + Store credentials indefinitely on disk. See + linkgit:git-credential-store[1] for details. + +You may also have third-party helpers installed; search for +`credential-*` in the output of `git help -a`, and consult the +documentation of individual helpers. Once you have selected a helper, +you can tell git to use it by putting its name into the +credential.helper variable. + +1. Find a helper. ++ +------------------------------------------- +$ git help -a | grep credential- +credential-foo +------------------------------------------- + +2. Read its description. ++ +------------------------------------------- +$ git help credential-foo +------------------------------------------- + +3. Tell git to use it. ++ +------------------------------------------- +$ git config --global credential.helper foo +------------------------------------------- + +If there are multiple instances of the `credential.helper` configuration +variable, each helper will be tried in turn, and may provide a username, +password, or nothing. Once git has acquired both a username and a +password, no more helpers will be tried. + + +CREDENTIAL CONTEXTS +------------------- + +Git considers each credential to have a context defined by a URL. This context +is used to look up context-specific configuration, and is passed to any +helpers, which may use it as an index into secure storage. + +For instance, imagine we are accessing `https://example.com/foo.git`. When git +looks into a config file to see if a section matches this context, it will +consider the two a match if the context is a more-specific subset of the +pattern in the config file. For example, if you have this in your config file: + +-------------------------------------- +[credential "https://example.com"] + username = foo +-------------------------------------- + +then we will match: both protocols are the same, both hosts are the same, and +the "pattern" URL does not care about the path component at all. However, this +context would not match: + +-------------------------------------- +[credential "https://kernel.org"] + username = foo +-------------------------------------- + +because the hostnames differ. Nor would it match `foo.example.com`; git +compares hostnames exactly, without considering whether two hosts are part of +the same domain. Likewise, a config entry for `http://example.com` would not +match: git compares the protocols exactly. + + +CONFIGURATION OPTIONS +--------------------- + +Options for a credential context can be configured either in +`credential.\*` (which applies to all credentials), or +`credential.<url>.\*`, where <url> matches the context as described +above. + +The following options are available in either location: + +helper:: + + The name of an external credential helper, and any associated options. + If the helper name is not an absolute path, then the string `git + credential-` is prepended. The resulting string is executed by the + shell (so, for example, setting this to `foo --option=bar` will execute + `git credential-foo --option=bar` via the shell. See the manual of + specific helpers for examples of their use. + +username:: + + A default username, if one is not provided in the URL. + +useHttpPath:: + + By default, git does not consider the "path" component of an http URL + to be worth matching via external helpers. This means that a credential + stored for `https://example.com/foo.git` will also be used for + `https://example.com/bar.git`. If you do want to distinguish these + cases, set this option to `true`. + + +CUSTOM HELPERS +-------------- + +You can write your own custom helpers to interface with any system in +which you keep credentials. See the documentation for git's +link:technical/api-credentials.html[credentials API] for details. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt index d861ec452f..aeb0cdc973 100644 --- a/Documentation/gitcvs-migration.txt +++ b/Documentation/gitcvs-migration.txt @@ -7,7 +7,8 @@ gitcvs-migration - git for CVS users SYNOPSIS -------- -git cvsimport * +[verse] +'git cvsimport' * DESCRIPTION ----------- diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 6af29a4603..370624c171 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -7,6 +7,7 @@ gitdiffcore - Tweaking diff output SYNOPSIS -------- +[verse] 'git diff' * DESCRIPTION diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index e10ac58cae..a17a354936 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -7,6 +7,7 @@ gitk - The git repository browser SYNOPSIS -------- +[verse] 'gitk' [<option>...] [<revs>] [--] [<path>...] DESCRIPTION diff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.txt new file mode 100644 index 0000000000..c6713cf5d7 --- /dev/null +++ b/Documentation/gitnamespaces.txt @@ -0,0 +1,82 @@ +gitnamespaces(7) +================ + +NAME +---- +gitnamespaces - Git namespaces + +SYNOPSIS +-------- +[verse] +GIT_NAMESPACE=<namespace> 'git upload-pack' +GIT_NAMESPACE=<namespace> 'git receive-pack' + + +DESCRIPTION +----------- + +Git supports dividing the refs of a single repository into multiple +namespaces, each of which has its own branches, tags, and HEAD. Git can +expose each namespace as an independent repository to pull from and push +to, while sharing the object store, and exposing all the refs to +operations such as linkgit:git-gc[1]. + +Storing multiple repositories as namespaces of a single repository +avoids storing duplicate copies of the same objects, such as when +storing multiple branches of the same source. The alternates mechanism +provides similar support for avoiding duplicates, but alternates do not +prevent duplication between new objects added to the repositories +without ongoing maintenance, while namespaces do. + +To specify a namespace, set the `GIT_NAMESPACE` environment variable to +the namespace. For each ref namespace, git stores the corresponding +refs in a directory under `refs/namespaces/`. For example, +`GIT_NAMESPACE=foo` will store refs under `refs/namespaces/foo/`. You +can also specify namespaces via the `--namespace` option to +linkgit:git[1]. + +Note that namespaces which include a `/` will expand to a hierarchy of +namespaces; for example, `GIT_NAMESPACE=foo/bar` will store refs under +`refs/namespaces/foo/refs/namespaces/bar/`. This makes paths in +`GIT_NAMESPACE` behave hierarchically, so that cloning with +`GIT_NAMESPACE=foo/bar` produces the same result as cloning with +`GIT_NAMESPACE=foo` and cloning from that repo with `GIT_NAMESPACE=bar`. It +also avoids ambiguity with strange namespace paths such as `foo/refs/heads/`, +which could otherwise generate directory/file conflicts within the `refs` +directory. + +linkgit:git-upload-pack[1] and linkgit:git-receive-pack[1] rewrite the +names of refs as specified by `GIT_NAMESPACE`. git-upload-pack and +git-receive-pack will ignore all references outside the specified +namespace. + +The smart HTTP server, linkgit:git-http-backend[1], will pass +GIT_NAMESPACE through to the backend programs; see +linkgit:git-http-backend[1] for sample configuration to expose +repository namespaces as repositories. + +For a simple local test, you can use linkgit:git-remote-ext[1]: + +---------- +git clone ext::'git --namespace=foo %s /tmp/prefixed.git' +---------- + +SECURITY +-------- + +Anyone with access to any namespace within a repository can potentially +access objects from any other namespace stored in the same repository. +You can't directly say "give me object ABCD" if you don't have a ref to +it, but you can do some other sneaky things like: + +. Claiming to push ABCD, at which point the server will optimize out the + need for you to actually send it. Now you have a ref to ABCD and can + fetch it (claiming not to have it, of course). + +. Requesting other refs, claiming that you have ABCD, at which point the + server may generate deltas against ABCD. + +None of this causes a problem if you only host public repositories, or +if everyone who may read one namespace may also read everything in every +other namespace (for instance, if everyone in an organization has read +permission to every repository). diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index eb3d040783..5c891f1169 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -23,32 +23,25 @@ objects:: Object store associated with this repository. Usually an object store is self sufficient (i.e. all the objects that are referred to by an object found in it are also - found in it), but there are couple of ways to violate - it. + found in it), but there are a few ways to violate it. + -. You could populate the repository by running a commit walker -without `-a` option. Depending on which options are given, you -could have only commit objects without associated blobs and -trees this way, for example. A repository with this kind of -incomplete object store is not suitable to be published to the -outside world but sometimes useful for private repository. -. You also could have an incomplete but locally usable repository -by cloning shallowly. See linkgit:git-clone[1]. -. You can be using `objects/info/alternates` mechanism, or -`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow' +. You could have an incomplete but locally usable repository +by creating a shallow clone. See linkgit:git-clone[1]. +. You could be using the `objects/info/alternates` or +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow' objects from other object stores. A repository with this kind of incomplete object store is not suitable to be published for use with dumb transports but otherwise is OK as long as -`objects/info/alternates` points at the right object stores -it borrows from. +`objects/info/alternates` points at the object stores it +borrows from. objects/[0-9a-f][0-9a-f]:: - Traditionally, each object is stored in its own file. - They are split into 256 subdirectories using the first - two letters from its object name to keep the number of - directory entries `objects` directory itself needs to - hold. Objects found here are often called 'unpacked' - (or 'loose') objects. + A newly created object is stored in its own file. + The objects are splayed over 256 subdirectories using + the first two characters of the sha1 object name to + keep the number of directory entries in `objects` + itself to a manageable number. Objects found + here are often called 'unpacked' (or 'loose') objects. objects/pack:: Packs (files that store many object in compressed form, @@ -85,7 +78,7 @@ objects/info/http-alternates:: refs:: References are stored in subdirectories of this - directory. The 'git prune' command knows to keep + directory. The 'git prune' command knows to preserve objects reachable from refs found in this directory and its subdirectories. @@ -119,16 +112,17 @@ HEAD:: + HEAD can also record a specific commit directly, instead of being a symref to point at the current branch. Such a state -is often called 'detached HEAD', and almost all commands work -identically as normal. See linkgit:git-checkout[1] for -details. +is often called 'detached HEAD.' See linkgit:git-checkout[1] +for details. branches:: A slightly deprecated way to store shorthands to be used - to specify URL to 'git fetch', 'git pull' and 'git push' - commands is to store a file in `branches/<name>` and - give 'name' to these commands in place of 'repository' - argument. + to specify a URL to 'git fetch', 'git pull' and 'git push'. + A file can be stored as `branches/<name>` and then + 'name' can be given to these commands in place of + 'repository' argument. See the REMOTES section in + linkgit:git-fetch[1] for details. This mechanism is legacy + and not likely to be found in modern repositories. hooks:: Hooks are customization scripts used by various git @@ -173,9 +167,11 @@ info/exclude:: at it. See also: linkgit:gitignore[5]. remotes:: - Stores shorthands to be used to give URL and default - refnames to interact with remote repository to - 'git fetch', 'git pull' and 'git push' commands. + Stores shorthands for URL and default refnames for use + when interacting with remote repositories via 'git fetch', + 'git pull' and 'git push' commands. See the REMOTES section + in linkgit:git-fetch[1] for details. This mechanism is legacy + and not likely to be found in modern repositories. logs:: Records of changes made to refs are stored in this diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index 7fe5848d1f..f1e4422acc 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -7,6 +7,7 @@ gittutorial-2 - A tutorial introduction to git: part two SYNOPSIS -------- +[verse] git * DESCRIPTION diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 0982f74ef6..dee050567e 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -7,6 +7,7 @@ gittutorial - A tutorial introduction to git (for version 1.5.1 or newer) SYNOPSIS -------- +[verse] git * DESCRIPTION diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt new file mode 100644 index 0000000000..7aba497b74 --- /dev/null +++ b/Documentation/gitweb.conf.txt @@ -0,0 +1,889 @@ +gitweb.conf(5) +============== + +NAME +---- +gitweb.conf - Gitweb (git web interface) configuration file + +SYNOPSIS +-------- +/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl + +DESCRIPTION +----------- + +The gitweb CGI script for viewing Git repositories over the web uses a +perl script fragment as its configuration file. You can set variables +using "`our $variable = value`"; text from a "#" character until the +end of a line is ignored. See *perlsyn*(1) for details. + +An example: + + # gitweb configuration file for http://git.example.org + # + our $projectroot = "/srv/git"; # FHS recommendation + our $site_name = 'Example.org >> Repos'; + + +The configuration file is used to override the default settings that +were built into gitweb at the time the 'gitweb.cgi' script was generated. + +While one could just alter the configuration settings in the gitweb +CGI itself, those changes would be lost upon upgrade. Configuration +settings might also be placed into a file in the same directory as the +CGI script with the default name 'gitweb_config.perl' -- allowing +one to have multiple gitweb instances with different configurations by +the use of symlinks. + +Note that some configuration can be controlled on per-repository rather than +gitweb-wide basis: see "Per-repository gitweb configuration" subsection on +linkgit:gitweb[1] manpage. + + +DISCUSSION +---------- +Gitweb reads configuration data from the following sources in the +following order: + + * built-in values (some set during build stage), + + * common system-wide configuration file (defaults to + '/etc/gitweb-common.conf'), + + * either per-instance configuration file (defaults to 'gitweb_config.perl' + in the same directory as the installed gitweb), or if it does not exists + then fallback system-wide configuration file (defaults to '/etc/gitweb.conf'). + +Values obtained in later configuration files override values obtained earlier +in the above sequence. + +Locations of the common system-wide configuration file, the fallback +system-wide configuration file and the per-instance configuration file +are defined at compile time using build-time Makefile configuration +variables, respectively `GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` +and `GITWEB_CONFIG`. + +You can also override locations of gitweb configuration files during +runtime by setting the following environment variables: +`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG` +to a non-empty value. + + +The syntax of the configuration files is that of Perl, since these files are +handled by sourcing them as fragments of Perl code (the language that +gitweb itself is written in). Variables are typically set using the +`our` qualifier (as in "`our $variable = <value>;`") to avoid syntax +errors if a new version of gitweb no longer uses a variable and therefore +stops declaring it. + +You can include other configuration file using read_config_file() +subroutine. For example, one might want to put gitweb configuration +related to access control for viewing repositories via Gitolite (one +of git repository management tools) in a separate file, e.g. in +'/etc/gitweb-gitolite.conf'. To include it, put + +-------------------------------------------------- +read_config_file("/etc/gitweb-gitolite.conf"); +-------------------------------------------------- + +somewhere in gitweb configuration file used, e.g. in per-installation +gitweb configuration file. Note that read_config_file() checks itself +that the file it reads exists, and does nothing if it is not found. +It also handles errors in included file. + + +The default configuration with no configuration file at all may work +perfectly well for some installations. Still, a configuration file is +useful for customizing or tweaking the behavior of gitweb in many ways, and +some optional features will not be present unless explicitly enabled using +the configurable `%features` variable (see also "Configuring gitweb +features" section below). + + +CONFIGURATION VARIABLES +----------------------- +Some configuration variables have their default values (embedded in the CGI +script) set during building gitweb -- if that is the case, this fact is put +in their description. See gitweb's 'INSTALL' file for instructions on building +and installing gitweb. + + +Location of repositories +~~~~~~~~~~~~~~~~~~~~~~~~ +The configuration variables described below control how gitweb finds +git repositories, and how repositories are displayed and accessed. + +See also "Repositories" and later subsections in linkgit:gitweb[1] manpage. + +$projectroot:: + Absolute filesystem path which will be prepended to project path; + the path to repository is `$projectroot/$project`. Set to + `$GITWEB_PROJECTROOT` during installation. This variable has to be + set correctly for gitweb to find repositories. ++ +For example, if `$projectroot` is set to "/srv/git" by putting the following +in gitweb config file: ++ +---------------------------------------------------------------------------- +our $projectroot = "/srv/git"; +---------------------------------------------------------------------------- ++ +then ++ +------------------------------------------------ +http://git.example.com/gitweb.cgi?p=foo/bar.git +------------------------------------------------ ++ +and its path_info based equivalent ++ +------------------------------------------------ +http://git.example.com/gitweb.cgi/foo/bar.git +------------------------------------------------ ++ +will map to the path '/srv/git/foo/bar.git' on the filesystem. + +$projects_list:: + Name of a plain text file listing projects, or a name of directory + to be scanned for projects. ++ +Project list files should list one project per line, with each line +having the following format ++ +----------------------------------------------------------------------------- +<URI-encoded filesystem path to repository> SP <URI-encoded repository owner> +----------------------------------------------------------------------------- ++ +The default value of this variable is determined by the `GITWEB_LIST` +makefile variable at installation time. If this variable is empty, gitweb +will fall back to scanning the `$projectroot` directory for repositories. + +$project_maxdepth:: + If `$projects_list` variable is unset, gitweb will recursively + scan filesystem for git repositories. The `$project_maxdepth` + is used to limit traversing depth, relative to `$projectroot` + (starting point); it means that directories which are further + from `$projectroot` than `$project_maxdepth` will be skipped. ++ +It is purely performance optimization, originally intended for MacOS X, +where recursive directory traversal is slow. Gitweb follows symbolic +links, but it detects cycles, ignoring any duplicate files and directories. ++ +The default value of this variable is determined by the build-time +configuration variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to +2007. + +$export_ok:: + Show repository only if this file exists (in repository). Only + effective if this variable evaluates to true. Can be set when + building gitweb by setting `GITWEB_EXPORT_OK`. This path is + relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok', + unless started with `--export-all`. By default this variable is + not set, which means that this feature is turned off. + +$export_auth_hook:: + Function used to determine which repositories should be shown. + This subroutine should take one parameter, the full path to + a project, and if it returns true, that project will be included + in the projects list and can be accessed through gitweb as long + as it fulfills the other requirements described by $export_ok, + $projects_list, and $projects_maxdepth. Example: ++ +---------------------------------------------------------------------------- +our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; }; +---------------------------------------------------------------------------- ++ +though the above might be done by using `$export_ok` instead ++ +---------------------------------------------------------------------------- +our $export_ok = "git-daemon-export-ok"; +---------------------------------------------------------------------------- ++ +If not set (default), it means that this feature is disabled. ++ +See also more involved example in "Controlling access to git repositories" +subsection on linkgit:gitweb[1] manpage. + +$strict_export:: + Only allow viewing of repositories also shown on the overview page. + This for example makes `$gitweb_export_ok` file decide if repository is + available and not only if it is shown. If `$gitweb_list` points to + file with list of project, only those repositories listed would be + available for gitweb. Can be set during building gitweb via + `GITWEB_STRICT_EXPORT`. By default this variable is not set, which + means that you can directly access those repositories that are hidden + from projects list page (e.g. the are not listed in the $projects_list + file). + + +Finding files +~~~~~~~~~~~~~ +The following configuration variables tell gitweb where to find files. +The values of these variables are paths on the filesystem. + +$GIT:: + Core git executable to use. By default set to `$GIT_BINDIR/git`, which + in turn is by default set to `$(bindir)/git`. If you use git installed + from a binary package, you should usually set this to "/usr/bin/git". + This can just be "git" if your web server has a sensible PATH; from + security point of view it is better to use absolute path to git binary. + If you have multiple git versions installed it can be used to choose + which one to use. Must be (correctly) set for gitweb to be able to + work. + +$mimetypes_file:: + File to use for (filename extension based) guessing of MIME types before + trying '/etc/mime.types'. *NOTE* that this path, if relative, is taken + as relative to the current git repository, not to CGI script. If unset, + only '/etc/mime.types' is used (if present on filesystem). If no mimetypes + file is found, mimetype guessing based on extension of file is disabled. + Unset by default. + +$highlight_bin:: + Path to the highlight executable to use (it must be the one from + http://www.andre-simon.de[] due to assumptions about parameters and output). + By default set to 'highlight'; set it to full path to highlight + executable if it is not installed on your web server's PATH. + Note that 'highlight' feature must be set for gitweb to actually + use syntax hightlighting. ++ +*NOTE*: if you want to add support for new file type (supported by +"highlight" but not used by gitweb), you need to modify `%highlight_ext` +or `%highlight_basename`, depending on whether you detect type of file +based on extension (for example "sh") or on its basename (for example +"Makefile"). The keys of these hashes are extension and basename, +respectively, and value for given key is name of syntax to be passed via +`--syntax <syntax>` to highlighter. ++ +For example if repositories you are hosting use "phtml" extension for +PHP files, and you want to have correct syntax-highlighting for those +files, you can add the following to gitweb configuration: ++ +--------------------------------------------------------- +our %highlight_ext; +$highlight_ext{'phtml'} = 'php'; +--------------------------------------------------------- + + +Links and their targets +~~~~~~~~~~~~~~~~~~~~~~~ +The configuration variables described below configure some of gitweb links: +their target and their look (text or image), and where to find page +prerequisites (stylesheet, favicon, images, scripts). Usually they are left +at their default values, with the possible exception of `@stylesheets` +variable. + +@stylesheets:: + List of URIs of stylesheets (relative to the base URI of a page). You + might specify more than one stylesheet, for example to use "gitweb.css" + as base with site specific modifications in a separate stylesheet + to make it easier to upgrade gitweb. For example, you can add + a `site` stylesheet by putting ++ +---------------------------------------------------------------------------- +push @stylesheets, "gitweb-site.css"; +---------------------------------------------------------------------------- ++ +in the gitweb config file. Those values that are relative paths are +relative to base URI of gitweb. ++ +This list should contain the URI of gitweb's standard stylesheet. The default +URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS` +makefile variable. Its default value is 'static/gitweb.css' +(or 'static/gitweb.min.css' if the `CSSMIN` variable is defined, +i.e. if CSS minifier is used during build). ++ +*Note*: there is also a legacy `$stylesheet` configuration variable, which was +used by older gitweb. If `$stylesheet` variable is defined, only CSS stylesheet +given by this variable is used by gitweb. + +$logo:: + Points to the location where you put 'git-logo.png' on your web + server, or to be more the generic URI of logo, 72x27 size). This image + is displayed in the top right corner of each gitweb page and used as + a logo for the Atom feed. Relative to the base URI of gitweb (as a path). + Can be adjusted when building gitweb using `GITWEB_LOGO` variable + By default set to 'static/git-logo.png'. + +$favicon:: + Points to the location where you put 'git-favicon.png' on your web + server, or to be more the generic URI of favicon, which will be served + as "image/png" type. Web browsers that support favicons (website icons) + may display them in the browser's URL bar and next to the site name in + bookmarks. Relative to the base URI of gitweb. Can be adjusted at + build time using `GITWEB_FAVICON` variable. + By default set to 'static/git-favicon.png'. + +$javascript:: + Points to the location where you put 'gitweb.js' on your web server, + or to be more generic the URI of JavaScript code used by gitweb. + Relative to the base URI of gitweb. Can be set at build time using + the `GITWEB_JS` build-time configuration variable. ++ +The default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if +the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used +at build time. *Note* that this single file is generated from multiple +individual JavaScript "modules". + +$home_link:: + Target of the home link on the top of all pages (the first part of view + "breadcrumbs"). By default it is set to the absolute URI of a current page + (to the value of `$my_uri` variable, or to "/" if `$my_uri` is undefined + or is an empty string). + +$home_link_str:: + Label for the "home link" at the top of all pages, leading to `$home_link` + (usually the main gitweb page, which contains the projects list). It is + used as the first component of gitweb's "breadcrumb trail": + `<home link> / <project> / <action>`. Can be set at build time using + the `GITWEB_HOME_LINK_STR` variable. By default it is set to "projects", + as this link leads to the list of projects. Other popular choice it to + set it to the name of site. + +$logo_url:: +$logo_label:: + URI and label (title) for the Git logo link (or your site logo, + if you chose to use different logo image). By default, these both + refer to git homepage, http://git-scm.com[]; in the past, they pointed + to git documentation at http://www.kernel.org[]. + + +Changing gitweb's look +~~~~~~~~~~~~~~~~~~~~~~ +You can adjust how pages generated by gitweb look using the variables described +below. You can change the site name, add common headers and footers for all +pages, and add a description of this gitweb installation on its main page +(which is the projects list page), etc. + +$site_name:: + Name of your site or organization, to appear in page titles. Set it + to something descriptive for clearer bookmarks etc. If this variable + is not set or is, then gitweb uses the value of the `SERVER_NAME` + CGI environment variable, setting site name to "$SERVER_NAME Git", + or "Untitled Git" if this variable is not set (e.g. if running gitweb + as standalone script). ++ +Can be set using the `GITWEB_SITENAME` at build time. Unset by default. + +$site_html_head_string:: + HTML snippet to be included in the <head> section of each page. + Can be set using `GITWEB_SITE_HTML_HEAD_STRING` at build time. + No default value. + +$site_header:: + Name of a file with HTML to be included at the top of each page. + Relative to the directory containing the 'gitweb.cgi' script. + Can be set using `GITWEB_SITE_HEADER` at build time. No default + value. + +$site_footer:: + Name of a file with HTML to be included at the bottom of each page. + Relative to the directory containing the 'gitweb.cgi' script. + Can be set using `GITWEB_SITE_FOOTER` at build time. No default + value. + +$home_text:: + Name of a HTML file which, if it exists, is included on the + gitweb projects overview page ("projects_list" view). Relative to + the directory containing the gitweb.cgi script. Default value + can be adjusted during build time using `GITWEB_HOMETEXT` variable. + By default set to 'indextext.html'. + +$projects_list_description_width:: + The width (in characters) of the "Description" column of the projects list. + Longer descriptions will be truncated (trying to cut at word boundary); + the full description is available in the 'title' attribute (usually shown on + mouseover). The default is 25, which might be too small if you + use long project descriptions. + +$default_projects_order:: + Default value of ordering of projects on projects list page, which + means the ordering used if you don't explicitly sort projects list + (if there is no "o" CGI query parameter in the URL). Valid values + are "none" (unsorted), "project" (projects are by project name, + i.e. path to repository relative to `$projectroot`), "descr" + (project description), "owner", and "age" (by date of most current + commit). ++ +Default value is "project". Unknown value means unsorted. + + +Changing gitweb's behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~ +These configuration variables control _internal_ gitweb behavior. + +$default_blob_plain_mimetype:: + Default mimetype for the blob_plain (raw) view, if mimetype checking + doesn't result in some other type; by default "text/plain". + Gitweb guesses mimetype of a file to display based on extension + of its filename, using `$mimetypes_file` (if set and file exists) + and '/etc/mime.types' files (see *mime.types*(5) manpage; only + filename extension rules are supported by gitweb). + +$default_text_plain_charset:: + Default charset for text files. If this is not set, the web server + configuration will be used. Unset by default. + +$fallback_encoding:: + Gitweb assumes this charset when a line contains non-UTF-8 characters. + The fallback decoding is used without error checking, so it can be even + "utf-8". The value must be a valid encoding; see the *Encoding::Supported*(3pm) + man page for a list. The default is "latin1", aka. "iso-8859-1". + +@diff_opts:: + Rename detection options for git-diff and git-diff-tree. The default is + (\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies, + or set it to () i.e. empty list if you don't want to have renames + detection. ++ +*Note* that rename and especially copy detection can be quite +CPU-intensive. Note also that non git tools can have problems with +patches generated with options mentioned above, especially when they +involve file copies (\'-C') or criss-cross renames (\'-B'). + + +Some optional features and policies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Most of features are configured via `%feature` hash; however some of extra +gitweb features can be turned on and configured using variables described +below. This list beside configuration variables that control how gitweb +looks does contain variables configuring administrative side of gitweb +(e.g. cross-site scripting prevention; admittedly this as side effect +affects how "summary" pages look like, or load limiting). + +@git_base_url_list:: + List of git base URLs. These URLs are used to generate URLs + describing from where to fetch a project, which are shown on + project summary page. The full fetch URL is "`$git_base_url/$project`", + for each element of this list. You can set up multiple base URLs + (for example one for `git://` protocol, and one for `http://` + protocol). ++ +Note that per repository configuration can be set in '$GIT_DIR/cloneurl' +file, or as values of multi-value `gitweb.url` configuration variable in +project config. Per-repository configuration takes precedence over value +composed from `@git_base_url_list` elements and project name. ++ +You can setup one single value (single entry/item in this list) at build +time by setting the `GITWEB_BASE_URL` built-time configuration variable. +By default it is set to (), i.e. an empty list. This means that gitweb +would not try to create project URL (to fetch) from project name. + +$projects_list_group_categories:: + Whether to enables the grouping of projects by category on the project + list page. The category of a project is determined by the + `$GIT_DIR/category` file or the `gitweb.category` variable in each + repository's configuration. Disabled by default (set to 0). + +$project_list_default_category:: + Default category for projects for which none is specified. If this is + set to the empty string, such projects will remain uncategorized and + listed at the top, above categorized projects. Used only if project + categories are enabled, which means if `$projects_list_group_categories` + is true. By default set to "" (empty string). + +$prevent_xss:: + If true, some gitweb features are disabled to prevent content in + repositories from launching cross-site scripting (XSS) attacks. Set this + to true if you don't trust the content of your repositories. + False by default (set to 0). + +$maxload:: + Used to set the maximum load that we will still respond to gitweb queries. + If the server load exceeds this value then gitweb will return + "503 Service Unavailable" error. The server load is taken to be 0 + if gitweb cannot determine its value. Currently it works only on Linux, + where it uses '/proc/loadavg'; the load there is the number of active + tasks on the system -- processes that are actually running -- averaged + over the last minute. ++ +Set `$maxload` to undefined value (`undef`) to turn this feature off. +The default value is 300. + +$per_request_config:: + If this is set to code reference, it will be run once for each request. + You can set parts of configuration that change per session this way. + For example, one might use the following code in a gitweb configuration + file ++ +-------------------------------------------------------------------------------- +our $per_request_config = sub { + $ENV{GL_USER} = $cgi->remote_user || "gitweb"; +}; +-------------------------------------------------------------------------------- ++ +If `$per_request_config` is not a code reference, it is interpreted as boolean +value. If it is true gitweb will process config files once per request, +and if it is false gitweb will process config files only once, each time it +is executed. True by default (set to 1). ++ +*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default +values before every request, so if you want to change them, be sure to set +this variable to true or a code reference effecting the desired changes. ++ +This variable matters only when using persistent web environments that +serve multiple requests using single gitweb instance, like mod_perl, +FastCGI or Plackup. + + +Other variables +~~~~~~~~~~~~~~~ +Usually you should not need to change (adjust) any of configuration +variables described below; they should be automatically set by gitweb to +correct value. + + +$version:: + Gitweb version, set automatically when creating gitweb.cgi from + gitweb.perl. You might want to modify it if you are running modified + gitweb, for example ++ +--------------------------------------------------- +our $version .= " with caching"; +--------------------------------------------------- ++ +if you run modified version of gitweb with caching support. This variable +is purely informational, used e.g. in the "generator" meta header in HTML +header. + +$my_url:: +$my_uri:: + Full URL and absolute URL of the gitweb script; + in earlier versions of gitweb you might have need to set those + variables, but now there should be no need to do it. See + `$per_request_config` if you need to set them still. + +$base_url:: + Base URL for relative URLs in pages generated by gitweb, + (e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs), + needed and used '<base href="$base_url">' only for URLs with nonempty + PATH_INFO. Usually gitweb sets its value correctly, + and there is no need to set this variable, e.g. to $my_uri or "/". + See `$per_request_config` if you need to override it anyway. + + +CONFIGURING GITWEB FEATURES +--------------------------- +Many gitweb features can be enabled (or disabled) and configured using the +`%feature` hash. Names of gitweb features are keys of this hash. + +Each `%feature` hash element is a hash reference and has the following +structure: +---------------------------------------------------------------------- +"<feature_name>" => { + "sub" => <feature-sub (subroutine)>, + "override" => <allow-override (boolean)>, + "default" => [ <options>... ] +}, +---------------------------------------------------------------------- +Some features cannot be overridden per project. For those +features the structure of appropriate `%feature` hash element has a simpler +form: +---------------------------------------------------------------------- +"<feature_name>" => { + "override" => 0, + "default" => [ <options>... ] +}, +---------------------------------------------------------------------- +As one can see it lacks the \'sub' element. + +The meaning of each part of feature configuration is described +below: + +default:: + List (array reference) of feature parameters (if there are any), + used also to toggle (enable or disable) given feature. ++ +Note that it is currently *always* an array reference, even if +feature doesn't accept any configuration parameters, and \'default' +is used only to turn it on or off. In such case you turn feature on +by setting this element to `[1]`, and torn it off by setting it to +`[0]`. See also the passage about the "blame" feature in the "Examples" +section. ++ +To disable features that accept parameters (are configurable), you +need to set this element to empty list i.e. `[]`. + +override:: + If this field has a true value then the given feature is + overriddable, which means that it can be configured + (or enabled/disabled) on a per-repository basis. ++ +Usually given "<feature>" is configurable via the `gitweb.<feature>` +config variable in the per-repository git configuration file. ++ +*Note* that no feature is overriddable by default. + +sub:: + Internal detail of implementation. What is important is that + if this field is not present then per-repository override for + given feature is not supported. ++ +You wouldn't need to ever change it in gitweb config file. + + +Features in `%feature` +~~~~~~~~~~~~~~~~~~~~~~ +The gitweb features that are configurable via `%feature` hash are listed +below. This should be a complete list, but ultimately the authoritative +and complete list is in gitweb.cgi source code, with features described +in the comments. + +blame:: + Enable the "blame" and "blame_incremental" blob views, showing for + each line the last commit that modified it; see linkgit:git-blame[1]. + This can be very CPU-intensive and is therefore disabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.blame` configuration variable (boolean). + +snapshot:: + Enable and configure the "snapshot" action, which allows user to + download a compressed archive of any tree or commit, as produced + by linkgit:git-archive[1] and possibly additionally compressed. + This can potentially generate high traffic if you have large project. ++ +The value of \'default' is a list of names of snapshot formats, +defined in `%known_snapshot_formats` hash, that you wish to offer. +Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz +compressed tar archive) and "zip"; please consult gitweb sources for +a definitive list. By default only "tgz" is offered. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.blame` configuration variable, which contains +a comma separated list of formats or "none" to disable snapshots. +Unknown values are ignored. + +grep:: + Enable grep search, which lists the files in currently selected + tree (directory) containing the given string; see linkgit:git-grep[1]. + This can be potentially CPU-intensive, of course. Enabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.grep` configuration variable (boolean). + +pickaxe:: + Enable the so called pickaxe search, which will list the commits + that introduced or removed a given string in a file. This can be + practical and quite faster alternative to "blame" action, but it is + still potentially CPU-intensive. Enabled by default. ++ +The pickaxe search is described in linkgit:git-log[1] (the +description of `-S<string>` option, which refers to pickaxe entry in +linkgit:gitdiffcore[7] for more details). ++ +This feature can be configured on a per-repository basis by setting +repository's `gitweb.pickaxe` configuration variable (boolean). + +show-sizes:: + Enable showing size of blobs (ordinary files) in a "tree" view, in a + separate column, similar to what `ls -l` does; see description of + `-l` option in linkgit:git-ls-tree[1] manpage. This costs a bit of + I/O. Enabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.showsizes` configuration variable (boolean). + +patches:: + Enable and configure "patches" view, which displays list of commits in email + (plain text) output format; see also linkgit:git-format-patch[1]. + The value is the maximum number of patches in a patchset generated + in "patches" view. Set the 'default' field to a list containing single + item of or to an empty list to disable patch view, or to a list + containing a single negative number to remove any limit. + Default value is 16. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.patches` configuration variable (integer). + +avatar:: + Avatar support. When this feature is enabled, views such as + "shortlog" or "commit" will display an avatar associated with + the email of each committer and author. ++ +Currently available providers are *"gravatar"* and *"picon"*. +Only one provider at a time can be selected ('default' is one element list). +If an unknown provider is specified, the feature is disabled. +*Note* that some providers might require extra Perl packages to be +installed; see 'gitweb/INSTALL' for more details. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.avatar` configuration variable. ++ +See also `%avatar_size` with pixel sizes for icons and avatars +("default" is used for one-line like "log" and "shortlog", "double" +is used for two-line like "commit", "commitdiff" or "tag"). If the +default font sizes or lineheights are changed (e.g. via adding extra +CSS stylesheet in `@stylesheets`), it may be appropriate to change +these values. + +highlight:: + Server-side syntax highlight support in "blob" view. It requires + `$highlight_bin` program to be available (see the description of + this variable in the "Configuration variables" section above), + and therefore is disabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.highlight` configuration variable (boolean). + +remote_heads:: + Enable displaying remote heads (remote-tracking branches) in the "heads" + list. In most cases the list of remote-tracking branches is an + unnecessary internal private detail, and this feature is therefore + disabled by default. linkgit:git-instaweb[1], which is usually used + to browse local repositories, enables and uses this feature. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.remote_heads` configuration variable (boolean). + + +The remaining features cannot be overridden on a per project basis. + +search:: + Enable text search, which will list the commits which match author, + committer or commit text to a given string; see the description of + `--author`, `--committer` and `--grep` options in linkgit:git-log[1] + manpage. Enabled by default. ++ +Project specific override is not supported. + +forks:: + If this feature is enabled, gitweb considers projects in + subdirectories of project root (basename) to be forks of existing + projects. For each project `$projname.git`, projects in the + `$projname/` directory and its subdirectories will not be + shown in the main projects list. Instead, a \'+' mark is shown + next to `$projname`, which links to a "forks" view that lists all + the forks (all projects in `$projname/` subdirectory). Additionally + a "forks" view for a project is linked from project summary page. ++ +If the project list is taken from a file (`$projects_list` points to a +file), forks are only recognized if they are listed after the main project +in that file. ++ +Project specific override is not supported. + +actions:: + Insert custom links to the action bar of all project pages. This + allows you to link to third-party scripts integrating into gitweb. ++ +The "default" value consists of a list of triplets in the form +`("<label>", "<link>", "<position>")` where "position" is the label +after which to insert the link, "link" is a format string where `%n` +expands to the project name, `%f` to the project path within the +filesystem (i.e. "$projectroot/$project"), `%h` to the current hash +(\'h' gitweb parameter) and `%b` to the current hash base +(\'hb' gitweb parameter); `%%` expands to \'%'. ++ +For example, at the time this page was written, the http://repo.or.cz[] +git hosting site set it to the following to enable graphical log +(using the third party tool *git-browser*): ++ +---------------------------------------------------------------------- +$feature{'actions'}{'default'} = + [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')]; +---------------------------------------------------------------------- ++ +This adds a link titled "graphiclog" after the "summary" link, leading to +`git-browser` script, passing `r=<project>` as a query parameter. ++ +Project specific override is not supported. + +timed:: + Enable displaying how much time and how many git commands it took to + generate and display each page in the page footer (at the bottom of + page). For example the footer might contain: "This page took 6.53325 + seconds and 13 git commands to generate." Disabled by default. ++ +Project specific override is not supported. + +javascript-timezone:: + Enable and configure the ability to change a common timezone for dates + in gitweb output via JavaScript. Dates in gitweb output include + authordate and committerdate in "commit", "commitdiff" and "log" + views, and taggerdate in "tag" view. Enabled by default. ++ +The value is a list of three values: a default timezone (for if the client +hasn't selected some other timezone and saved it in a cookie), a name of cookie +where to store selected timezone, and a CSS class used to mark up +dates for manipulation. If you want to turn this feature off, set "default" +to empty list: `[]`. ++ +Typical gitweb config files will only change starting (default) timezone, +and leave other elements at their default values: ++ +--------------------------------------------------------------------------- +$feature{'javascript-timezone'}{'default'}[0] = "utc"; +--------------------------------------------------------------------------- ++ +The example configuration presented here is guaranteed to be backwards +and forward compatible. ++ +Timezone values can be "local" (for local timezone that browser uses), "utc" +(what gitweb uses when JavaScript or this feature is disabled), or numerical +timezones in the form of "+/-HHMM", such as "+0200". ++ +Project specific override is not supported. + + +EXAMPLES +-------- + +To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and +"zip" snapshots), while allowing individual projects to turn them off, put +the following in your GITWEB_CONFIG file: + + $feature{'blame'}{'default'} = [1]; + $feature{'blame'}{'override'} = 1; + + $feature{'pickaxe'}{'default'} = [1]; + $feature{'pickaxe'}{'override'} = 1; + + $feature{'snapshot'}{'default'} = ['zip', 'tgz']; + $feature{'snapshot'}{'override'} = 1; + +If you allow overriding for the snapshot feature, you can specify which +snapshot formats are globally disabled. You can also add any command line +options you want (such as setting the compression level). For instance, you +can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by +adding the following lines to your gitweb configuration file: + + $known_snapshot_formats{'zip'}{'disabled'} = 1; + $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; + +ENVIRONMENT +----------- +The location of per-instance and system-wide configuration files can be +overridden using the following environment variables: + +GITWEB_CONFIG:: + Sets location of per-instance configuration file. +GITWEB_CONFIG_SYSTEM:: + Sets location of fallback system-wide configuration file. + This file is read only if per-instance one does not exist. +GITWEB_CONFIG_COMMON:: + Sets location of common system-wide configuration file. + + +FILES +----- +gitweb_config.perl:: + This is default name of per-instance configuration file. The + format of this file is described above. +/etc/gitweb.conf:: + This is default name of fallback system-wide configuration + file. This file is used only if per-instance configuration + variable is not found. +/etc/gitweb-common.conf:: + This is default name of common system-wide configuration + file. + + +SEE ALSO +-------- +linkgit:gitweb[1], linkgit:git-instaweb[1] + +'gitweb/README', 'gitweb/INSTALL' + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt new file mode 100644 index 0000000000..605a085326 --- /dev/null +++ b/Documentation/gitweb.txt @@ -0,0 +1,704 @@ +gitweb(1) +========= + +NAME +---- +gitweb - Git web interface (web frontend to Git repositories) + +SYNOPSIS +-------- +To get started with gitweb, run linkgit:git-instaweb[1] from a git repository. +This would configure and start your web server, and run web browser pointing to +gitweb. + + +DESCRIPTION +----------- +Gitweb provides a web interface to git repositories. It's features include: + +* Viewing multiple Git repositories with common root. +* Browsing every revision of the repository. +* Viewing the contents of files in the repository at any revision. +* Viewing the revision log of branches, history of files and directories, + see what was changed when, by who. +* Viewing the blame/annotation details of any file (if enabled). +* Generating RSS and Atom feeds of commits, for any branch. + The feeds are auto-discoverable in modern web browsers. +* Viewing everything that was changed in a revision, and step through + revisions one at a time, viewing the history of the repository. +* Finding commits which commit messages matches given search term. + +See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or +http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, +browsed using gitweb itself. + + +CONFIGURATION +------------- +Various aspects of gitweb's behavior can be controlled through the configuration +file 'gitweb_config.perl' or '/etc/gitweb.conf'. See the linkgit:gitweb.conf[5] +for details. + +Repositories +~~~~~~~~~~~~ +Gitweb can show information from one or more Git repositories. These +repositories have to be all on local filesystem, and have to share common +repository root, i.e. be all under a single parent repository (but see also +"Advanced web server setup" section, "Webserver configuration with multiple +projects' root" subsection). + +----------------------------------------------------------------------- +our $projectroot = '/path/to/parent/directory'; +----------------------------------------------------------------------- + +The default value for `$projectroot` is '/pub/git'. You can change it during +building gitweb via `GITWEB_PROJECTROOT` build configuration variable. + +By default all git repositories under `$projectroot` are visible and available +to gitweb. The list of projects is generated by default by scanning the +`$projectroot` directory for git repositories (for object databases to be +more exact; gitweb is not interested in a working area, and is best suited +to showing "bare" repositories). + +The name of repository in gitweb is path to it's `$GIT_DIR` (it's object +database) relative to `$projectroot`. Therefore the repository $repo can be +found at "$projectroot/$repo". + + +Projects list file format +~~~~~~~~~~~~~~~~~~~~~~~~~ +Instead of having gitweb find repositories by scanning filesystem +starting from $projectroot, you can provide a pre-generated list of +visible projects by setting `$projects_list` to point to a plain text +file with a list of projects (with some additional info). + +This file uses the following format: + +* One record (for project / repository) per line; does not support line +continuation (newline escaping). + +* Leading and trailing whitespace are ignored. + +* Whitespace separated fields; any run of whitespace can be used as field +separator (rules for Perl's "`split(" ", $line)`"). + +* Fields use modified URI encoding, defined in RFC 3986, section 2.1 +(Percent-Encoding), or rather "Query string encoding" (see +link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference +being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be +also percent-encoded). ++ +Reserved characters are: "%" (used for encoding), "{plus}" (can be used to +encode SPACE), all whitespace characters as defined in Perl, including SP, +TAB and LF, (used to separate fields in a record). + +* Currently recognized fields are: +<repository path>:: + path to repository GIT_DIR, relative to `$projectroot` +<repository owner>:: + displayed as repository owner, preferably full name, or email, + or both + +You can generate the projects list index file using the project_index action +(the 'TXT' link on projects list page) directly from gitweb; see also +"Generating projects list using gitweb" section below. + +Example contents: +----------------------------------------------------------------------- +foo.git Joe+R+Hacker+<joe@example.com> +foo/bar.git O+W+Ner+<owner@example.org> +----------------------------------------------------------------------- + + +By default this file controls only which projects are *visible* on projects +list page (note that entries that do not point to correctly recognized git +repositories won't be displayed by gitweb). Even if a project is not +visible on projects list page, you can view it nevertheless by hand-crafting +a gitweb URL. By setting `$strict_export` configuration variable (see +linkgit:gitweb.conf[5]) to true value you can allow viewing only of +repositories also shown on the overview page (i.e. only projects explicitly +listed in projects list file will be accessible). + + +Generating projects list using gitweb +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We assume that GITWEB_CONFIG has its default Makefile value, namely +'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file: +---------------------------------------------------------------------------- +read_config_file("gitweb_config.perl"); +$projects_list = $projectroot; +---------------------------------------------------------------------------- + +Then create the following script to get list of project in the format +suitable for GITWEB_LIST build configuration variable (or +`$projects_list` variable in gitweb config): + +---------------------------------------------------------------------------- +#!/bin/sh + +export GITWEB_CONFIG="gitweb_make_index.perl" +export GATEWAY_INTERFACE="CGI/1.1" +export HTTP_ACCEPT="*/*" +export REQUEST_METHOD="GET" +export QUERY_STRING="a=project_index" + +perl -- /var/www/cgi-bin/gitweb.cgi +---------------------------------------------------------------------------- + +Run this script and save its output to a file. This file could then be used +as projects list file, which means that you can set `$projects_list` to its +filename. + + +Controlling access to git repositories +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default all git repositories under `$projectroot` are visible and +available to gitweb. You can however configure how gitweb controls access +to repositories. + +* As described in "Projects list file format" section, you can control which +projects are *visible* by selectively including repositories in projects +list file, and setting `$projects_list` gitweb configuration variable to +point to it. With `$strict_export` set, projects list file can be used to +control which repositories are *available* as well. + +* You can configure gitweb to only list and allow viewing of the explicitly +exported repositories, via `$export_ok` variable in gitweb config file; see +linkgit:gitweb.conf[5] manpage. If it evaluates to true, gitweb shows +repositories only if this file named by `$export_ok` exists in its object +database (if directory has the magic file named `$export_ok`). ++ +For example linkgit:git-daemon[1] by default (unless `--export-all` option +is used) allows pulling only for those repositories that have +'git-daemon-export-ok' file. Adding ++ +-------------------------------------------------------------------------- +our $export_ok = "git-daemon-export-ok"; +-------------------------------------------------------------------------- ++ +makes gitweb show and allow access only to those repositories that can be +fetched from via `git://` protocol. + +* Finally, it is possible to specify an arbitrary perl subroutine that will +be called for each repository to determine if it can be exported. The +subroutine receives an absolute path to the project (repository) as its only +parameter (i.e. "$projectroot/$project"). ++ +For example, if you use mod_perl to run the script, and have dumb +HTTP protocol authentication configured for your repositories, you +can use the following hook to allow access only if the user is +authorized to read the files: ++ +-------------------------------------------------------------------------- +$export_auth_hook = sub { + use Apache2::SubRequest (); + use Apache2::Const -compile => qw(HTTP_OK); + my $path = "$_[0]/HEAD"; + my $r = Apache2::RequestUtil->request; + my $sub = $r->lookup_file($path); + return $sub->filename eq $path + && $sub->status == Apache2::Const::HTTP_OK; +}; +-------------------------------------------------------------------------- + + +Per-repository gitweb configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can configure individual repositories shown in gitweb by creating file +in the 'GIT_DIR' of git repository, or by setting some repo configuration +variable (in 'GIT_DIR/config', see linkgit:git-config[1]). + +You can use the following files in repository: + +README.html:: + A html file (HTML fragment) which is included on the gitweb project + "summary" page inside `<div>` block element. You can use it for longer + description of a project, to provide links (for example to project's + homepage), etc. This is recognized only if XSS prevention is off + (`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include + a README safely when XSS prevention is on may be worked out in the + future. + +description (or `gitweb.description`):: + Short (shortened to `$projects_list_description_width` in the projects + list page, which is 25 characters by default; see + linkgit:gitweb.conf[5]) single line description of a project (of a + repository). Plain text file; HTML will be escaped. By default set to ++ +------------------------------------------------------------------------------- +Unnamed repository; edit this file to name it for gitweb. +------------------------------------------------------------------------------- ++ +from the template during repository creation, usually installed in +'/usr/share/git-core/templates/'. You can use the `gitweb.description` repo +configuration variable, but the file takes precedence. + +category (or `gitweb.category`):: + Singe line category of a project, used to group projects if + `$projects_list_group_categories` is enabled. By default (file and + configuration variable absent), uncategorized projects are put in the + `$project_list_default_category` category. You can use the + `gitweb.category` repo configuration variable, but the file takes + precedence. ++ +The configuration variables `$projects_list_group_categories` and +`$project_list_default_category` are described in linkgit:gitweb.conf[5] + +cloneurl (or multiple-valued `gitweb.url`):: + File with repository URL (used for clone and fetch), one per line. + Displayed in the project summary page. You can use multiple-valued + `gitweb.url` repository configuration variable for that, but the file + takes precedence. ++ +This is per-repository enhancement / version of global prefix-based +`@git_base_url_list` gitweb configuration variable (see +linkgit:gitweb.conf[5]). + +gitweb.owner:: + You can use the `gitweb.owner` repository configuration variable to set + repository's owner. It is displayed in the project list and summary + page. ++ +If it's not set, filesystem directory's owner is used (via GECOS field, +i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset +(gitweb scans `$projectroot` for repositories); if `$projects_list` +points to file with list of repositories, then project owner defaults to +value from this file for given repository. + +various `gitweb.*` config variables (in config):: + Read description of `%feature` hash for detailed list, and descriptions. + See also "Configuring gitweb features" section in linkgit:gitweb.conf[5] + + +ACTIONS, AND URLS +----------------- +Gitweb can use path_info (component) based URLs, or it can pass all necessary +information via query parameters. The typical gitweb URLs are broken down in to +five components: + +----------------------------------------------------------------------- +.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments> +----------------------------------------------------------------------- + +repo:: + The repository the action will be performed on. ++ +All actions except for those that list all available projects, +in whatever form, require this parameter. + +action:: + The action that will be run. Defaults to 'projects_list' if repo + is not set, and to 'summary' otherwise. + +revision:: + Revision shown. Defaults to HEAD. + +path:: + The path within the <repository> that the action is performed on, + for those actions that require it. + +arguments:: + Any arguments that control the behaviour of the action. + +Some actions require or allow to specify two revisions, and sometimes even two +pathnames. In most general form such path_info (component) based gitweb URL +looks like this: + +----------------------------------------------------------------------- +.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments> +----------------------------------------------------------------------- + + +Each action is implemented as a subroutine, and must be present in %actions +hash. Some actions are disabled by default, and must be turned on via feature +mechanism. For example to enable 'blame' view add the following to gitweb +configuration file: + +----------------------------------------------------------------------- +$feature{'blame'}{'default'} = [1]; +----------------------------------------------------------------------- + + +Actions: +~~~~~~~~ +The standard actions are: + +project_list:: + Lists the available Git repositories. This is the default command if no + repository is specified in the URL. + +summary:: + Displays summary about given repository. This is the default command if + no action is specified in URL, and only repository is specified. + +heads:: +remotes:: + Lists all local or all remote-tracking branches in given repository. ++ +The latter is not available by default, unless configured. + +tags:: + List all tags (lightweight and annotated) in given repository. + +blob:: +tree:: + Shows the files and directories in a given repository path, at given + revision. This is default command if no action is specified in the URL, + and path is given. + +blob_plain:: + Returns the raw data for the file in given repository, at given path and + revision. Links to this action are marked 'raw'. + +blobdiff:: + Shows the difference between two revisions of the same file. + +blame:: +blame_incremental:: + Shows the blame (also called annotation) information for a file. On a + per line basis it shows the revision in which that line was last changed + and the user that committed the change. The incremental version (which + if configured is used automatically when JavaScript is enabled) uses + Ajax to incrementally add blame info to the contents of given file. ++ +This action is disabled by default for performance reasons. + +commit:: +commitdiff:: + Shows information about a specific commit in a repository. The 'commit' + view shows information about commit in more detail, the 'commitdiff' + action shows changeset for given commit. + +patch:: + Returns the commit in plain text mail format, suitable for applying with + linkgit:git-am[1]. + +tag:: + Display specific annotated tag (tag object). + +log:: +shortlog:: + Shows log information (commit message or just commit subject) for a + given branch (starting from given revision). ++ +The 'shortlog' view is more compact; it shows one commit per line. + +history:: + Shows history of the file or directory in a given repository path, + starting from given revision (defaults to HEAD, i.e. default branch). ++ +This view is similar to 'shortlog' view. + +rss:: +atom:: + Generates an RSS (or Atom) feed of changes to repository. + + +WEBSERVER CONFIGURATION +----------------------- +This section explains how to configure some common webservers to run gitweb. In +all cases, `/path/to/gitweb` in the examples is the directory you ran installed +gitweb in, and contains `gitweb_config.perl`. + +If you've configured a web server that isn't listed here for gitweb, please send +in the instructions so they can be included in a future release. + +Apache as CGI +~~~~~~~~~~~~~ +Apache must be configured to support CGI scripts in the directory in +which gitweb is installed. Let's assume that it is '/var/www/cgi-bin' +directory. + +----------------------------------------------------------------------- +ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" + +<Directory "/var/www/cgi-bin"> + Options Indexes FollowSymlinks ExecCGI + AllowOverride None + Order allow,deny + Allow from all +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/cgi-bin/gitweb.cgi + +Apache with mod_perl, via ModPerl::Registry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can use mod_perl with gitweb. You must install Apache::Registry +(for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable +this support. + +Assuming that gitweb is installed to '/var/www/perl', the following +Apache configuration (for mod_perl 2.x) is suitable. + +----------------------------------------------------------------------- +Alias /perl "/var/www/perl" + +<Directory "/var/www/perl"> + SetHandler perl-script + PerlResponseHandler ModPerl::Registry + PerlOptions +ParseHeaders + Options Indexes FollowSymlinks +ExecCGI + AllowOverride None + Order allow,deny + Allow from all +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/perl/gitweb.cgi + +Apache with FastCGI +~~~~~~~~~~~~~~~~~~~ +Gitweb works with Apache and FastCGI. First you need to rename, copy +or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is +installed in '/usr/share/gitweb' directory. The following Apache +configuration is suitable (UNTESTED!) + +----------------------------------------------------------------------- +FastCgiServer /usr/share/gitweb/gitweb.cgi +ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi + +Alias /gitweb/static /usr/share/gitweb/static +<Directory /usr/share/gitweb/static> + SetHandler default-handler +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/gitweb + + +ADVANCED WEB SERVER SETUP +------------------------- +All of those examples use request rewriting, and need `mod_rewrite` +(or equivalent; examples below are written for Apache). + +Single URL for gitweb and for fetching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you want to have one URL for both gitweb and your `http://` +repositories, you can configure Apache like this: + +----------------------------------------------------------------------- +<VirtualHost *:80> + ServerName git.example.org + DocumentRoot /pub/git + SetEnv GITWEB_CONFIG /etc/gitweb.conf + + # turning on mod rewrite + RewriteEngine on + + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi + + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ + /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] +</VirtualHost> +----------------------------------------------------------------------- + +The above configuration expects your public repositories to live under +'/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`, +both as cloneable GIT URL and as browseable gitweb interface. If you then +start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` +then you can even use the `git://` URL with exactly the same path. + +Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the +named file (i.e. in this example '/etc/gitweb.conf') as a configuration for +gitweb. You don't really need it in above example; it is required only if +your configuration file is in different place than built-in (during +compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'. See +linkgit:gitweb.conf[5] for details, especially information about precedence +rules. + +If you use the rewrite rules from the example you *might* also need +something like the following in your gitweb configuration file +('/etc/gitweb.conf' following example): +---------------------------------------------------------------------------- +@stylesheets = ("/some/absolute/path/gitweb.css"); +$my_uri = "/"; +$home_link = "/"; +$per_request_config = 1; +---------------------------------------------------------------------------- +Nowadays though gitweb should create HTML base tag when needed (to set base +URI for relative links), so it should work automatically. + + +Webserver configuration with multiple projects' root +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you want to use gitweb with several project roots you can edit your +Apache virtual host and gitweb configuration files in the following way. + +The virtual host configuration (in Apache configuration file) should look +like this: +-------------------------------------------------------------------------- +<VirtualHost *:80> + ServerName git.example.org + DocumentRoot /pub/git + SetEnv GITWEB_CONFIG /etc/gitweb.conf + + # turning on mod rewrite + RewriteEngine on + + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT] + + # look for a public_git folder in unix users' home + # http://git.example.org/~<user>/ + RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # http://git.example.org/+<user>/ + #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # http://git.example.org/user/<user>/ + #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # defined list of project roots + RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT] + RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT] + + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ + /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] +</VirtualHost> +-------------------------------------------------------------------------- + +Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT` +environment variable from a web server, so you need to put the following +line in gitweb configuration file ('/etc/gitweb.conf' in above example): +-------------------------------------------------------------------------- +$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; +-------------------------------------------------------------------------- +*Note* that this requires to be set for each request, so either +`$per_request_config` must be false, or the above must be put in code +referenced by `$per_request_config`; + +These configurations enable two things. First, each unix user (`<user>`) of +the server will be able to browse through gitweb git repositories found in +'~/public_git/' with the following url: + + http://git.example.org/~<user>/ + +If you do not want this feature on your server just remove the second +rewrite rule. + +If you already use `mod_userdir` in your virtual host or you don't want to +use the \'~' as first character, just comment or remove the second rewrite +rule, and uncomment one of the following according to what you want. + +Second, repositories found in '/pub/scm/' and '/var/git/' will be accessible +through `http://git.example.org/scm/` and `http://git.example.org/var/`. +You can add as many project roots as you want by adding rewrite rules like +the third and the fourth. + + +PATH_INFO usage +~~~~~~~~~~~~~~~ +If you enable PATH_INFO usage in gitweb by putting +---------------------------------------------------------------------------- +$feature{'pathinfo'}{'default'} = [1]; +---------------------------------------------------------------------------- +in your gitweb configuration file, it is possible to set up your server so +that it consumes and produces URLs in the form + + http://git.example.com/project.git/shortlog/sometag + +i.e. without 'gitweb.cgi' part, by using a configuration such as the +following. This configuration assumes that '/var/www/gitweb' is the +DocumentRoot of your webserver, contains the gitweb.cgi script and +complementary static files (stylesheet, favicon, JavaScript): + +---------------------------------------------------------------------------- +<VirtualHost *:80> + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + <Directory /var/www/gitweb> + Options ExecCGI + AddHandler cgi-script cgi + + DirectoryIndex gitweb.cgi + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^.* /gitweb.cgi/$0 [L,PT] + </Directory> +</VirtualHost> +---------------------------------------------------------------------------- +The rewrite rule guarantees that existing static files will be properly +served, whereas any other URL will be passed to gitweb as PATH_INFO +parameter. + +*Notice* that in this case you don't need special settings for +`@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client" +access to your project .git dirs (described in "Single URL for gitweb and +for fetching" section). A possible workaround for the latter is the +following: in your project root dir (e.g. '/pub/git') have the projects +named *without* a .git extension (e.g. '/pub/git/project' instead of +'/pub/git/project.git') and configure Apache as follows: +---------------------------------------------------------------------------- +<VirtualHost *:80> + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3 + <Directory /var/www/gitweb> + Options ExecCGI + AddHandler cgi-script cgi + + DirectoryIndex gitweb.cgi + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^.* /gitweb.cgi/$0 [L,PT] + </Directory> +</VirtualHost> +---------------------------------------------------------------------------- + +The additional AliasMatch makes it so that + + http://git.example.com/project.git + +will give raw access to the project's git dir (so that the project can be +cloned), while + + http://git.example.com/project + +will provide human-friendly gitweb access. + +This solution is not 100% bulletproof, in the sense that if some project has +a named ref (branch, tag) starting with 'git/', then paths such as + + http://git.example.com/project/command/abranch..git/abranch + +will fail with a 404 error. + + +BUGS +---- +Please report any bugs or feature requests to git@vger.kernel.org, +putting "gitweb" in the subject of email. + +SEE ALSO +-------- +linkgit:gitweb.conf[5], linkgit:git-instaweb[1] + +'gitweb/README', 'gitweb/INSTALL' + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 1ef55fffcf..5e4f362ff8 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -7,6 +7,7 @@ gitworkflows - An overview of recommended workflows with git SYNOPSIS -------- +[verse] git * diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 33716a31d0..3595b586bc 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -161,8 +161,8 @@ to point at the new commit. [[def_head]]head:: A <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a - <<def_branch,branch>>. Heads are stored in - `$GIT_DIR/refs/heads/`, except when using packed refs. (See + <<def_branch,branch>>. Heads are stored in a file in + `$GIT_DIR/refs/heads/` directory, except when using packed refs. (See linkgit:git-pack-refs[1].) [[def_HEAD]]HEAD:: @@ -170,8 +170,8 @@ to point at the new commit. working tree>> is normally derived from the state of the tree referred to by HEAD. HEAD is a reference to one of the <<def_head,heads>> in your repository, except when using a - <<def_detached_HEAD,detached HEAD>>, in which case it may - reference an arbitrary commit. + <<def_detached_HEAD,detached HEAD>>, in which case it directly + references an arbitrary commit. [[def_head_ref]]head ref:: A synonym for <<def_head,head>>. @@ -277,7 +277,8 @@ This commit is referred to as a "merge commit", or sometimes just a Pattern used to specify paths. + Pathspecs are used on the command line of "git ls-files", "git -ls-tree", "git grep", "git checkout", and many other commands to +ls-tree", "git add", "git grep", "git diff", "git checkout", +and many other commands to limit the scope of operations to some subset of the tree or worktree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The @@ -296,6 +297,37 @@ For example, Documentation/*.jpg will match all .jpg files in the Documentation subtree, including Documentation/chapter_1/figure_1.jpg. ++ +A pathspec that begins with a colon `:` has special meaning. In the +short form, the leading colon `:` is followed by zero or more "magic +signature" letters (which optionally is terminated by another colon `:`), +and the remainder is the pattern to match against the path. The optional +colon that terminates the "magic signature" can be omitted if the pattern +begins with a character that cannot be a "magic signature" and is not a +colon. ++ +In the long form, the leading colon `:` is followed by a open +parenthesis `(`, a comma-separated list of zero or more "magic words", +and a close parentheses `)`, and the remainder is the pattern to match +against the path. ++ +The "magic signature" consists of an ASCII symbol that is not +alphanumeric. ++ +-- +top `/`;; + The magic word `top` (mnemonic: `/`) makes the pattern match + from the root of the working tree, even when you are running + the command from inside a subdirectory. +-- ++ +Currently only the slash `/` is recognized as the "magic signature", +but it is envisioned that we will support more types of magic in later +versions of git. ++ +A pathspec with only a colon means "there is no pathspec". This form +should not be combined with other pathspec. + [[def_parent]]parent:: A <<def_commit_object,commit object>> contains a (possibly empty) list of the logical predecessor(s) in the line of development, i.e. its @@ -350,8 +382,9 @@ including Documentation/chapter_1/figure_1.jpg. [[def_ref]]ref:: A 40-byte hex representation of a <<def_SHA1,SHA1>> or a name that - denotes a particular <<def_object,object>>. These may be stored in - `$GIT_DIR/refs/`. + denotes a particular <<def_object,object>>. They may be stored in + a file under `$GIT_DIR/refs/` directory, or + in the `$GIT_DIR/packed-refs` file. [[def_reflog]]reflog:: A reflog shows the local "history" of a ref. In other words, @@ -427,14 +460,14 @@ including Documentation/chapter_1/figure_1.jpg. command. [[def_tag]]tag:: - A <<def_ref,ref>> pointing to a <<def_tag_object,tag>> or - <<def_commit_object,commit object>>. In contrast to a <<def_head,head>>, - a tag is not changed by a <<def_commit,commit>>. Tags (not - <<def_tag_object,tag objects>>) are stored in `$GIT_DIR/refs/tags/`. A - git tag has nothing to do with a Lisp tag (which would be - called an <<def_object_type,object type>> in git's context). A - tag is most typically used to mark a particular point in the - commit ancestry <<def_chain,chain>>. + A <<def_ref,ref>> under `refs/tags/` namespace that points to an + object of an arbitrary type (typically a tag points to either a + <<def_tag_object,tag>> or a <<def_commit_object,commit object>>). + In contrast to a <<def_head,head>>, a tag is not updated by + the `commit` command. A git tag has nothing to do with a Lisp + tag (which would be called an <<def_object_type,object type>> + in git's context). A tag is most typically used to mark a particular + point in the commit ancestry <<def_chain,chain>>. [[def_tag_object]]tag object:: An <<def_object,object>> containing a <<def_ref,ref>> pointing to diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index d527b30770..8823a37067 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -176,7 +176,7 @@ by doing the following: - Update "What's cooking" message to review the updates to existing topics, newly added topics and graduated topics. - This step is helped with Meta/UWC script (where Meta/ contains + This step is helped with Meta/cook script (where Meta/ contains a checkout of the 'todo' branch). - Merge topics to 'next'. For each branch whose tip is not @@ -197,10 +197,9 @@ by doing the following: - Nothing is next-worthy; do not do anything. - - Rebase topics that do not have any commit in next yet. This - step is optional but sometimes is worth doing when an old - series that is not in next can take advantage of low-level - framework change that is merged to 'master' already. + - [** OBSOLETE **] Optionally rebase topics that do not have any commit + in next yet, when they can take advantage of low-level framework + change that is merged to 'master' already. $ git rebase master ai/topic @@ -209,7 +208,7 @@ by doing the following: pre-rebase hook to make sure that topics that are already in 'next' are not rebased beyond the merged commit. - - Rebuild "pu" to merge the tips of topics not in 'next'. + - [** OBSOLETE **] Rebuild "pu" to merge the tips of topics not in 'next'. $ git checkout pu $ git reset --hard next @@ -241,7 +240,7 @@ by doing the following: - Fetch html and man branches back from k.org, and push four integration branches and the two documentation branches to - repo.or.cz + repo.or.cz and other mirrors. Some observations to be made. diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt new file mode 100644 index 0000000000..a1351c5bb8 --- /dev/null +++ b/Documentation/howto/using-signed-tag-in-pull-request.txt @@ -0,0 +1,217 @@ +From: Junio C Hamano <gitster@pobox.com> +Date: Tue, 17 Jan 2011 13:00:00 -0800 +Subject: Using signed tag in pull requests +Abstract: Beginning v1.7.9, a contributor can push a signed tag to her + publishing repository and ask her integrator to pull it. This assures the + integrator that the pulled history is authentic and allows others to + later validate it. +Content-type: text/asciidoc + +Using signed tag in pull requests +================================= + +A typical distributed workflow using Git is for a contributor to fork a +project, build on it, publish the result to her public repository, and ask +the "upstream" person (often the owner of the project where she forked +from) to pull from her public repository. Requesting such a "pull" is made +easy by the `git request-pull` command. + +Earlier, a typical pull request may have started like this: + +------------ + The following changes since commit 406da78032179...: + + Froboz 3.2 (2011-09-30 14:20:57 -0700) + + are available in the git repository at: + + example.com:/git/froboz.git for-xyzzy +------------ + +followed by a shortlog of the changes and a diffstat. + +The request was for a branch name (e.g. `for-xyzzy`) in the public +repository of the contributor, and even though it stated where the +contributor forked her work from, the message did not say anything about +the commit to expect at the tip of the for-xyzzy branch. If the site that +hosts the public repository of the contributor cannot be fully trusted, it +was unnecessarily hard to make sure what was pulled by the integrator was +genuinely what the contributor had produced for the project. Also there +was no easy way for third-party auditors to later verify the resulting +history. + +Starting from Git release v1.7.9, a contributor can add a signed tag to +the commit at the tip of the history and ask the integrator to pull that +signed tag. When the integrator runs `git pull`, the signed tag is +automatically verified to assure that the history is not tampered with. +In addition, the resulting merge commit records the content of the signed +tag, so that other people can verify that the branch merged by the +integrator was signed by the contributor, without fetching the signed tag +used to validate the pull request separately and keeping it in the refs +namespace. + +This document describes the workflow between the contributor and the +integrator, using Git v1.7.9 or later. + + +A contributor or a lieutenant +----------------------------- + +After preparing her work to be pulled, the contributor uses `git tag -s` +to create a signed tag: + +------------ + $ git checkout work + $ ... "git pull" from sublieutenants, "git commit" your own work ... + $ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work +------------ + +Note that this example uses the `-m` option to create a signed tag with +just a one-liner message, but this is for illustration purposes only. It +is advisable to compose a well-written explanation of what the topic does +to justify why it is worthwhile for the integrator to pull it, as this +message will eventually become part of the final history after the +integrator responds to the pull request (as we will see later). + +Then she pushes the tag out to her public repository: + +------------ + $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy +------------ + +There is no need to push the `work` branch or anything else. + +Note that the above command line used a plus sign at the beginning of +`+frotz-for-xyzzy` to allow forcing the update of a tag, as the same +contributor may want to reuse a signed tag with the same name after the +previous pull request has already been responded to. + +The contributor then prepares a message to request a "pull": + +------------ + $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt +------------ + +The arguments are: + +. the version of the integrator's commit the contributor based her work on; +. the URL of the repository, to which the contributor has pushed what she + wants to get pulled; and +. the name of the tag the contributor wants to get pulled (earlier, she could + write only a branch name here). + +The resulting msg.txt file begins like so: + +------------ + The following changes since commit 406da78032179...: + + Froboz 3.2 (2011-09-30 14:20:57 -0700) + + are available in the git repository at: + + example.com:/git/froboz.git frotz-for-xyzzy + + for you to fetch changes up to 703f05ad5835c...: + + Add tests and documentation for frotz (2011-12-02 10:02:52 -0800) + + ----------------------------------------------- + Completed frotz feature + ----------------------------------------------- +------------ + +followed by a shortlog of the changes and a diffstat. Comparing this with +the earlier illustration of the output from the traditional `git request-pull` +command, the reader should notice that: + +. The tip commit to expect is shown to the integrator; and +. The signed tag message is shown prominently between the dashed lines + before the shortlog. + +The latter is why the contributor would want to justify why pulling her +work is worthwhile when creating the signed tag. The contributor then +opens her favorite MUA, reads msg.txt, edits and sends it to her upstream +integrator. + + +Integrator +---------- + +After receiving such a pull request message, the integrator fetches and +integrates the tag named in the request, with: + +------------ + $ git pull example.com:/git/froboz.git/ frotz-for-xyzzy +------------ + +This operation will always open an editor to allow the integrator to fine +tune the commit log message when merging a signed tag. Also, pulling a +signed tag will always create a merge commit even when the integrator does +not have any new commit since the contributor's work forked (i.e. 'fast +forward'), so that the integrator can properly explain what the merge is +about and why it was made. + +In the editor, the integrator will see something like this: + +------------ + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/ + + Completed frotz feature + # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB + # gpg: Good signature from "Con Tributor <nitfol@example.com>" +------------ + +Notice that the message recorded in the signed tag "Completed frotz +feature" appears here, and again that is why it is important for the +contributor to explain her work well when creating the signed tag. + +As usual, the lines commented with `#` are stripped out. The resulting +commit records the signed tag used for this validation in a hidden field +so that it can later be used by others to audit the history. There is no +need for the integrator to keep a separate copy of the tag in his +repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the +above example), and there is no need to publish the tag to his public +repository, either. + +After the integrator responds to the pull request and her work becomes +part of the permanent history, the contributor can remove the tag from +her public repository, if she chooses, in order to keep the tag namespace +of her public repository clean, with: + +------------ + $ git push example.com:/git/froboz.git :frotz-for-xyzzy +------------ + + +Auditors +-------- + +The `--show-signature` option can be given to `git log` or `git show` and +shows the verification status of the embedded signed tag in merge commits +created when the integrator responded to a pull request of a signed tag. + +A typical output from `git show --show-signature` may look like this: + +------------ + $ git show --show-signature + commit 02306ef6a3498a39118aef9df7975bdb50091585 + merged tag 'frotz-for-xyzzy' + gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB + gpg: Good signature from "Con Tributor <nitfol@example.com>" + Merge: 406da78 703f05a + Author: Inte Grator <xyzzy@example.com> + Date: Tue Jan 17 13:49:41 2012 -0800 + + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/ + + Completed frotz feature + + * tag 'frotz-for-xyzzy' (100 commits) + Add tests and documentation for frotz + ... +------------ + +There is no need for the auditor to explicitly fetch the contributor's +signature, or to even be aware of what tag(s) the contributor and integrator +used to communicate the signature. All the required information is recorded +as part of the merge commit. diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh index 35f440876e..327f69bcf5 100755 --- a/Documentation/install-doc-quick.sh +++ b/Documentation/install-doc-quick.sh @@ -1,31 +1,39 @@ #!/bin/sh -# This requires a branch named in $head -# (usually 'man' or 'html', provided by the git.git repository) -set -e -head="$1" -mandir="$2" -SUBDIRECTORY_OK=t -USAGE='<refname> <target directory>' -. "$(git --exec-path)"/git-sh-setup -cd_to_toplevel +# This requires git-manpages and/or git-htmldocs repositories -test -z "$mandir" && usage -if ! git rev-parse --verify "$head^0" >/dev/null; then - echo >&2 "head: $head does not exist in the current repository" - usage +repository=${1?repository} +destdir=${2?destination} + +head=master GIT_DIR= +for d in "$repository/.git" "$repository" +do + if GIT_DIR="$d" git rev-parse refs/heads/master >/dev/null 2>&1 + then + GIT_DIR="$d" + export GIT_DIR + break + fi +done + +if test -z "$GIT_DIR" +then + echo >&2 "Neither $repository nor $repository/.git is a repository" + exit 1 fi -GIT_INDEX_FILE=`pwd`/.quick-doc.index -export GIT_INDEX_FILE +GIT_WORK_TREE=$(pwd) +GIT_INDEX_FILE=$(pwd)/.quick-doc.$$ +export GIT_INDEX_FILE GIT_WORK_TREE rm -f "$GIT_INDEX_FILE" trap 'rm -f "$GIT_INDEX_FILE"' 0 git read-tree $head -git checkout-index -a -f --prefix="$mandir"/ +git checkout-index -a -f --prefix="$destdir"/ -if test -n "$GZ"; then +if test -n "$GZ" +then git ls-tree -r --name-only $head | - xargs printf "$mandir/%s\n" | + xargs printf "$destdir/%s\n" | xargs gzip -f fi rm -f "$GIT_INDEX_FILE" diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 8920258baa..861bd6f553 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -16,6 +16,16 @@ merge.defaultToUpstream:: to their corresponding remote tracking branches, and the tips of these tracking branches are merged. +merge.ff:: + By default, git does not create an extra merge commit when merging + a commit that is a descendant of the current commit. Instead, the + tip of the current branch is fast-forwarded. When set to `false`, + this variable tells git to create an extra merge commit in such + a case (equivalent to giving the `--no-ff` option from the command + line). When set to `only`, only such fast-forward merges are + allowed (equivalent to giving the `--ff-only` option from the + command line). + merge.log:: In addition to branch names, populate the log message with at most the specified number of one-line descriptions from the diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index b613d4ed08..1a5c12e317 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -7,6 +7,11 @@ With --no-commit perform the merge but pretend the merge failed and do not autocommit, to give the user a chance to inspect and further tweak the merge result before committing. +--edit:: +-e:: + Invoke editor before committing successful merge to further + edit the default merge message. + --ff:: --no-ff:: Do not generate a merge commit if the merge resolved as diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 561cc9f7d7..880b6f2e6f 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -132,6 +132,10 @@ The placeholders are: - '%N': commit notes - '%gD': reflog selector, e.g., `refs/stash@\{1\}` - '%gd': shortened reflog selector, e.g., `stash@\{1\}` +- '%gn': reflog identity name +- '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%ge': reflog identity email +- '%gE': reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%gs': reflog subject - '%Cred': switch color to red - '%Cgreen': switch color to green diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 50923e2ce9..2a3dc8664f 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -19,6 +19,11 @@ configuration (see linkgit:git-config[1]). This should make "--pretty=oneline" a whole lot more readable for people using 80-column terminals. +--no-abbrev-commit:: + Show the full 40-byte hexadecimal commit object name. This negates + `--abbrev-commit` and those options which imply it such as + "--oneline". It also overrides the 'log.abbrevCommit' variable. + --oneline:: This is a shorthand for "--pretty=oneline --abbrev-commit" used together. @@ -30,19 +35,34 @@ people using 80-column terminals. preferred by the user. For non plumbing commands this defaults to UTF-8. ---no-notes:: ---show-notes[=<ref>]:: +--notes[=<ref>]:: Show the notes (see linkgit:git-notes[1]) that annotate the commit, when showing the commit log message. This is the default for `git log`, `git show` and `git whatchanged` commands when - there is no `--pretty`, `--format` nor `--oneline` option is - given on the command line. + there is no `--pretty`, `--format` nor `--oneline` option given + on the command line. ++ +By default, the notes shown are from the notes refs listed in the +'core.notesRef' and 'notes.displayRef' variables (or corresponding +environment overrides). See linkgit:git-config[1] for more details. + -With an optional argument, add this ref to the list of notes. The ref -is taken to be in `refs/notes/` if it is not qualified. +With an optional '<ref>' argument, show this notes ref instead of the +default notes ref(s). The ref is taken to be in `refs/notes/` if it +is not qualified. ++ +Multiple --notes options can be combined to control which notes are +being displayed. Examples: "--notes=foo" will show only notes from +"refs/notes/foo"; "--notes=foo --notes" will show both notes from +"refs/notes/foo" and from the default notes ref(s). + +--no-notes:: + Do not show notes. This negates the above `--notes` option, by + resetting the list of notes refs from which notes are shown. + Options are parsed in the order given on the command line, so e.g. + "--notes --notes=foo --no-notes --notes=bar" will only show notes + from "refs/notes/bar". +--show-notes[=<ref>]:: --[no-]standard-notes:: - Enable or disable populating the notes ref list from the - 'core.notesRef' and 'notes.displayRef' variables (or - corresponding environment overrides). Enabled by default. - See linkgit:git-config[1]. + These options are deprecated. Use the above --notes/--no-notes + options instead. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 73111bb051..39e6207269 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -139,6 +139,10 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). is automatically prepended if missing. If pattern lacks '?', '*', or '[', '/*' at the end is implied. +--ignore-missing:: + + Upon seeing an invalid object name in the input, pretend as if + the bad input was not given. ifndef::git-rev-list[] --bisect:: @@ -268,7 +272,7 @@ Default mode:: --full-history:: - As the default mode but does not prune some history. + Same as the default mode, but does not prune some history. --dense:: @@ -309,7 +313,7 @@ that you are filtering for a file `foo` in this commit graph: \ / / / / `-------------' ----------------------------------------------------------------------- -The horizontal line of history A--P is taken to be the first parent of +The horizontal line of history A---P is taken to be the first parent of each merge. The commits are: * `I` is the initial commit, in which `foo` exists with contents @@ -730,7 +734,10 @@ ifdef::git-rev-list[] Print a number stating how many commits would have been listed, and suppress all other output. When used together with '--left-right', instead print the counts for left and - right commits, separated by a tab. + right commits, separated by a tab. When used together with + '--cherry-mark', omit patch equivalent commits from these + counts and print the count for equivalent commits separated + by a tab. endif::git-rev-list[] diff --git a/Documentation/sequencer.txt b/Documentation/sequencer.txt new file mode 100644 index 0000000000..5747f442f2 --- /dev/null +++ b/Documentation/sequencer.txt @@ -0,0 +1,12 @@ +--continue:: + Continue the operation in progress using the information in + '.git/sequencer'. Can be used to continue after resolving + conflicts in a failed cherry-pick or revert. + +--quit:: + Forget about the current operation in progress. Can be used + to clear the sequencer state after a failed cherry-pick or + revert. + +--abort:: + Cancel the operation and return to the pre-sequence state. diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt new file mode 100644 index 0000000000..49b3d52952 --- /dev/null +++ b/Documentation/technical/api-argv-array.txt @@ -0,0 +1,46 @@ +argv-array API +============== + +The argv-array API allows one to dynamically build and store +NULL-terminated lists. An argv-array maintains the invariant that the +`argv` member always points to a non-NULL array, and that the array is +always NULL-terminated at the element pointed to by `argv[argc]`. This +makes the result suitable for passing to functions expecting to receive +argv from main(), or the link:api-run-command.html[run-command API]. + +The link:api-string-list.html[string-list API] is similar, but cannot be +used for these purposes; instead of storing a straight string pointer, +it contains an item structure with a `util` field that is not compatible +with the traditional argv interface. + +Each `argv_array` manages its own memory. Any strings pushed into the +array are duplicated, and all memory is freed by argv_array_clear(). + +Data Structures +--------------- + +`struct argv_array`:: + + A single array. This should be initialized by assignment from + `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv` + member contains the actual array; the `argc` member contains the + number of elements in the array, not including the terminating + NULL. + +Functions +--------- + +`argv_array_init`:: + Initialize an array. This is no different than assigning from + `ARGV_ARRAY_INIT`. + +`argv_array_push`:: + Push a copy of a string onto the end of the array. + +`argv_array_pushf`:: + Format a string and push it onto the end of the array. This is a + convenience wrapper combining `strbuf_addf` and `argv_array_push`. + +`argv_array_clear`:: + Free all memory associated with the array and return it to the + initial, empty state. diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index 5cb2b0590a..b0cafe87be 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -49,6 +49,8 @@ Additionally, if `foo` is a new command, there are 3 more things to do: . Add an entry for `git-foo` to `command-list.txt`. +. Add an entry for `/git-foo` to `.gitignore`. + How a built-in is called ------------------------ diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt new file mode 100644 index 0000000000..21ca6a2553 --- /dev/null +++ b/Documentation/technical/api-credentials.txt @@ -0,0 +1,245 @@ +credentials API +=============== + +The credentials API provides an abstracted way of gathering username and +password credentials from the user (even though credentials in the wider +world can take many forms, in this document the word "credential" always +refers to a username and password pair). + +Data Structures +--------------- + +`struct credential`:: + + This struct represents a single username/password combination + along with any associated context. All string fields should be + heap-allocated (or NULL if they are not known or not applicable). + The meaning of the individual context fields is the same as + their counterparts in the helper protocol; see the section below + for a description of each field. ++ +The `helpers` member of the struct is a `string_list` of helpers. Each +string specifies an external helper which will be run, in order, to +either acquire or store credentials. See the section on credential +helpers below. ++ +This struct should always be initialized with `CREDENTIAL_INIT` or +`credential_init`. + + +Functions +--------- + +`credential_init`:: + + Initialize a credential structure, setting all fields to empty. + +`credential_clear`:: + + Free any resources associated with the credential structure, + returning it to a pristine initialized state. + +`credential_fill`:: + + Instruct the credential subsystem to fill the username and + password fields of the passed credential struct by first + consulting helpers, then asking the user. After this function + returns, the username and password fields of the credential are + guaranteed to be non-NULL. If an error occurs, the function will + die(). + +`credential_reject`:: + + Inform the credential subsystem that the provided credentials + have been rejected. This will cause the credential subsystem to + notify any helpers of the rejection (which allows them, for + example, to purge the invalid credentials from storage). It + will also free() the username and password fields of the + credential and set them to NULL (readying the credential for + another call to `credential_fill`). Any errors from helpers are + ignored. + +`credential_approve`:: + + Inform the credential subsystem that the provided credentials + were successfully used for authentication. This will cause the + credential subsystem to notify any helpers of the approval, so + that they may store the result to be used again. Any errors + from helpers are ignored. + +`credential_from_url`:: + + Parse a URL into broken-down credential fields. + +Example +------- + +The example below shows how the functions of the credential API could be +used to login to a fictitious "foo" service on a remote host: + +----------------------------------------------------------------------- +int foo_login(struct foo_connection *f) +{ + int status; + /* + * Create a credential with some context; we don't yet know the + * username or password. + */ + + struct credential c = CREDENTIAL_INIT; + c.protocol = xstrdup("foo"); + c.host = xstrdup(f->hostname); + + /* + * Fill in the username and password fields by contacting + * helpers and/or asking the user. The function will die if it + * fails. + */ + credential_fill(&c); + + /* + * Otherwise, we have a username and password. Try to use it. + */ + status = send_foo_login(f, c.username, c.password); + switch (status) { + case FOO_OK: + /* It worked. Store the credential for later use. */ + credential_accept(&c); + break; + case FOO_BAD_LOGIN: + /* Erase the credential from storage so we don't try it + * again. */ + credential_reject(&c); + break; + default: + /* + * Some other error occured. We don't know if the + * credential is good or bad, so report nothing to the + * credential subsystem. + */ + } + + /* Free any associated resources. */ + credential_clear(&c); + + return status; +} +----------------------------------------------------------------------- + + +Credential Helpers +------------------ + +Credential helpers are programs executed by git to fetch or save +credentials from and to long-term storage (where "long-term" is simply +longer than a single git process; e.g., credentials may be stored +in-memory for a few minutes, or indefinitely on disk). + +Each helper is specified by a single string. The string is transformed +by git into a command to be executed using these rules: + + 1. If the helper string begins with "!", it is considered a shell + snippet, and everything after the "!" becomes the command. + + 2. Otherwise, if the helper string begins with an absolute path, the + verbatim helper string becomes the command. + + 3. Otherwise, the string "git credential-" is prepended to the helper + string, and the result becomes the command. + +The resulting command then has an "operation" argument appended to it +(see below for details), and the result is executed by the shell. + +Here are some example specifications: + +---------------------------------------------------- +# run "git credential-foo" +foo + +# same as above, but pass an argument to the helper +foo --bar=baz + +# the arguments are parsed by the shell, so use shell +# quoting if necessary +foo --bar="whitespace arg" + +# you can also use an absolute path, which will not use the git wrapper +/path/to/my/helper --with-arguments + +# or you can specify your own shell snippet +!f() { echo "password=`cat $HOME/.secret`"; }; f +---------------------------------------------------- + +Generally speaking, rule (3) above is the simplest for users to specify. +Authors of credential helpers should make an effort to assist their +users by naming their program "git-credential-$NAME", and putting it in +the $PATH or $GIT_EXEC_PATH during installation, which will allow a user +to enable it with `git config credential.helper $NAME`. + +When a helper is executed, it will have one "operation" argument +appended to its command line, which is one of: + +`get`:: + + Return a matching credential, if any exists. + +`store`:: + + Store the credential, if applicable to the helper. + +`erase`:: + + Remove a matching credential, if any, from the helper's storage. + +The details of the credential will be provided on the helper's stdin +stream. The credential is split into a set of named attributes. +Attributes are provided to the helper, one per line. Each attribute is +specified by a key-value pair, separated by an `=` (equals) sign, +followed by a newline. The key may contain any bytes except `=`, +newline, or NUL. The value may contain any bytes except newline or NUL. +In both cases, all bytes are treated as-is (i.e., there is no quoting, +and one cannot transmit a value with newline or NUL in it). The list of +attributes is terminated by a blank line or end-of-file. + +Git will send the following attributes (but may not send all of +them for a given credential; for example, a `host` attribute makes no +sense when dealing with a non-network protocol): + +`protocol`:: + + The protocol over which the credential will be used (e.g., + `https`). + +`host`:: + + The remote hostname for a network credential. + +`path`:: + + The path with which the credential will be used. E.g., for + accessing a remote https repository, this will be the + repository's path on the server. + +`username`:: + + The credential's username, if we already have one (e.g., from a + URL, from the user, or from a previously run helper). + +`password`:: + + The credential's password, if we are asking it to be stored. + +For a `get` operation, the helper should produce a list of attributes +on stdout in the same format. A helper is free to produce a subset, or +even no values at all if it has nothing useful to provide. Any provided +attributes will overwrite those already known about by git. + +For a `store` or `erase` operation, the helper's output is ignored. +If it fails to perform the requested operation, it may complain to +stderr to inform the user. If it does not support the requested +operation (e.g., a read-only store), it should silently ignore the +request. + +If a helper receives any other operation, it should silently ignore the +request. This leaves room for future operations to be added (older +helpers will just ignore the new requests). diff --git a/Documentation/technical/api-diff.txt b/Documentation/technical/api-diff.txt index 20b0241d30..2d2ebc04b7 100644 --- a/Documentation/technical/api-diff.txt +++ b/Documentation/technical/api-diff.txt @@ -32,7 +32,7 @@ Calling sequence * As you find different pairs of files, call `diff_change()` to feed modified files, `diff_addremove()` to feed created or deleted files, - or `diff_unmerged()` to feed a file whose state is 'unmerged' to the + or `diff_unmerge()` to feed a file whose state is 'unmerged' to the API. These are thin wrappers to a lower-level `diff_queue()` function that is flexible enough to record any of these kinds of changes. @@ -50,7 +50,7 @@ Data structures This is the internal representation for a single file (blob). It records the blob object name (if known -- for a work tree file it typically is a NUL SHA-1), filemode and pathname. This is what the -`diff_addremove()`, `diff_change()` and `diff_unmerged()` synthesize and +`diff_addremove()`, `diff_change()` and `diff_unmerge()` synthesize and feed `diff_queue()` function with. * `struct diff_filepair` diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt index 9d97eaa9de..ce363b6305 100644 --- a/Documentation/technical/api-gitattributes.txt +++ b/Documentation/technical/api-gitattributes.txt @@ -11,27 +11,15 @@ Data Structure `struct git_attr`:: An attribute is an opaque object that is identified by its name. - Pass the name and its length to `git_attr()` function to obtain - the object of this type. The internal representation of this - structure is of no interest to the calling programs. + Pass the name to `git_attr()` function to obtain the object of + this type. The internal representation of this structure is + of no interest to the calling programs. The name of the + attribute can be retrieved by calling `git_attr_name()`. `struct git_attr_check`:: This structure represents a set of attributes to check in a call - to `git_checkattr()` function, and receives the results. - - -Calling Sequence ----------------- - -* Prepare an array of `struct git_attr_check` to define the list of - attributes you would want to check. To populate this array, you would - need to define necessary attributes by calling `git_attr()` function. - -* Call git_checkattr() to check the attributes for the path. - -* Inspect `git_attr_check` structure to see how each of the attribute in - the array is defined for the path. + to `git_check_attr()` function, and receives the results. Attribute Values @@ -57,6 +45,19 @@ If none of the above returns true, `.value` member points at a string value of the attribute for the path. +Querying Specific Attributes +---------------------------- + +* Prepare an array of `struct git_attr_check` to define the list of + attributes you would want to check. To populate this array, you would + need to define necessary attributes by calling `git_attr()` function. + +* Call `git_check_attr()` to check the attributes for the path. + +* Inspect `git_attr_check` structure to see how each of the attribute in + the array is defined for the path. + + Example ------- @@ -72,18 +73,18 @@ static void setup_check(void) { if (check[0].attr) return; /* already done */ - check[0].attr = git_attr("crlf", 4); - check[1].attr = git_attr("ident", 5); + check[0].attr = git_attr("crlf"); + check[1].attr = git_attr("ident"); } ------------ -. Call `git_checkattr()` with the prepared array of `struct git_attr_check`: +. Call `git_check_attr()` with the prepared array of `struct git_attr_check`: ------------ const char *path; setup_check(); - git_checkattr(path, ARRAY_SIZE(check), check); + git_check_attr(path, ARRAY_SIZE(check), check); ------------ . Act on `.value` member of the result, left in `check[]`: @@ -108,4 +109,20 @@ static void setup_check(void) } ------------ -(JC) + +Querying All Attributes +----------------------- + +To get the values of all attributes associated with a file: + +* Call `git_all_attrs()`, which returns an array of `git_attr_check` + structures. + +* Iterate over the `git_attr_check` array to examine the attribute + names and values. The name of the attribute described by a + `git_attr_check` object can be retrieved via + `git_attr_name(check[i].attr)`. (Please note that no items will be + returned for unset attributes, so `ATTR_UNSET()` will return false + for all returned `git_array_check` objects.) + +* Free the `git_array_check` array. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index f6a4a361bd..4b92514f60 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -135,9 +135,14 @@ There are some macros to easily define options: describes the group or an empty string. Start the description with an upper-case letter. -`OPT_BOOLEAN(short, long, &int_var, description)`:: - Introduce a boolean option. - `int_var` is incremented on each use. +`OPT_BOOL(short, long, &int_var, description)`:: + Introduce a boolean option. `int_var` is set to one with + `--option` and set to zero with `--no-option`. + +`OPT_COUNTUP(short, long, &int_var, description)`:: + Introduce a count-up option. + `int_var` is incremented on each use of `--option`, and + reset to zero with `--no-option`. `OPT_BIT(short, long, &int_var, description, mask)`:: Introduce a boolean option. @@ -148,8 +153,9 @@ There are some macros to easily define options: If used, `int_var` is bitwise-anded with the inverted `mask`. `OPT_SET_INT(short, long, &int_var, description, integer)`:: - Introduce a boolean option. - If used, set `int_var` to `integer`. + Introduce an integer option. + `int_var` is set to `integer` with `--option`, and + reset to zero with `--no-option`. `OPT_SET_PTR(short, long, &ptr_var, description, ptr)`:: Introduce a boolean option. @@ -198,6 +204,11 @@ There are some macros to easily define options: "auto", set `int_var` to 1 if stdout is a tty or a pager, 0 otherwise. +`OPT_NOOP_NOARG(short, long)`:: + Introduce an option that has no effect and takes no arguments. + Use it to hide deprecated options that are still to be recognized + and ignored silently. + The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt new file mode 100644 index 0000000000..dbbea95db7 --- /dev/null +++ b/Documentation/technical/api-ref-iteration.txt @@ -0,0 +1,81 @@ +ref iteration API +================= + + +Iteration of refs is done by using an iterate function which will call a +callback function for every ref. The callback function has this +signature: + + int handle_one_ref(const char *refname, const unsigned char *sha1, + int flags, void *cb_data); + +There are different kinds of iterate functions which all take a +callback of this type. The callback is then called for each found ref +until the callback returns nonzero. The returned value is then also +returned by the iterate function. + +Iteration functions +------------------- + +* `head_ref()` just iterates the head ref. + +* `for_each_ref()` iterates all refs. + +* `for_each_ref_in()` iterates all refs which have a defined prefix and + strips that prefix from the passed variable refname. + +* `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`, + `for_each_replace_ref()` iterate refs from the respective area. + +* `for_each_glob_ref()` iterates all refs that match the specified glob + pattern. + +* `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined. + +* `head_ref_submodule()`, `for_each_ref_submodule()`, + `for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`, + `for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()` + do the same as the functions descibed above but for a specified + submodule. + +* `for_each_rawref()` can be used to learn about broken ref and symref. + +* `for_each_reflog()` iterates each reflog file. + +Submodules +---------- + +If you want to iterate the refs of a submodule you first need to add the +submodules object database. You can do this by a code-snippet like +this: + + const char *path = "path/to/submodule" + if (!add_submodule_odb(path)) + die("Error submodule '%s' not populated.", path); + +`add_submodule_odb()` will return an non-zero value on success. If you +do not do this you will get an error for each ref that it does not point +to a valid object. + +Note: As a side-effect of this you can not safely assume that all +objects you lookup are available in superproject. All submodule objects +will be available the same way as the superprojects objects. + +Example: +-------- + +---- +static int handle_remote_ref(const char *refname, + const unsigned char *sha1, int flags, void *cb_data) +{ + struct strbuf *output = cb_data; + strbuf_addf(output, "%s\n", refname); + return 0; +} + +... + + struct strbuf output = STRBUF_INIT; + for_each_remote_ref(handle_remote_ref, &output); + printf("%s", output.buf); +---- diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-sha1-array.txt new file mode 100644 index 0000000000..4a4bae8109 --- /dev/null +++ b/Documentation/technical/api-sha1-array.txt @@ -0,0 +1,79 @@ +sha1-array API +============== + +The sha1-array API provides storage and manipulation of sets of SHA1 +identifiers. The emphasis is on storage and processing efficiency, +making them suitable for large lists. Note that the ordering of items is +not preserved over some operations. + +Data Structures +--------------- + +`struct sha1_array`:: + + A single array of SHA1 hashes. This should be initialized by + assignment from `SHA1_ARRAY_INIT`. The `sha1` member contains + the actual data. The `nr` member contains the number of items in + the set. The `alloc` and `sorted` members are used internally, + and should not be needed by API callers. + +Functions +--------- + +`sha1_array_append`:: + Add an item to the set. The sha1 will be placed at the end of + the array (but note that some operations below may lose this + ordering). + +`sha1_array_sort`:: + Sort the elements in the array. + +`sha1_array_lookup`:: + Perform a binary search of the array for a specific sha1. + If found, returns the offset (in number of elements) of the + sha1. If not found, returns a negative integer. If the array is + not sorted, this function has the side effect of sorting it. + +`sha1_array_clear`:: + Free all memory associated with the array and return it to the + initial, empty state. + +`sha1_array_for_each_unique`:: + Efficiently iterate over each unique element of the list, + executing the callback function for each one. If the array is + not sorted, this function has the side effect of sorting it. + +Examples +-------- + +----------------------------------------- +void print_callback(const unsigned char sha1[20], + void *data) +{ + printf("%s\n", sha1_to_hex(sha1)); +} + +void some_func(void) +{ + struct sha1_array hashes = SHA1_ARRAY_INIT; + unsigned char sha1[20]; + + /* Read objects into our set */ + while (read_object_from_stdin(sha1)) + sha1_array_append(&hashes, sha1); + + /* Check if some objects are in our set */ + while (read_object_from_stdin(sha1)) { + if (sha1_array_lookup(&hashes, sha1) >= 0) + printf("it's in there!\n"); + + /* + * Print the unique set of objects. We could also have + * avoided adding duplicate objects in the first place, + * but we would end up re-sorting the array repeatedly. + * Instead, this will sort once and then skip duplicates + * in linear time. + */ + sha1_array_for_each_unique(&hashes, print_callback, NULL); +} +----------------------------------------- diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 3f575bdcff..ce24eb96f5 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -29,6 +29,9 @@ member (you need this if you add things later) and you should set the . Can sort an unsorted list using `sort_string_list`. +. Can remove individual items of an unsorted list using + `unsorted_string_list_delete_item`. + . Finally it should free the list using `string_list_clear`. Example: @@ -112,6 +115,13 @@ write `string_list_insert(...)->util = ...;`. The above two functions need to look through all items, as opposed to their counterpart for sorted lists, which performs a binary search. +`unsorted_string_list_delete_item`:: + + Remove an item from a string_list. The `string` pointer of the items + will be freed in case the `strdup_strings` member of the string_list + is set. The third parameter controls if the `util` pointer of the + items should be freed or not. + Data structures --------------- diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 7b233ca196..8930b3fabc 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -147,8 +147,9 @@ GIT index format - 160-bit object name for the object that would result from writing this span of index as a tree. - An entry can be in an invalidated state and is represented by having -1 - in the entry_count field. + An entry can be in an invalidated state and is represented by having + -1 in the entry_count field. In this case, there is no object name + and the next entry starts immediately after the newline. The entries are written out in the top-down, depth-first order. The first entry represents the root level of the repository, followed by the diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 369f91d3b9..546980c0a4 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -60,6 +60,13 @@ process on the server side over the Git protocol is this: "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" | nc -v example.com 9418 +If the server refuses the request for some reasons, it could abort +gracefully with an error message. + +---- + error-line = PKT-LINE("ERR" SP explanation-text) +---- + SSH Transport ------------- @@ -179,34 +186,36 @@ and descriptions. Packfile Negotiation -------------------- -After reference and capabilities discovery, the client can decide -to terminate the connection by sending a flush-pkt, telling the -server it can now gracefully terminate (as happens with the ls-remote -command) or it can enter the negotiation phase, where the client and -server determine what the minimal packfile necessary for transport is. - -Once the client has the initial list of references that the server -has, as well as the list of capabilities, it will begin telling the -server what objects it wants and what objects it has, so the server -can make a packfile that only contains the objects that the client needs. -The client will also send a list of the capabilities it wants to be in -effect, out of what the server said it could do with the first 'want' line. +After reference and capabilities discovery, the client can decide to +terminate the connection by sending a flush-pkt, telling the server it can +now gracefully terminate, and disconnect, when it does not need any pack +data. This can happen with the ls-remote command, and also can happen when +the client already is up-to-date. + +Otherwise, it enters the negotiation phase, where the client and +server determine what the minimal packfile necessary for transport is, +by telling the server what objects it wants, its shallow objects +(if any), and the maximum commit depth it wants (if any). The client +will also send a list of the capabilities it wants to be in effect, +out of what the server said it could do with the first 'want' line. ---- upload-request = want-list - have-list - compute-end + *shallow-line + *1depth-request + flush-pkt want-list = first-want *additional-want - flush-pkt + + shallow-line = PKT_LINE("shallow" SP obj-id) + + depth-request = PKT_LINE("deepen" SP depth) first-want = PKT-LINE("want" SP obj-id SP capability-list LF) additional-want = PKT-LINE("want" SP obj-id LF) - have-list = *have-line - have-line = PKT-LINE("have" SP obj-id LF) - compute-end = flush-pkt / PKT-LINE("done") + depth = 1*DIGIT ---- Clients MUST send all the obj-ids it wants from the reference @@ -215,21 +224,64 @@ discovery phase as 'want' lines. Clients MUST send at least one obj-id in a 'want' command which did not appear in the response obtained through ref discovery. -If client is requesting a shallow clone, it will now send a 'deepen' -line with the depth it is requesting. +The client MUST write all obj-ids which it only has shallow copies +of (meaning that it does not have the parents of a commit) as +'shallow' lines so that the server is aware of the limitations of +the client's history. Clients MUST NOT mention an obj-id which +it does not know exists on the server. + +The client now sends the maximum commit history depth it wants for +this transaction, which is the number of commits it wants from the +tip of the history, if any, as a 'deepen' line. A depth of 0 is the +same as not making a depth request. The client does not want to receive +any commits beyond this depth, nor objects needed only to complete +those commits. Commits whose parents are not received as a result are +defined as shallow and marked as such in the server. This information +is sent back to the client in the next step. + +Once all the 'want's and 'shallow's (and optional 'deepen') are +transferred, clients MUST send a flush-pkt, to tell the server side +that it is done sending the list. + +Otherwise, if the client sent a positive depth request, the server +will determine which commits will and will not be shallow and +send this information to the client. If the client did not request +a positive depth, this step is skipped. -Once all the "want"s (and optional 'deepen') are transferred, -clients MUST send a flush-pkt. If the client has all the references -on the server, client flushes and disconnects. +---- + shallow-update = *shallow-line + *unshallow-line + flush-pkt + + shallow-line = PKT-LINE("shallow" SP obj-id) + + unshallow-line = PKT-LINE("unshallow" SP obj-id) +---- -TODO: shallow/unshallow response and document the deepen command in the ABNF. +If the client has requested a positive depth, the server will compute +the set of commits which are no deeper than the desired depth, starting +at the client's wants. The server writes 'shallow' lines for each +commit whose parents will not be sent as a result. The server writes +an 'unshallow' line for each commit which the client has indicated is +shallow, but is no longer shallow at the currently requested depth +(that is, its parents will now be sent). The server MUST NOT mark +as unshallow anything which the client has not indicated was shallow. Now the client will send a list of the obj-ids it has using 'have' -lines. In multi_ack mode, the canonical implementation will send up -to 32 of these at a time, then will send a flush-pkt. The canonical -implementation will skip ahead and send the next 32 immediately, -so that there is always a block of 32 "in-flight on the wire" at a -time. +lines, so the server can make a packfile that only contains the objects +that the client needs. In multi_ack mode, the canonical implementation +will send up to 32 of these at a time, then will send a flush-pkt. The +canonical implementation will skip ahead and send the next 32 immediately, +so that there is always a block of 32 "in-flight on the wire" at a time. + +---- + upload-haves = have-list + compute-end + + have-list = *have-line + have-line = PKT-LINE("have" SP obj-id LF) + compute-end = flush-pkt / PKT-LINE("done") +---- If the server reads 'have' lines, it then will respond by ACKing any of the obj-ids the client said it had that the server also has. The |