diff options
Diffstat (limited to 'Documentation')
169 files changed, 4478 insertions, 1762 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 45577117c2..69f7e9b76c 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -76,11 +76,19 @@ For shell scripts specifically (not exhaustive): - We do not use Process Substitution <(list) or >(list). + - Do not write control structures on a single line with semicolon. + "then" should be on the next line for if statements, and "do" + should be on the next line for "while" and "for". + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell functions. + - We prefer a space between the function name and the parentheses. The + opening "{" should also be on the same line. + E.g.: my_function () { + - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, [::], [==], nor [..]) for portability. @@ -104,6 +112,14 @@ For C programs: - We try to keep to at most 80 characters per line. + - We try to support a wide range of C compilers to compile git with, + including old ones. That means that you should not use C99 + initializers, even if a lot of compilers grok it. + + - Variables have to be declared at the beginning of the block. + + - NULL pointers shall be written as NULL, not as 0. + - When declaring pointers, the star sides with the variable name, i.e. "char *string", not "char* string" or "char * string". This makes it easier to understand code diff --git a/Documentation/Makefile b/Documentation/Makefile index 9fee0b9261..971977b8aa 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -21,11 +21,33 @@ ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. SP_ARTICLES = user-manual +SP_ARTICLES += howto/new-command SP_ARTICLES += howto/revert-branch-rebase SP_ARTICLES += howto/using-merge-subtree SP_ARTICLES += howto/using-signed-tag-in-pull-request +SP_ARTICLES += howto/use-git-daemon +SP_ARTICLES += howto/update-hook-example +SP_ARTICLES += howto/setup-git-server-over-http +SP_ARTICLES += howto/separating-topic-branches +SP_ARTICLES += howto/revert-a-faulty-merge +SP_ARTICLES += howto/recover-corrupted-blob-object +SP_ARTICLES += howto/rebuild-from-update-hook +SP_ARTICLES += howto/rebase-from-internal-branch +SP_ARTICLES += howto/maintain-git API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) + +TECH_DOCS = technical/index-format +TECH_DOCS += technical/pack-format +TECH_DOCS += technical/pack-heuristics +TECH_DOCS += technical/pack-protocol +TECH_DOCS += technical/protocol-capabilities +TECH_DOCS += technical/protocol-common +TECH_DOCS += technical/racy-git +TECH_DOCS += technical/send-pack-pipeline +TECH_DOCS += technical/shallow +TECH_DOCS += technical/trivial-merge +SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) @@ -44,9 +66,10 @@ man5dir=$(mandir)/man5 man7dir=$(mandir)/man7 # DESTDIR= -ASCIIDOC=asciidoc +ASCIIDOC = asciidoc ASCIIDOC_EXTRA = MANPAGE_XSL = manpage-normal.xsl +XMLTO = xmlto XMLTO_EXTRA = INSTALL?=install RM ?= rm -f @@ -66,12 +89,6 @@ endif -include ../config.mak # -# For asciidoc ... -# -7.1.2, set ASCIIDOC7 -# 8.0-, no extra settings are needed -# - -# # For docbook-xsl ... # -1.68.1, no extra settings are needed? # 1.69.0, set ASCIIDOC_ROFF? @@ -81,9 +98,6 @@ endif # 1.73.0-, no extra settings are needed # -ifndef ASCIIDOC7 -ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal -endif ifdef DOCBOOK_XSL_172 ASCIIDOC_EXTRA += -a git-asciidoc-no-roff MANPAGE_XSL = manpage-1.72.xsl @@ -134,15 +148,6 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' endif -# -# Please note that there is a minor bug in asciidoc. -# The version after 6.0.3 _will_ include the patch found here: -# http://marc.theaimsgroup.com/?l=git&m=111558757202243&w=2 -# -# Until that version is released you may have to apply the patch -# yourself - yes, all 6 characters of it! -# - QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir QUIET_SUBDIR1 = @@ -173,8 +178,6 @@ all: html man html: $(DOC_HTML) -$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7): asciidoc.conf - man: man1 man5 man7 man1: $(DOC_MAN1) man5: $(DOC_MAN5) @@ -248,11 +251,11 @@ clean: $(RM) *.texi *.texi+ *.texi++ git.info gitman.info $(RM) *.pdf $(RM) howto-index.txt howto/*.html doc.dep - $(RM) technical/api-*.html technical/api-index.txt + $(RM) technical/*.html technical/api-index.txt $(RM) $(cmds_txt) *.made $(RM) manpage-base-url.xsl -$(MAN_HTML): %.html : %.txt +$(MAN_HTML): %.html : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ @@ -263,9 +266,9 @@ manpage-base-url.xsl: manpage-base-url.xsl.in %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(QUIET_XMLTO)$(RM) $@ && \ - xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.xml : %.txt +%.xml : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ @@ -280,7 +283,8 @@ technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh -$(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ +$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt @@ -325,7 +329,7 @@ $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml howto-index.txt: howto-index.sh $(wildcard howto/*.txt) $(QUIET_GEN)$(RM) $@+ $@ && \ - '$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \ + '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \ mv $@+ $@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt @@ -333,6 +337,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt WEBDOC_DEST = /pub/software/scm/git/docs +howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \ @@ -360,4 +365,7 @@ require-htmlrepo:: quick-install-html: require-htmlrepo '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) +print-man1: + @for i in $(MAN1_TXT); do echo $$i; done + .PHONY: FORCE diff --git a/Documentation/RelNotes/1.5.2.1.txt b/Documentation/RelNotes/1.5.2.1.txt index ebf20e22a7..d41984df0b 100644 --- a/Documentation/RelNotes/1.5.2.1.txt +++ b/Documentation/RelNotes/1.5.2.1.txt @@ -45,9 +45,3 @@ Fixes since v1.5.2 - git-fastimport --import-marks was broken; fixed. - A lot of documentation updates, clarifications and fixes. - --- -exec >/var/tmp/1 -O=v1.5.2-65-g996e2d6 -echo O=`git describe refs/heads/maint` -git shortlog --no-merges $O..refs/heads/maint diff --git a/Documentation/RelNotes/1.6.0.2.txt b/Documentation/RelNotes/1.6.0.2.txt index e1e24b3295..7d8fb85e1b 100644 --- a/Documentation/RelNotes/1.6.0.2.txt +++ b/Documentation/RelNotes/1.6.0.2.txt @@ -79,9 +79,3 @@ Fixes since v1.6.0.1 packfile. Also contains many documentation updates. - --- -exec >/var/tmp/1 -O=v1.6.0.1-78-g3632cfc -echo O=$(git describe maint) -git shortlog --no-merges $O..maint diff --git a/Documentation/RelNotes/1.6.1.3.txt b/Documentation/RelNotes/1.6.1.3.txt index 6f0bde156a..cd08d8174e 100644 --- a/Documentation/RelNotes/1.6.1.3.txt +++ b/Documentation/RelNotes/1.6.1.3.txt @@ -26,7 +26,3 @@ Fixes since v1.6.1.2 * RPM binary package installed the html manpages in a wrong place. Also includes minor documentation fixes and updates. - - --- -git shortlog --no-merges v1.6.1.2-33-gc789350.. diff --git a/Documentation/RelNotes/1.6.1.4.txt b/Documentation/RelNotes/1.6.1.4.txt index 0ce6316d75..ccbad794c0 100644 --- a/Documentation/RelNotes/1.6.1.4.txt +++ b/Documentation/RelNotes/1.6.1.4.txt @@ -39,6 +39,3 @@ Fixes since v1.6.1.3 This fix was first merged to 1.6.2.3. Also includes minor documentation fixes and updates. - --- -git shortlog --no-merges v1.6.1.3.. diff --git a/Documentation/RelNotes/1.6.1.txt b/Documentation/RelNotes/1.6.1.txt index adb7ccab0a..7b152a6fdc 100644 --- a/Documentation/RelNotes/1.6.1.txt +++ b/Documentation/RelNotes/1.6.1.txt @@ -278,9 +278,3 @@ release, unless otherwise noted. * "gitweb" did not mark non-ASCII characters imported from external HTML fragments correctly. - --- -exec >/var/tmp/1 -O=v1.6.1-rc3-74-gf66bc5f -echo O=$(git describe master) -git shortlog --no-merges $O..master ^maint diff --git a/Documentation/RelNotes/1.7.10.1.txt b/Documentation/RelNotes/1.7.10.1.txt index 36b8deef19..806a965a1b 100644 --- a/Documentation/RelNotes/1.7.10.1.txt +++ b/Documentation/RelNotes/1.7.10.1.txt @@ -1,12 +1,22 @@ Git v1.7.10.1 Release Notes =========================== +Additions since v1.7.10 +----------------------- + +Localization message files for Danish and German have been added. + + Fixes since v1.7.10 ------------------- * "git add -p" is not designed to deal with unmerged paths but did not exclude them and tried to apply funny patches only to fail. + * "git blame" started missing quite a few changes from the origin + since we stopped using the diff minimalization by default in v1.7.2 + era. + * When PATH contains an unreadable directory, alias expansion code did not kick in, and failed with an error that said "git-subcmd" was not found. @@ -36,6 +46,21 @@ Fixes since v1.7.10 * Rename detection logic used to match two empty files as renames during merge-recursive, leading to unnatural mismerges. + * The parser in "fast-import" did not diagnose ":9" style references + that is not followed by required SP/LF as an error. + + * When "git fetch" encounters repositories with too many references, + the command line of "fetch-pack" that is run by a helper + e.g. remote-curl, may fail to hold all of them. Now such an + internal invocation can feed the references through the standard + input of "fetch-pack". + + * "git fetch" that recurses into submodules on demand did not check + if it needs to go into submodules when non branches (most notably, + tags) are fetched. + + * "log -p --graph" used with "--stat" had a few formatting error. + * Running "notes merge --commit" failed to perform correctly when run from any directory inside $GIT_DIR/. When "notes merge" stops with conflicts, $GIT_DIR/NOTES_MERGE_WORKTREE is the place a user edits @@ -47,4 +72,7 @@ Fixes since v1.7.10 $there using the upstream information to a remote unreleated to $there. + * Giving "--continue" to a conflicted "rebase -i" session skipped a + commit that only results in changes to submodules. + Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.2.txt b/Documentation/RelNotes/1.7.10.2.txt new file mode 100644 index 0000000000..7a7e9d6fd1 --- /dev/null +++ b/Documentation/RelNotes/1.7.10.2.txt @@ -0,0 +1,85 @@ +Git v1.7.10.2 Release Notes +=========================== + +Fixes since v1.7.10.1 +--------------------- + + * The test scaffolding for git-daemon was flaky. + + * The test scaffolding for fast-import was flaky. + + * The filesystem boundary was not correctly reported when .git directory + discovery stopped at a mount point. + + * HTTP transport that requires authentication did not work correctly when + multiple connections are used simultaneously. + + * Minor memory leak during unpack_trees (hence "merge" and "checkout" + to check out another branch) has been plugged. + + * In the older days, the header "Conflicts:" in "cherry-pick" and "merge" + was separated by a blank line from the list of paths that follow for + readability, but when "merge" was rewritten in C, we lost it by + mistake. Remove the newline from "cherry-pick" to make them match + again. + + * The command line parser choked "git cherry-pick $name" when $name can + be both revision name and a pathname, even though $name can never be a + path in the context of the command. + + * The "include.path" facility in the configuration mechanism added in + 1.7.10 forgot to interpret "~/path" and "~user/path" as it should. + + * "git config --rename-section" to rename an existing section into a + bogus one did not check the new name. + + * The "diff --no-index" codepath used limited-length buffers, risking + pathnames getting truncated. Update it to use the strbuf API. + + * The report from "git fetch" said "new branch" even for a non branch + ref. + + * The http-backend (the server side of the smart http transfer) used + to overwrite GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL with the + value obtained from REMOTE_USER unconditionally, making it + impossible for the server side site-specific customization to use + different identity sources to affect the names logged. It now uses + REMOTE_USER only as a fallback value. + + * "log --graph" was not very friendly with "--stat" option and its + output had line breaks at wrong places. + + * Octopus merge strategy did not reduce heads that are recorded in the + final commit correctly. + + * "git push" over smart-http lost progress output a few releases ago; + this release resurrects it. + + * The error and advice messages given by "git push" when it fails due + to non-ff were not very helpful to new users; it has been broken + into three cases, and each is given a separate advice message. + + * The insn sheet given by "rebase -i" did not make it clear that the + insn lines can be re-ordered to affect the order of the commits in + the resulting history. + + * "git repack" used to write out unreachable objects as loose objects + when repacking, even if such loose objects will immediately pruned + due to its age. + + * A contrib script "rerere-train" did not work out of the box unless + user futzed with her $PATH. + + * "git rev-parse --show-prefix" used to emit nothing when run at the + top-level of the working tree, but now it gives a blank line. + + * The i18n of error message "git stash save" was not properly done. + + * "git submodule" used a sed script that some platforms mishandled. + + * When using a Perl script on a system where "perl" found on user's + $PATH could be ancient or otherwise broken, we allow builders to + specify the path to a good copy of Perl with $PERL_PATH. The + gitweb test forgot to use that Perl when running its test. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.3.txt b/Documentation/RelNotes/1.7.10.3.txt new file mode 100644 index 0000000000..703fbf1d60 --- /dev/null +++ b/Documentation/RelNotes/1.7.10.3.txt @@ -0,0 +1,43 @@ +Git v1.7.10.3 Release Notes +=========================== + +Fixes since v1.7.10.2 +--------------------- + + * The message file for German translation has been updated a bit. + + * Running "git checkout" on an unborn branch used to corrupt HEAD. + + * When checking out another commit from an already detached state, we + used to report all commits that are not reachable from any of the + refs as lossage, but some of them might be reachable from the new + HEAD, and there is no need to warn about them. + + * Some time ago, "git clone" lost the progress output for its + "checkout" phase; when run without any "--quiet" option, it should + give progress to the lengthy operation. + + * The directory path used in "git diff --no-index", when it recurses + down, was broken with a recent update after v1.7.10.1 release. + + * "log -z --pretty=tformat:..." did not terminate each record with + NUL. The fix is not entirely correct when the output also asks for + --patch and/or --stat, though. + + * The DWIM behaviour for "log --pretty=format:%gd -g" was somewhat + broken and gave undue precedence to configured log.date, causing + "git stash list" to show "stash@{time stamp string}". + + * "git status --porcelain" ignored "--branch" option by mistake. The + output for "git status --branch -z" was also incorrect and did not + terminate the record for the current branch name with NUL as asked. + + * When a submodule repository uses alternate object store mechanism, + some commands that were started from the superproject did not + notice it and failed with "No such object" errors. The subcommands + of "git submodule" command that recursed into the submodule in a + separate process were OK; only the ones that cheated and peeked + directly into the submodule's repository from the primary process + were affected. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.4.txt b/Documentation/RelNotes/1.7.10.4.txt new file mode 100644 index 0000000000..326670df6e --- /dev/null +++ b/Documentation/RelNotes/1.7.10.4.txt @@ -0,0 +1,29 @@ +Git v1.7.10.4 Release Notes +=========================== + +Fixes since v1.7.10.3 +--------------------- + + * The message file for Swedish translation has been updated a bit. + + * A name taken from mailmap was copied into an internal buffer + incorrectly and could overun the buffer if it is too long. + + * A malformed commit object that has a header line chomped in the + middle could kill git with a NULL pointer dereference. + + * An author/committer name that is a single character was mishandled + as an invalid name by mistake. + + * The progress indicator for a large "git checkout" was sent to + stderr even if it is not a terminal. + + * "git grep -e '$pattern'", unlike the case where the patterns are + read from a file, did not treat individual lines in the given + pattern argument as separate regular expressions as it should. + + * When "git rebase" was given a bad commit to replay the history on, + its error message did not correctly give the command line argument + it had trouble parsing. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.5.txt b/Documentation/RelNotes/1.7.10.5.txt new file mode 100644 index 0000000000..4db1770e38 --- /dev/null +++ b/Documentation/RelNotes/1.7.10.5.txt @@ -0,0 +1,12 @@ +Git v1.7.10.5 Release Notes +=========================== + +Fixes since v1.7.10.4 +--------------------- + + * "git fast-export" did not give a readable error message when the + same mark erroneously appeared twice in the --import-marks input. + + * "git rebase -p" used to pay attention to rebase.autosquash which + was wrong. "git rebase -p -i" should, but "git rebase -p" by + itself should not. diff --git a/Documentation/RelNotes/1.7.11.1.txt b/Documentation/RelNotes/1.7.11.1.txt new file mode 100644 index 0000000000..577eccaacd --- /dev/null +++ b/Documentation/RelNotes/1.7.11.1.txt @@ -0,0 +1,9 @@ +Git v1.7.11.1 Release Notes +=========================== + +Fixes since v1.7.11 +------------------- + + * The cross links in the HTML version of manual pages were broken. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.2.txt b/Documentation/RelNotes/1.7.11.2.txt new file mode 100644 index 0000000000..a0d24d1270 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.2.txt @@ -0,0 +1,53 @@ +Git v1.7.11.2 Release Notes +=========================== + +Fixes since v1.7.11.1 +--------------------- + + * On Cygwin, the platform pread(2) is not thread safe, just like our + own compat/ emulation, and cannot be used in the index-pack + program. Makefile variable NO_THREAD_SAFE_PREAD can be defined to + avoid use of this function in a threaded program. + + * "git add" allows adding a regular file to the path where a + submodule used to exist, but "git update-index" does not allow an + equivalent operation to Porcelain writers. + + * "git archive" incorrectly computed the header checksum; the symptom + was observed only when using pathnames with hi-bit set. + + * "git blame" did not try to make sure that the abbreviated commit + object names in its output are unique. + + * Running "git bundle verify" on a bundle that records a complete + history said "it requires these 0 commits". + + * "git clone --single-branch" to clone a single branch did not limit + the cloning to the specified branch. + + * "git diff --no-index" did not correctly handle relative paths and + did not correctly give exit codes when run under "--quiet" option. + + * "git diff --no-index" did not work with pagers correctly. + + * "git diff COPYING HEAD:COPYING" gave a nonsense error message that + claimed that the treeish HEAD did not have COPYING in it. + + * When "git log" gets "--simplify-merges/by-decoration" together with + "--first-parent", the combination of these options makes the + simplification logic to use in-core commit objects that haven't + been examined for relevance, either producing incorrect result or + taking too long to produce any output. Teach the simplification + logic to ignore commits that the first-parent traversal logic + ignored when both are in effect to work around the issue. + + * "git ls-files --exclude=t -i" did not consider anything under t/ as + excluded, as it did not pay attention to exclusion of leading paths + while walking the index. Other two users of excluded() are also + updated. + + * "git request-pull $url dev" when the tip of "dev" branch was tagged + with "ext4-for-linus" used the contents from the tag in the output + but still asked the "dev" branch to be pulled, not the tag. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.3.txt b/Documentation/RelNotes/1.7.11.3.txt new file mode 100644 index 0000000000..64494f89d9 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.3.txt @@ -0,0 +1,53 @@ +Git v1.7.11.3 Release Notes +=========================== + +Fixes since v1.7.11.3 +--------------------- + + * The error message from "git push $there :bogo" (and its equivalent + "git push $there --delete bogo") mentioned that we tried and failed + to guess what ref is being deleted based on the LHS of the refspec, + which we don't. + + * A handful of files and directories we create had tighter than + necessary permission bits when the user wanted to have group + writability (e.g. by setting "umask 002"). + + * "commit --amend" used to refuse amending a commit with an empty log + message, with or without "--allow-empty-message". + + * "git commit --amend --only --" was meant to allow "Clever" people to + rewrite the commit message without making any change even when they + have already changes for the next commit added to their index, but + it never worked as advertised since it was introduced in 1.3.0 era. + + * Even though the index can record pathnames longer than 1<<12 bytes, + in some places we were not comparing them in full, potentially + replacing index entries instead of adding. + + * "git show"'s auto-walking behaviour was an unreliable and + unpredictable hack; it now behaves just like "git log" does when it + walks. + + * "git diff", "git status" and anything that internally uses the + comparison machinery was utterly broken when the difference + involved a file with "-" as its name. This was due to the way "git + diff --no-index" was incorrectly bolted on to the system, making + any comparison that involves a file "-" at the root level + incorrectly read from the standard input. + + * We did not have test to make sure "git rebase" without extra options + filters out an empty commit in the original history. + + * "git fast-export" produced an input stream for fast-import without + properly quoting pathnames when they contain SPs in them. + + * "git checkout --detach", when you are still on an unborn branch, + should be forbidden, but it wasn't. + + * Some implementations of Perl terminates "lines" with CRLF even when + the script is operating on just a sequence of bytes. Make sure to + use "$PERL_PATH", the version of Perl the user told Git to use, in + our tests to avoid unnecessary breakages in tests. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.4.txt b/Documentation/RelNotes/1.7.11.4.txt new file mode 100644 index 0000000000..3a640c2d4d --- /dev/null +++ b/Documentation/RelNotes/1.7.11.4.txt @@ -0,0 +1,31 @@ +Git v1.7.11.4 Release Notes +=========================== + +Fixes since v1.7.11.3 +--------------------- + + * "$GIT_DIR/COMMIT_EDITMSG" file that is used to hold the commit log + message user edits was not documented. + + * The advise() function did not use varargs correctly to format + its message. + + * When "git am" failed, old timers knew to check .git/rebase-apply/patch + to see what went wrong, but we never told the users about it. + + * "git commit-tree" learned a more natural "-p <parent> <tree>" order + of arguments long time ago, but recently forgot it by mistake. + + * "git diff --no-ext-diff" did not output anything for a typechange + filepair when GIT_EXTERNAL_DIFF is in effect. + + * In 1.7.9 era, we taught "git rebase" about the raw timestamp format + but we did not teach the same trick to "filter-branch", which rolled + a similar logic on its own. + + * When "git submodule add" clones a submodule repository, it can get + confused where to store the resulting submodule repository in the + superproject's .git/ directory when there is a symbolic link in the + path to the current directory. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.5.txt b/Documentation/RelNotes/1.7.11.5.txt new file mode 100644 index 0000000000..0a2ed855c5 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.5.txt @@ -0,0 +1,36 @@ +Git v1.7.11.5 Release Notes +=========================== + +Fixes since v1.7.11.4 +--------------------- + + * The Makefile rule to create assembly output (primarily for + debugging purposes) did not create it next to the source. + + * The code to avoid mistaken attempt to add the object directory + itself as its own alternate could read beyond end of a string while + comparison. + + * On some architectures, "block-sha1" did not compile correctly + when compilers inferred alignment guarantees from our source we + did not intend to make. + + * When talking to a remote running ssh on IPv6 enabled host, whose + address is spelled as "[HOST]:PORT", we did not parse the address + correctly and failed to connect. + + * git-blame.el (in compat/) have been updated to use Elisp more + correctly. + + * "git checkout <branchname>" to come back from a detached HEAD state + incorrectly computed reachability of the detached HEAD, resulting + in unnecessary warnings. + + * "git mergetool" did not support --tool-help option to give the list + of supported backends, like "git difftool" does. + + * "git grep" stopped spawning an external "grep" long time ago, but a + duplicated test to check internal and external "grep" was left + behind. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.6.txt b/Documentation/RelNotes/1.7.11.6.txt new file mode 100644 index 0000000000..ba7d3c3966 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.6.txt @@ -0,0 +1,84 @@ +Git v1.7.11.6 Release Notes +=========================== + +Fixes since v1.7.11.5 +--------------------- + + * "ciabot" script (in contrib/) has been updated with extensive + documentation. + + * "git foo" errored out with "Not a directory" when the user had a + non-directory on $PATH, and worse yet it masked an alias "foo" from + running. + + * When the user exports a non-default IFS without HT, scripts that + rely on being able to parse "ls-files -s | while read a b c..." + started to fail. Protect them from such a misconfiguration. + + * When the user gives an argument that can be taken as both a + revision name and a pathname without disambiguating with "--", we + used to give a help message "Use '--' to separate". The message + has been clarified to show where that '--' goes on the command + line. + + * Documentation for the configuration file format had a confusing + example. + + * Older parts of the documentation described as if having a regular + file in .git/refs/ hierarchy were the only way to have branches and + tags, which is not true for quite some time. + + * It was generally understood that "--long-option"s to many of our + subcommands can be abbreviated to the unique prefix, but it was not + easy to find it described for new readers of the documentation set. + + * The "--topo-order", "--date-order" (and the lack of either means + the default order) options to "rev-list" and "log" family of + commands were poorly described in the documentation. + + * "git commit --amend" let the user edit the log message and then + died when the human-readable committer name was given + insufficiently by getpwent(3). + + * The exit status code from "git config" was way overspecified while + being incorrect. The implementation has been updated to give the + documented status for a case that was documented, and introduce a + new code for "all other errors". + + * The output from "git diff -B" for a file that ends with an + incomplete line did not put "\ No newline..." on a line of its own. + + * "git diff" had a confusion between taking data from a path in the + working tree and taking data from an object that happens to have + name 0{40} recorded in a tree. + + * The "--rebase" option to "git pull" can be abbreviated to "-r", + but we didn't document it. + + * When "git push" triggered the automatic gc on the receiving end, a + message from "git prune" that said it was removing cruft leaked to + the standard output, breaking the communication protocol. + + * The reflog entries left by "git rebase" and "git rebase -i" were + inconsistent (the interactive one gave an abbreviated object name). + + * "git send-email" did not unquote encoded words that appear on the + header correctly, and lost "_" from strings. + + * "git stash apply/pop" did not trigger "rerere" upon conflicts + unlike other mergy operations. + + * "git submodule <cmd> path" did not error out when the path to the + submodule was misspelt. + + * "git submodule update -f" did not update paths in the working tree + that has local changes. + (merge 01d4721 sz/submodule-force-update later to maint). + + * "gitweb" when used with PATH_INFO failed to notice directories with + SP (and other characters that need URL-style quoting) in them. + + * Fallback 'getpass' implementation made unportable use of stdio API. + + * A utility shell function test_seq has been added as a replacement + for the 'seq' utility found on some platforms. diff --git a/Documentation/RelNotes/1.7.11.7.txt b/Documentation/RelNotes/1.7.11.7.txt new file mode 100644 index 0000000000..e7e79d999b --- /dev/null +++ b/Documentation/RelNotes/1.7.11.7.txt @@ -0,0 +1,46 @@ +Git v1.7.11.7 Release Notes +=========================== + +Fixes since v1.7.11.6 +--------------------- + + * The synopsis said "checkout [-B branch]" to make it clear the + branch name is a parameter to the option, but the heading for the + option description was "-B::", not "-B branch::", making the + documentation misleading. + + * Git ships with a fall-back regexp implementation for platforms with + buggy regexp library, but it was easy for people to keep using their + platform regexp. A new test has been added to check this. + + * "git apply -p0" did not parse pathnames on "diff --git" line + correctly. This caused patches that had pathnames in no other + places to be mistakenly rejected (most notably, binary patch that + does not rename nor change mode). Textual patches, renames or mode + changes have preimage and postimage pathnames in different places + in a form that can be parsed unambiguously and did not suffer from + this problem. + + * After "gitk" showed the contents of a tag, neither "Reread + references" nor "Reload" did not update what is shown as the + contents of it, when the user overwrote the tag with "git tag -f". + + * "git for-each-ref" did not currectly support more than one --sort + option. + + * "git log .." errored out saying it is both rev range and a path + when there is no disambiguating "--" is on the command line. + Update the command line parser to interpret ".." as a path in such + a case. + + * Pushing to smart HTTP server with recent Git fails without having + the username in the URL to force authentication, if the server is + configured to allow GET anonymously, while requiring authentication + for POST. + + * "git show --format='%ci'" did not give timestamp correctly for + commits created without human readable name on "committer" line. + (merge e27ddb6 jc/maint-ident-missing-human-name later to maint). + + * "git show --quiet" ought to be a synonym for "git show -s", but + wasn't. diff --git a/Documentation/RelNotes/1.7.11.txt b/Documentation/RelNotes/1.7.11.txt index 429f304972..15b954ca4b 100644 --- a/Documentation/RelNotes/1.7.11.txt +++ b/Documentation/RelNotes/1.7.11.txt @@ -6,35 +6,59 @@ Updates since v1.7.10 UI, Workflows & Features + * A new mode for push, "simple", which is a cross between "current" + and "upstream", has been introduced. "git push" without any refspec + will push the current branch out to the same name at the remote + repository only when it is set to track the branch with the same + name over there. The plan is to make this mode the new default + value when push.default is not configured. + + * A couple of commands learned the "--column" option to produce + columnar output. + * A third-party tool "git subtree" is distributed in contrib/ + * A remote helper that acts as a proxy and caches ssl session for the + https:// transport is added to the contrib/ area. + * Error messages given when @{u} is used for a branch without its - upstream configured have been clatified. + upstream configured have been clarified. - * Even with "-q"uiet option, "checkout" used to report setting up + * Even with the "-q"uiet option, "checkout" used to report setting up tracking. Also "branch" learned the "-q"uiet option to squelch informational message. + * Your build platform may support hardlinks but you may prefer not to + use them, e.g. when installing to DESTDIR to make a tarball and + untarring on a filesystem that has poor support for hardlinks. + There is a Makefile option NO_INSTALL_HARDLINKS for you. + * The smart-http backend used to always override GIT_COMMITTER_* variables with REMOTE_USER and REMOTE_ADDR, but these variables are now preserved when set. - * "include.path" mechanism of the configuration files learned to - understand "~/path" and "~user/path". - * "git am" learned the "--include" option, which is an opposite of existing the "--exclude" option. - * When "git am -3" needs to fall back to an application to a - synthesized preimage followed by a 3-way merge, the paths that + * When "git am -3" needs to fall back to an application of the patch + to a synthesized preimage followed by a 3-way merge, the paths that needed such treatment are now reported to the end user, so that the result in them can be eyeballed with extra care. - * The "fmt-merge-msg" command learns to list the primary contributors - involved in the side topic you are merging. + * The output from "diff/log --stat" used to always allocate 4 columns + to show the number of modified lines, but not anymore. - * The cases "git push" fails due to non-ff can be broken into three - categories; each case is given a separate advise message. + * "git difftool" learned the "--dir-diff" option to spawn external + diff tools that can compare two directory hierarchies at a time + after populating two temporary directories, instead of running an + instance of the external tool once per a file pair. + + * The "fmt-merge-msg" command learned to list the primary contributors + involved in the side topic you are merging in a comment in the merge + commit template. + + * "git rebase" learned to optionally keep commits that do not + introduce any change in the original history. * "git push --recurse-submodules" learned to optionally look into the histories of submodules bound to the superproject and push them @@ -47,44 +71,54 @@ UI, Workflows & Features Foreign Interface - * "git svn" used to die with unwanted SIGPIPE when talking with HTTP + * "git svn" used to die with unwanted SIGPIPE when talking with an HTTP server that uses keep-alive. * "git svn" learned to use platform specific authentication providers, e.g. gnome-keyring, kwallet, etc. - * "git p4" has been moved out of contrib/ area. + * "git p4" has been moved out of the contrib/ area and has seen more + work on importing labels as tags from (and exporting tags as labels + to) p4. -Performance +Performance and Internal Implementation (please report possible regressions) - * "git apply" had some memory leaks plugged. + * Bash completion script (in contrib/) have been cleaned up to make + future work on it simpler. + + * An experimental "version 4" format of the index file has been + introduced to reduce on-disk footprint and I/O overhead. - * "git repack" used to write out unreachable objects as loose objects - when repacking, even if such loose objects will immediately pruned - due to its age. + * "git archive" learned to produce its output without reading the + blob object it writes out in memory in its entirety. + + * "git index-pack" that runs when fetching or pushing objects to + complete the packfile on the receiving end learned to use multiple + threads to do its job when available. + + * The code to compute hash values for lines used by the internal diff + engine was optimized on little-endian machines, using the same + trick the kernel folks came up with. + + * "git apply" had some memory leaks plugged. * Setting up a revision traversal with many starting points was inefficient as these were placed in a date-order priority queue one-by-one. Now they are collected in the queue unordered first, and sorted immediately before getting used. -Internal Implementation (please report possible regressions) - - * "git rev-parse --show-prefix" used to emit nothing when run at the - top-level of the working tree, but now it gives a blank line. - - * Minor memory leak during unpack_trees (hence "merge" and "checkout" - to check out another branch) has been plugged. - * More lower-level commands learned to use the streaming API to read from the object store without keeping everything in core. + * The weighting parameters to suggestion command name typo have been + tweaked, so that "git tags" will suggest "tag?" and not "stage?". + * Because "sh" on the user's PATH may be utterly broken on some systems, run-command API now uses SHELL_PATH, not /bin/sh, when spawning an external command (not applicable to Windows port). - * The API to iterate over refs/ hierarchy has been tweaked to allow - walking only a subset of it more efficiently. + * The API to iterate over the refs/ hierarchy has been tweaked to + allow walking only a subset of it more efficiently. Also contains minor documentation updates and code clean-ups. @@ -96,71 +130,10 @@ Unless otherwise noted, all the fixes since v1.7.10 in the maintenance releases are contained in this release (see release notes to them for details). - * The test scaffolding for git-daemon was flaky. - (merge 46e3581 js/daemon-test-race-fix later to maint). - - * The test scaffolding for fast-import was flaky. - (merge 7fb8e16 pw/t5800-import-race-fix later to maint). - - * Octopus merge strategy did not reduce heads that are recorded in the - final commit correctly. - (merge 5802f81 jc/merge-reduce-parents-early later to maint). - - * In the older days, the header "Conflicts:" in "cherry-pick" and - "merge" was separated by a blank line from the list of paths that - follow for readability, but when "merge" was rewritten in C, we lost - it by mistake. Remove the newline from "cherry-pick" to make them - match again. - (merge 5112068 rt/cherry-revert-conflict-summary later to maint). - - * The filesystem boundary was not correctly reported when .git - directory discovery stopped at a mount point. - (merge 2565b43 cb/maint-report-mount-point-correctly-in-setup later to maint). - - * The command line parser choked "git cherry-pick $name" when $name - can be both revision name and a pathname, even though $name can - never be a path in the context of the command. - (merge 6d5b93f cb/cherry-pick-rev-path-confusion later to maint). - - * HTTP transport that requires authentication did not work correctly - when multiple connections are used simultaneously. - (merge 6f4c347 cb/http-multi-curl-auth later to maint). - - * The i18n of error message "git stash save" was not properly done. - (merge ed3c400 rl/maint-stash-i18n-save-error later to maint). - - * The report from "git fetch" said "new branch" even for a non branch - ref. - (merge 0997ada mb/fetch-call-a-non-branch-a-ref later to maint). - - * The "diff --no-index" codepath used limited-length buffers, risking - pathnames getting truncated. Update it to use the strbuf API. - (merge 875b91b jm/maint-strncpy-diff-no-index later to maint). - - * The parser in "fast-import" did not diagnose ":9" style references - that is not followed by required SP/LF as an error. - (merge 06454cb pw/fast-import-dataref-parsing later to maint). - - * When "git fetch" encounters repositories with too many references, - the command line of "fetch-pack" that is run by a helper - e.g. remote-curl, may fail to hold all of them. Now such an - internal invocation can feed the references through the standard - input of "fetch-pack". - (merge 7103d25 it/fetch-pack-many-refs later to maint). - - * "git fetch" that recurses into submodules on demand did not check - if it needs to go into submodules when non branches (most notably, - tags) are fetched. - (merge a6801ad jl/maint-submodule-recurse-fetch later to maint). - - * "git blame" started missing quite a few changes from the origin - since we stopped using the diff minimalization by default in v1.7.2 - era. - (merge 059a500 jc/maint-blame-minimal later to maint). - - * "log -p --graph" used with "--stat" had a few formatting error. - (merge e2c5966 lp/maint-diff-three-dash-with-graph later to maint). - - * Giving "--continue" to a conflicted "rebase -i" session skipped a - commit that only results in changes to submodules. - (merge a6754cd jk/rebase-i-submodule-conflict-only later to maint). + * "git submodule init" used to report "registered for path ..." + even for submodules that were registered earlier. + (cherry-pick c1c259e jl/submodule-report-new-path-once later to maint). + + * "git diff --stat" used to fully count a binary file with modified + execution bits whose contents is unmodified, which was not quite + right. diff --git a/Documentation/RelNotes/1.7.12.1.txt b/Documentation/RelNotes/1.7.12.1.txt new file mode 100644 index 0000000000..b8f04af19f --- /dev/null +++ b/Documentation/RelNotes/1.7.12.1.txt @@ -0,0 +1,134 @@ +Git 1.7.12.1 Release Notes +========================== + +Fixes since v1.7.12 +------------------- + + * "git apply -p0" did not parse pathnames on "diff --git" line + correctly. This caused patches that had pathnames in no other + places to be mistakenly rejected (most notably, binary patch that + does not rename nor change mode). Textual patches, renames or mode + changes have preimage and postimage pathnames in different places + in a form that can be parsed unambiguously and did not suffer from + this problem. + + * "git cherry-pick A C B" used to replay changes in A and then B and + then C if these three commits had committer timestamps in that + order, which is not what the user who said "A C B" naturally + expects. + + * "git commit --amend" let the user edit the log message and then + died when the human-readable committer name was given + insufficiently by getpwent(3). + + * Some capabilities were asked by fetch-pack even when upload-pack + did not advertise that they are available. fetch-pack has been + fixed not to do so. + + * "git diff" had a confusion between taking data from a path in the + working tree and taking data from an object that happens to have + name 0{40} recorded in a tree. + + * "git for-each-ref" did not correctly support more than one --sort + option. + + * "git log .." errored out saying it is both rev range and a path + when there is no disambiguating "--" is on the command line. + Update the command line parser to interpret ".." as a path in such + a case. + + * The "--topo-order", "--date-order" (and the lack of either means + the default order) options to "rev-list" and "log" family of + commands were poorly described in the documentation. + + * "git prune" without "-v" used to warn about leftover temporary + files (which is an indication of an earlier aborted operation). + + * Pushing to smart HTTP server with recent Git fails without having + the username in the URL to force authentication, if the server is + configured to allow GET anonymously, while requiring authentication + for POST. + + * The reflog entries left by "git rebase" and "git rebase -i" were + inconsistent (the interactive one gave an abbreviated object name). + + * When "git push" triggered the automatic gc on the receiving end, a + message from "git prune" that said it was removing cruft leaked to + the standard output, breaking the communication protocol. + + * "git show --quiet" ought to be a synonym for "git show -s", but + wasn't. + + * "git show --format='%ci'" did not give timestamp correctly for + commits created without human readable name on "committer" line. + + * "git send-email" did not unquote encoded words that appear on the + header correctly, and lost "_" from strings. + + * The interactive prompt "git send-email" gives was error prone. It + asked "What e-mail address do you want to use?" with the address it + guessed (correctly) the user would want to use in its prompt, + tempting the user to say "y". But the response was taken as "No, + please use 'y' as the e-mail address instead", which is most + certainly not what the user meant. + + * "gitweb" when used with PATH_INFO failed to notice directories with + SP (and other characters that need URL-style quoting) in them. + + * When the user gives an argument that can be taken as both a + revision name and a pathname without disambiguating with "--", we + used to give a help message "Use '--' to separate". The message + has been clarified to show where that '--' goes on the command + line. + + * When the user exports a non-default IFS without HT, scripts that + rely on being able to parse "ls-files -s | while read a b c..." + started to fail. Protect them from such a misconfiguration. + + * The attribute system may be asked for a path that itself or its + leading directories no longer exists in the working tree, and it is + fine if we cannot open .gitattribute file in such a case. Failure + to open per-directory .gitattributes with error status other than + ENOENT and ENOTDIR should be diagnosed, but it wasn't. + + * After "gitk" showed the contents of a tag, neither "Reread + references" nor "Reload" did not update what is shown as the + contents of it, when the user overwrote the tag with "git tag -f". + + * "ciabot" script (in contrib/) has been updated with extensive + documentation. + + * "git-jump" script (in contrib/) did not work well when + diff.noprefix or diff.mnemonicprefix is in effect. + + * Older parts of the documentation described as if having a regular + file in .git/refs/ hierarchy were the only way to have branches and + tags, which is not true for quite some time. + + * A utility shell function test_seq has been added as a replacement + for the 'seq' utility found on some platforms. + + * Compatibility wrapper to learn the maximum number of file + descriptors we can open around sysconf(_SC_OPEN_MAX) and + getrlimit(RLIMIT_NO_FILE) has been introduced for portability. + + * We used curl_easy_strerror() without checking version of cURL, + breaking the build for versions before curl 7.12.0. + + * Code to work around MacOS X UTF-8 gotcha has been cleaned up. + + * Fallback 'getpass' implementation made unportable use of stdio API. + + * The "--rebase" option to "git pull" can be abbreviated to "-r", + but we didn't document it. + + * It was generally understood that "--long-option"s to many of our + subcommands can be abbreviated to the unique prefix, but it was not + easy to find it described for new readers of the documentation set. + + * The synopsis said "checkout [-B branch]" to make it clear the + branch name is a parameter to the option, but the heading for the + option description was "-B::", not "-B branch::", making the + documentation misleading. + +Also contains numerous documentation updates. diff --git a/Documentation/RelNotes/1.7.12.2.txt b/Documentation/RelNotes/1.7.12.2.txt new file mode 100644 index 0000000000..69255745e6 --- /dev/null +++ b/Documentation/RelNotes/1.7.12.2.txt @@ -0,0 +1,40 @@ +Git 1.7.12.2 Release Notes +========================== + +Fixes since v1.7.12.1 +--------------------- + + * When "git am" is fed an input that has multiple "Content-type: ..." + header, it did not grok charset= attribute correctly. + + * Even during a conflicted merge, "git blame $path" always meant to + blame uncommitted changes to the "working tree" version; make it + more useful by showing cleanly merged parts as coming from the other + branch that is being merged. + + * "git blame MAKEFILE" run in a history that has "Makefile" but not + "MAKEFILE" should say "No such file MAKEFILE in HEAD", but got + confused on a case insensitive filesystem and failed to do so. + + * "git fetch --all", when passed "--no-tags", did not honor the + "--no-tags" option while fetching from individual remotes (the same + issue existed with "--tags", but combination "--all --tags" makes + much less sense than "--all --no-tags"). + + * "git log/diff/format-patch --stat" showed the "N line(s) added" + comment in user's locale and caused careless submitters to send + patches with such a line in them to projects whose project language + is not their language, mildly irritating others. Localization to + the line has been disabled for now. + + * "git log --all-match --grep=A --grep=B" ought to show commits that + mention both A and B, but when these three options are used with + --author or --committer, it showed commits that mention either A or + B (or both) instead. + + * The subcommand to remove the definition of a remote in "git remote" + was named "rm" even though all other subcommands were spelled out. + Introduce "git remote remove" to remove confusion, and keep "rm" as + a backward compatible synonym. + +Also contains a handful of documentation updates. diff --git a/Documentation/RelNotes/1.7.12.3.txt b/Documentation/RelNotes/1.7.12.3.txt new file mode 100644 index 0000000000..ecda427a35 --- /dev/null +++ b/Documentation/RelNotes/1.7.12.3.txt @@ -0,0 +1,34 @@ +Git 1.7.12.3 Release Notes +========================== + +Fixes since v1.7.12.2 +--------------------- + + * "git am" mishandled a patch attached as application/octet-stream + (e.g. not text/*); Content-Transfer-Encoding (e.g. base64) was not + honored correctly. + + * It was unclear in the documentation for "git blame" that it is + unnecessary for users to use the "--follow" option. + + * A repository created with "git clone --single" had its fetch + refspecs set up just like a clone without "--single", leading the + subsequent "git fetch" to slurp all the other branches, defeating + the whole point of specifying "only this branch". + + * "git fetch" over http had an old workaround for an unlikely server + misconfiguration; it turns out that this hurts debuggability of the + configuration in general, and has been reverted. + + * "git fetch" over http advertised that it supports "deflate", which + is much less common, and did not advertise the more common "gzip" on + its Accept-Encoding header. + + * "git receive-pack" (the counterpart to "git push") did not give + progress output while processing objects it received to the puser + when run over the smart-http protocol. + + * "git status" honored the ignore=dirty settings in .gitmodules but + "git commit" didn't. + +Also contains a handful of documentation updates. diff --git a/Documentation/RelNotes/1.7.12.4.txt b/Documentation/RelNotes/1.7.12.4.txt new file mode 100644 index 0000000000..c6da3cc939 --- /dev/null +++ b/Documentation/RelNotes/1.7.12.4.txt @@ -0,0 +1,23 @@ +Git 1.7.12.4 Release Notes +========================== + +Fixes since v1.7.12.3 +--------------------- + + * "git fetch" over the dumb-http revision walker could segfault when + curl's multi interface was used. + + * It was possible to give specific paths for "asciidoc" and other + tools in the documentation toolchain, but not for "xmlto". + + * "gitweb" did not give the correct committer timezone in its feed + output due to a typo. + + * The "-Xours" (and similarly -Xtheirs) backend option to "git + merge -s recursive" was ignored for binary files. Now it is + honored. + + * The "binary" synthetic attribute made "diff" to treat the path as + binary, but not "merge". + +Also contains many documentation updates. diff --git a/Documentation/RelNotes/1.7.12.txt b/Documentation/RelNotes/1.7.12.txt new file mode 100644 index 0000000000..010d8c7de4 --- /dev/null +++ b/Documentation/RelNotes/1.7.12.txt @@ -0,0 +1,136 @@ +Git v1.7.12 Release Notes +========================= + +Updates since v1.7.11 +--------------------- + +UI, Workflows & Features + + * Git can be told to normalize pathnames it read from readdir(3) and + all arguments it got from the command line into precomposed UTF-8 + (assuming that they come as decomposed UTF-8), in order to work + around issues on Mac OS. + + I think there still are other places that need conversion + (e.g. paths that are read from stdin for some commands), but this + should be a good first step in the right direction. + + * Per-user $HOME/.gitconfig file can optionally be stored in + $HOME/.config/git/config instead, which is in line with XDG. + + * The value of core.attributesfile and core.excludesfile default to + $HOME/.config/git/attributes and $HOME/.config/git/ignore respectively + when these files exist. + + * Logic to disambiguate abbreviated object names have been taught to + take advantage of object types that are expected in the context, + e.g. XXXXXX in the "git describe" output v1.2.3-gXXXXXX must be a + commit object, not a blob nor a tree. This will help us prolong + the lifetime of abbreviated object names. + + * "git apply" learned to wiggle the base version and perform three-way + merge when a patch does not exactly apply to the version you have. + + * Scripted Porcelain writers now have access to the credential API via + the "git credential" plumbing command. + + * "git help" used to always default to "man" format even on platforms + where "man" viewer is not widely available. + + * "git clone --local $path" started its life as an experiment to + optionally use link/copy when cloning a repository on the disk, but + we didn't deprecate it after we made the option a no-op to always + use the optimization. The command learned "--no-local" option to + turn this off, as a more explicit alternative over use of file:// + URL. + + * "git fetch" and friends used to say "remote side hung up + unexpectedly" when they failed to get response they expect from the + other side, but one common reason why they don't get expected + response is that the remote repository does not exist or cannot be + read. The error message in this case was updated to give better + hints to the user. + + * "git help -w $cmd" can show HTML version of documentation for + "git-$cmd" by setting help.htmlpath to somewhere other than the + default location where the build procedure installs them locally; + the variable can even point at a http:// URL. + + * "git rebase [-i] --root $tip" can now be used to rewrite all the + history leading to "$tip" down to the root commit. + + * "git rebase -i" learned "-x <cmd>" to insert "exec <cmd>" after + each commit in the resulting history. + + * "git status" gives finer classification to various states of paths + in conflicted state and offer advice messages in its output. + + * "git submodule" learned to deal with nested submodule structure + where a module is contained within a module whose origin is + specified as a relative URL to its superproject's origin. + + * A rather heavy-ish "git completion" script has been split to create + a separate "git prompting" script, to help lazy-autoloading of the + completion part while making prompting part always available. + + * "gitweb" pays attention to various forms of credits that are + similar to "Signed-off-by:" lines in the commit objects and + highlights them accordingly. + + +Foreign Interface + + * "mediawiki" remote helper (in contrib/) learned to handle file + attachments. + + * "git p4" now uses "Jobs:" and "p4 move" when appropriate. + + * vcs-svn has been updated to clean-up compilation, lift 32-bit + limitations, etc. + + +Performance, Internal Implementation, etc. (please report possible regressions) + + * Some tests showed false failures caused by a bug in ecryptofs. + + * We no longer use AsciiDoc7 syntax in our documentation and favor a + more modern style. + + * "git am --rebasing" codepath was taught to grab authorship, log + message and the patch text directly out of existing commits. This + will help rebasing commits that have confusing "diff" output in + their log messages. + + * "git index-pack" and "git pack-objects" use streaming API to read + from the object store to avoid having to hold a large blob object + in-core while they are doing their thing. + + * Code to match paths with exclude patterns learned to avoid calling + fnmatch() by comparing fixed leading substring literally when + possible. + + * "git log -n 1 -- rarely-touched-path" was spending unnecessary + cycles after showing the first change to find the next one, only to + discard it. + + * "git svn" got a large-looking code reorganization at the last + minute before the code freeze. + + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.11 +------------------- + +Unless otherwise noted, all the fixes since v1.7.11 in the maintenance +releases are contained in this release (see release notes to them for +details). + + * "git submodule add" was confused when the superproject did not have + its repository in its usual place in the working tree and GIT_DIR + and GIT_WORK_TREE was used to access it. + + * "git commit --amend" let the user edit the log message and then died + when the human-readable committer name was given insufficiently by + getpwent(3). diff --git a/Documentation/RelNotes/1.8.0.1.txt b/Documentation/RelNotes/1.8.0.1.txt new file mode 100644 index 0000000000..1f372fa0b5 --- /dev/null +++ b/Documentation/RelNotes/1.8.0.1.txt @@ -0,0 +1,64 @@ +Git v1.8.0.1 Release Notes +========================== + +Fixes since v1.8.0 +------------------ + + * The configuration parser had an unnecessary hardcoded limit on + variable names that was not checked consistently. + + * The "say" function in the test scaffolding incorrectly allowed + "echo" to interpret "\a" as if it were a C-string asking for a + BEL output. + + * "git mergetool" feeds /dev/null as a common ancestor when dealing + with an add/add conflict, but p4merge backend cannot handle + it. Work it around by passing a temporary empty file. + + * "git log -F -E --grep='<ere>'" failed to use the given <ere> + pattern as extended regular expression, and instead looked for the + string literally. + + * "git grep -e pattern <tree>" asked the attribute system to read + "<tree>:.gitattributes" file in the working tree, which was + nonsense. + + * A symbolic ref refs/heads/SYM was not correctly removed with "git + branch -d SYM"; the command removed the ref pointed by SYM + instead. + + * Earlier we fixed documentation to hyphenate "remote-tracking branch" + to clarify that these are not a remote entity, but unhyphenated + spelling snuck in to a few places since then. + + * "git pull --rebase" run while the HEAD is detached tried to find + the upstream branch of the detached HEAD (which by definition + does not exist) and emitted unnecessary error messages. + + * The refs/replace hierarchy was not mentioned in the + repository-layout docs. + + * Sometimes curl_multi_timeout() function suggested a wrong timeout + value when there is no file descriptors to wait on and the http + transport ended up sleeping for minutes in select(2) system call. + A workaround has been added for this. + + * Various rfc2047 quoting issues around a non-ASCII name on the + From: line in the output from format-patch have been corrected. + + * "git diff -G<pattern>" did not honor textconv filter when looking + for changes. + + * Bash completion script (in contrib/) did not correctly complete a + lazy "git checkout $name_of_remote_tracking_branch_that_is_unique" + command line. + + * RSS feed from "gitweb" had a xss hole in its title output. + + * "git config --path $key" segfaulted on "[section] key" (a boolean + "true" spelled without "=", not "[section] key = true"). + + * "git checkout -b foo" while on an unborn branch did not say + "Switched to a new branch 'foo'" like other cases. + +Also contains other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.8.0.2.txt b/Documentation/RelNotes/1.8.0.2.txt new file mode 100644 index 0000000000..8497e051de --- /dev/null +++ b/Documentation/RelNotes/1.8.0.2.txt @@ -0,0 +1,34 @@ +Git v1.8.0.2 Release Notes +========================== + +Fixes since v1.8.0.1 +-------------------- + + * Various codepaths have workaround for a common misconfiguration to + spell "UTF-8" as "utf8", but it was not used uniformly. Most + notably, mailinfo (which is used by "git am") lacked this support. + + * We failed to mention a file without any content change but whose + permission bit was modified, or (worse yet) a new file without any + content in the "git diff --stat" output. + + * When "--stat-count" hides a diffstat for binary contents, the total + number of added and removed lines at the bottom was computed + incorrectly. + + * When "--stat-count" hides a diffstat for unmerged paths, the total + number of affected files at the bottom of the "diff --stat" output + was computed incorrectly. + + * "diff --shortstat" miscounted the total number of affected files + when there were unmerged paths. + + * "git p4" used to try expanding malformed "$keyword$" that spans + across multiple lines. + + * "git update-ref -d --deref SYM" to delete a ref through a symbolic + ref that points to it did not remove it correctly. + + * Syntax highlighting in "gitweb" was not quite working. + +Also contains other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.8.0.3.txt b/Documentation/RelNotes/1.8.0.3.txt new file mode 100644 index 0000000000..92b1e4b363 --- /dev/null +++ b/Documentation/RelNotes/1.8.0.3.txt @@ -0,0 +1,14 @@ +Git v1.8.0.3 Release Notes +========================== + +Fixes since v1.8.0.2 +-------------------- + + * "git log -p -S<string>" did not apply the textconv filter while + looking for the <string>. + + * In the documentation, some invalid example e-mail addresses were + formatted into mailto: links. + +Also contains many documentation updates backported from the 'master' +branch that is preparing for the upcoming 1.8.1 release. diff --git a/Documentation/RelNotes/1.8.0.txt b/Documentation/RelNotes/1.8.0.txt new file mode 100644 index 0000000000..43883c14f0 --- /dev/null +++ b/Documentation/RelNotes/1.8.0.txt @@ -0,0 +1,267 @@ +Git v1.8.0 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the next major release (not *this* one), we will change the +behavior of the "git push" command. + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). We will use the "simple" semantics that pushes the +current branch to the branch with the same name, only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this, and +"git push" will warn about the upcoming change until you set this +variable in this release. + +"git branch --set-upstream" is deprecated and may be removed in a +relatively distant future. "git branch [-u|--set-upstream-to]" has +been introduced with a saner order of arguments. + + +Updates since v1.7.12 +--------------------- + +UI, Workflows & Features + + * A credential helper for Win32 to allow access to the keychain of + the logged-in user has been added. + + * An initial port to HP NonStop. + + * A credential helper to allow access to the Gnome keyring has been + added. + + * When "git am" sanitizes the "Subject:" line, we strip the prefix from + "Re: subject" and also from a less common "re: subject", but left + the even less common "RE: subject" intact. Now we strip that too. + + * It was tempting to say "git branch --set-upstream origin/master", + but that tells Git to arrange the local branch "origin/master" to + integrate with the currently checked out branch, which is highly + unlikely what the user meant. The option is deprecated; use the + new "--set-upstream-to" (with a short-and-sweet "-u") option + instead. + + * "git cherry-pick" learned the "--allow-empty-message" option to + allow it to replay a commit without any log message. + + * After "git cherry-pick -s" gave control back to the user asking + help to resolve conflicts, concluding "git commit" used to need to + be run with "-s" if the user wants to sign it off; now the command + leaves the sign-off line in the log template. + + * "git daemon" learned the "--access-hook" option to allow an + external command to decline service based on the client address, + repository path, etc. + + * "git difftool --dir-diff" learned to use symbolic links to prepare + a temporary copy of the working tree when available. + + * "git grep" learned to use a non-standard pattern type by default if + a configuration variable tells it to. + + * Accumulated updates to "git gui" has been merged. + + * "git log -g" learned the "--grep-reflog=<pattern>" option to limit + its output to commits with a reflog message that matches the given + pattern. + + * "git merge-base" learned the "--is-ancestor A B" option to tell if A is + an ancestor of B. The result is indicated by its exit status code. + + * "git mergetool" now allows users to override the actual command used + with the mergetool.$name.cmd configuration variable even for built-in + mergetool backends. + + * "git rebase -i" learned the "--edit-todo" option to open an editor + to edit the instruction sheet. + + +Foreign Interface + + * "git svn" has been updated to work with SVN 1.7. + + * "git p4" learned the "--conflicts" option to specify what to do when + encountering a conflict during "p4 submit". + + +Performance, Internal Implementation, etc. + + * Git ships with a fall-back regexp implementation for platforms with + buggy regexp library, but it was easy for people to keep using their + platform regexp by mistake. A new test has been added to check this. + + * The "check-docs" build target has been updated and greatly + simplified. + + * The test suite is run under MALLOC_CHECK_ when running with a glibc + that supports the feature. + + * The documentation in the TeXinfo format was using indented output + for materials meant to be examples that are better typeset in + monospace. + + * Compatibility wrapper around some mkdir(2) implementations that + reject parameters with trailing slash has been introduced. + + * Compatibility wrapper for systems that lack usable setitimer() has + been added. + + * The option parsing of "git checkout" had error checking, dwim and + defaulting missing options, all mixed in the code, and issuing an + appropriate error message with useful context was getting harder. + The code has been reorganized to allow giving a proper diagnosis + when the user says "git checkout -b -t foo bar" (e.g. "-t" is not a + good name for a branch). + + * Many internal uses of a "git merge-base" equivalent were only to see + if one commit fast-forwards to the other, which did not need the + full set of merge bases to be computed. They have been updated to + use less expensive checks. + + * The heuristics to detect and silently convert latin1 to utf8 when + we were told to use utf-8 in the log message has been transplanted + from "mailinfo" to "commit" and "commit-tree". + + * Messages given by "git <subcommand> -h" from many subcommands have + been marked for translation. + + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.12 +------------------- + +Unless otherwise noted, all the fixes since v1.7.12 in the +maintenance track are contained in this release (see release notes +to them for details). + + * The attribute system may be asked for a path that itself or its + leading directories no longer exists in the working tree, and it is + fine if we cannot open .gitattribute file in such a case. Failure + to open per-directory .gitattributes with error status other than + ENOENT and ENOTDIR should be diagnosed, but it wasn't. + + * When looking for $HOME/.gitconfig etc., it is OK if we cannot read + them because they do not exist, but we did not diagnose existing + files that we cannot read. + + * When "git am" is fed an input that has multiple "Content-type: ..." + header, it did not grok charset= attribute correctly. + + * "git am" mishandled a patch attached as application/octet-stream + (e.g. not text/*); Content-Transfer-Encoding (e.g. base64) was not + honored correctly. + + * "git blame MAKEFILE" run in a history that has "Makefile" but not + "MAKEFILE" should say "No such file MAKEFILE in HEAD", but got + confused on a case insensitive filesystem and failed to do so. + + * Even during a conflicted merge, "git blame $path" always meant to + blame uncommitted changes to the "working tree" version; make it + more useful by showing cleanly merged parts as coming from the other + branch that is being merged. + + * It was unclear in the documentation for "git blame" that it is + unnecessary for users to use the "--follow" option. + + * Output from "git branch -v" contains "(no branch)" that could be + localized, but the code to align it along with the names of + branches was counting in bytes, not in display columns. + + * "git cherry-pick A C B" used to replay changes in A and then B and + then C if these three commits had committer timestamps in that + order, which is not what the user who said "A C B" naturally + expects. + + * A repository created with "git clone --single" had its fetch + refspecs set up just like a clone without "--single", leading the + subsequent "git fetch" to slurp all the other branches, defeating + the whole point of specifying "only this branch". + + * Documentation talked about "first line of commit log" when it meant + the title of the commit. The description was clarified by defining + how the title is decided and rewording the casual mention of "first + line" to "title". + + * "git cvsimport" did not thoroughly cleanse tag names that it + inferred from the names of the tags it obtained from CVS, which + caused "git tag" to barf and stop the import in the middle. + + * Earlier we made the diffstat summary line that shows the number of + lines added/deleted localizable, but it was found irritating having + to see them in various languages on a list whose discussion language + is English, and this change has been reverted. + + * "git fetch --all", when passed "--no-tags", did not honor the + "--no-tags" option while fetching from individual remotes (the same + issue existed with "--tags", but the combination "--all --tags" makes + much less sense than "--all --no-tags"). + + * "git fetch" over http had an old workaround for an unlikely server + misconfiguration; it turns out that this hurts debuggability of the + configuration in general, and has been reverted. + + * "git fetch" over http advertised that it supports "deflate", which + is much less common, and did not advertise the more common "gzip" on + its Accept-Encoding header. + + * "git fetch" over the dumb-http revision walker could segfault when + curl's multi interface was used. + + * "git gc --auto" notified the user that auto-packing has triggered + even under the "--quiet" option. + + * After "gitk" showed the contents of a tag, neither "Reread + references" nor "Reload" updated what is shown as the + contents of it when the user overwrote the tag with "git tag -f". + + * "git log --all-match --grep=A --grep=B" ought to show commits that + mention both A and B, but when these three options are used with + --author or --committer, it showed commits that mention either A or + B (or both) instead. + + * The "-Xours" backend option to "git merge -s recursive" was ignored + for binary files. + + * "git p4", when "--use-client-spec" and "--detect-branches" are used + together, misdetected branches. + + * "git receive-pack" (the counterpart to "git push") did not give + progress output while processing objects it received to the puser + when run over the smart-http protocol. + + * When you misspell the command name you give to the "exec" action in + the "git rebase -i" instruction sheet you were told that 'rebase' is not a + git subcommand from "git rebase --continue". + + * The subcommand in "git remote" to remove a defined remote was + "rm" and the command did not take a fully-spelled "remove". + + * The interactive prompt that "git send-email" gives was error prone. It + asked "What e-mail address do you want to use?" with the address it + guessed (correctly) the user would want to use in its prompt, + tempting the user to say "y". But the response was taken as "No, + please use 'y' as the e-mail address instead", which is most + certainly not what the user meant. + + * "git show --format='%ci'" did not give the timestamp correctly for + commits created without human readable name on the "committer" line. + + * "git show --quiet" ought to be a synonym for "git show -s", but + wasn't. + + * "git submodule frotz" was not diagnosed as "frotz" being an unknown + subcommand to "git submodule"; the user instead got a complaint + that "git submodule status" was run with an unknown path "frotz". + + * "git status" honored the ignore=dirty settings in .gitmodules but + "git commit" didn't. + + * "gitweb" did not give the correct committer timezone in its feed + output due to a typo. diff --git a/Documentation/RelNotes/1.8.1.1.txt b/Documentation/RelNotes/1.8.1.1.txt new file mode 100644 index 0000000000..6cde07ba29 --- /dev/null +++ b/Documentation/RelNotes/1.8.1.1.txt @@ -0,0 +1,87 @@ +Git 1.8.1.1 Release Notes +========================= + +Fixes since v1.8.1 +------------------ + + * The attribute mechanism didn't allow limiting attributes to be + applied to only a single directory itself with "path/" like the + exclude mechanism does. + + * When attempting to read the XDG-style $HOME/.config/git/config and + finding that $HOME/.config/git is a file, we gave a wrong error + message, instead of treating the case as "a custom config file does + not exist there" and moving on. + + * After failing to create a temporary file using mkstemp(), failing + pathname was not reported correctly on some platforms. + + * http transport was wrong to ask for the username when the + authentication is done by certificate identity. + + * The behaviour visible to the end users was confusing, when they + attempt to kill a process spawned in the editor that was in turn + launched by Git with SIGINT (or SIGQUIT), as Git would catch that + signal and die. We ignore these signals now. + + * A child process that was killed by a signal (e.g. SIGINT) was + reported in an inconsistent way depending on how the process was + spawned by us, with or without a shell in between. + + * After "git add -N" and then writing a tree object out of the + index, the cache-tree data structure got corrupted. + + * "git apply" misbehaved when fixing whitespace breakages by removing + excess trailing blank lines in some corner cases. + + * A tar archive created by "git archive" recorded a directory in a + way that made NetBSD's implementation of "tar" sometimes unhappy. + + * When "git clone --separate-git-dir=$over_there" is interrupted, it + failed to remove the real location of the $GIT_DIR it created. + This was most visible when interrupting a submodule update. + + * "git fetch --mirror" and fetch that uses other forms of refspec + with wildcard used to attempt to update a symbolic ref that match + the wildcard on the receiving end, which made little sense (the + real ref that is pointed at by the symbolic ref would be updated + anyway). Symbolic refs no longer are affected by such a fetch. + + * The "log --graph" codepath fell into infinite loop in some + corner cases. + + * "git merge" started calling prepare-commit-msg hook like "git + commit" does some time ago, but forgot to pay attention to the exit + status of the hook. + + * "git pack-refs" that ran in parallel to another process that + created new refs had a race that can lose new ones. + + * When a line to be wrapped has a solid run of non space characters + whose length exactly is the wrap width, "git shortlog -w" failed + to add a newline after such a line. + + * The way "git svn" asked for password using SSH_ASKPASS and + GIT_ASKPASS was not in line with the rest of the system. + + * "gitweb", when sorting by age to show repositories with new + activities first, used to sort repositories with absolutely + nothing in it early, which was not very useful. + + * "gitweb", when sorting by age to show repositories with new + activities first, used to sort repositories with absolutely + nothing in it early, which was not very useful. + + * When autoconf is used, any build on a different commit always ran + "config.status --recheck" even when unnecessary. + + * Some scripted programs written in Python did not get updated when + PYTHON_PATH changed. + + * We have been carrying a translated and long-unmaintained copy of an + old version of the tutorial; removed. + + * Portability issues in many self-test scripts have been addressed. + + +Also contains other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.8.1.2.txt b/Documentation/RelNotes/1.8.1.2.txt new file mode 100644 index 0000000000..76ad0b3d01 --- /dev/null +++ b/Documentation/RelNotes/1.8.1.2.txt @@ -0,0 +1,13 @@ +Git 1.8.1.2 Release Notes +========================= + +Fixes since v1.8.1.1 +-------------------- + + * "git archive" did not record uncompressed size in the header when + streaming a zip archive, which confused some implementations of unzip. + + * When users spelled "cc:" in lowercase in the fake "header" in the + trailer part, "git send-email" failed to pick up the addresses from + there. As e-mail headers field names are case insensitive, this + script should follow suit and treat "cc:" and "Cc:" the same way. diff --git a/Documentation/RelNotes/1.8.1.txt b/Documentation/RelNotes/1.8.1.txt new file mode 100644 index 0000000000..d6f9555923 --- /dev/null +++ b/Documentation/RelNotes/1.8.1.txt @@ -0,0 +1,241 @@ +Git v1.8.1 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the next major release (not *this* one), we will change the +behavior of the "git push" command. + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). We will use the "simple" semantics that pushes the +current branch to the branch with the same name, only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this, and +"git push" will warn about the upcoming change until you set this +variable in this release. + +"git branch --set-upstream" is deprecated and may be removed in a +relatively distant future. "git branch [-u|--set-upstream-to]" has +been introduced with a saner order of arguments to replace it. + + +Updates since v1.8.0 +-------------------- + +UI, Workflows & Features + + * Command-line completion scripts for tcsh and zsh have been added. + + * "git-prompt" scriptlet (in contrib/completion) can be told to paint + pieces of the hints in the prompt string in colors. + + * Some documentation pages that used to ship only in the plain text + format are now formatted in HTML as well. + + * We used to have a workaround for a bug in ancient "less" that + causes it to exit without any output when the terminal is resized. + The bug has been fixed in "less" version 406 (June 2007), and the + workaround has been removed in this release. + + * When "git checkout" checks out a branch, it tells the user how far + behind (or ahead) the new branch is relative to the remote tracking + branch it builds upon. The message now also advises how to sync + them up by pushing or pulling. This can be disabled with the + advice.statusHints configuration variable. + + * "git config --get" used to diagnose presence of multiple + definitions of the same variable in the same configuration file as + an error, but it now applies the "last one wins" rule used by the + internal configuration logic. Strictly speaking, this may be an + API regression but it is expected that nobody will notice it in + practice. + + * A new configuration variable "diff.context" can be used to + give the default number of context lines in the patch output, to + override the hardcoded default of 3 lines. + + * "git format-patch" learned the "--notes=<ref>" option to give + notes for the commit after the three-dash lines in its output. + + * "git log -p -S<string>" now looks for the <string> after applying + the textconv filter (if defined); earlier it inspected the contents + of the blobs without filtering. + + * "git log --grep=<pcre>" learned to honor the "grep.patterntype" + configuration set to "perl". + + * "git replace -d <object>" now interprets <object> as an extended + SHA-1 (e.g. HEAD~4 is allowed), instead of only accepting full hex + object name. + + * "git rm $submodule" used to punt on removing a submodule working + tree to avoid losing the repository embedded in it. Because + recent git uses a mechanism to separate the submodule repository + from the submodule working tree, "git rm" learned to detect this + case and removes the submodule working tree when it is safe to do so. + + * "git send-email" used to prompt for the sender address, even when + the committer identity is well specified (e.g. via user.name and + user.email configuration variables). The command no longer gives + this prompt when not necessary. + + * "git send-email" did not allow non-address garbage strings to + appear after addresses on Cc: lines in the patch files (and when + told to pick them up to find more recipients), e.g. + + Cc: Stable Kernel <stable@k.org> # for v3.2 and up + + The command now strips " # for v3.2 and up" part before adding the + remainder of this line to the list of recipients. + + * "git submodule add" learned to add a new submodule at the same + path as the path where an unrelated submodule was bound to in an + existing revision via the "--name" option. + + * "git submodule sync" learned the "--recursive" option. + + * "diff.submodule" configuration variable can be used to give custom + default value to the "git diff --submodule" option. + + * "git symbolic-ref" learned the "-d $symref" option to delete the + named symbolic ref, which is more intuitive way to spell it than + "update-ref -d --no-deref $symref". + + +Foreign Interface + + * "git cvsimport" can be told to record timezones (other than GMT) + per-author via its author info file. + + * The remote helper interface to interact with subversion + repositories (one of the GSoC 2012 projects) has been merged. + + * A new remote-helper interface for Mercurial has been added to + contrib/remote-helpers. + + * The documentation for git(1) was pointing at a page at an external + site for the list of authors that no longer existed. The link has + been updated to point at an alternative site. + + +Performance, Internal Implementation, etc. + + * Compilation on Cygwin with newer header files are supported now. + + * A couple of low-level implementation updates on MinGW. + + * The logic to generate the initial advertisement from "upload-pack" + (i.e. what is invoked by "git fetch" on the other side of the + connection) to list what refs are available in the repository has + been optimized. + + * The logic to find set of attributes that match a given path has + been optimized. + + * Use preloadindex in "git diff-index" and "git update-index", which + has a nice speedup on systems with slow stat calls (and even on + Linux). + + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.8.0 +------------------ + +Unless otherwise noted, all the fixes since v1.8.0 in the maintenance +track are contained in this release (see release notes to them for +details). + + * The configuration parser had an unnecessary hardcoded limit on + variable names that was not checked consistently. + + * The "say" function in the test scaffolding incorrectly allowed + "echo" to interpret "\a" as if it were a C-string asking for a + BEL output. + + * "git mergetool" feeds /dev/null as a common ancestor when dealing + with an add/add conflict, but p4merge backend cannot handle + it. Work it around by passing a temporary empty file. + + * "git log -F -E --grep='<ere>'" failed to use the given <ere> + pattern as extended regular expression, and instead looked for the + string literally. + + * "git grep -e pattern <tree>" asked the attribute system to read + "<tree>:.gitattributes" file in the working tree, which was + nonsense. + + * A symbolic ref refs/heads/SYM was not correctly removed with "git + branch -d SYM"; the command removed the ref pointed by SYM + instead. + + * Update "remote tracking branch" in the documentation to + "remote-tracking branch". + + * "git pull --rebase" run while the HEAD is detached tried to find + the upstream branch of the detached HEAD (which by definition + does not exist) and emitted unnecessary error messages. + + * The refs/replace hierarchy was not mentioned in the + repository-layout docs. + + * Various rfc2047 quoting issues around a non-ASCII name on the + From: line in the output from format-patch have been corrected. + + * Sometimes curl_multi_timeout() function suggested a wrong timeout + value when there is no file descriptor to wait on and the http + transport ended up sleeping for minutes in select(2) system call. + A workaround has been added for this. + + * For a fetch refspec (or the result of applying wildcard on one), + we always want the RHS to map to something inside "refs/" + hierarchy, but the logic to check it was not exactly right. + (merge 5c08c1f jc/maint-fetch-tighten-refname-check later to maint). + + * "git diff -G<pattern>" did not honor textconv filter when looking + for changes. + + * Some HTTP servers ask for auth only during the actual packing phase + (not in ls-remote phase); this is not really a recommended + configuration, but the clients used to fail to authenticate with + such servers. + (merge 2e736fd jk/maint-http-half-auth-fetch later to maint). + + * "git p4" used to try expanding malformed "$keyword$" that spans + across multiple lines. + + * Syntax highlighting in "gitweb" was not quite working. + + * RSS feed from "gitweb" had a xss hole in its title output. + + * "git config --path $key" segfaulted on "[section] key" (a boolean + "true" spelled without "=", not "[section] key = true"). + + * "git checkout -b foo" while on an unborn branch did not say + "Switched to a new branch 'foo'" like other cases. + + * Various codepaths have workaround for a common misconfiguration to + spell "UTF-8" as "utf8", but it was not used uniformly. Most + notably, mailinfo (which is used by "git am") lacked this support. + + * We failed to mention a file without any content change but whose + permission bit was modified, or (worse yet) a new file without any + content in the "git diff --stat" output. + + * When "--stat-count" hides a diffstat for binary contents, the total + number of added and removed lines at the bottom was computed + incorrectly. + + * When "--stat-count" hides a diffstat for unmerged paths, the total + number of affected files at the bottom of the "diff --stat" output + was computed incorrectly. + + * "diff --shortstat" miscounted the total number of affected files + when there were unmerged paths. + + * "update-ref -d --deref SYM" to delete a ref through a symbolic ref + that points to it did not remove it correctly. diff --git a/Documentation/RelNotes/1.8.2.txt b/Documentation/RelNotes/1.8.2.txt new file mode 100644 index 0000000000..f6d15059dc --- /dev/null +++ b/Documentation/RelNotes/1.8.2.txt @@ -0,0 +1,261 @@ +Git v1.8.2 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the upcoming major release (tentatively called 1.8.2), we will +change the behavior of the "git push" command. + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). We will use the "simple" semantics that pushes the +current branch to the branch with the same name, only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this. + + +Updates since v1.8.1 +-------------------- + +UI, Workflows & Features + + * Initial ports to QNX and z/OS UNIX System Services have started. + + * Output from the tests is coloured using "green is okay, yellow is + questionable, red is bad and blue is informative" scheme. + + * In bare repositories, "git shortlog" and other commands now read + mailmap files from the tip of the history, to help running these + tools in server settings. + + * Color specifiers, e.g. "%C(blue)Hello%C(reset)", used in the + "--format=" option of "git log" and friends can be disabled when + the output is not sent to a terminal by prefixing them with + "auto,", e.g. "%C(auto,blue)Hello%C(auto,reset)". + + * Scripts can ask Git that wildcard patterns in pathspecs they give do + not have any significance, i.e. take them as literal strings. + + * The pathspec code learned to grok "foo/**/bar" as a pattern that + matches "bar" in 0-or-more levels of subdirectory in "foo". + + * "git blame" (and "git diff") learned the "--no-follow" option. + + * "git cherry-pick" can be used to replay a root commit to an unborn + branch. + + * "git commit" can be told to use --cleanup=whitespace by setting the + configuration variable commit.cleanup to 'whitespace'. + + * "git fetch --mirror" and fetch that uses other forms of refspec + with wildcard used to attempt to update a symbolic ref that match + the wildcard on the receiving end, which made little sense (the + real ref that is pointed at by the symbolic ref would be updated + anyway). Symbolic refs no longer are affected by such a fetch. + + * "git format-patch" now detects more cases in which a whole branch + is being exported, and uses the description for the branch, when + asked to write a cover letter for the series. + + * "git format-patch" learned "-v $count" option, and prepends a + string "v$count-" to the names of its output files, and also + automatically sets the subject prefix to "PATCH v$count". This + allows patches from rerolled series to be stored under different + names and makes it easier to reuse cover letter messsages. + + * "git log" and friends can be told with --use-mailmap option to + rewrite the names and email addresses of people using the mailmap + mechanism. + + * "git push" now requires "-f" to update a tag, even if it is a + fast-forward, as tags are meant to be fixed points. + + * When "git rebase" fails to generate patches to be applied (e.g. due + to oom), it failed to detect the failure and instead behaved as if + there were nothing to do. A workaround to use a temporary file has + been applied, but we probably would want to revisit this later, as + it hurts the common case of not failing at all. + + * "git submodule" started learning a new mode to integrate with the + tip of the remote branch (as opposed to integrating with the commit + recorded in the superproject's gitlink). + + +Foreign Interface + + * "git fast-export" has been updated for its use in the context of + the remote helper interface. + + * A new remote helper to interact with bzr has been added to contrib/. + + +Performance, Internal Implementation, etc. + + * "git fsck" has been taught to be pickier about entries in tree + objects that should not be there, e.g. ".", ".git", and "..". + + * Matching paths with common forms of pathspecs that contain wildcard + characters has been optimized further. + + * The implementation of "imap-send" has been updated to reuse xml + quoting code from http-push codepath. + + * There is a simple-minded checker for the test scripts in t/ + directory to catch most common mistakes (it is not enabled by + default). + + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.8.1 +------------------ + +Unless otherwise noted, all the fixes since v1.8.1 in the maintenance +track are contained in this release (see release notes to them for +details). + + * An element on GIT_CEILING_DIRECTORIES list that does not name the + real path to a directory (i.e. a symbolic link) could have caused + the GIT_DIR discovery logic to escape the ceiling. + (merge 059b379 mh/ceiling later to maint). + + * When attempting to read the XDG-style $HOME/.config/git/config and + finding that $HOME/.config/git is a file, we gave a wrong error + message, instead of treating the case as "a custom config file does + not exist there" and moving on. + (merge 8f2bbe4 jn/warn-on-inaccessible-loosen later to maint). + + * The behaviour visible to the end users was confusing, when they + attempt to kill a process spawned in the editor that was in turn + launched by Git with SIGINT (or SIGQUIT), as Git would catch that + signal and die. We ignore these signals now. + (merge 1250857 pf/editor-ignore-sigint later to maint). + + * A child process that was killed by a signal (e.g. SIGINT) was + reported in an inconsistent way depending on how the process was + spawned by us, with or without a shell in between. + (merge 709ca73 jk/unify-exit-code-by-receiving-signal later to maint). + + * After failing to create a temporary file using mkstemp(), failing + pathname was not reported correctly on some platforms. + (merge f7be59b jc/mkstemp-more-careful-error-reporting later to maint). + + * The attribute mechanism didn't allow limiting attributes to be + applied to only a single directory itself with "path/" like the + exclude mechanism does. + (merge 94bc671 ja/directory-attrs later to maint). + + * "git apply" misbehaved when fixing whitespace breakages by removing + excess trailing blank lines. + (merge 5de7166 jc/apply-trailing-blank-removal later to maint). + + * A tar archive created by "git archive" recorded a directory in a + way that made NetBSD's implementation of "tar" sometimes unhappy. + (merge 22f0dcd rs/leave-base-name-in-name-field-of-tar later to maint). + + * "git archive" did not record uncompressed size in the header when + streaming a zip archive, which confused some implementations of unzip. + (merge 5ea2c84 rs/zip-with-uncompressed-size-in-the-header later to maint). + + * When "git clone --separate-git-dir=$over_there" is interrupted, it + failed to remove the real location of the $GIT_DIR it created. + This was most visible when interrupting a submodule update. + (merge 9be1980 jl/interrupt-clone-remove-separate-git-dir later to maint). + + * The way "git svn" asked for password using SSH_ASKPASS and + GIT_ASKPASS was not in line with the rest of the system. + (merge e9263e4 ss/svn-prompt later to maint). + + * The --graph code fell into infinite loop when asked to do what the + code did not expect. + (merge 656197a mk/maint-graph-infinity-loop later to maint). + + * http transport was wrong to ask for the username when the + authentication is done by certificate identity. + (merge 75e9a40 rb/http-cert-cred-no-username-prompt later to maint). + + * "git pack-refs" that ran in parallel to another process that + created new refs had a nasty race. + (merge b3f1280 jk/repack-ref-racefix later to maint). + + * After "git add -N" and then writing a tree object out of the + index, the cache-tree data structure got corrupted. + (merge eec3e7e nd/invalidate-i-t-a-cache-tree later to maint). + + * "git merge --no-edit" computed who were involved in the work done + on the side branch, even though that information is to be discarded + without getting seen in the editor. + (merge 9bcbb1c jc/maint-fmt-merge-msg-no-edit-lose-credit later to maint). + + * "git merge" started calling prepare-commit-msg hook like "git + commit" does some time ago, but forgot to pay attention to the exit + status of the hook. + (merge 3e4141d ap/merge-stop-at-prepare-commit-msg-failure later to maint). + + * When users spell "cc:" in lowercase in the fake "header" in the + trailer part, "git send-email" failed to pick up the addresses from + there. As e-mail headers field names are case insensitive, this + script should follow suit and treat "cc:" and "Cc:" the same way. + (merge 6310071 nz/send-email-headers-are-case-insensitive later to maint). + + * Output from "git status --ignored" showed an unexpected interaction + with "--untracked". + (merge a45fb69 ap/status-ignored-in-ignored-directory later to maint). + + * "gitweb", when sorting by age to show repositories with new + activities first, used to sort repositories with absolutely + nothing in it early, which was not very useful. + (merge 28dae18 md/gitweb-sort-by-age later to maint). + + * "gitweb"'s code to sanitize control characters before passing it to + "highlight" filter lost known-to-be-safe control characters by + mistake. + (merge 0e901d2 os/gitweb-highlight-uncaptured later to maint). + + * When a line to be wrapped has a solid run of non space characters + whose length exactly is the wrap width, "git shortlog -w" failed + to add a newline after such a line. + (merge e0db176 sp/shortlog-missing-lf later to maint). + + * Command line completion leaked an unnecessary error message while + looking for possible matches with paths in <tree-ish>. + (merge ca87dd6 ds/completion-silence-in-tree-path-probe later to maint). + + * Command line completion for "tcsh" emitted an unwanted space + after completing a single directory name. + (merge 92f1c04 mk/complete-tcsh later to maint). + + * Some shells do not behave correctly when IFS is unset; work it + around by explicitly setting it to the default value. + (merge 393050c jc/maint-fbsd-sh-ifs-workaround later to maint). + + * Some scripted programs written in Python did not get updated when + PYTHON_PATH changed. + (cherry-pick 96a4647fca54031974cd6ad1 later to maint). + + * When autoconf is used, any build on a different commit always ran + "config.status --recheck" even when unnecessary. + (merge 1226504 jn/less-reconfigure later to maint). + + * We have been carrying a translated and long-unmaintained copy of an + old version of the tutorial; removed. + (merge 0a85441 ta/remove-stale-translated-tut later to maint). + + * t4014, t9502 and t0200 tests had various portability issues that + broke on OpenBSD. + (merge 27f6342 jc/maint-test-portability later to maint). + + * t9020 and t3600 tests had various portability issues. + (merge 5a02966 jc/test-portability later to maint). + + * t9200 runs "cvs init" on a directory that already exists, but a + platform can configure this fail for the current user (e.g. you + need to be in the cvsadmin group on NetBSD 6.0). + (merge 8666df0 jc/test-cvs-no-init-in-existing-dir later to maint). + + * t9020 and t9810 had a few non-portable shell script construct. + (merge 2797914 tb/test-t9020-no-which later to maint). + (merge 6f4e505 tb/test-t9810-no-sed-i later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0dbf2c9843..90133d8c3b 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -1,65 +1,5 @@ -Checklist (and a short version for the impatient): - - Commits: - - - make commits of logical units - - check for unnecessary whitespace with "git diff --check" - before committing - - do not check in commented out code or unneeded files - - the first line of the commit message should be a short - description (50 characters is the soft limit, see DISCUSSION - in git-commit(1)), and should skip the full stop - - the body should provide a meaningful commit message, which: - . explains the problem the change tries to solve, iow, what - is wrong with the current code without the change. - . justifies the way the change solves the problem, iow, why - the result with the change is better. - . alternate solutions considered but discarded, if any. - - describe changes in imperative mood, e.g. "make xyzzy do frotz" - instead of "[This patch] makes xyzzy do frotz" or "[I] changed - xyzzy to do frotz", as if you are giving orders to the codebase - to change its behaviour. - - try to make sure your explanation can be understood without - external resources. Instead of giving a URL to a mailing list - archive, summarize the relevant points of the discussion. - - add a "Signed-off-by: Your Name <you@example.com>" line to the - commit message (or just use the option "-s" when committing) - to confirm that you agree to the Developer's Certificate of Origin - - make sure that you have tests for the bug you are fixing - - make sure that the test suite passes after your commit - - Patch: - - - use "git format-patch -M" to create the patch - - do not PGP sign your patch - - do not attach your patch, but read in the mail - body, unless you cannot teach your mailer to - leave the formatting of the patch alone. - - be careful doing cut & paste into your mailer, not to - corrupt whitespaces. - - provide additional information (which is unsuitable for - the commit message) between the "---" and the diffstat - - if you change, add, or remove a command line option or - make some other user interface change, the associated - documentation should be updated as well. - - if your name is not writable in ASCII, make sure that - you send off a message in the correct encoding. - - send the patch to the list (git@vger.kernel.org) and the - maintainer (gitster@pobox.com) if (and only if) the patch - is ready for inclusion. If you use git-send-email(1), - please test it first by sending email to yourself. - - see below for instructions specific to your mailer - -Long version: - -I started reading over the SubmittingPatches document for Linux -kernel, primarily because I wanted to have a document similar to -it for the core GIT to make sure people understand what they are -doing when they write "Signed-off-by" line. - -But the patch submission requirements are a lot more relaxed -here on the technical/contents front, because the core GIT is -thousand times smaller ;-). So here is only the relevant bits. +Here are some guidelines for people who want to contribute their code +to this software. (0) Decide what to base your work on. @@ -86,6 +26,10 @@ change is relevant to. wait until some of the dependent topics graduate to 'master', and rebase your work. + - Some parts of the system have dedicated maintainers with their own + repositories (see the section "Subsystems" below). Changes to + these parts should be based on their trees. + To find the tip of a topic branch, run "git log --first-parent master..pu" and look for the merge commit. The second parent of this commit is the tip of the topic branch. @@ -113,26 +57,53 @@ change, the approach taken by the change, and if relevant how this differs substantially from the prior version, are all good things to have. +Make sure that you have tests for the bug you are fixing. + +When adding a new feature, make sure that you have new tests to show +the feature triggers the new behaviour when it should, and to show the +feature does not trigger when it shouldn't. Also make sure that the +test suite passes after your commit. Do not forget to update the +documentation to describe the updated behaviour. + Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped in templates/hooks--pre-commit. To help ensure this does not happen, run git diff --check on your changes before you commit. -(1a) Try to be nice to older C compilers +(2) Describe your changes well. + +The first line of the commit message should be a short description (50 +characters is the soft limit, see DISCUSSION in git-commit(1)), and +should skip the full stop. It is also conventional in most cases to +prefix the first line with "area: " where the area is a filename or +identifier for the general area of the code being modified, e.g. + + . archive: ustar header checksum is computed unsigned + . git-cherry-pick.txt: clarify the use of revision range notation + +If in doubt which identifier to use, run "git log --no-merges" on the +files you are modifying to see the current conventions. -We try to support a wide range of C compilers to compile -git with. That means that you should not use C99 initializers, even -if a lot of compilers grok it. +The body should provide a meaningful commit message, which: -Also, variables have to be declared at the beginning of the block -(you can check this with gcc, using the -Wdeclaration-after-statement -option). + . explains the problem the change tries to solve, iow, what is wrong + with the current code without the change. -Another thing: NULL pointers shall be written as NULL, not as 0. + . justifies the way the change solves the problem, iow, why the + result with the change is better. + . alternate solutions considered but discarded, if any. -(2) Generate your patch using git tools out of your commits. +Describe your changes in imperative mood, e.g. "make xyzzy do frotz" +instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy +to do frotz", as if you are giving orders to the codebase to change +its behaviour. Try to make sure your explanation can be understood +without external resources. Instead of giving a URL to a mailing list +archive, summarize the relevant points of the discussion. + + +(3) Generate your patch using git tools out of your commits. git based diff tools generate unidiff which is the preferred format. @@ -140,22 +111,27 @@ 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 receiving end can handle them just fine. -Please make sure your patch does not include any extra files -which do not belong in a patch submission. Make sure to review +Please make sure your patch does not add commented out debugging code, +or include any extra files which do not relate to what your patch +is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before sending out, please make sure it cleanly applies to the "master" branch head. If you are preparing a work based on "next" branch, that is fine, but please mark it as such. -(3) Sending your patches. +(4) Sending your patches. People on the git mailing list need to be able to read and comment on the changes you are submitting. It is important for a developer to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of your code. For this reason, all patches should be submitted -"inline". WARNING: Be wary of your MUAs word-wrap +"inline". If your log message (including your name on the +Signed-off-by line) is not writable in ASCII, make sure that +you send off a message in the correct encoding. + +WARNING: Be wary of your MUAs word-wrap corrupting your patch. Do not cut-n-paste your patch; you can lose tabs that way if you are not careful. @@ -179,7 +155,8 @@ message starts, you can put a "From: " line to name that person. You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" -material between the three dash lines and the diffstat. +material between the three dash lines and the diffstat. Git-notes +can also be inserted using the `--notes` option. Do not attach the patch as a MIME attachment, compressed or not. Do not let your e-mail client send quoted-printable. Do not let @@ -207,19 +184,25 @@ patch, format it as "multipart/signed", not a text/plain message that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is not a text/plain, it's something else. -Unless your patch is a very trivial and an obviously correct one, -first send it with "To:" set to the mailing list, with "cc:" listing +Send your patch with "To:" set to the mailing list, with "cc:" listing people who are involved in the area you are touching (the output from "git blame $path" and "git shortlog --no-merges $path" would help to -identify them), to solicit comments and reviews. After the list -reached a consensus that it is a good idea to apply the patch, re-send -it with "To:" set to the maintainer and optionally "cc:" the list for -inclusion. Do not forget to add trailers such as "Acked-by:", -"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as -necessary. +identify them), to solicit comments and reviews. + +After the list reached a consensus that it is a good idea to apply the +patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the +list [*2*] for inclusion. + +Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and +"Tested-by:" lines as necessary to credit people who helped your +patch. + [Addresses] + *1* The current maintainer: gitster@pobox.com + *2* The mailing list: git@vger.kernel.org -(4) Sign your work + +(5) Sign your work To improve tracking of who did what, we've borrowed the "sign-off" procedure from the Linux kernel project on patches @@ -290,6 +273,26 @@ You can also create your own tag or use one that's in common usage such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". ------------------------------------------------ +Subsystems with dedicated maintainers + +Some parts of the system have dedicated maintainers with their own +repositories. + + - git-gui/ comes from git-gui project, maintained by Pat Thoyts: + + git://repo.or.cz/git-gui.git + + - gitk-git/ comes from Paul Mackerras's gitk project: + + git://ozlabs.org/~paulus/gitk + + - po/ comes from the localization coordinator, Jiang Xin: + + https://github.com/git-l10n/git-po/ + +Patches to these parts should be based on their trees. + +------------------------------------------------ An ideal patch flow Here is an ideal patch flow for this project the current maintainer diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index aea8627be0..1273a85c8a 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -36,7 +36,7 @@ ifndef::git-asciidoc-no-roff[] # v1.72 breaks with this because it replaces dots not in roff requests. [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> ifdef::doctype-manpage[] .ft C endif::doctype-manpage[] @@ -53,7 +53,7 @@ ifdef::doctype-manpage[] # The following two small workarounds insert a simple paragraph after screen [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> | </literallayout><simpara></simpara> {title#}</example> @@ -90,6 +90,8 @@ endif::backend-docbook[] endif::doctype-manpage[] ifdef::backend-xhtml11[] +[attributes] +git-relative-html-prefix= [linkgit-inlinemacro] -<a href="{target}.html">{target}{0?({0})}</a> +<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a> endif::backend-xhtml11[] diff --git a/Documentation/config.txt b/Documentation/config.txt index 83ad8ebce0..b87f744643 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -95,8 +95,8 @@ included file is expanded immediately, as if its contents had been found at the location of the include directive. If the value of the `include.path` variable is a relative path, the path is considered to be relative to the configuration file in which the include directive was -found. The value of `include.path` is subject to tilde expansion: `{tilde}/` -is expanded to the value of `$HOME`, and `{tilde}user/` to the specified +found. The value of `include.path` is subject to tilde expansion: `~/` +is expanded to the value of `$HOME`, and `~user/` to the specified user's home directory. See below for examples. Example @@ -140,10 +140,11 @@ advice.*:: can tell Git that you do not need help by setting these to 'false': + -- - pushNonFastForward:: + pushUpdateRejected:: Set this variable to 'false' if you want to disable - 'pushNonFFCurrent', 'pushNonFFDefault', and - 'pushNonFFMatching' simultaneously. + 'pushNonFFCurrent', 'pushNonFFDefault', + 'pushNonFFMatching', and 'pushAlreadyExists' + simultaneously. pushNonFFCurrent:: Advice shown when linkgit:git-push[1] fails due to a non-fast-forward update to the current branch. @@ -158,10 +159,15 @@ advice.*:: 'matching refs' explicitly (i.e. you used ':', or specified a refspec that isn't your current branch) and it resulted in a non-fast-forward error. + pushAlreadyExists:: + Shown when linkgit:git-push[1] rejects an update that + does not qualify for fast-forwarding (e.g., a tag.) 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. + Show directions on how to proceed from the current + state in the output of linkgit:git-status[1], in + the template shown when writing commit messages in + linkgit:git-commit[1], and in the help message shown + by linkgit:git-checkout[1] when switching branch. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to merge to avoid overwriting local changes. @@ -176,6 +182,9 @@ advice.*:: 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. + amWorkDir:: + Advice that shows the location of the patch file when + linkgit:git-am[1] fails to apply it. -- core.fileMode:: @@ -210,6 +219,15 @@ The default is false, except linkgit:git-clone[1] or linkgit:git-init[1] will probe and set core.ignorecase true if appropriate when the repository is created. +core.precomposeunicode:: + This option is only used by Mac OS implementation of git. + When core.precomposeunicode=true, git reverts the unicode decomposition + of filenames done by Mac OS. This is useful when sharing a repository + between Mac OS and Linux or Windows. + (Git for Windows 1.7.10 or higher is needed, or git under cygwin 1.7). + When false, file names are handled fully transparent by git, + which is backward compatible with older versions of git. + core.trustctime:: If false, the ctime differences between the index and the working tree are ignored; useful when the inode change time @@ -481,9 +499,11 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. core.excludesfile:: In addition to '.gitignore' (per-directory) and '.git/info/exclude', git looks into this file for patterns - of files which are not meant to be tracked. "{tilde}/" is expanded - to the value of `$HOME` and "{tilde}user/" to the specified user's - home directory. See linkgit:gitignore[5]. + of files which are not meant to be tracked. "`~/`" is expanded + to the value of `$HOME` and "`~user/`" to the specified user's + home directory. Its default value is $XDG_CONFIG_HOME/git/ignore. + If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/ignore + is used instead. See linkgit:gitignore[5]. core.askpass:: Some commands (e.g. svn and http interfaces) that interactively @@ -498,7 +518,9 @@ core.attributesfile:: In addition to '.gitattributes' (per-directory) and '.git/info/attributes', git looks into this file for attributes (see linkgit:gitattributes[5]). Path expansions are made the same - way as for `core.excludesfile`. + way as for `core.excludesfile`. Its default value is + $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not + set or empty, $HOME/.config/git/attributes is used instead. core.editor:: Commands such as `commit` and `tag` that lets you edit @@ -521,14 +543,14 @@ core.pager:: `LESS` variable to some other value. Alternately, these settings can be overridden on a project or global basis by setting the `core.pager` option. - Setting `core.pager` has no affect on the `LESS` + Setting `core.pager` has no effect on the `LESS` environment variable behaviour above, so if you want to override git's default settings this way, you need to be explicit. For example, to disable the S option in a backward compatible manner, set `core.pager` - to `less -+$LESS -FRX`. This will be passed to the - shell by git, which will translate the final command to - `LESS=FRSX less -+FRSX -FRX`. + to `less -+S`. This will be passed to the shell by + git, which will translate the final command to + `LESS=FRSX less -+S`. core.whitespace:: A comma separated list of common whitespace problems to @@ -542,8 +564,9 @@ core.whitespace:: * `space-before-tab` treats a space character that appears immediately before a tab character in the initial indent part of the line as an error (enabled by default). -* `indent-with-non-tab` treats a line that is indented with 8 or more - space characters as an error (not enabled by default). +* `indent-with-non-tab` treats a line that is indented with space + characters instead of the equivalent tabs as an error (not enabled by + default). * `tab-in-indent` treats a tab character in the initial indent part of the line as an error (not enabled by default). * `blank-at-eof` treats blank lines added at the end of file as an error @@ -716,6 +739,12 @@ branch.<name>.rebase:: it unless you understand the implications (see linkgit:git-rebase[1] for details). +branch.<name>.description:: + Branch description, can be edited with + `git branch --edit-description`. Branch description is + automatically added in the format-patch cover letter or + request-pull summary. + browser.<tool>.cmd:: Specify the command to invoke the specified browser. The specified command is evaluated in shell with the URLs passed @@ -856,6 +885,53 @@ color.ui:: `never` if you prefer git commands not to use color unless enabled explicitly with some other configuration or the `--color` option. +column.ui:: + Specify whether supported commands should output in columns. + This variable consists of a list of tokens separated by spaces + or commas: ++ +-- +`always`;; + always show in columns +`never`;; + never show in columns +`auto`;; + show in columns if the output is to the terminal +`column`;; + fill columns before rows (default) +`row`;; + fill rows before columns +`plain`;; + show in one column +`dense`;; + make unequal size columns to utilize more space +`nodense`;; + make equal size columns +-- ++ +This option defaults to 'never'. + +column.branch:: + Specify whether to output branch listing in `git branch` in columns. + See `column.ui` for details. + +column.status:: + Specify whether to output untracked files in `git status` in columns. + See `column.ui` for details. + +column.tag:: + Specify whether to output tag listing in `git tag` in columns. + See `column.ui` for details. + +commit.cleanup:: + This setting overrides the default of the `--cleanup` option in + `git commit`. See linkgit:git-commit[1] for details. Changing the + default can be useful when you always want to keep lines that begin + with comment character `#` in your log message, in which case you + would do `git config commit.cleanup whitespace` (note that you will + have to remove the help lines that begin with `#` in the commit log + template yourself, if you do this). + commit.status:: A boolean to enable/disable inclusion of status information in the commit message template when using an editor to prepare the commit @@ -863,7 +939,7 @@ commit.status:: commit.template:: Specify a file to use as the template for new commit messages. - "{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the + "`~/`" is expanded to the value of `$HOME` and "`~user/`" to the specified user's home directory. credential.helper:: @@ -906,12 +982,6 @@ difftool.<tool>.cmd:: difftool.prompt:: Prompt before each invocation of the diff tool. -diff.wordRegex:: - A POSIX Extended Regular Expression used to determine what is a "word" - when performing word-by-word difference calculations. Character - sequences that match the regular expression are "words", all other - characters are *ignorable* whitespace. - fetch.recurseSubmodules:: This option can be either set to a boolean value or to 'on-demand'. Setting it to a boolean changes the behavior of fetch and pull to @@ -988,7 +1058,7 @@ format.thread:: a boolean value, or `shallow` or `deep`. `shallow` threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the - `\--in-reply-to`, and the first patch mail, in this order. + `--in-reply-to`, and the first patch mail, in this order. `deep` threading makes every mail a reply to the previous one. A true boolean value is the same as `shallow`, and a false value disables threading. @@ -1155,8 +1225,16 @@ gitweb.snapshot:: grep.lineNumber:: If set to true, enable '-n' option by default. +grep.patternType:: + Set the default matching behavior. Using a value of 'basic', 'extended', + 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', + '--fixed-strings', or '--perl-regexp' option accordingly, while the + value 'default' will return to the default matching behavior. + grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. + If set to true, enable '--extended-regexp' option by default. This + option is ignored when the 'grep.patternType' option is set to a value + other than 'default'. gpg.program:: Use this custom program instead of "gpg" found on $PATH when @@ -1292,6 +1370,12 @@ help.autocorrect:: value is 0 - the command will be just shown but not executed. This is the default. +help.htmlpath:: + Specify the path where the HTML documentation resides. File system paths + and URLs are supported. HTML pages will be prefixed with this path when + help is displayed in the 'web' format. This defaults to the documentation + path of your Git installation. + http.proxy:: Override the HTTP proxy, normally configured using the 'http_proxy', 'https_proxy', and 'all_proxy' environment variables (see @@ -1419,7 +1503,7 @@ 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 by the `\--patch` mode of + 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 @@ -1427,13 +1511,13 @@ interactive.singlekey:: 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`. + 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. Setting a value for log.date is similar to using 'git log''s - `\--date` option. Possible values are `relative`, `local`, + `--date` option. Possible values are `relative`, `local`, `default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1] for details. @@ -1450,6 +1534,10 @@ log.showroot:: Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which normally hide the root commit will now show it. True by default. +log.mailmap:: + If true, makes linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] assume `--use-mailmap`. + mailmap.file:: The location of an augmenting mailmap file. The default mailmap, located in the root of the repository, is loaded @@ -1458,6 +1546,14 @@ mailmap.file:: subdirectory, or somewhere outside of the repository itself. See linkgit:git-shortlog[1] and linkgit:git-blame[1]. +mailmap.blob:: + Like `mailmap.file`, but consider the value as a reference to a + blob in the repository. If both `mailmap.file` and + `mailmap.blob` are given, both are parsed, with entries from + `mailmap.file` taking precedence. In a bare repository, this + defaults to `HEAD:.mailmap`. In a non-bare repository, it + defaults to empty. + man.viewer:: Specify the programs that may be used to display help in the 'man' format. See linkgit:git-help[1]. @@ -1623,18 +1719,18 @@ pack.indexVersion:: and this config option ignored whenever the corresponding pack is larger than 2 GB. + -If you have an old git that does not understand the version 2 `{asterisk}.idx` file, +If you have an old git that does not understand the version 2 `*.idx` file, cloning or fetching over a non native protocol (e.g. "http" and "rsync") -that will copy both `{asterisk}.pack` file and corresponding `{asterisk}.idx` file from the +that will copy both `*.pack` file and corresponding `*.idx` file from the other side may give you a repository that cannot be accessed with your -older version of git. If the `{asterisk}.pack` file is smaller than 2 GB, however, +older version of git. If the `*.pack` file is smaller than 2 GB, however, you can use linkgit:git-index-pack[1] on the *.pack file to regenerate -the `{asterisk}.idx` file. +the `*.idx` file. pack.packSizeLimit:: The maximum size of a pack. This setting only affects packing to a file when repacking, i.e. the git:// protocol - is unaffected. It can be overridden by the `\--max-pack-size` + is unaffected. It can be overridden by the `--max-pack-size` option of linkgit:git-repack[1]. The minimum size allowed is limited to 1 MiB. The default is unlimited. Common unit suffixes of 'k', 'm', or 'g' are @@ -1644,8 +1740,8 @@ pager.<cmd>:: If the value is boolean, turns on or off pagination of the output of a particular git subcommand when writing to a tty. Otherwise, turns on pagination for the subcommand using the - pager specified by the value of `pager.<cmd>`. If `\--paginate` - or `\--no-pager` is specified on the command line, it takes + pager specified by the value of `pager.<cmd>`. If `--paginate` + or `--no-pager` is specified on the command line, it takes precedence over this option. To disable pagination for all commands, set `core.pager` or `GIT_PAGER` to `cat`. @@ -1653,9 +1749,9 @@ pretty.<name>:: Alias for a --pretty= format string, as specified in linkgit:git-log[1]. Any aliases defined here can be used just as the built-in pretty formats could. For example, - running `git config pretty.changelog "format:{asterisk} %H %s"` + running `git config pretty.changelog "format:* %H %s"` would cause the invocation `git log --pretty=changelog` - to be equivalent to running `git log "--pretty=format:{asterisk} %H %s"`. + to be equivalent to running `git log "--pretty=format:* %H %s"`. Note that an alias with the same name as a built-in format will be silently ignored. @@ -1682,13 +1778,33 @@ push.default:: no refspec is implied by any of the options given on the command line. Possible values are: + +-- * `nothing` - do not push anything. -* `matching` - push all matching branches. - All branches having the same name in both ends are considered to be - matching. This is the default. +* `matching` - push all branches having the same name in both ends. + This is for those who prepare all the branches into a publishable + shape and then push them out with a single command. It is not + appropriate for pushing into a repository shared by multiple users, + since locally stalled branches will attempt a non-fast forward push + if other users updated the branch. + + + This is currently the default, but Git 2.0 will change the default + to `simple`. * `upstream` - push the current branch to its upstream branch. -* `tracking` - deprecated synonym for `upstream`. + With this, `git push` will update the same remote ref as the one which + is merged by `git pull`, making `push` and `pull` symmetrical. + See "branch.<name>.merge" for how to configure the upstream branch. +* `simple` - like `upstream`, but refuses to push if the upstream + branch's name is different from the local one. This is the safest + option and is well-suited for beginners. It will become the default + in Git 2.0. * `current` - push the current branch to a branch of the same name. +-- ++ +The `simple`, `current` and `upstream` modes are for those who want to +push out a single branch after finishing work, even when the other +branches are not yet ready to be pushed out. If you are working with +other people to push into the same shared repository, you would want +to use one of these. rebase.stat:: Whether to show a diffstat of what changed upstream since the last @@ -1768,7 +1884,7 @@ remote.<name>.push:: remote.<name>.mirror:: If true, pushing to this remote will automatically behave - as if the `\--mirror` option was given on the command line. + as if the `--mirror` option was given on the command line. remote.<name>.skipDefaultUpdate:: If true, this remote will be skipped by default when updating @@ -1916,6 +2032,12 @@ submodule.<name>.update:: URL and other values found in the `.gitmodules` file. See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. +submodule.<name>.branch:: + The remote branch name for a submodule, used by `git submodule + update --remote`. Set this option to override the value found in + the `.gitmodules` file. See linkgit:git-submodule[1] and + linkgit:gitmodules[5] for details. + submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this submodule. It can be overridden by using the --[no-]recurse-submodules diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 6aa1be0478..4314ad0fbb 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -54,7 +54,11 @@ and accumulating child directory counts in the parent directories: diff.statGraphWidth:: Limit the width of the graph part in --stat output. If set, applies - to all commands generating --stat outuput except format-patch. + to all commands generating --stat output except format-patch. + +diff.context:: + Generate diffs with <n> lines of context instead of the default + of 3. This value is overridden by the -U option. diff.external:: If this config variable is set, diff generation is not @@ -103,6 +107,19 @@ diff.suppressBlankEmpty:: A boolean to inhibit the standard behavior of printing a space before each empty output line. Defaults to false. +diff.submodule:: + Specify the format in which differences in submodules are + shown. The "log" format lists the commits in the range like + linkgit:git-submodule[1] `summary` does. The "short" format + format just shows the names of the commits at the beginning + and end of the range. Defaults to short. + +diff.wordRegex:: + A POSIX Extended Regular Expression used to determine what is a "word" + when performing word-by-word difference calculations. Character + sequences that match the regular expression are "words", all other + characters are *ignorable* whitespace. + diff.<driver>.command:: The custom diff driver command. See linkgit:gitattributes[5] for details. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index c57460c03d..55f499a160 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -175,7 +175,7 @@ In the above example output, the function signature was changed from both files (hence two `-` removals from both file1 and file2, plus `++` to mean one line that was added does not appear in either file1 nor file2). Also eight other lines are the same -from file1 but do not appear in file2 (hence prefixed with `{plus}`). +from file1 but do not appear in file2 (hence prefixed with `+`). When shown by `git diff-tree -c`, it compares the parents of a merge commit with the merge result (i.e. file1..fileN are the diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 378f19f0e2..39f2c5074c 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -59,7 +59,7 @@ endif::git-format-patch[] Generate a diffstat. By default, as much space as necessary will be used for the filename part, and the rest for the graph part. Maximum width defaults to terminal width, or 80 columns - if not connected to a terminal, and can be overriden by + if not connected to a terminal, and can be overridden by `<width>`. The width of the filename part can be limited by giving another width `<name-width>` after a comma. The width of the graph part can be limited by using @@ -74,7 +74,7 @@ These parameters can also be set individually with `--stat-width=<width>`, `--stat-name-width=<name-width>` and `--stat-count=<count>`. --numstat:: - Similar to `\--stat`, but shows number of added and + Similar to `--stat`, but shows number of added and deleted lines in decimal notation and pathname without abbreviation, to make it more machine friendly. For binary files, outputs two `-` instead of saying @@ -170,7 +170,8 @@ any of those replacements occurred. the commits in the range like linkgit:git-submodule[1] `summary` does. Omitting the `--submodule` option or specifying `--submodule=short`, uses the 'short' format. This format just shows the names of the commits - at the beginning and end of the range. + at the beginning and end of the range. Can be tweaked via the + `diff.submodule` configuration variable. --color[=<when>]:: Show colored diff. @@ -308,7 +309,11 @@ endif::git-log[] index (i.e. amount of addition/deletions compared to the file's size). For example, `-M90%` means git should consider a delete/add pair to be a rename if more than 90% of the file - hasn't changed. + hasn't changed. Without a `%` sign, the number is to be read as + a fraction, with a decimal point before it. I.e., `-M5` becomes + 0.5, and is thus the same as `-M50%`. Similarly, `-M05` is + the same as `-M5%`. To limit detection to exact renames, use + `-M100%`. -C[<n>]:: --find-copies[=<n>]:: diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index ae413e52a5..048337b40f 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -98,8 +98,8 @@ you originally wrote. <9> switch to the master branch. <10> merge a topic branch into your master branch. <11> review commit logs; other forms to limit output can be -combined and include `\--max-count=10` (show 10 commits), -`\--until=2005-12-10`, etc. +combined and include `--max-count=10` (show 10 commits), +`--until=2005-12-10`, etc. <12> view only the changes that touch what's in `curses/` directory, since `v2.43` tag. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 39d326abc6..6e98bdf149 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -10,7 +10,8 @@ --depth=<depth>:: Deepen the history of a 'shallow' repository created by `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) - by the specified number of commits. + to the specified number of commits from the tip of each remote + branch history. Tags for the deepened commits are not fetched. ifndef::git-pull[] --dry-run:: @@ -56,14 +57,11 @@ endif::git-pull[] ifndef::git-pull[] -t:: --tags:: - Most of the tags are fetched automatically as branch - heads are downloaded, but tags that do not point at - objects reachable from the branch heads that are being - tracked will not be fetched by this mechanism. This - flag lets all tags and their associated objects be - downloaded. The default behavior for a remote may be - specified with the remote.<name>.tagopt setting. See - linkgit:git-config[1]. + This is a short-hand for giving "refs/tags/*:refs/tags/*" + refspec from the command line, to ask all tags to be fetched + and stored locally. Because this acts as an explicit + refspec, the default refspecs (configured with the + remote.$name.fetch variable) are overridden and not used. --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 9c1d395722..fd9e36b99f 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -155,7 +155,7 @@ Configuration The optional configuration variable `core.excludesfile` indicates a path to a file containing patterns of file names to exclude from git-add, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to -those in info/exclude. See linkgit:gitrepository-layout[5]. +those in info/exclude. See linkgit:gitignore[5]. EXAMPLES diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index afd2c9ae59..634b84e4b9 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -9,7 +9,7 @@ git-apply - Apply a patch to files and/or to the index SYNOPSIS -------- [verse] -'git apply' [--stat] [--numstat] [--summary] [--check] [--index] +'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--3way] [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached] @@ -72,6 +72,15 @@ OPTIONS cached data, apply the patch, and store the result in the index without using the working tree. This implies `--index`. +-3:: +--3way:: + When the patch does not apply cleanly, fall back on 3-way merge if + the patch records the identity of blobs it is supposed to apply to, + and we have those blobs available locally, possibly leaving the + conflict markers in the files in the working tree for the user to + resolve. This option implies the `--index` option, and is incompatible + with the `--reject` and the `--cached` options. + --build-fake-ancestor=<file>:: Newer 'git diff' output has embedded 'index information' for each blob to help identify the original version that diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index ac7006e640..59d73e532f 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -160,7 +160,7 @@ EXAMPLES 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`:: +`git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip >git-1.4.0.tar.gz`:: Create a compressed tarball for v1.4.0 release, but without a global extended pax header. diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 8a2ba37904..ec4497e098 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -257,7 +257,7 @@ Date: Sat May 3 11:59:44 2008 -0700 Linux 2.6.26-rc1 -:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M Makefile +:100644 100644 5cf82581... 4492984e... M Makefile ------------- At this point we can see what the commit does, check it out (if it's @@ -331,7 +331,7 @@ Date: Sat May 3 11:59:44 2008 -0700 Linux 2.6.26-rc1 -:100644 100644 5cf8258195331a4dbdddff08b8d68642638eea57 4492984efc09ab72ff6219a7bc21fb6a957c4cd5 M Makefile +:100644 100644 5cf82581... 4492984e... M Makefile bisect run success ------------- diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 9516914236..e44173f66a 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -20,6 +20,12 @@ last modified the line. Optionally, start annotating from the given revision. The command can also limit the range of lines annotated. +The origin of lines is automatically followed across whole-file +renames (currently there is no option to turn the rename-following +off). To follow lines moved from one file to another, or to follow +lines that were copied and pasted from another file, etc., see the +`-C` and `-M` options. + The report does not tell you anything about lines which have been deleted or replaced; you need to use a tool such as 'git diff' or the "pickaxe" interface briefly mentioned in the following paragraph. @@ -160,7 +166,7 @@ introduced the file with: git log --diff-filter=A --pretty=short -- foo and then annotate the change between the commit and its -parents, using `commit{caret}!` notation: +parents, using `commit^!` notation: git blame -C -C -f $commit^! -- foo diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index e71370d6b4..45a225e0aa 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -10,8 +10,11 @@ SYNOPSIS [verse] 'git branch' [--color[=<when>] | --no-color] [-r | -a] [--list] [-v [--abbrev=<length> | --no-abbrev]] + [--column[=<options>] | --no-column] [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] +'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] +'git branch' --unset-upstream [<branchname>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> 'git branch' (-d | -D) [-r] <branchname>... 'git branch' --edit-description [<branchname>] @@ -47,7 +50,7 @@ branch so that 'git pull' will appropriately merge from the remote-tracking branch. This behavior may be changed via the global `branch.autosetupmerge` configuration flag. That setting can be overridden by using the `--track` and `--no-track` options, and -changed later using `git branch --set-upstream`. +changed later using `git branch --set-upstream-to`. With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match @@ -107,6 +110,14 @@ OPTIONS default to color output. Same as `--color=never`. +--column[=<options>]:: +--no-column:: + Display branch listing in columns. See configuration variable + column.branch for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' respectively. ++ +This option is only applicable in non-verbose mode. + -r:: --remotes:: List or delete (if used with -d) the remote-tracking branches. @@ -120,11 +131,13 @@ OPTIONS use `git branch --list <pattern>` to list matching branches. -v:: +-vv:: --verbose:: When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print - the name of the upstream branch, as well. + the name of the upstream branch, as well (see also `git remote + show <remote>`). -q:: --quiet:: @@ -164,6 +177,16 @@ start-point is either a local or remote-tracking branch. like `--track` would when creating the branch, except that where branch points to is not changed. +-u <upstream>:: +--set-upstream-to=<upstream>:: + Set up <branchname>'s tracking information so <upstream> is + considered <branchname>'s upstream branch. If no <branchname> + is specified, then it defaults to the current branch. + +--unset-upstream:: + Remove the upstream information for <branchname>. If no branch + is specified it defaults to the current branch. + --edit-description:: Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. `request-pull`). diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 92b01ec25d..bc023cc5f3 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -61,7 +61,7 @@ unbundle <file>:: A list of arguments, acceptable to 'git rev-parse' and 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES below), that specifies the specific objects and references - to transport. For example, `master{tilde}10..master` causes the + to transport. For example, `master~10..master` causes the current master reference to be packaged along with all objects added since its 10th ancestor commit. There is no explicit limit to the number of references and objects that may be @@ -80,12 +80,12 @@ SPECIFYING REFERENCES 'git bundle' will only package references that are shown by 'git show-ref': this includes heads, tags, and remote heads. References -such as `master{tilde}1` cannot be packaged, but are perfectly suitable for +such as `master~1` cannot be packaged, but are perfectly suitable for defining the basis. More than one reference may be packaged, and more than one basis can be specified. The objects packaged are those not contained in the union of the given bases. Each basis can be -specified explicitly (e.g. `^master{tilde}10`), or implicitly (e.g. -`master{tilde}10..master`, `--since=10.days.ago master`). +specified explicitly (e.g. `^master~10`), or implicitly (e.g. +`master~10..master`, `--since=10.days.ago master`). It is very important that the basis used be held by the destination. It is okay to err on the side of caution, causing the bundle file @@ -112,13 +112,12 @@ machineA$ git bundle create file.bundle master machineA$ git tag -f lastR2bundle master ---------------- -Then you transfer file.bundle to the target machine B. If you are creating -the repository on machine B, then you can clone from the bundle as if it -were a remote repository instead of creating an empty repository and then -pulling or fetching objects from the bundle: +Then you transfer file.bundle to the target machine B. Because this +bundle does not require any existing object to be extracted, you can +create a new repository on machine B by cloning from it: ---------------- -machineB$ git clone /home/me/tmp/file.bundle R2 +machineB$ git clone -b master /home/me/tmp/file.bundle R2 ---------------- This will define a remote called "origin" in the resulting repository that diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 103e7b128d..98009d1bd5 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -40,9 +40,9 @@ git imposes the following rules on how references are named: . They cannot have ASCII control characters (i.e. bytes whose values are lower than \040, or \177 `DEL`), space, tilde `~`, - caret `{caret}`, or colon `:` anywhere. + caret `^`, or colon `:` anywhere. -. They cannot have question-mark `?`, asterisk `{asterisk}`, or open +. They cannot have question-mark `?`, asterisk `*`, or open bracket `[` anywhere. See the `--refspec-pattern` option below for an exception to this rule. @@ -62,10 +62,10 @@ unquoted (by mistake), and also avoids ambiguities in certain reference name expressions (see linkgit:gitrevisions[7]): . A double-dot `..` is often used as in `ref1..ref2`, and in some - contexts this notation means `{caret}ref1 ref2` (i.e. not in + contexts this notation means `^ref1 ref2` (i.e. not in `ref1` and in `ref2`). -. A tilde `~` and caret `{caret}` are used to introduce the postfix +. A tilde `~` and caret `^` are used to introduce the postfix 'nth parent' and 'peel onion' operation. . A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s @@ -92,9 +92,9 @@ OPTIONS --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}` + enabled, <refname> is allowed to contain a single `*` in place of a one full pathname component (e.g., - `foo/{asterisk}/bar` but not `foo/bar{asterisk}`). + `foo/*/bar` but not `foo/bar*`). --normalize:: Normalize 'refname' by removing any leading slash (`/`) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index c0a96e6c1e..6f04d22f5e 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -21,18 +21,34 @@ or the specified tree. If no paths are given, 'git checkout' will also update `HEAD` to set the specified branch as the current branch. -'git checkout' [<branch>]:: +'git checkout' <branch>:: + To prepare for working on <branch>, switch to it by updating + the index and the files in the working tree, and by pointing + HEAD at the branch. Local modifications to the files in the + working tree are kept, so that they can be committed to the + <branch>. ++ +If <branch> is not found but there does exist a tracking branch in +exactly one remote (call it <remote>) with a matching name, treat as +equivalent to ++ +------------ +$ git checkout -b <branch> --track <remote>/<branch> +------------ ++ +You could omit <branch>, in which case the command degenerates to +"check out the current branch", which is a glorified no-op with a +rather expensive side-effects to show only the tracking information, +if exists, for the current branch. + 'git checkout' -b|-B <new_branch> [<start point>]:: -'git checkout' [--detach] [<commit>]:: - This form switches branches by updating the index, working - tree, and HEAD to reflect the specified branch or commit. -+ -If `-b` is given, a new branch is created as if linkgit:git-branch[1] -were called and then checked out; in this case you can -use the `--track` or `--no-track` options, which will be passed to -'git branch'. As a convenience, `--track` without `-b` implies branch -creation; see the description of `--track` below. + Specifying `-b` causes a new branch to be created as if + linkgit:git-branch[1] were called and then checked out. In + this case you can use the `--track` or `--no-track` options, + which will be passed to 'git branch'. As a convenience, + `--track` without `-b` implies branch creation; see the + description of `--track` below. + If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it is reset. This is the transactional equivalent of @@ -45,6 +61,21 @@ $ git checkout <branch> that is to say, the branch is not reset/created unless "git checkout" is successful. +'git checkout' --detach [<branch>]:: +'git checkout' <commit>:: + + Prepare to work on top of <commit>, by detaching HEAD at it + (see "DETACHED HEAD" section), and updating the index and the + files in the working tree. Local modifications to the files + in the working tree are kept, so that the resulting working + tree will be the state recorded in the commit plus the local + modifications. ++ +Passing `--detach` forces this behavior in the case of a <branch> (without +the option, giving a branch name to the command would check out the branch, +instead of detaching HEAD at it), or the current commit, +if no <branch> is specified. + 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...:: When <paths> or `--patch` are given, 'git checkout' does *not* @@ -84,11 +115,11 @@ entries; instead, unmerged entries are ignored. When checking out paths from the index, check out stage #2 ('ours') or #3 ('theirs') for unmerged paths. --b:: +-b <new_branch>:: Create a new branch named <new_branch> and start it at <start_point>; see linkgit:git-branch[1] for details. --B:: +-B <new_branch>:: Creates the branch <new_branch> and start it at <start_point>; if it already exists, then reset it to <start_point>. This is equivalent to running "git branch" with "-f"; see @@ -124,7 +155,7 @@ explicitly give a name with '-b' in such a case. <commit> is not a branch name. See the "DETACHED HEAD" section below for details. ---orphan:: +--orphan <new_branch>:: Create a new 'orphan' branch, named <new_branch>, started from <start_point> and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new @@ -184,7 +215,7 @@ the conflicted merge in the specified paths. + This means that you can use `git checkout -p` to selectively discard edits from your current working tree. See the ``Interactive Mode'' -section of linkgit:git-add[1] to learn how to operate the `\--patch` mode. +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, @@ -193,11 +224,11 @@ section of linkgit:git-add[1] to learn how to operate the `\--patch` mode. commit, your HEAD becomes "detached" and you are no longer on any branch (see below for details). + -As a special case, the `"@\{-N\}"` syntax for the N-th last branch +As a special case, the `"@{-N}"` syntax for the N-th last branch checks out the branch (instead of detaching). You may also specify -`-` which is synonymous with `"@\{-1\}"`. +`-` which is synonymous with `"@{-1}"`. + -As a further special case, you may use `"A\...B"` as a shortcut for the +As a further special case, you may use `"A...B"` as a shortcut for the merge base of `A` and `B` if there is exactly one merge base. You can leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. @@ -367,6 +398,18 @@ $ git checkout hello.c <3> <2> take a file out of another commit <3> restore hello.c from the index + +If you want to check out _all_ C source files out of the index, +you can say ++ +------------ +$ git checkout -- '*.c' +------------ ++ +Note the quotes around `*.c`. The file `hello.c` will also be +checked out, even though it is no longer in the working tree, +because the file globbing is used to match entries in the index +(not in the working tree by the shell). ++ If you have an unfortunate branch that is named `hello.c`, this step would be confused as an instruction to switch to that branch. You should instead write: diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 3d25a20b67..c205d2363e 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -47,7 +47,9 @@ OPTIONS linkgit:gitrevisions[7]. Sets of commits can be passed but no traversal is done by default, as if the '--no-walk' option was specified, see - linkgit:git-rev-list[1]. + linkgit:git-rev-list[1]. Note that specifying a range will + feed all <commit>... arguments to a single revision walk + (see a later example that uses 'maint master..next'). -e:: --edit:: @@ -116,6 +118,11 @@ effect to your index in a row. previous commit are dropped. To force the inclusion of those commits use `--keep-redundant-commits`. +--allow-empty-message:: + By default, cherry-picking a commit with an empty message will fail. + This option overrides that behaviour, allowing commits with empty + messages to be cherry picked. + --keep-redundant-commits:: If a commit being cherry picked duplicates a commit already in the current history, it will become empty. By default these @@ -149,7 +156,16 @@ EXAMPLES 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 maint next ^master`:: +`git cherry-pick maint master..next`:: + + Apply the changes introduced by all commits that are + ancestors of maint or next, but not master or any of its + ancestors. Note that the latter does not mean `maint` and + everything between `master` and `next`; specifically, + `maint` will not be used if it is included in `master`. + +`git cherry-pick master~4 master~2`:: Apply the changes introduced by the fifth and third last commits pointed to by master and create 2 new commits with @@ -170,7 +186,7 @@ EXAMPLES 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-clean.txt b/Documentation/git-clean.txt index 79fb984144..9f42c0d0e6 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -63,6 +63,10 @@ OPTIONS Remove only files ignored by git. This may be useful to rebuild everything from scratch, but keep manually created files. +SEE ALSO +-------- +linkgit:gitignore[5] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 6e22522c4f..7fefdb0384 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -29,7 +29,8 @@ currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without arguments will in addition merge the remote master branch into the -current master branch, if any. +current master branch, if any (this is untrue when "--single-branch" +is given; see below). This default configuration is achieved by creating references to the remote branch heads under `refs/remotes/origin` and @@ -46,13 +47,18 @@ OPTIONS mechanism and clones the repository by making a copy of HEAD and everything under objects and refs directories. The files under `.git/objects/` directory are hardlinked - to save space when possible. This is now the default when - the source repository is specified with `/path/to/repo` - syntax, so it essentially is a no-op option. To force - copying instead of hardlinking (which may be desirable - if you are trying to make a back-up of your repository), - but still avoid the usual "git aware" transport - mechanism, `--no-hardlinks` can be used. + to save space when possible. ++ +If the repository is specified as a local path (e.g., `/path/to/repo`), +this is the default, and --local is essentially a no-op. If the +repository is specified as a URL, then this flag is ignored (and we +never use the local optimizations). Specifying `--no-local` will +override the default when `/path/to/repo` is given, using the regular +git transport instead. ++ +To force copying instead of hardlinking (which may be desirable if you +are trying to make a back-up of your repository), but still avoid the +usual "git aware" transport mechanism, `--no-hardlinks` can be used. --no-hardlinks:: Optimize the cloning process from a repository on a @@ -147,9 +153,10 @@ objects from the source repository into a pack in the cloned repository. -b <name>:: Instead of pointing the newly created HEAD to the branch pointed to by the cloned repository's HEAD, point to `<name>` branch - instead. `--branch` can also take tags and treat them like - detached HEAD. In a non-bare repository, this is the branch - that will be checked out. + instead. In a non-bare repository, this is the branch that will + be checked out. + `--branch` can also take tags and detaches the HEAD at that commit + in the resulting repository. --upload-pack <upload-pack>:: -u <upload-pack>:: @@ -188,6 +195,11 @@ objects from the source repository into a pack in the cloned repository. clone with the `--depth` option, this is the default, unless `--no-single-branch` is given to fetch the histories near the tips of all branches. + Further fetches into the resulting repository will only update the + remote-tracking branch for the branch this option was used for the + initial cloning. If the HEAD at the remote did not point at any + branch when `--single-branch` clone was made, no remote-tracking + branch is created. --recursive:: --recurse-submodules:: diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt new file mode 100644 index 0000000000..5d6f1cc464 --- /dev/null +++ b/Documentation/git-column.txt @@ -0,0 +1,53 @@ +git-column(1) +============= + +NAME +---- +git-column - Display data in columns + +SYNOPSIS +-------- +[verse] +'git column' [--command=<name>] [--[raw-]mode=<mode>] [--width=<width>] + [--indent=<string>] [--nl=<string>] [--padding=<n>] + +DESCRIPTION +----------- +This command formats its input into multiple columns. + +OPTIONS +------- +--command=<name>:: + Look up layout mode using configuration variable column.<name> and + column.ui. + +--mode=<mode>:: + Specify layout mode. See configuration variable column.ui for option + syntax. + +--raw-mode=<n>:: + Same as --mode but take mode encoded as a number. This is mainly used + by other commands that have already parsed layout mode. + +--width=<width>:: + Specify the terminal width. By default 'git column' will detect the + terminal width, or fall back to 80 if it is unable to do so. + +--indent=<string>:: + String to be printed at the beginning of each line. + +--nl=<N>:: + String to be printed at the end of each line, + including newline character. + +--padding=<N>:: + The number of spaces between columns. One space by default. + + +Author +------ +Written by Nguyen Thai Ngoc Duy <pclouds@gmail.com> + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index cfb9906bb5..a221169515 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -45,7 +45,7 @@ OPTIONS 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 + A paragraph in the commit log message. This can be given more than once and each <message> becomes its own paragraph. -F <file>:: @@ -72,13 +72,13 @@ if set: GIT_COMMITTER_NAME GIT_COMMITTER_EMAIL GIT_COMMITTER_DATE - EMAIL (nb "<", ">" and "\n"s are stripped) 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 the hostname used for outgoing mail (taken +present, the environment variable EMAIL, or, if that is not set, +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). @@ -88,15 +88,6 @@ for one to be entered and terminated with ^D. include::date-formats.txt[] -Diagnostics ------------ -You don't exist. Go away!:: - The passwd(5) gecos field couldn't be read -Your parents must have hated you!:: - The passwd(5) gecos field is longer than a giant static buffer. -Your sysadmin must hate you!:: - The passwd(5) name field is longer than a giant static buffer. - Discussion ---------- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 68abfcacca..41b27da325 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -13,7 +13,7 @@ SYNOPSIS [-F <file> | -m <msg>] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] [--status | --no-status] - [-i | -o] [--] [<file>...] + [-i | -o] [-S[<keyid>]] [--] [<file>...] DESCRIPTION ----------- @@ -42,7 +42,7 @@ The content to be added can be specified in several ways: 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 + 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 @@ -101,12 +101,20 @@ OPTIONS When doing a dry-run, give the output in the short-format. See linkgit:git-status[1] for details. Implies `--dry-run`. +--branch:: + Show the branch and tracking info even in short-format. + --porcelain:: When doing a dry-run, give the output in a porcelain-ready format. See linkgit:git-status[1] for details. Implies `--dry-run`. +--long:: + When doing a dry-run, give the output in a the long-format. + Implies `--dry-run`. + -z:: +--null:: When showing `short` or `porcelain` status output, terminate entries in the status output with NUL, instead of LF. If no format is given, implies the `--porcelain` output format. @@ -171,7 +179,9 @@ OPTIONS only if the message is to be edited. Otherwise only whitespace removed. The 'verbatim' mode does not change message at all, 'whitespace' removes just leading/trailing whitespace lines - and 'strip' removes both whitespace and commentary. + and 'strip' removes both whitespace and commentary. The default + can be changed by the 'commit.cleanup' configuration variable + (see linkgit:git-config[1]). -e:: --edit:: @@ -180,6 +190,11 @@ OPTIONS commit log message unmodified. This option lets you further edit the message taken from these sources. +--no-edit:: + Use the selected commit message without launching an editor. + For example, `git commit --amend --no-edit` amends a commit + without changing its commit message. + --amend:: Used to amend the tip of the current branch. Prepare the tree object you would want to replace the latest commit as usual @@ -205,6 +220,9 @@ You should understand the implications of rewriting history if you amend a commit that has already been published. (See the "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) +--no-post-rewrite:: + Bypass the post-rewrite hook. + -i:: --include:: Before making a commit out of staged contents so far, @@ -268,6 +286,10 @@ configuration variable documented in linkgit:git-config[1]. commit message template when using an editor to prepare the default commit message. +-S[<keyid>]:: +--gpg-sign[=<keyid>]:: + GPG-sign commit. + \--:: Do not interpret any more arguments as options. @@ -287,7 +309,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, @@ -381,8 +403,10 @@ DISCUSSION Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. -Tools that turn commits into email, for example, use the first line -on the Subject: line and the rest of the commit in the body. +The text up to the first blank line in a commit message is treated +as the commit title, and that title is used throughout git. +For example, linkgit:git-format-patch[1] turns a commit into email, and it uses +the title on the Subject line and the rest of the commit in the body. include::i18n.txt[] @@ -399,6 +423,15 @@ This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, and `post-commit` hooks. See linkgit:githooks[5] for more information. +FILES +----- + +`$GIT_DIR/COMMIT_EDITMSG`:: + This file contains the commit message of a commit in progress. + If `git commit` exits due to an error before creating a commit, + any commit message that has been provided by the user (e.g., in + an editor session) will be available in this file, but will be + overwritten by the next invocation of `git commit`. SEE ALSO -------- diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 81b03982e3..9ae2508f3f 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -44,22 +44,26 @@ a "true" or "false" string for bool), or '--path', which does some path expansion (see '--path' below). If no type specifier is passed, no checks or transformations are performed on the value. -The file-option can be one of '--system', '--global' or '--file' -which specify where the values will be read from or written to. -The default is to assume the config file of the current repository, -.git/config unless defined otherwise with GIT_DIR and GIT_CONFIG -(see <<FILES>>). +When reading, the values are read from the system, global and +repository local configuration files by default, and options +'--system', '--global', '--local' and '--file <filename>' can be +used to tell the command to read from only that location (see <<FILES>>). -This command will fail (with exit code ret) if: +When writing, the new value is written to the repository local +configuration file by default, and options '--system', '--global', +'--file <filename>' can be used to tell the command to write to +that location (you can say '--local' but that is the default). + +This command will fail with non-zero status upon error. Some exit +codes are: . The config file is invalid (ret=3), . can not write to the config file (ret=4), . no section or name was provided (ret=2), . the section or key is invalid (ret=1), . you try to unset an option which does not exist (ret=5), -. you try to unset/set an option for which multiple lines match (ret=5), -. you try to use an invalid regexp (ret=6), or -. you use '--global' option without $HOME being properly set (ret=128). +. you try to unset/set an option for which multiple lines match (ret=5), or +. you try to use an invalid regexp (ret=6). On success, the command returns the exit code 0. @@ -93,10 +97,11 @@ OPTIONS --global:: For writing options: write to global ~/.gitconfig file rather than - the repository .git/config. + the repository .git/config, write to $XDG_CONFIG_HOME/git/config file + if this file exists and the ~/.gitconfig file doesn't. + -For reading options: read only from global ~/.gitconfig rather than -from all available files. +For reading options: read only from global ~/.gitconfig and from +$XDG_CONFIG_HOME/git/config rather than from all available files. + See also <<FILES>>. @@ -190,18 +195,24 @@ See also <<FILES>>. FILES ----- -If not set explicitly with '--file', there are three files where +If not set explicitly with '--file', there are four files where 'git config' will search for configuration options: $GIT_DIR/config:: - Repository specific configuration file. (The filename is - of course relative to the repository root, not the working - directory.) + Repository specific configuration file. ~/.gitconfig:: User-specific configuration file. Also called "global" configuration file. +$XDG_CONFIG_HOME/git/config:: + Second user-specific configuration file. If $XDG_CONFIG_HOME is not set + or empty, $HOME/.config/git/config will be used. Any single-valued + variable set in this file will be overwritten by whatever is in + ~/.gitconfig. It is a good idea not to create this file if + you sometimes use older versions of Git, as support for this + file was added fairly recently. + $(prefix)/etc/gitconfig:: System-wide configuration file. @@ -229,6 +240,10 @@ GIT_CONFIG:: Using the "--global" option forces this to ~/.gitconfig. Using the "--system" option forces this to $(prefix)/etc/gitconfig. +GIT_CONFIG_NOSYSTEM:: + Whether to skip reading settings from the system-wide + $(prefix)/etc/gitconfig file. See linkgit:git[1] for details. + See also <<FILES>>. @@ -256,7 +271,7 @@ Given a .git/config like this: ; Proxy settings [core] - gitproxy="proxy-command" for kernel.org + gitproxy=proxy-command for kernel.org gitproxy=default-proxy ; for all the rest you can set the filemode to true with @@ -331,7 +346,7 @@ To actually match only values with an exclamation mark, you have to To add a new proxy, without altering any of the existing ones, use ------------ -% git config core.gitproxy '"proxy-command" for example.com' +% git config --add core.gitproxy '"proxy-command" for example.com' ------------ An example to use customized color from the configuration in your diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt index 11edc5a173..d15db42d43 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -3,7 +3,7 @@ git-credential-cache--daemon(1) NAME ---- -git-credential-cache--daemon - temporarily store user credentials in memory +git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index f3d09c5d51..eeff5fa989 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -3,7 +3,7 @@ git-credential-cache(1) NAME ---- -git-credential-cache - helper to temporarily store passwords in memory +git-credential-cache - Helper to temporarily store passwords in memory SYNOPSIS -------- diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 31093467d1..b27c03c361 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -3,7 +3,7 @@ git-credential-store(1) NAME ---- -git-credential-store - helper to store credentials on disk +git-credential-store - Helper to store credentials on disk SYNOPSIS -------- diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt new file mode 100644 index 0000000000..810e957124 --- /dev/null +++ b/Documentation/git-credential.txt @@ -0,0 +1,154 @@ +git-credential(1) +================= + +NAME +---- +git-credential - Retrieve and store user credentials + +SYNOPSIS +-------- +------------------ +git credential <fill|approve|reject> +------------------ + +DESCRIPTION +----------- + +Git has an internal interface for storing and retrieving credentials +from system-specific helpers, as well as prompting the user for +usernames and passwords. The git-credential command exposes this +interface to scripts which may want to retrieve, store, or prompt for +credentials in the same manner as git. The design of this scriptable +interface models the internal C API; see +link:technical/api-credentials.txt[the git credential API] for more +background on the concepts. + +git-credential takes an "action" option on the command-line (one of +`fill`, `approve`, or `reject`) and reads a credential description +on stdin (see <<IOFMT,INPUT/OUTPUT FORMAT>>). + +If the action is `fill`, git-credential will attempt to add "username" +and "password" attributes to the description by reading config files, +by contacting any configured credential helpers, or by prompting the +user. The username and password attributes of the credential +description are then printed to stdout together with the attributes +already provided. + +If the action is `approve`, git-credential will send the description +to any configured credential helpers, which may store the credential +for later use. + +If the action is `reject`, git-credential will send the description to +any configured credential helpers, which may erase any stored +credential matching the description. + +If the action is `approve` or `reject`, no output should be emitted. + +TYPICAL USE OF GIT CREDENTIAL +----------------------------- + +An application using git-credential will typically use `git +credential` following these steps: + + 1. Generate a credential description based on the context. ++ +For example, if we want a password for +`https://example.com/foo.git`, we might generate the following +credential description (don't forget the blank line at the end; it +tells `git credential` that the application finished feeding all the +infomation it has): + + protocol=https + host=example.com + path=foo.git + + 2. Ask git-credential to give us a username and password for this + description. This is done by running `git credential fill`, + feeding the description from step (1) to its standard input. The complete + credential description (including the credential per se, i.e. the + login and password) will be produced on standard output, like: + + protocol=https + host=example.com + username=bob + password=secr3t ++ +In most cases, this means the attributes given in the input will be +repeated in the output, but git may also modify the credential +description, for example by removing the `path` attribute when the +protocol is HTTP(s) and `credential.useHttpPath` is false. ++ +If the `git credential` knew about the password, this step may +not have involved the user actually typing this password (the +user may have typed a password to unlock the keychain instead, +or no user interaction was done if the keychain was already +unlocked) before it returned `password=secr3t`. + + 3. Use the credential (e.g., access the URL with the username and + password from step (2)), and see if it's accepted. + + 4. Report on the success or failure of the password. If the + credential allowed the operation to complete successfully, then + it can be marked with an "approve" action to tell `git + credential` to reuse it in its next invocation. If the credential + was rejected during the operation, use the "reject" action so + that `git credential` will ask for a new password in its next + invocation. In either case, `git credential` should be fed with + the credential description obtained from step (2) (which also + contain the ones provided in step (1)). + +[[IOFMT]] +INPUT/OUTPUT FORMAT +------------------- + +`git credential` reads and/or writes (depending on the action used) +credential information in its standard input/output. This information +can correspond either to keys for which `git credential` will obtain +the login/password information (e.g. host, protocol, path), or to the +actual credential data to be obtained (login/password). + +The credential is split into a set of named attributes, with one +attribute 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 understands the following attributes: + +`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. + +`url`:: + + When this special attribute is read by `git credential`, the + value is parsed as a URL and treated as if its constituent parts + were read (e.g., `url=https://example.com` would behave as if + `protocol=https` and `host=example.com` had been provided). This + can help callers avoid parsing URLs themselves. Note that any + components which are missing from the URL (e.g., there is no + username in the example above) will be set to empty; if you want + to provide a URL and override some attributes, provide the URL + attribute first, followed by any overrides. diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 6695ab3b4b..9d5353e8be 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -137,17 +137,19 @@ This option can be used several times to provide several detection regexes. -A <author-conv-file>:: CVS by default uses the Unix username when writing its commit logs. Using this option and an author-conv-file - in this format + maps the name recorded in CVS to author name, e-mail and + optional timezone: + --------- exon=Andreas Ericsson <ae@op5.se> - spawn=Simon Pawn <spawn@frog-pond.org> + spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago --------- + 'git cvsimport' will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly -all along. +all along. If a timezone is specified, GIT_AUTHOR_DATE will +have the corresponding offset applied. + For convenience, this data is saved to `$GIT_DIR/cvs-authors` each time the '-A' option is provided and read from that same @@ -211,11 +213,9 @@ Problems related to tags: * Multiple tags on the same revision are not imported. If you suspect that any of these issues may apply to the repository you -want to import consider using these alternative tools which proved to be -more stable in practice: +want to imort, consider using cvs2git: -* cvs2git (part of cvs2svn), `http://cvs2svn.tigris.org` -* parsecvs, `http://cgit.freedesktop.org/~keithp/parsecvs` +* cvs2git (part of cvs2svn), `http://subversion.apache.org/` GIT --- diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 827bc988ed..88d814af0e 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 31b28fc29f..7e5098a95e 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -16,6 +16,7 @@ SYNOPSIS [--reuseaddr] [--detach] [--pid-file=<file>] [--enable=<service>] [--disable=<service>] [--allow-override=<service>] [--forbid-override=<service>] + [--access-hook=<path>] [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]] [<directory>...] @@ -171,6 +172,21 @@ the facility of inet daemon to achieve the same before spawning errors are not enabled, all errors report "access denied" to the client. The default is --no-informative-errors. +--access-hook=<path>:: + Every time a client connects, first run an external command + specified by the <path> with service name (e.g. "upload-pack"), + path to the repository, hostname (%H), canonical hostname + (%CH), ip address (%IP), and tcp port (%P) as its command line + arguments. The external command can decide to decline the + service by exiting with a non-zero status (or to allow it by + exiting with a zero status). It can also look at the $REMOTE_ADDR + and $REMOTE_PORT environment variables to learn about the + requestor when making this decision. ++ +The external command can optionally write a single line to its +standard output to be sent to the requestor as an error message when +it declines the service. + <directory>:: A directory to add to the whitelist of allowed directories. Unless --strict-paths is specified this will also include subdirectories @@ -204,7 +220,7 @@ receive-pack:: can push anything into the repository, including removal of refs). This is solely meant for a closed LAN setting where everybody is friendly. This service can be - enabled by `daemon.receivepack` configuration item to + enabled by setting `daemon.receivepack` configuration item to `true`. EXAMPLES diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 039cce2e98..72d6bb612b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -36,12 +36,12 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref - found in `.git/refs/`. This option enables matching + found in `refs/` namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. This option enables matching + found in `refs/tags` namespace. This option enables matching a lightweight (non-annotated) tag. --contains:: diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index f8d0819113..f8c06013f3 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git diff' [options] [<commit>] [--] [<path>...] 'git diff' [options] --cached [<commit>] [--] [<path>...] 'git diff' [options] <commit> <commit> [--] [<path>...] +'git diff' [options] <blob> <blob> 'git diff' [options] [--no-index] [--] <path> <path> DESCRIPTION @@ -55,6 +56,11 @@ directories. This behavior can be forced by --no-index. This is to view the changes between two arbitrary <commit>. +'git diff' [options] <blob> <blob>:: + + This form is to view the differences between the raw + contents of two blob objects. + 'git diff' [--options] <commit>..<commit> [--] [<path>...]:: This is synonymous to the previous form. If <commit> on @@ -72,8 +78,7 @@ directories. This behavior can be forced by --no-index. Just in case if you are doing something exotic, it should be noted that all of the <commit> in the above description, except in the last two forms that use ".." notations, can be any -<tree>. The third form ('git diff <commit> <commit>') can also -be used to compare two <blob> objects. +<tree>. For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index fe38f667f9..73ca7025a3 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -19,6 +19,12 @@ linkgit:git-diff[1]. OPTIONS ------- +-d:: +--dir-diff:: + Copy the modified files to a temporary location and perform + a directory diff on them. This mode never prompts before + launching the diff tool. + -y:: --no-prompt:: Do not prompt before launching a diff tool. @@ -30,11 +36,9 @@ OPTIONS -t <tool>:: --tool=<tool>:: - Use the diff tool specified by <tool>. - Valid diff tools are: - araxis, bc3, deltawalker, diffuse, emerge, ecmerge, gvimdiff, - kdiff3, kompare, meld, opendiff, p4merge, tkdiff, vimdiff and - xxdiff. + Use the diff tool specified by <tool>. Valid values include + emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help` + for the list of valid <tool> settings. + If a diff tool is not specified, 'git difftool' will use the configuration variable `diff.tool`. If the @@ -62,6 +66,17 @@ of the diff post-image. `$MERGED` is the name of the file which is being compared. `$BASE` is provided for compatibility with custom merge tool commands and has the same value as `$MERGED`. +--tool-help:: + Print a list of diff tools that may be used with `--tool`. + +--symlinks:: +--no-symlinks:: + 'git difftool''s default behavior is create symlinks to the + working tree when run in `--dir-diff` mode. ++ + Specifying `--no-symlinks` instructs 'git difftool' to create + copies instead. `--no-symlinks` is the default on Windows. + -x <command>:: --extcmd=<command>:: Specify a custom command for viewing diffs. diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index f37eada63a..d6487e1ce0 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -104,7 +104,7 @@ marks the same across runs. [<git-rev-list-args>...]:: A list of arguments, acceptable to 'git rev-parse' and 'git rev-list', that specifies the specific objects and references - to export. For example, `master{tilde}10..master` causes the + to export. For example, `master~10..master` causes the current master reference to be exported along with all objects added since its 10th ancestor commit. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index b52dca5133..bf1a02a80d 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -33,34 +33,46 @@ the frontend program in use. OPTIONS ------- ---date-format=<fmt>:: - Specify the type of dates the frontend will supply to - fast-import within `author`, `committer` and `tagger` commands. - See ``Date Formats'' below for details about which formats - are supported, and their syntax. --force:: Force updating modified existing branches, even if doing so would cause commits to be lost (as the new commit does not contain the old commit). ---max-pack-size=<n>:: - Maximum size of each output packfile. - The default is unlimited. +--quiet:: + Disable all non-fatal output, making fast-import silent when it + is successful. This option disables the output shown by + \--stats. ---big-file-threshold=<n>:: - Maximum size of a blob that fast-import will attempt to - create a delta for, expressed in bytes. The default is 512m - (512 MiB). Some importers may wish to lower this on systems - with constrained memory. +--stats:: + Display some basic statistics about the objects fast-import has + created, the packfiles they were stored into, and the + memory used by fast-import during this run. Showing this output + is currently the default, but can be disabled with \--quiet. ---depth=<n>:: - Maximum delta depth, for blob and tree deltification. - Default is 10. +Options for Frontends +~~~~~~~~~~~~~~~~~~~~~ ---active-branches=<n>:: - Maximum number of branches to maintain active at once. - See ``Memory Utilization'' below for details. Default is 5. +--cat-blob-fd=<fd>:: + Write responses to `cat-blob` and `ls` queries to the + file descriptor <fd> instead of `stdout`. Allows `progress` + output intended for the end-user to be separated from other + output. + +--date-format=<fmt>:: + Specify the type of dates the frontend will supply to + fast-import within `author`, `committer` and `tagger` commands. + See ``Date Formats'' below for details about which formats + are supported, and their syntax. + +--done:: + Terminate with error if there is no `done` command at the end of + the stream. This option might be useful for detecting errors + that cause the frontend to terminate before it has started to + write a stream. + +Locations of Marks Files +~~~~~~~~~~~~~~~~~~~~~~~~ --export-marks=<file>:: Dumps the internal marks table to <file> when complete. @@ -83,31 +95,33 @@ OPTIONS Like --import-marks but instead of erroring out, silently skips the file if it does not exist. ---relative-marks:: +--[no-]relative-marks:: After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. In git-fast-import this means that the paths are relative to the .git/info/fast-import directory. However, other importers may use a different location. ++ +Relative and non-relative marks may be combined by interweaving +--(no-)-relative-marks with the --(import|export)-marks= 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= - options. +Performance and Compression Tuning +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---cat-blob-fd=<fd>:: - Write responses to `cat-blob` and `ls` queries to the - file descriptor <fd> instead of `stdout`. Allows `progress` - output intended for the end-user to be separated from other - output. +--active-branches=<n>:: + Maximum number of branches to maintain active at once. + See ``Memory Utilization'' below for details. Default is 5. ---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. +--big-file-threshold=<n>:: + Maximum size of a blob that fast-import will attempt to + create a delta for, expressed in bytes. The default is 512m + (512 MiB). Some importers may wish to lower this on systems + with constrained memory. + +--depth=<n>:: + Maximum delta depth, for blob and tree deltification. + Default is 10. --export-pack-edges=<file>:: After creating a packfile, print a line of data to @@ -118,16 +132,9 @@ OPTIONS as these commits can be used as edge points during calls to 'git pack-objects'. ---quiet:: - Disable all non-fatal output, making fast-import silent when it - is successful. This option disables the output shown by - \--stats. - ---stats:: - Display some basic statistics about the objects fast-import has - created, the packfiles they were stored into, and the - memory used by fast-import during this run. Showing this output - is currently the default, but can be disabled with \--quiet. +--max-pack-size=<n>:: + Maximum size of each output packfile. + The default is unlimited. Performance @@ -423,7 +430,7 @@ they made it. Here `<name>` is the person's display name (for example ``Com M Itter'') and `<email>` is the person's email address -(``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) +(``\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>` and `<email>` are free-form and may contain any sequence @@ -438,7 +445,9 @@ their syntax. ^^^^^^ The `from` command is used to specify the commit to initialize this branch from. This revision will be the first ancestor of the -new commit. +new commit. The state of the tree built at this commit will begin +with the state at the `from` commit, and be altered by the content +modifications in this commit. Omitting the `from` command in the first commit of a new branch will cause fast-import to create that commit with no ancestor. This @@ -479,16 +488,18 @@ current branch value should be written as: ---- from refs/heads/branch^0 ---- -The `{caret}0` suffix is necessary as fast-import does not permit a branch to +The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the -`from` command is even read from the input. Adding `{caret}0` will force +`from` command is even read from the input. Adding `^0` will force fast-import to resolve the commit through Git's revision parsing library, rather than its internal branch table, thereby loading in the existing value of the branch. `merge` ^^^^^^^ -Includes one additional ancestor commit. If the `from` command is +Includes one additional ancestor commit. The additional ancestry +link does not change the way the tree state is built at this commit. +If the `from` command is omitted when creating a new branch, the first `merge` commit will be the first ancestor of the current commit, and the branch will start out with no files. An unlimited number of `merge` commands per @@ -554,8 +565,12 @@ A `<path>` string must use UNIX-style directory separators (forward slash `/`), may contain any byte other than `LF`, and must not start with double quote (`"`). -If an `LF` or double quote must be encoded into `<path>` shell-style -quoting should be used, e.g. `"path/with\n and \" in it"`. +A path can use C-style string quoting; this is accepted in all cases +and mandatory if the filename starts with double quote or contains +`LF`. In C-style quoting, the complete name should be surrounded with +double quotes, and any `LF`, backslash, or double quote characters +must be escaped by preceding them with a backslash (e.g., +`"path/with\n, \\ and \" in it"`). The value of `<path>` must be in canonical form. That is it must not: @@ -979,7 +994,7 @@ Reading from a named tree:: See `filemodify` above for a detailed description of `<path>`. -Output uses the same format as `git ls-tree <tree> {litdd} <path>`: +Output uses the same format as `git ls-tree <tree> -- <path>`: ==== <mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF @@ -1047,7 +1062,9 @@ done:: Error out if the stream ends without a 'done' command. Without this feature, errors causing the frontend to end abruptly at a convenient point in the stream can go - undetected. + undetected. This may occur, for example, if an import + front end dies in mid-operation without emitting SIGTERM + or SIGKILL at its subordinate git fast-import instance. `option` ~~~~~~~~ diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 474fa307a0..8c751202d7 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -9,7 +9,10 @@ git-fetch-pack - Receive missing objects from another repository SYNOPSIS -------- [verse] -'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...] +'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] + [--upload-pack=<git-upload-pack>] + [--depth=<n>] [--no-progress] + [-v] [<host>:]<directory> [<refs>...] DESCRIPTION ----------- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 0f2f117383..e2301f5c01 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,7 +32,8 @@ changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. -*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +*NOTE*: This command honors `.git/info/grafts` file and refs in +the `refs/replace/` namespace. If you have any grafts or replacement refs defined, running this command will make them permanent. @@ -96,8 +97,8 @@ OPTIONS --index-filter <command>:: This is the filter for rewriting the index. It is similar to the tree filter but does not check out the tree, which makes it much - faster. Frequently used with `git rm \--cached - \--ignore-unmatch ...`, see EXAMPLES below. For hairy + faster. Frequently used with `git rm --cached + --ignore-unmatch ...`, see EXAMPLES below. For hairy cases, see linkgit:git-update-index[1]. --parent-filter <command>:: @@ -222,11 +223,11 @@ However, if the file is absent from the tree of some commit, a simple `rm filename` will fail for that tree and commit. Thus you may instead want to use `rm -f filename` as the script. -Using `\--index-filter` with 'git rm' yields a significantly faster +Using `--index-filter` with 'git rm' yields a significantly faster version. Like with using `rm filename`, `git rm --cached filename` will fail if the file is absent from the tree of a commit. If you want to "completely forget" a file, it does not matter when it entered -history, so we also add `\--ignore-unmatch`: +history, so we also add `--ignore-unmatch`: -------------------------------------------------------------------------- git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD @@ -242,8 +243,8 @@ git filter-branch --subdirectory-filter foodir -- --all ------------------------------------------------------- Thus you can, e.g., turn a library subdirectory into a repository of -its own. Note the `\--` that separates 'filter-branch' options from -revision options, and the `\--all` to rewrite all branches and tags. +its own. Note the `--` that separates 'filter-branch' options from +revision options, and the `--all` to rewrite all branches and tags. To set a commit (which typically is at the tip of another history) to be the parent of the current initial commit, in @@ -303,6 +304,11 @@ committed a merge between P1 and P2, it will be propagated properly and all children of the merge will become merge commits with P1,P2 as their parents instead of the merge commit. +*NOTE* the changes introduced by the commits, and which are not reverted +by subsequent commits, will still be in the rewritten branch. If you want +to throw out _changes_ together with the commits, you should use the +interactive mode of 'git rebase'. + You can rewrite the commit log messages using `--msg-filter`. For example, 'git svn-id' strings in a repository created by 'git svn' can be removed this way: @@ -313,11 +319,6 @@ git filter-branch --msg-filter ' ' ------------------------------------------------------- -To restrict rewriting to only part of the history, specify a revision -range in addition to the new branch name. The new branch name will -point to the top-most revision that a 'git rev-list' of this range -will print. - If you need to add 'Acked-by' lines to, say, the last 10 commits (none of which is a merge), use this command: @@ -328,11 +329,10 @@ git filter-branch --msg-filter ' ' HEAD~10..HEAD -------------------------------------------------------- -*NOTE* the changes introduced by the commits, and which are not reverted -by subsequent commits, will still be in the rewritten branch. If you want -to throw out _changes_ together with the commits, you should use the -interactive mode of 'git rebase'. - +To restrict rewriting to only part of the history, specify a revision +range in addition to the new branch name. The new branch name will +point to the top-most revision that a 'git rev-list' of this range +will print. Consider this history: @@ -371,23 +371,23 @@ Checklist for Shrinking a Repository ------------------------------------ git-filter-branch is often used to get rid of a subset of files, -usually with some combination of `\--index-filter` and -`\--subdirectory-filter`. People expect the resulting repository to +usually with some combination of `--index-filter` and +`--subdirectory-filter`. People expect the resulting repository to be smaller than the original, but you need a few more steps to actually make it smaller, because git tries hard not to lose your objects until you tell it to. First make sure that: * You really removed all variants of a filename, if a blob was moved - over its lifetime. `git log \--name-only \--follow \--all \-- - filename` can help you find renames. + over its lifetime. `git log --name-only --follow --all -- filename` + can help you find renames. -* You really filtered all refs: use `\--tag-name-filter cat \-- - \--all` when calling git-filter-branch. +* You really filtered all refs: use `--tag-name-filter cat -- --all` + when calling git-filter-branch. Then there are two ways to get a smaller repository. A safer way is to clone, that keeps your original intact. -* Clone it with `git clone +++file:///path/to/repo+++`. The clone +* Clone it with `git clone file:///path/to/repo`. The clone will not have the removed objects. See linkgit:git-clone[1]. (Note that cloning with a plain path just hardlinks everything!) @@ -397,14 +397,14 @@ approach, so *make a backup* or go back to cloning it. You have been warned. * Remove the original refs backed up by git-filter-branch: say `git - for-each-ref \--format="%(refname)" refs/original/ | xargs -n 1 git + for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d`. -* Expire all reflogs with `git reflog expire \--expire=now \--all`. +* Expire all reflogs with `git reflog expire --expire=now --all`. -* Garbage collect all unreferenced objects with `git gc \--prune=now` +* Garbage collect all unreferenced objects with `git gc --prune=now` (or if your git-gc is not new enough to support arguments to - `\--prune`, use `git repack -ad; git prune` instead). + `--prune`, use `git repack -ad; git prune` instead). GIT --- diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index c872b883ba..f2e08d11c1 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`, and `date` to extract the named component. The complete message in a commit and tag object is `contents`. -Its first line is `contents:subject`, the remaining lines -are `contents:body` and the optional GPG signature -is `contents:signature`. +Its first line is `contents:subject`, where subject is the concatenation +of all lines of the commit message up to the first blank line. The next +line is 'contents:body', where body is all of the lines after the first +blank line. Finally, the optional GPG signature is `contents:signature`. For sorting purposes, fields with numeric values sort in numeric order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). @@ -116,7 +117,7 @@ returns an empty string instead. As a special case for the date-type fields, you may specify a format for the date by adding one of `:default`, `:relative`, `:short`, `:local`, -`:iso8601` or `:rfc2822` to the end of the fieldname; e.g. +`:iso8601`, `:rfc2822` or `:raw` to the end of the fieldname; e.g. `%(taggerdate:relative)`. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 6ea9be775c..9a914d0159 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -18,9 +18,9 @@ SYNOPSIS [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] - [--subject-prefix=Subject-Prefix] + [--subject-prefix=Subject-Prefix] [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] - [--cover-letter] [--quiet] + [--cover-letter] [--quiet] [--notes[=<ref>]] [<common diff options>] [ <since> | <revision range> ] @@ -45,7 +45,7 @@ There are two ways to specify which commits to operate on. The first rule takes precedence in the case of a single <commit>. To apply the second rule, i.e., format everything since the beginning of history up until <commit>, use the '\--root' option: `git format-patch -\--root <commit>`. If you want to format only <commit> itself, you +--root <commit>`. If you want to format only <commit> itself, you can do this with `git format-patch -1 <commit>`. By default, each output file is numbered sequentially from 1, and uses the @@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified. If `-o` is specified, output files are created in <dir>. Otherwise they are created in the current working directory. -By default, the subject of a single patch is "[PATCH] First Line" and -the subject when multiple patches are output is "[PATCH n/m] First -Line". To force 1/1 to be added for a single patch, use `-n`. To omit -patch numbers from the subject, use `-N`. +By default, the subject of a single patch is "[PATCH] " followed by +the concatenation of lines from the commit message up to the first blank +line (see the DISCUSSION section of linkgit:git-commit[1]). + +When multiple patches are output, the subject prefix will instead be +"[PATCH n/m] ". To force 1/1 to be added for a single patch, use `-n`. +To omit patch numbers from the subject, use `-N`. If given `--thread`, `git-format-patch` will generate `In-Reply-To` and `References` headers to make the second and subsequent patch mails appear @@ -134,7 +137,7 @@ include::diff-options.txt[] The optional <style> argument can be either `shallow` or `deep`. 'shallow' threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the -`\--in-reply-to`, and the first patch mail, in this order. 'deep' +`--in-reply-to`, and the first patch mail, in this order. 'deep' threading makes every mail a reply to the previous one. + The default is `--no-thread`, unless the 'format.thread' configuration @@ -163,6 +166,15 @@ will want to ensure that threading is disabled for `git send-email`. allows for useful naming of a patch series, and can be combined with the `--numbered` option. +-v <n>:: +--reroll-count=<n>:: + Mark the series as the <n>-th iteration of the topic. The + output filenames have `v<n>` pretended to them, and the + subject prefix ("PATCH" by default, but configurable via the + `--subject-prefix` option) has ` v<n>` appended to it. E.g. + `--reroll-count=4` may produce `v4-0001-add-makefile.patch` + file that has "Subject: [PATCH v4 1/20] Add makefile" in it. + --to=<email>:: Add a `To:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. @@ -188,6 +200,18 @@ will want to ensure that threading is disabled for `git send-email`. containing the shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--notes[=<ref>]:: + Append the notes (see linkgit:git-notes[1]) for the commit + after the three-dash line. ++ +The expected use case of this is to write supporting explanation for +the commit that does not belong to the commit log message proper, +and include it with the patch submission. While one can simply write +these explanations after `format-patch` has run but before sending, +keeping them as git notes allows them to be maintained between versions +of the patch series (but see the discussion of the `notes.rewrite` +configuration options in linkgit:git-notes[1] to use this workflow). + --[no]-signature=<signature>:: Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index bbb25da2dd..da348fc942 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -23,8 +23,8 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the -index file, all SHA1 references in .git/refs/*, and all reflogs (unless ---no-reflogs is given) as heads. +index file, all SHA1 references in `refs` namespace, and all reflogs +(unless --no-reflogs is given) as heads. --unreachable:: Print out objects that exist but that aren't reachable from any diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 815afcb922..b370b025b8 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -84,7 +84,7 @@ The optional configuration variable 'gc.reflogExpireUnreachable' can be set to indicate how long historical reflog entries which are not part of the current branch should remain available in this repository. These types of entries are generally created as -a result of using `git commit \--amend` or `git rebase` and are the +a result of using `git commit --amend` or `git rebase` and are the commits prior to the amend or rebase occurring. Since these changes are not part of the current project most users will want to expire them sooner. This option defaults to '30 days'. diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 343eadd407..cfecf848fb 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -31,7 +31,9 @@ SYNOPSIS DESCRIPTION ----------- Look for specified patterns in the tracked files in the work tree, blobs -registered in the index file, or blobs in given tree objects. +registered in the index file, or blobs in given tree objects. Patterns +are lists of one or more search expressions separated by newline +characters. An empty string as search expression matches all lines. CONFIGURATION @@ -40,8 +42,16 @@ CONFIGURATION grep.lineNumber:: If set to true, enable '-n' option by default. +grep.patternType:: + Set the default matching behavior. Using a value of 'basic', 'extended', + 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', + '--fixed-strings', or '--perl-regexp' option accordingly, while the + value 'default' will return to the default matching behavior. + grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. + If set to true, enable '--extended-regexp' option by default. This + option is ignored when the 'grep.patternType' option is set to a value + other than 'default'. OPTIONS @@ -247,11 +257,11 @@ OPTIONS Examples -------- -`git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}`:: +`git grep 'time_t' -- '*.[ch]'`:: Looks for `time_t` in all tracked .c and .h files in the working directory and its subdirectories. -`git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \)`:: +`git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)`:: Looks for a line that has `#define` and either `MAX_PATH` or `PATH_MAX`. diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 909687fed4..39e6d0ddd8 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -74,6 +74,16 @@ OPTIONS --strict:: Die, if the pack contains broken objects or links. +--threads=<n>:: + Specifies the number of threads to spawn when resolving + deltas. This requires that index-pack be compiled with + pthreads otherwise this option is ignored with a warning. + This is meant to reduce packing time on multiprocessor + machines. The required amount of memory for the delta search + window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and use maximum 3 threads. + Note ---- diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 249fc878ec..22c0d6e4b1 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -24,10 +24,6 @@ each commit introduces are shown. OPTIONS ------- --<n>:: - Limits the number of commits to show. - Note that this is a commit limiting option, see below. - <since>..<until>:: Show only commits between the named two commits. When either <since> or <until> is omitted, it defaults to @@ -51,6 +47,11 @@ OPTIONS Print out the ref name given on the command line by which each commit was reached. +--use-mailmap:: + Use mailmap file to map author and committer names and email + to canonical real names and email addresses. See + linkgit:git-shortlog[1]. + --full-diff:: Without this flag, "git log -p <path>..." shows commits that touch the specified paths, and diffs about the same specified @@ -100,7 +101,7 @@ Examples 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 @@ -137,6 +138,8 @@ Examples This makes sense only when following a strict policy of merging all topic branches when staying on a single integration branch. +`git log -3`:: + Limits the number of commits to show to 3. Discussion ---------- @@ -169,7 +172,7 @@ log.showroot:: `git log -p` output would be shown without a diff attached. The default is `true`. -mailmap.file:: +mailmap.*:: See linkgit:git-shortlog[1]. notes.displayRef:: diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index c406a11001..d54932889f 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -48,7 +48,8 @@ $ gitk $(cd .git/lost-found/commit && echo ??*) ------------ After making sure you know which the object is the tag you are looking -for, you can reconnect it to your regular .git/refs hierarchy. +for, you can reconnect it to your regular `refs` hierarchy by using +the `update-ref` command. ------------ $ git cat-file -t 1ef2b196 diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index 7a9b86a58a..774de5e9d9 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -42,6 +42,11 @@ OPTIONS it successfully talked with the remote repository, whether it found any matching refs. +--get-url:: + Expand the URL of the given remote repository taking into account any + "url.<base>.insteadOf" config setting (See linkgit:git-config[1]) and + exit without talking to the remote. + <repository>:: Location of the repository. The shorthand defined in $GIT_DIR/branches/ can be used. Use "." (dot) to list references in diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index b295bf8330..87842e33f8 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git merge-base' [-a|--all] <commit> <commit>... 'git merge-base' [-a|--all] --octopus <commit>... +'git merge-base' --is-ancestor <commit> <commit> 'git merge-base' --independent <commit>... DESCRIPTION @@ -50,6 +51,12 @@ from linkgit:git-show-branch[1] when used with the `--merge-base` option. from any other. This mimics the behavior of 'git show-branch --independent'. +--is-ancestor:: + Check if the first <commit> is an ancestor of the second <commit>, + and exit with status 0 if true, or with status 1 if not. + Errors are signaled by a non-zero status that is not 1. + + OPTIONS ------- -a:: @@ -110,6 +117,27 @@ both '1' and '2' are merge-bases of A and B. Neither one is better than the other (both are 'best' merge bases). When the `--all` option is not given, it is unspecified which best one is output. +A common idiom to check "fast-forward-ness" between two commits A +and B is (or at least used to be) to compute the merge base between +A and B, and check if it is the same as A, in which case, A is an +ancestor of B. You will see this idiom used often in older scripts. + + A=$(git rev-parse --verify A) + if test "$A" = "$(git merge-base A B)" + then + ... A is an ancestor of B ... + fi + +In modern git, you can say this in a more direct way: + + if git merge-base --is-ancestor A B + then + ... A is an ancestor of B ... + fi + +instead. + + See also -------- linkgit:git-rev-list[1], diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 3ceefb8a1f..d34ea3c50b 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -99,7 +99,7 @@ commit or stash your changes before running 'git merge'. more than two parents (affectionately called an Octopus merge). + If no commit is given from the command line, and if `merge.defaultToUpstream` -configuration variable is set, merge the remote tracking branches +configuration variable is set, merge the remote-tracking branches that the current branch is configured to use as its upstream. See also the configuration section of this manual page. @@ -181,7 +181,7 @@ final result verbatim. When both sides made changes to the same area, however, git cannot randomly pick one side over the other, and asks you to resolve it by leaving what both sides did to that area. -By default, git uses the same style as that is used by "merge" program +By default, git uses the same style as the one used by the "merge" program from the RCS suite to present such a conflicted hunk, like this: ------------ diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 2a49de7cfe..6b563c500f 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -27,9 +27,9 @@ OPTIONS -t <tool>:: --tool=<tool>:: Use the merge resolution program specified by <tool>. - Valid merge tools are: - araxis, bc3, diffuse, ecmerge, emerge, gvimdiff, kdiff3, - meld, opendiff, p4merge, tkdiff, tortoisemerge, vimdiff and xxdiff. + Valid values include emerge, gvimdiff, kdiff3, + meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help` + for the list of valid <tool> settings. + If a merge resolution program is not specified, 'git mergetool' will use the configuration variable `merge.tool`. If the @@ -64,6 +64,9 @@ variable `mergetool.<tool>.trustExitCode` can be set to `true`. Otherwise, 'git mergetool' will prompt the user to indicate the success of the resolution after the custom tool has exited. +--tool-help:: + Print a list of merge tools that may be used with `--tool`. + -y:: --no-prompt:: Don't prompt before each invocation of the merge resolution diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index e8319eac69..46ef0466be 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -39,6 +39,10 @@ message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or "Notes:" for `refs/notes/commits`). +Notes can also be added to patches prepared with `git format-patch` by +using the `--notes` option. Such notes are added as a patch commentary +after a three dash separator line. + To change which notes are shown by 'git log', see the "notes.displayRef" configuration in linkgit:git-log[1]. @@ -70,7 +74,7 @@ copy:: second object). This subcommand is equivalent to: `git notes add [-f] -C $(git notes list <from-object>) <to-object>` + -In `\--stdin` mode, take lines in the format +In `--stdin` mode, take lines in the format + ---------- <from-object> SP <to-object> [ SP <rest> ] LF diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 3fac4137e2..beff6229c8 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -158,11 +158,14 @@ OPTIONS General options ~~~~~~~~~~~~~~~ -All commands except clone accept this option. +All commands except clone accept these options. --git-dir <dir>:: Set the 'GIT_DIR' environment variable. See linkgit:git[1]. +--verbose, -v:: + Provide more progress information. + Sync options ~~~~~~~~~~~~ These options can be used in the initial 'clone' as well as in @@ -176,6 +179,7 @@ subsequent 'sync' operations. + 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 @@ -193,12 +197,13 @@ git repository: --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. + them as tags in git. Limited usefulness as only imports labels + associated with new changelists. Deprecated. + +--import-labels:: + Import labels from p4 into git. --import-local:: By default, p4 branches are stored in 'refs/remotes/p4/', @@ -245,15 +250,12 @@ 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>]:: +-M:: 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 @@ -263,6 +265,34 @@ These options can be used to modify 'git p4 submit' behavior. Re-author p4 changes before submitting to p4. This option requires p4 admin privileges. +--export-labels:: + Export tags from git as p4 labels. Tags found in git are applied + to the perforce working directory. + +--dry-run, -n:: + Show just what commits would be submitted to p4; do not change + state in git or p4. + +--prepare-p4-only:: + Apply a commit to the p4 workspace, opening, adding and deleting + files in p4 as for a normal submit operation. Do not issue the + final "p4 submit", but instead print a message about how to + submit manually or revert. This option always stops after the + first (oldest) commit. Git tags are not exported to p4. + +--conflict=(ask|skip|quit):: + Conflicts can occur when applying a commit to p4. When this + happens, the default behavior ("ask") is to prompt whether to + skip this commit and continue, or quit. This option can be used + to bypass the prompt, causing conflicting commits to be automatically + skipped, or to quit trying to apply commits, without prompting. + +Rebase options +~~~~~~~~~~~~~~ +These options can be used to modify 'git p4 rebase' behavior. + +--import-labels:: + Import p4 labels. DEPOT PATH SYNTAX ----------------- @@ -427,11 +457,23 @@ git-p4.branchList:: enabled. Each entry should be a pair of branch names separated by a colon (:). This example declares that both branchA and branchB were created from main: ++ ------------- git config git-p4.branchList main:branchA git config --add git-p4.branchList main:branchB ------------- +git-p4.ignoredP4Labels:: + List of p4 labels to ignore. This is built automatically as + unimportable labels are discovered. + +git-p4.importLabels:: + Import p4 labels into git, as per --import-labels. + +git-p4.labelImportRegexp:: + Only p4 labels matching this regular expression will be imported. The + default value is '[a-zA-Z0-9_\-.]+$'. + git-p4.useClientSpec:: Specify that the p4 client spec should be used to identify p4 depot paths of interest. This is equivalent to specifying the @@ -441,13 +483,15 @@ git-p4.useClientSpec:: Submit variables ~~~~~~~~~~~~~~~~ git-p4.detectRenames:: - Detect renames. See linkgit:git-diff[1]. + Detect renames. See linkgit:git-diff[1]. This can be true, + false, or a score as expected by 'git diff -M'. git-p4.detectCopies:: - Detect copies. See linkgit:git-diff[1]. + Detect copies. See linkgit:git-diff[1]. This can be true, + false, or a score as expected by 'git diff -C'. git-p4.detectCopiesHarder:: - Detect copies harder. See linkgit:git-diff[1]. + Detect copies harder. See linkgit:git-diff[1]. A boolean. git-p4.preserveUser:: On submit, re-author changes to reflect the git author, @@ -480,11 +524,22 @@ git-p4.skipUserNameCheck:: user map, 'git p4' exits. This option can be used to force submission regardless. -git-p4.attemptRCSCleanup: - If enabled, 'git p4 submit' will attempt to cleanup RCS keywords - ($Header$, etc). These would otherwise cause merge conflicts and prevent - the submit going ahead. This option should be considered experimental at - present. +git-p4.attemptRCSCleanup:: + If enabled, 'git p4 submit' will attempt to cleanup RCS keywords + ($Header$, etc). These would otherwise cause merge conflicts and prevent + the submit going ahead. This option should be considered experimental at + present. + +git-p4.exportLabels:: + Export git tags to p4 labels, as per --export-labels. + +git-p4.labelExportRegexp:: + Only p4 labels matching this regular expression will be exported. The + default value is '[a-zA-Z0-9_\-.]+$'. + +git-p4.conflict:: + Specify submit behavior when a conflict with p4 is found, as per + --conflict. The default behavior is 'ask'. IMPLEMENTATION DETAILS ---------------------- diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index a3c6677bfa..f131677478 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -14,7 +14,8 @@ DESCRIPTION ----------- Traditionally, tips of branches and tags (collectively known as -'refs') were stored one file per ref under `$GIT_DIR/refs` +'refs') were stored one file per ref in a (sub)directory +under `$GIT_DIR/refs` directory. While many branch tips tend to be updated often, most tags and some branch tips are never updated. When a repository has hundreds or thousands of tags, this @@ -22,17 +23,18 @@ one-file-per-ref format both wastes storage and hurts performance. This command is used to solve the storage and performance -problem by stashing the refs in a single file, +problem by storing the refs in a single file, `$GIT_DIR/packed-refs`. When a ref is missing from the -traditional `$GIT_DIR/refs` hierarchy, it is looked up in this +traditional `$GIT_DIR/refs` directory hierarchy, it is looked +up in this file and used if found. Subsequent updates to branches always create new files under -`$GIT_DIR/refs` hierarchy. +`$GIT_DIR/refs` directory hierarchy. A recommended practice to deal with a repository with too many refs is to pack its refs with `--all --prune` once, and -occasionally run `git pack-refs \--prune`. Tags are by +occasionally run `git pack-refs --prune`. Tags are by definition stationary and are not expected to change. Branch heads will be packed with the initial `pack-refs --all`, but only the currently active branch heads will become unpacked, @@ -57,6 +59,15 @@ a repository with many branches of historical interests. The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. + +BUGS +---- + +Older documentation written before the packed-refs mechanism was +introduced may still say things like ".git/refs/heads/<branch> file +exists" when it means "branch <branch> exists". + + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 0f18ec891a..67fa5ee195 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -101,6 +101,7 @@ include::merge-options.txt[] :git-pull: 1 +-r:: --rebase:: Rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to @@ -110,7 +111,7 @@ include::merge-options.txt[] + 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. +`--rebase` instead of merging. + [NOTE] This is a potentially _dangerous_ mode of operation. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index a52b7b1a19..c964b796be 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -34,10 +34,12 @@ OPTIONS[[OPTIONS]] <refspec>...:: The format of a <refspec> parameter is an optional plus - `{plus}`, followed by the source ref <src>, followed + `+`, followed by the source ref <src>, followed by a colon `:`, followed by the destination ref <dst>. It is used to specify with what <src> object the <dst> ref - in the remote repository is to be updated. + in the remote repository is to be updated. If not specified, + the behavior of the command is controlled by the `push.default` + configuration variable. + The <src> is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as `master~4` or @@ -49,10 +51,11 @@ be named. If `:`<dst> is omitted, the same ref as <src> will be updated. + The object referenced by <src> is used to update the <dst> reference -on the remote side, but by default this is only allowed if the -update can fast-forward <dst>. By having the optional leading `{plus}`, -you can tell git to update the <dst> ref even when the update is not a -fast-forward. This does *not* attempt to merge <src> into <dst>. See +on the remote side. By default this is only allowed if <dst> is not +a tag (annotated or lightweight), and then only if it can fast-forward +<dst>. By having the optional leading `+`, you can tell git to update +the <dst> ref even if it is not allowed by default (e.g., it is not a +fast-forward.) This does *not* attempt to merge <src> into <dst>. See EXAMPLES below for details. + `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. @@ -60,12 +63,13 @@ EXAMPLES below for details. Pushing an empty <src> allows you to delete the <dst> ref from the remote repository. + -The special refspec `:` (or `{plus}:` to allow non-fast-forward updates) +The special refspec `:` (or `+:` to allow non-fast-forward updates) directs git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name already exists on the remote side. This is the default operation mode if no explicit refspec is found (that is neither on the command line -nor in any Push line of the corresponding remotes file---see below). +nor in any Push line of the corresponding remotes file---see below) and +no `push.default` configuration variable is set. --all:: Instead of naming each ref to push, specifies that all @@ -75,7 +79,7 @@ nor in any Push line of the corresponding remotes file---see below). Remove remote branches that don't have a local counterpart. For example a remote branch `tmp` will be removed if a local branch with the same name doesn't exist any more. This also respects refspecs, e.g. - `git push --prune remote refs/heads/{asterisk}:refs/tmp/{asterisk}` would + `git push --prune remote refs/heads/*:refs/tmp/*` would make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo` doesn't exist. @@ -172,7 +176,7 @@ useful if you write an alias or script around 'git push'. --recurse-submodules=check|on-demand:: Make sure all submodule commits used by the revisions to be - pushed are available on a remote tracking branch. If 'check' is + pushed are available on a remote-tracking branch. If 'check' is used git will verify that all submodule commits that changed in the revisions to be pushed are available on at least one remote of the submodule. If any commits are missing the push will be @@ -210,7 +214,7 @@ option is used. flag:: A single character indicating the status of the ref: (space);; for a successfully pushed fast-forward; -`{plus}`;; for a successful forced update; +`+`;; for a successful forced update; `-`;; for a successfully deleted ref; `*`;; for a successfully pushed new ref; `!`;; for a ref that was rejected or failed to push; and @@ -220,7 +224,7 @@ summary:: For a successfully pushed ref, the summary shows the old and new values of the ref in a form suitable for using as an argument to `git log` (this is `<old>..<new>` in most cases, and - `<old>\...<new>` for forced non-fast-forward updates). + `<old>...<new>` for forced non-fast-forward updates). + For a failed update, more details are given: + @@ -283,7 +287,8 @@ leading to commit A. The history looks like this: ---------------- Further suppose that the other person already pushed changes leading to A -back to the original repository you two obtained the original commit X. +back to the original repository from which you two obtained the original +commit X. The push done by the other person updated the branch that used to point at commit X to point at commit A. It is a fast-forward. @@ -357,7 +362,8 @@ Examples `git push origin :`. + The default behavior of this command when no <refspec> is given can be -configured by setting the `push` option of the remote. +configured by setting the `push` option of the remote, or the `push.default` +configuration variable. + For example, to default to pushing only the current branch to `origin` use `git config remote.origin.push HEAD`. Any valid <refspec> (like @@ -380,11 +386,23 @@ the ones in the examples below) can be configured as the default for 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 mothership 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 + `refs/remotes/satellite/master`) in the `mothership` repository; do the same for `dev` and `satellite/dev`. ++ +This is to emulate `git fetch` run on the `mothership` using `git +push` that is run in the opposite direction in order to integrate +the work done on `satellite`, and is often necessary when you can +only make connection in one way (i.e. satellite can ssh into +mothership but mothership cannot initiate connection to satellite +because the latter is behind a firewall or does not run sshd). ++ +After running this `git push` on the `satellite` machine, you would +ssh into the `mothership` and run `git merge` there to complete the +emulation of `git pull` that were run on `mothership` to pull changes +made on `satellite`. `git push origin HEAD:master`:: Push the current branch to the remote ref matching `master` in the @@ -402,7 +420,7 @@ the ones in the examples below) can be configured as the default for 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 +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-rebase.txt b/Documentation/git-rebase.txt index 841ebd6a9f..da067ecafa 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,11 +8,11 @@ git-rebase - Forward-port local commits to the updated upstream head SYNOPSIS -------- [verse] -'git rebase' [-i | --interactive] [options] [--onto <newbase>] +'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>] [<upstream>] [<branch>] -'git rebase' [-i | --interactive] [options] --onto <newbase> +'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>] --root [<branch>] -'git rebase' --continue | --skip | --abort +'git rebase' --continue | --skip | --abort | --edit-todo DESCRIPTION ----------- @@ -210,7 +210,7 @@ rebase.autosquash:: OPTIONS ------- -<newbase>:: +--onto <newbase>:: Starting point at which to create the new commits. If the --onto option is not specified, the starting point is <upstream>. May be any valid commit, and not just an @@ -245,6 +245,9 @@ leave out at most one of A and B, in which case it defaults to HEAD. --skip:: Restart the rebasing process by skipping the current patch. +--edit-todo:: + Edit the todo list during an interactive rebase. + -m:: --merge:: Use merging strategies to rebase. When the recursive (default) merge @@ -271,9 +274,9 @@ which makes little sense. -X <strategy-option>:: --strategy-option=<strategy-option>:: Pass the <strategy-option> through to the merge strategy. - This implies `\--merge` and, if no strategy has been + This implies `--merge` and, if no strategy has been specified, `-s recursive`. Note the reversal of 'ours' and - 'theirs' as noted in above for the `-m` option. + 'theirs' as noted above for the `-m` option. -q:: --quiet:: @@ -344,14 +347,36 @@ This uses the `--interactive` machinery internally, but combining it with the `--interactive` option explicitly is generally not a good idea unless you know what you are doing (see BUGS below). +-x <cmd>:: +--exec <cmd>:: + Append "exec <cmd>" after each line creating a commit in the + final history. <cmd> will be interpreted as one or more shell + commands. ++ +This option can only be used with the `--interactive` option +(see INTERACTIVE MODE below). ++ +You may execute several commands by either using one instance of `--exec` +with several commands: ++ + git rebase -i --exec "cmd1 && cmd2 && ..." ++ +or by giving more than one `--exec`: ++ + git rebase -i --exec "cmd1" --exec "cmd2" --exec ... ++ +If `--autosquash` is used, "exec" lines will not be appended for +the intermediate commits, and will only appear at the end of each +squash/fixup series. --root:: Rebase all commits reachable from <branch>, instead of limiting them with an <upstream>. This allows you to rebase - the root commit(s) on a branch. Must be used with --onto, and + the root commit(s) on a branch. When used with --onto, it will skip changes already contained in <newbase> (instead of - <upstream>). When used together with --preserve-merges, 'all' - root commits will be rewritten to have <newbase> as parent + <upstream>) whereas without --onto it will operate on every change. + When used together with both --onto and --preserve-merges, + 'all' root commits will be rewritten to have <newbase> as parent instead. --autosquash:: @@ -521,6 +546,24 @@ in `$SHELL`, or the default shell if `$SHELL` is not set), so you can use shell features (like "cd", ">", ";" ...). The command is run from the root of the working tree. +---------------------------------- +$ git rebase -i --exec "make test" +---------------------------------- + +This command lets you check that intermediate commits are compilable. +The todo list becomes like that: + +-------------------- +pick 5928aea one +exec make test +pick 04d0fda two +exec make test +pick ba46169 three +exec make test +pick f4593f9 four +exec make test +-------------------- + SPLITTING COMMITS ----------------- @@ -615,8 +658,8 @@ Easy case: The changes are literally the same.:: Hard case: The changes are not the same.:: This happens if the 'subsystem' rebase had conflicts, or used - `\--interactive` to omit, edit, squash, or fixup commits; or - if the upstream used one of `commit \--amend`, `reset`, or + `--interactive` to omit, edit, squash, or fixup commits; or + if the upstream used one of `commit --amend`, `reset`, or `filter-branch`. @@ -652,7 +695,7 @@ correspond to the ones before the rebase. NOTE: While an "easy case recovery" sometimes appears to be successful even in the hard case, it may have unintended consequences. For example, a commit that was removed via `git rebase - \--interactive` will be **resurrected**! + --interactive` will be **resurrected**! The idea is to manually tell 'git rebase' "where the old 'subsystem' ended and your 'topic' began", that is, what the old merge-base @@ -660,7 +703,7 @@ between them was. You will have to find a way to name the last commit of the old 'subsystem', for example: * With the 'subsystem' reflog: after 'git fetch', the old tip of - 'subsystem' is at `subsystem@\{1}`. Subsequent fetches will + 'subsystem' is at `subsystem@{1}`. Subsequent fetches will increase the number. (See linkgit:git-reflog[1].) * Relative to the tip of 'topic': knowing that your 'topic' has three diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 976dc14937..7fe2d2247b 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -39,13 +39,13 @@ as well). It is an alias for `git log -g --abbrev-commit --pretty=oneline`; see linkgit:git-log[1]. The reflog is useful in various git commands, to specify the old value -of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be -two moves ago", `master@\{one.week.ago\}` means "where master used to +of a reference. For example, `HEAD@{2}` means "where HEAD used to be +two moves ago", `master@{one.week.ago}` means "where master used to point to one week ago", and so on. See linkgit:gitrevisions[7] for more details. To delete single entries from the reflog, use the subcommand "delete" -and specify the _exact_ entry (e.g. "`git reflog delete master@\{2\}`"). +and specify the _exact_ entry (e.g. "`git reflog delete master@{2}`"). OPTIONS diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 674797cd83..6d696e0f90 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -35,6 +35,37 @@ 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'. +INVOCATION +---------- + +Remote helper programs are invoked with one or (optionally) two +arguments. The first argument specifies a remote repository as in git; +it is either the name of a configured remote or a URL. The second +argument specifies a URL; it is usually of the form +'<transport>://<address>', but any arbitrary string is possible. +The 'GIT_DIR' environment variable is set up for the remote helper +and can be used to determine where to store additional data or from +which directory to invoke auxiliary git commands. + +When git encounters a URL of the form '<transport>://<address>', where +'<transport>' is a protocol that it cannot handle natively, it +automatically invokes 'git remote-<transport>' with the full URL as +the second argument. If such a URL is encountered directly on the +command line, the first argument is the same as the second, and if it +is encountered in a configured remote, the first argument is the name +of that remote. + +A URL of the form '<transport>::<address>' explicitly instructs git to +invoke 'git remote-<transport>' with '<address>' as the second +argument. If such a URL is encountered directly on the command line, +the first argument is '<address>', and if it is encountered in a +configured remote, the first argument is the name of that remote. + +Additionally, when a configured remote has 'remote.<name>.vcs' set to +'<transport>', git explicitly invokes 'git remote-<transport>' with +'<name>' as the first argument. If set, the second argument is +'remote.<name>.url'; otherwise, the second argument is omitted. + INPUT FORMAT ------------ @@ -57,53 +88,17 @@ 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}`. +In the following, we list all defined capabilities and for +each we list which commands a helper with that capability +must provide. Capabilities for Pushing -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ 'connect':: Can attempt to connect to 'git receive-pack' (for pushing), - 'git upload-pack', etc for communication using the - packfile protocol. + 'git upload-pack', etc for communication using + git's native packfile protocol. This + requires a bidirectional, full-duplex connection. + Supported commands: 'connect'. @@ -113,16 +108,26 @@ Supported commands: 'connect'. + 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). +'export':: + Can discover remote refs and push specified objects from a + fast-import stream to remote refs. ++ +Supported commands: 'list for-push', 'export'. + +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 'push' and 'export', git prefers 'push'. +Other frontends may have some other order of preference. + Capabilities for Fetching -~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^ 'connect':: Can try to connect to 'git upload-pack' (for fetching), 'git receive-pack', etc for communication using the - packfile protocol. + git's native packfile protocol. This + requires a bidirectional, full-duplex connection. + Supported commands: 'connect'. @@ -144,51 +149,61 @@ 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. +Miscellaneous capabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +'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. + 'refspec' <refspec>:: - This modifies the 'import' capability. + 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 -`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. +A helper advertising the capability +`refspec refs/heads/*:refs/svn/origin/branches/*` +is saying that, when it is asked to `import refs/heads/topic`, the +stream it outputs will update the `refs/svn/origin/branches/topic` +ref. + This capability can be advertised multiple times. The first applicable refspec takes precedence. The left-hand of refspecs advertised with this capability must cover all refs reported by the list command. If no 'refspec' capability is advertised, -there is an implied `refspec {asterisk}:{asterisk}`. +there is an implied `refspec *:*`. -INVOCATION ----------- +'bidi-import':: + This modifies the 'import' capability. + The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers + to retrieve information about blobs and trees that already exist in + fast-import's memory. This requires a channel from fast-import to the + remote-helper. + If it is advertised in addition to "import", git establishes a pipe from + fast-import to the remote-helper's stdin. + It follows that git and fast-import are both connected to the + remote-helper's stdin. Because git can send multiple commands to + the remote-helper it is required that helpers that use 'bidi-import' + buffer all 'import' commands of a batch before sending data to fast-import. + This is to prevent mixing commands and fast-import responses on the + helper's stdin. -Remote helper programs are invoked with one or (optionally) two -arguments. The first argument specifies a remote repository as in git; -it is either the name of a configured remote or a URL. The second -argument specifies a URL; it is usually of the form -'<transport>://<address>', but any arbitrary string is possible. -The 'GIT_DIR' environment variable is set up for the remote helper -and can be used to determine where to store additional data or from -which directory to invoke auxiliary git commands. +'export-marks' <file>:: + This modifies the 'export' capability, instructing git to dump the + internal marks table to <file> when complete. For details, + read up on '--export-marks=<file>' in linkgit:git-fast-export[1]. + +'import-marks' <file>:: + This modifies the 'export' capability, instructing git to load the + marks specified in <file> before processing any input. For details, + read up on '--import-marks=<file>' in linkgit:git-fast-export[1]. -When git encounters a URL of the form '<transport>://<address>', where -'<transport>' is a protocol that it cannot handle natively, it -automatically invokes 'git remote-<transport>' with the full URL as -the second argument. If such a URL is encountered directly on the -command line, the first argument is the same as the second, and if it -is encountered in a configured remote, the first argument is the name -of that remote. -A URL of the form '<transport>::<address>' explicitly instructs git to -invoke 'git remote-<transport>' with '<address>' as the second -argument. If such a URL is encountered directly on the command line, -the first argument is '<address>', and if it is encountered in a -configured remote, the first argument is the name of that remote. -Additionally, when a configured remote has 'remote.<name>.vcs' set to -'<transport>', git explicitly invokes 'git remote-<transport>' with -'<name>' as the first argument. If set, the second argument is -'remote.<name>.url'; otherwise, the second argument is omitted. COMMANDS -------- @@ -198,9 +213,11 @@ Commands are given by the caller on the helper's standard input, one per line. 'capabilities':: Lists the capabilities of the helper, one per line, ending with a blank line. Each capability may be preceded with '*', - which marks them mandatory for git version using the remote - helper to understand (unknown mandatory capability is fatal - error). + which marks them mandatory for git versions using the remote + helper to understand. Any unknown mandatory capability is a + fatal error. ++ +Support for this command is mandatory. 'list':: Lists the refs, one per line, in the format "<value> <name> @@ -210,9 +227,20 @@ Commands are given by the caller on the helper's standard input, one per line. the name; unrecognized attributes are ignored. The list ends with a blank line. + -If 'push' is supported this may be called as 'list for-push' -to obtain the current refs prior to sending one or more 'push' -commands to the helper. +See REF LIST ATTRIBUTES for a list of currently defined attributes. ++ +Supported if the helper has the "fetch" or "import" capability. + +'list for-push':: + Similar to 'list', except that it is used if and only if + the caller wants to the resulting ref list to prepare + push commands. + A helper supporting both push and fetch can use this + to distinguish for which operation the output of 'list' + is going to be used, possibly reducing the amount + of work that needs to be performed. ++ +Supported if the helper has the "push" or "export" capability. 'option' <name> <value>:: Sets the transport helper option <name> to <value>. Outputs a @@ -222,6 +250,8 @@ commands to the helper. for it). Options should be set before other commands, and may influence the behavior of those commands. + +See OPTIONS for a list of currently defined options. ++ Supported if the helper has the "option" capability. 'fetch' <sha1> <name>:: @@ -230,7 +260,7 @@ Supported if the helper has the "option" capability. per line, terminated with a blank line. Outputs a single blank line when all fetch commands in the same batch are complete. Only objects which were reported - in the ref list with a sha1 may be fetched this way. + in the output of 'list' with a sha1 may be fetched this way. + Optionally may output a 'lock <file>' line indicating a file under GIT_DIR/objects/pack which is keeping a pack until refs can be @@ -286,8 +316,29 @@ terminated with a blank line. For each batch of 'import', the remote helper should produce a fast-import stream terminated by a 'done' command. + +Note that if the 'bidi-import' capability is used the complete batch +sequence has to be buffered before starting to send data to fast-import +to prevent mixing of commands and fast-import responses on the helper's +stdin. ++ Supported if the helper has the "import" capability. +'export':: + Instructs the remote helper that any subsequent input is + part of a fast-import stream (generated by 'git fast-export') + containing objects which should be pushed to the remote. ++ +Especially useful for interoperability with a foreign versioning +system. ++ +The 'export-marks' and 'import-marks' capabilities, if specified, +affect this command in so far as they are passed on to 'git +fast-export', which then will load/store a table of marks for +local objects. This can be used to implement for incremental +operations. ++ +Supported if the helper has the "export" capability. + 'connect' <service>:: Connects to given service. Standard input and standard output of helper are connected to specified service (git prefix is @@ -313,10 +364,9 @@ capabilities reported by the helper. REF LIST ATTRIBUTES ------------------- -'for-push':: - The caller wants to use the ref list to prepare push - commands. A helper might chose to acquire the ref list by - opening a different type of connection to the destination. +The 'list' command produces a list of refs in which each ref +may be followed by a list of attributes. The following ref list +attributes are defined. 'unchanged':: This ref is unchanged since the last import or fetch, although @@ -324,6 +374,10 @@ REF LIST ATTRIBUTES OPTIONS ------- + +The following options are defined and (under suitable circumstances) +set by git if the remote helper has the 'option' capability. + 'option verbosity' <n>:: Changes the verbosity of messages displayed by the helper. A value of 0 for <n> means that processes operate diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt index 2a67d456a3..612a625ced 100644 --- a/Documentation/git-remote-testgit.txt +++ b/Documentation/git-remote-testgit.txt @@ -19,7 +19,7 @@ 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'. +'git-remote-testgit'. SEE ALSO -------- diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index d376d19ef7..e8c396b5f9 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git remote' [-v | --verbose] 'git remote add' [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror=<fetch|push>] <name> <url> 'git remote rename' <old> <new> -'git remote rm' <name> +'git remote remove' <name> 'git remote set-head' <name> (-a | -d | <branch>) 'git remote set-branches' [--add] <name> <branch>... 'git remote set-url' [--push] <name> <newurl> [<oldurl>] @@ -67,14 +67,14 @@ multiple branches without grabbing all branches. 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 +When a fetch mirror is created with `--mirror=fetch`, the refs will not be stored in the 'refs/remotes/' namespace, but rather everything in 'refs/' on the remote will be directly mirrored into 'refs/' in the local repository. This option only makes sense in bare repositories, because a fetch would overwrite any local commits. + -When a push mirror is created with `\--mirror=push`, then `git push` -will always behave as if `\--mirror` was passed. +When a push mirror is created with `--mirror=push`, then `git push` +will always behave as if `--mirror` was passed. 'rename':: @@ -85,6 +85,7 @@ In case <old> and <new> are the same, and <old> is a file under `$GIT_DIR/remotes` or `$GIT_DIR/branches`, the remote is converted to the configuration file format. +'remove':: 'rm':: Remove the remote named <name>. All remote-tracking branches and diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 17df525275..51131d0858 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -14,14 +14,13 @@ SYNOPSIS DESCRIPTION ----------- -Adds a 'replace' reference in `.git/refs/replace/` +Adds a 'replace' reference in `refs/replace/` namespace. The name of the 'replace' reference is the SHA1 of the object that is replaced. The content of the 'replace' reference is the SHA1 of the replacement object. -Unless `-f` is given, the 'replace' reference must not yet exist in -`.git/refs/replace/` directory. +Unless `-f` is given, the 'replace' reference must not yet exist. Replacement references will be used by default by all git commands except those doing reachability traversal (prune, pack transfer and diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index b43b7c8c0e..a62227f84e 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -101,15 +101,15 @@ One way to do it is to pull master into the topic branch: The commits marked with `*` touch the same area in the same file; you need to resolve the conflicts when creating the commit -marked with `{plus}`. Then you can test the result to make sure your +marked with `+`. Then you can test the result to make sure your work-in-progress still works with what is in the latest master. After this test merge, there are two ways to continue your work on the topic. The easiest is to build on top of the test merge -commit `{plus}`, and when your work in the topic branch is finally +commit `+`, and when your work in the topic branch is finally ready, pull the topic branch into master, and/or ask the upstream to pull from you. By that time, however, the master or -the upstream might have been advanced since the test merge `{plus}`, +the upstream might have been advanced since the test merge `+`, in which case the final commit graph would look like this: ------------ diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index b674866e6d..978d8da50c 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git reset' [-q] [<commit>] [--] <paths>... 'git reset' (--patch | -p) [<commit>] [--] [<paths>...] -'git reset' (--soft | --mixed | --hard | --merge | --keep) [-q] [<commit>] +'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- @@ -41,13 +41,13 @@ working tree in one go. + 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. +section of linkgit:git-add[1] to learn how to operate the `--patch` mode. -'git reset' --<mode> [<commit>]:: +'git reset' [<mode>] [<commit>]:: This form resets the current branch head to <commit> and possibly updates the index (resetting it to the tree of <commit>) and - the working tree depending on <mode>, which - must be one of the following: + the working tree depending on <mode>. If <mode> is omitted, + defaults to "--mixed". The <mode> must be one of the following: + -- --soft:: diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 8023dc086d..3c63561f02 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -101,6 +101,12 @@ OPTIONS The option core.warnAmbiguousRefs is used to select the strict abbreviation mode. +--disambiguate=<prefix>:: + Show every object whose name begins with the given prefix. + The <prefix> must be at least 4 hexadecimal digits long to + avoid listing each and every object in the repository by + mistake. + --all:: Show all refs found in `refs/`. @@ -113,15 +119,14 @@ OPTIONS + If a `pattern` is given, only refs matching the given shell glob are shown. If the pattern does not contain a globbing character (`?`, -`{asterisk}`, or `[`), it is turned into a prefix match by -appending `/{asterisk}`. +`*`, or `[`), it is turned into a prefix match by appending `/*`. --glob=pattern:: Show all refs matching the shell glob pattern `pattern`. If the pattern does not start with `refs/`, this is automatically prepended. If the pattern does not contain a globbing - character (`?`, `{asterisk}`, or `[`), it is turned into a prefix - match by appending `/{asterisk}`. + character (`?`, `*`, or `[`), it is turned into a prefix + match by appending `/*`. --show-toplevel:: Show the absolute path of the top-level directory. @@ -138,7 +143,8 @@ appending `/{asterisk}`. --git-dir:: Show `$GIT_DIR` if defined. Otherwise show the path to - the .git directory, relative to the current directory. + the .git directory. The path shown, when relative, is + relative to the current working directory. + If `$GIT_DIR` is not defined and the current directory is not detected to lie in a git repository or work tree diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index b699a3458e..70152e8b1e 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -27,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 @@ -105,7 +105,7 @@ EXAMPLES 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~5..master~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 665ad4ddab..262436b7b1 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -79,8 +79,7 @@ a file that you have not told git about does not remove that file. File globbing matches across directory boundaries. Thus, given two directories `d` and `d2`, there is a difference between -using `git rm {apostrophe}d{asterisk}{apostrophe}` and -`git rm {apostrophe}d/{asterisk}{apostrophe}`, as the former will +using `git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all of directory `d2`. REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM @@ -135,6 +134,21 @@ use the following command: git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached ---------------- +Submodules +~~~~~~~~~~ +Only submodules using a gitfile (which means they were cloned +with a git version 1.7.8 or newer) will be removed from the work +tree, as their repository lives inside the .git directory of the +superproject. If a submodule (or one of those nested inside it) +still uses a .git directory, `git rm` will fail - no matter if forced +or not - to protect the submodule's history. + +A submodule is considered up-to-date when the HEAD is the same as +recorded in the index, no tracked files are modified and no untracked +files that aren't ignored are present in the submodules work tree. +Ignored files are deemed expendable and won't stop a submodule's work +tree from being removed. + EXAMPLES -------- `git rm Documentation/\*.txt`:: diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 324117072d..eeb561cf14 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -126,6 +126,10 @@ The --to option must be repeated for each user you want on the to list. + Note that no attempts whatsoever are made to validate the encoding. +--compose-encoding=<encoding>:: + Specify encoding of compose message. Default is the value of the + 'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed. + Sending ~~~~~~~ diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index ff3755b4c7..c308e91537 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -14,8 +14,7 @@ git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] DESCRIPTION ----------- Summarizes 'git log' output in a format suitable for inclusion -in release announcements. Each commit will be grouped by author and -the first line of the commit message will be shown. +in release announcements. Each commit will be grouped by author and title. Additionally, "[PATCH]" will be stripped from the commit description. @@ -47,7 +46,7 @@ OPTIONS --format[=<format>]:: Instead of the commit subject, use some other information to describe each commit. '<format>' can be any string accepted - by the `--format` option of 'git log', such as '{asterisk} [%h] %s'. + by the `--format` option of 'git log', such as '* [%h] %s'. (See the "PRETTY FORMATS" section of linkgit:git-log[1].) Each pretty-printed commit will be rewrapped before it is shown. @@ -57,6 +56,9 @@ OPTIONS line of each entry is indented by `indent1` spaces, and the second and subsequent lines are indented by `indent2` spaces. `width`, `indent1`, and `indent2` default to 76, 6 and 9 respectively. ++ +If width is `0` (zero) then indent the lines of the output without wrapping +them. MAPPING AUTHORS diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index fcee0008a9..5dbcd47fec 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -73,7 +73,7 @@ OPTIONS --exclude-existing[=<pattern>]:: Make 'git show-ref' act as a filter that reads refs from stdin of the - form "`{caret}(?:<anything>\s)?<refname>(?:{backslash}{caret}{})?$`" + form "`^(?:<anything>\s)?<refname>(?:\^{})?$`" and performs the following actions on each: (1) strip "{caret}{}" at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 1e38819e67..ae4edcccfb 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -52,10 +52,10 @@ EXAMPLES 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`. diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 43af38aa4b..711ffe17a7 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -36,8 +36,8 @@ you create one. The latest stash you created is stored in `refs/stash`; older stashes are found in the reflog of this reference and can be named using -the usual reflog syntax (e.g. `stash@\{0}` is the most recently -created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}` +the usual reflog syntax (e.g. `stash@{0}` is the most recently +created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}` is also possible). OPTIONS @@ -66,7 +66,7 @@ constructed such that its index state is the same as the index state of your repository, and its worktree contains only the changes you selected interactively. The selected changes are then rolled back from your worktree. See the ``Interactive Mode'' section of -linkgit:git-add[1] to learn how to operate the `\--patch` mode. +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. @@ -74,7 +74,7 @@ The `--patch` option implies `--keep-index`. You can use list [<options>]:: List the stashes that you currently have. Each 'stash' is listed - with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is + with its name (e.g. `stash@{0}` is the latest stash, `stash@{1}` is the one before, etc.), the name of the branch that was current when the stash was made, and a short description of the commit the stash was based on. @@ -93,7 +93,7 @@ show [<stash>]:: stashed state and its original parent. When no `<stash>` is given, shows the latest one. By default, the command shows the diffstat, but it will accept any format known to 'git diff' (e.g., `git stash show - -p stash@\{1}` to view the second most recent stash in patch form). + -p stash@{1}` to view the second most recent stash in patch form). pop [--index] [-q|--quiet] [<stash>]:: @@ -111,8 +111,8 @@ tree's changes, but also the index's ones. However, this can fail, when you have conflicts (which are stored in the index, where you therefore can no longer apply the changes as they were originally). + -When no `<stash>` is given, `stash@\{0}` is assumed, otherwise `<stash>` must -be a reference of the form `stash@\{<revision>}`. +When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must +be a reference of the form `stash@{<revision>}`. apply [--index] [-q|--quiet] [<stash>]:: @@ -143,9 +143,9 @@ clear:: drop [-q|--quiet] [<stash>]:: Remove a single stashed state from the stash list. When no `<stash>` - is given, it removes the latest one. i.e. `stash@\{0}`, otherwise - `<stash>` must a valid stash log reference of the form - `stash@\{<revision>}`. + is given, it removes the latest one. i.e. `stash@{0}`, otherwise + `<stash>` must be a valid stash log reference of the form + `stash@{<revision>}`. create:: diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 3d51717bbe..9f1ef9a463 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -38,6 +38,9 @@ OPTIONS across git versions and regardless of user configuration. See below for details. +--long:: + Give the output in the long-format. This is the default. + -u[<mode>]:: --untracked-files[=<mode>]:: Show untracked files. @@ -77,6 +80,13 @@ configuration variable documented in linkgit:git-config[1]. Terminate entries with NUL, instead of LF. This implies the `--porcelain` output format if no other format is given. +--column[=<options>]:: +--no-column:: + Display untracked files in columns. See configuration variable + column.status for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' + respectively. + OUTPUT ------ @@ -98,12 +108,12 @@ In the short-format, the status of each path is shown as XY PATH1 -> PATH2 -where `PATH1` is the path in the `HEAD`, and the ` \-> PATH2` part is +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 @@ -177,7 +187,7 @@ order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL and the terminating newline (but a space still separates the status field from the first filename). Third, filenames containing special characters are not specially formatted; no quoting or -backslash-escaping is performed. Fourth, there is no branch line. +backslash-escaping is performed. CONFIGURATION ------------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index c243ee552b..b1996f1a63 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,11 +9,11 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b branch] [-f|--force] +'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] -'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] +'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] @@ -43,9 +43,9 @@ if you choose to go that route. Submodules are composed from a so-called `gitlink` tree entry in the main repository that refers to a particular commit object within the inner repository that is completely separate. -A record in the `.gitmodules` file at the root of the source -tree assigns a logical name to the submodule and describes -the default URL the submodule shall be cloned from. +A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the +root of the source tree assigns a logical name to the submodule and +describes the default URL the submodule shall be cloned from. The logical name can be used for overriding this URL within your local repository configuration (see 'submodule init'). @@ -112,7 +112,6 @@ status:: initialized, `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing repository and `U` if the submodule has merge conflicts. - This command is the default command for 'git submodule'. + If `--recursive` is specified, this command will recurse into nested submodules, and show their status as well. @@ -140,7 +139,8 @@ update:: 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`, `merge` or `none`. + `rebase`, `merge` or `none`. `none` can be overridden by specifying + `--checkout`. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the @@ -149,9 +149,10 @@ submodule with the `--init` option. 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. +If `--force` is specified, the submodule will be checked out (using +`git checkout --force` if appropriate), even if the commit specified in the +index of the containing repository already matches the commit checked out in +the submodule. summary:: Show commit summary between the given commit (defaults to HEAD) and @@ -207,13 +208,17 @@ OPTIONS -b:: --branch:: Branch of repository to add as submodule. + The name of the branch is recorded as `submodule.<path>.branch` in + `.gitmodules` for `update --remote`. -f:: --force:: This option is only valid for add and update commands. When running add, allow adding an otherwise ignored submodule path. When running update, throw away local changes in submodules when - switching to a different commit. + switching to a different commit; and always run a checkout operation + in the submodule, even if the commit listed in the index of the + containing repository matches the commit checked out in the submodule. --cached:: This option is only valid for status and summary commands. These @@ -233,6 +238,27 @@ OPTIONS (the default). This limit only applies to modified submodules. The size is always limited to 1 for added/deleted/typechanged submodules. +--remote:: + This option is only valid for the update command. Instead of using + the superproject's recorded SHA-1 to update the submodule, use the + status of the submodule's remote tracking branch. The remote used + is branch's remote (`branch.<name>.remote`), defaulting to `origin`. + The remote branch used defaults to `master`, but the branch name may + be overridden by setting the `submodule.<name>.branch` option in + either `.gitmodules` or `.git/config` (with `.git/config` taking + precedence). ++ +This works for any of the supported update procedures (`--checkout`, +`--rebase`, etc.). The only change is the source of the target SHA-1. +For example, `submodule update --remote --merge` will merge upstream +submodule changes into the submodules, while `submodule update +--merge` will merge superproject gitlink changes into the submodules. ++ +In order to ensure a current tracking branch state, `update --remote` +fetches the submodule's remote repository before calculating the +SHA-1. If you don't want to fetch, you should use `submodule update +--remote --no-fetch`. + -N:: --no-fetch:: This option is only valid for the update command. @@ -262,6 +288,11 @@ OPTIONS Initialize all submodules for which "git submodule init" has not been called so far before updating. +--name:: + This option is only valid for the add command. It sets the submodule's + name to the given string instead of defaulting to its path. The name + must be valid as a directory name and may not end with a '/'. + --reference <repository>:: This option is only valid for add and update commands. These commands sometimes need to clone a remote repository. In this case, diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 34ee785064..34d438b0ab 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -146,6 +146,13 @@ Skip "branches" and "tags" of first level directories;; ------------------------------------------------------------------------ -- +--log-window-size=<n>;; + Fetch <n> log entries per request when scanning Subversion history. + The default is 100. For very large Subversion repositories, larger + values may be needed for 'clone'/'fetch' to complete in reasonable + time. But overly large values may lead to higher memory usage and + request timeouts. + 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; @@ -189,18 +196,16 @@ and have no uncommitted changes. last fetched commit from the upstream SVN. 'dcommit':: - Commit each diff from a specified head directly to the SVN + Commit each diff from the current branch directly to the SVN repository, and then rebase or reset (depending on whether or not there is a diff between SVN and head). This will create a revision in SVN for each commit in git. - It is recommended that you run 'git svn' fetch and rebase (not - pull or merge) your commits against the latest changes in the - SVN repository. - An optional revision or branch argument may be specified, and - causes 'git svn' to do all work on that revision/branch - instead of HEAD. - This is advantageous over 'set-tree' (below) because it produces - cleaner, more linear history. ++ +When an optional git branch name (or a git commit object name) +is specified as an argument, the subcommand works on the specified +branch, not on the current branch. ++ +Use of 'dcommit' is preferred to 'set-tree' (below). + --no-rebase;; After committing, do not rebase or reset. @@ -341,6 +346,16 @@ Any other arguments are passed directly to 'git log' corresponding git commit hash (this can optionally be followed by a tree-ish to specify which branch should be searched). When given a tree-ish, returns the corresponding SVN revision number. ++ +--before;; + Don't require an exact match if given an SVN revision, instead find + the commit corresponding to the state of the SVN repository (on the + current branch) at the specified revision. ++ +--after;; + Don't require an exact match if given an SVN revision; if there is + not an exact match return the closest match searching forward in the + history. 'set-tree':: You should consider using 'dcommit' instead of this command. @@ -572,6 +587,8 @@ config key: svn.repackflags --merge:: -s<strategy>:: --strategy=<strategy>:: +-p:: +--preserve-merges:: These are only used with the 'dcommit' and 'rebase' commands. + Passed directly to 'git rebase' when using 'dcommit' if a @@ -621,10 +638,19 @@ ADVANCED OPTIONS Default: "svn" --follow-parent:: + This option is only relevant if we are tracking branches (using + one of the repository layout options --trunk, --tags, + --branches, --stdlayout). For each tracked branch, try to find + out where its revision was copied from, and set + a suitable parent in the first git commit for the branch. This is especially helpful when we're tracking a directory - that has been moved around within the repository, or if we - started tracking a branch and never tracked the trunk it was - descended from. This feature is enabled by default, use + that has been moved around within the repository. If this + feature is disabled, the branches created by 'git svn' will all + be linear and not share any history, meaning that there will be + no information on where branches were branched off or merged. + However, following long/convoluted histories can take a long + time, so disabling this feature may speed up the cloning + process. This feature is enabled by default, use --no-follow-parent to disable it. + [verse] @@ -732,7 +758,8 @@ for rewriteRoot and rewriteUUID which can be used together. BASIC EXAMPLES -------------- -Tracking and contributing to the trunk of a Subversion-managed project: +Tracking and contributing to the trunk of a Subversion-managed project +(ignoring tags and branches): ------------------------------------------------------------------------ # Clone a repo (like git clone): @@ -757,8 +784,10 @@ Tracking and contributing to an entire Subversion-managed project (complete with a trunk, tags and branches): ------------------------------------------------------------------------ -# Clone a repo (like git clone): - git svn clone http://svn.example.com/project -T trunk -b branches -t tags +# Clone a repo with standard SVN directory layout (like git clone): + git svn clone http://svn.example.com/project --stdlayout +# Or, if the repo uses a non-standard directory layout: + git svn clone http://svn.example.com/project -T tr -b branch -t tag # View all branches and tags you have cloned: git branch -r # Create a new branch in SVN @@ -800,18 +829,19 @@ have each person clone that repository with 'git clone': REBASE VS. PULL/MERGE --------------------- - -Originally, 'git svn' recommended that the 'remotes/git-svn' branch be -pulled or merged from. This is because the author favored +Prefer to use 'git svn rebase' or 'git rebase', rather than +'git pull' or 'git merge' to synchronize unintegrated commits with a 'git svn' +branch. Doing so will keep the history of unintegrated commits linear with +respect to the upstream SVN repository and allow the use of the preferred +'git svn dcommit' subcommand to push unintegrated commits back into SVN. + +Originally, 'git svn' recommended that developers pulled or merged from +the 'git svn' branch. This was because the author favored `git svn set-tree B` to commit a single head rather than the -`git svn set-tree A..B` notation to commit multiple commits. - -If you use `git svn set-tree A..B` to commit several diffs and you do -not have the latest remotes/git-svn merged into my-branch, you should -use `git svn rebase` to update your work branch instead of `git pull` or -`git merge`. `pull`/`merge` can cause non-linear history to be flattened -when committing into SVN, which can lead to merge commits reversing -previous commits in SVN. +`git svn set-tree A..B` notation to commit multiple commits. Use of +'git pull' or 'git merge' with `git svn set-tree A..B` will cause non-linear +history to be flattened when committing into SVN and this can lead to merge +commits unexpectedly reversing previous commits in SVN. MERGE TRACKING -------------- @@ -822,6 +852,52 @@ inside git back upstream to SVN users. Therefore it is advised that users keep history as linear as possible inside git to ease compatibility with SVN (see the CAVEATS section below). +HANDLING OF SVN BRANCHES +------------------------ +If 'git svn' is configured to fetch branches (and --follow-branches +is in effect), it sometimes creates multiple git branches for one +SVN branch, where the addtional branches have names of the form +'branchname@nnn' (with nnn an SVN revision number). These additional +branches are created if 'git svn' cannot find a parent commit for the +first commit in an SVN branch, to connect the branch to the history of +the other branches. + +Normally, the first commit in an SVN branch consists +of a copy operation. 'git svn' will read this commit to get the SVN +revision the branch was created from. It will then try to find the +git commit that corresponds to this SVN revision, and use that as the +parent of the branch. However, it is possible that there is no suitable +git commit to serve as parent. This will happen, among other reasons, +if the SVN branch is a copy of a revision that was not fetched by 'git +svn' (e.g. because it is an old revision that was skipped with +'--revision'), or if in SVN a directory was copied that is not tracked +by 'git svn' (such as a branch that is not tracked at all, or a +subdirectory of a tracked branch). In these cases, 'git svn' will still +create a git branch, but instead of using an existing git commit as the +parent of the branch, it will read the SVN history of the directory the +branch was copied from and create appropriate git commits. This is +indicated by the message "Initializing parent: <branchname>". + +Additionally, it will create a special branch named +'<branchname>@<SVN-Revision>', where <SVN-Revision> is the SVN revision +number the branch was copied from. This branch will point to the newly +created parent commit of the branch. If in SVN the branch was deleted +and later recreated from a different version, there will be multiple +such branches with an '@'. + +Note that this may mean that multiple git commits are created for a +single SVN revision. + +An example: in an SVN repository with a standard +trunk/tags/branches layout, a directory trunk/sub is created in r.100. +In r.200, trunk/sub is branched by copying it to branches/. 'git svn +clone -s' will then create a branch 'sub'. It will also create new git +commits for r.100 through r.199 and use these as the history of branch +'sub'. Thus there will be two git commits for each revision from r.100 +to r.199 (one containing trunk/, one containing trunk/sub/). Finally, +it will create a branch 'sub@200' pointing to the new parent commit of +branch 'sub' (i.e. the commit for r.200 and trunk/sub/). + CAVEATS ------- @@ -863,6 +939,21 @@ already dcommitted. It is considered bad practice to --amend commits you've already pushed to a remote repository for other users, and dcommit with SVN is analogous to that. +When cloning an SVN repository, if none of the options for describing +the repository layout is used (--trunk, --tags, --branches, +--stdlayout), 'git svn clone' will create a git repository with +completely linear history, where branches and tags appear as separate +directories in the working copy. While this is the easiest way to get a +copy of a complete repository, for projects with many branches it will +lead to a working copy many times larger than just the trunk. Thus for +projects using the standard directory structure (trunk/branches/tags), +it is recommended to clone with option '--stdlayout'. If the project +uses a non-standard structure, and/or if branches and tags are not +required, it is easiest to only clone one directory (typically trunk), +without giving any repository layout options. If the full history with +branches and tags is required, the options '--trunk' / '--branches' / +'--tags' must be used. + When using multiple --branches or --tags, 'git svn' does not automatically handle name collisions (for example, if two branches from different paths have the same name, or if a branch and a tag have the same name). In these cases, @@ -886,6 +977,12 @@ the possible corner cases (git doesn't do it, either). Committing renamed and copied files is fully supported if they're similar enough for git to detect them. +In SVN, it is possible (though discouraged) to commit changes to a tag +(because a tag is just a directory copy, thus technically the same as a +branch). When cloning an SVN repository, 'git svn' cannot know if such a +commit to a tag will happen in the future. Thus it acts conservatively +and imports all SVN tags as branches, prefixing the tag name with 'tags/'. + CONFIGURATION ------------- diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 981d3a8fc1..ef68ad2b71 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -3,13 +3,14 @@ git-symbolic-ref(1) NAME ---- -git-symbolic-ref - Read and modify symbolic refs +git-symbolic-ref - Read, modify and delete symbolic refs SYNOPSIS -------- [verse] 'git symbolic-ref' [-m <reason>] <name> <ref> 'git symbolic-ref' [-q] [--short] <name> +'git symbolic-ref' --delete [-q] <name> DESCRIPTION ----------- @@ -21,6 +22,9 @@ argument to see which branch your working tree is on. Given two arguments, creates or updates a symbolic ref <name> to point at the given branch <ref>. +Given `--delete` and an additional argument, deletes the given +symbolic ref. + A symbolic ref is a regular file that stores a string that begins with `ref: refs/`. For example, your `.git/HEAD` is a regular file whose contents is `ref: refs/heads/master`. @@ -28,6 +32,10 @@ a regular file whose contents is `ref: refs/heads/master`. OPTIONS ------- +-d:: +--delete:: + Delete the symbolic ref <name>. + -q:: --quiet:: Do not issue an error message if the <name> is not a diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 8d32b9a814..6470cffd32 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -13,17 +13,17 @@ SYNOPSIS <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>] + [--column[=<options>] | --no-column] [<pattern>...] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION ----------- -Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given to delete, list or verify tags. -Unless `-f` is given, the tag to be created must not yet exist in the -`.git/refs/tags/` directory. +Unless `-f` is given, the named tag must not yet exist. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command creates a 'tag' object, and requires a tag message. Unless @@ -84,6 +84,14 @@ OPTIONS using fnmatch(3)). Multiple patterns may be given; if any of them matches, the tag is shown. +--column[=<options>]:: +--no-column:: + Display tag listing in columns. See configuration variable + column.tag for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' respectively. ++ +This option is only applicable when listing tags without annotation lines. + --contains <commit>:: Only list tags which contain the specified commit. @@ -121,7 +129,7 @@ OPTIONS CONFIGURATION ------------- By default, 'git tag' in sign-with-default mode (-s) will use your -committer identity (of the form "Your Name <your@email.address>") to +committer identity (of the form "Your Name <\your@email.address>") to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows: diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 346e7a2079..f7362dc2d1 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -63,7 +63,7 @@ EXAMPLES Create a tarball for v1.4.0 release. -`git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz`:: +`git tar-tree v1.4.0^{tree} git-1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a tarball for v1.4.0 release, but without a global extended pax header. diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index a3081f4e23..9d0b1515c5 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -19,7 +19,7 @@ SYNOPSIS [--ignore-submodules] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] - [-z] [--stdin] + [-z] [--stdin] [--index-version <n>] [--verbose] [--] [<file>...] @@ -143,6 +143,10 @@ you will need to handle the situation manually. --verbose:: Report what is being added and removed from index. +--index-version <n>:: + Write the resulting index out in the named on-disk format version. + The current default version is 2. + -z:: Only meaningful with `--stdin` or `--index-info`; paths are separated with NUL character instead of LF. diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 988a3234f4..67edf58689 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -59,15 +59,6 @@ ifdef::git-default-pager[] The build you are using chose '{git-default-pager}' as the default. endif::git-default-pager[] -Diagnostics ------------ -You don't exist. Go away!:: - The passwd(5) gecos field couldn't be read -Your parents must have hated you!:: - The passwd(5) gecos field is longer than a giant static buffer. -Your sysadmin must hate you!:: - The passwd(5) name field is longer than a giant static buffer. - SEE ALSO -------- linkgit:git-commit-tree[1] diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 76c7f7eec5..6c8f510c3f 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -58,7 +58,7 @@ Examples 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.txt b/Documentation/git.txt index c2b523c589..555250dfa0 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -22,18 +22,17 @@ unusually rich command set that provides both high-level operations and full access to internals. See linkgit:gittutorial[7] to get started, then see -link:everyday.html[Everyday Git] for a useful minimum set of commands, and -"man git-commandname" for documentation of each command. CVS users may -also want to read linkgit:gitcvs-migration[7]. See -the link:user-manual.html[Git User's Manual] for a more in-depth -introduction. +link:everyday.html[Everyday Git] for a useful minimum set of +commands. The link:user-manual.html[Git User's Manual] has a more +in-depth introduction. -The '<command>' is either a name of a Git command (see below) or an alias -as defined in the configuration file (see linkgit:git-config[1]). +After you mastered the basic concepts, you can come back to this +page to learn what commands git offers. You can learn more about +individual git commands with "git help command". linkgit:gitcli[7] +manual page gives you an overview of the command line command syntax. -Formatted and hyperlinked version of the latest git -documentation can be viewed at -`http://www.kernel.org/pub/software/scm/git/docs/`. +Formatted and hyperlinked version of the latest git documentation +can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`. ifdef::stalenotes[] [NOTE] @@ -44,9 +43,49 @@ 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.10/git.html[documentation for release 1.7.10] +* link:v1.8.1.1/git.html[documentation for release 1.8.1.1] * release notes for + link:RelNotes/1.8.1.1.txt[1.8.1.1], + link:RelNotes/1.8.1.txt[1.8.1]. + +* link:v1.8.0.3/git.html[documentation for release 1.8.0.3] + +* release notes for + link:RelNotes/1.8.0.3.txt[1.8.0.3], + link:RelNotes/1.8.0.2.txt[1.8.0.2], + link:RelNotes/1.8.0.1.txt[1.8.0.1], + link:RelNotes/1.8.0.txt[1.8.0]. + +* link:v1.7.12.4/git.html[documentation for release 1.7.12.4] + +* release notes for + link:RelNotes/1.7.12.4.txt[1.7.12.4], + link:RelNotes/1.7.12.3.txt[1.7.12.3], + link:RelNotes/1.7.12.2.txt[1.7.12.2], + link:RelNotes/1.7.12.1.txt[1.7.12.1], + link:RelNotes/1.7.12.txt[1.7.12]. + +* link:v1.7.11.7/git.html[documentation for release 1.7.11.7] + +* release notes for + link:RelNotes/1.7.11.7.txt[1.7.11.7], + link:RelNotes/1.7.11.6.txt[1.7.11.6], + link:RelNotes/1.7.11.5.txt[1.7.11.5], + link:RelNotes/1.7.11.4.txt[1.7.11.4], + link:RelNotes/1.7.11.3.txt[1.7.11.3], + link:RelNotes/1.7.11.2.txt[1.7.11.2], + link:RelNotes/1.7.11.1.txt[1.7.11.1], + link:RelNotes/1.7.11.txt[1.7.11]. + +* link:v1.7.10.5/git.html[documentation for release 1.7.10.5] + +* release notes for + link:RelNotes/1.7.10.5.txt[1.7.10.5], + link:RelNotes/1.7.10.4.txt[1.7.10.4], + link:RelNotes/1.7.10.3.txt[1.7.10.3], + link:RelNotes/1.7.10.2.txt[1.7.10.2], + link:RelNotes/1.7.10.1.txt[1.7.10.1], link:RelNotes/1.7.10.txt[1.7.10]. * link:v1.7.9.7/git.html[documentation for release 1.7.9.7] @@ -390,24 +429,11 @@ help ...`. Do not use replacement refs to replace git objects. See linkgit:git-replace[1] for more information. +--literal-pathspecs:: + Treat pathspecs literally, rather than as glob patterns. This is + equivalent to setting the `GIT_LITERAL_PATHSPECS` environment + variable to `1`. -FURTHER DOCUMENTATION ---------------------- - -See the references above to get started using git. The following is -probably more detail than necessary for a first-time user. - -The link:user-manual.html#git-concepts[git concepts chapter of the -user-manual] and linkgit:gitcore-tutorial[7] both provide -introductions to the underlying git architecture. - -See linkgit:gitworkflows[7] for an overview of recommended workflows. - -See also the link:howto-index.html[howto] documents for some useful -examples. - -The internals are documented in the -link:technical/api-index.html[GIT API documentation]. GIT COMMANDS ------------ @@ -636,6 +662,7 @@ git so take care if using Cogito etc. If the 'GIT_DIR' environment variable is set then it specifies a path to use instead of the default `.git` for the base of the repository. + The '--git-dir' command-line option also sets this value. 'GIT_WORK_TREE':: Set the path to the working tree. The value will not be @@ -724,7 +751,7 @@ other 'GIT_EDITOR':: This environment variable overrides `$EDITOR` and `$VISUAL`. - It is used by several git comands when, on interactive mode, + It is used by several git commands when, on interactive mode, an editor is to be launched. See also linkgit:git-var[1] and the `core.editor` option in linkgit:git-config[1]. @@ -751,6 +778,14 @@ for further details. and read the password from its STDOUT. See also the 'core.askpass' option in linkgit:git-config[1]. +'GIT_CONFIG_NOSYSTEM':: + Whether to skip reading settings from the system-wide + `$(prefix)/etc/gitconfig` file. This environment variable can + be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a + predictable environment for a picky script, or you can set it + temporarily to avoid using a buggy `/etc/gitconfig` file while + waiting for someone with sufficient permissions to fix it. + 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', @@ -775,6 +810,16 @@ for further details. as a file path and will try to write the trace messages into it. +GIT_LITERAL_PATHSPECS:: + Setting this variable to `1` will cause git to treat all + pathspecs literally, rather than as glob patterns. For example, + running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search + for commits that touch the path `*.c`, not any paths that the + glob `*.c` matches. You might want this if you are feeding + literal paths to git (e.g., paths previously given to you by + `git ls-tree`, `--raw` diff output, etc). + + Discussion[[Discussion]] ------------------------ @@ -828,12 +873,37 @@ The index is also capable of storing multiple entries (called "stages") for a given pathname. These stages are used to hold the various unmerged version of a file when a merge is in progress. +FURTHER DOCUMENTATION +--------------------- + +See the references in the "description" section to get started +using git. The following is probably more detail than necessary +for a first-time user. + +The link:user-manual.html#git-concepts[git concepts chapter of the +user-manual] and linkgit:gitcore-tutorial[7] both provide +introductions to the underlying git architecture. + +See linkgit:gitworkflows[7] for an overview of recommended workflows. + +See also the link:howto-index.html[howto] documents for some useful +examples. + +The internals are documented in the +link:technical/api-index.html[GIT API documentation]. + +Users migrating from CVS may also want to +read linkgit:gitcvs-migration[7]. + + Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio C Hamano. Numerous contributions have come from the git mailing list -<git@vger.kernel.org>. For a more complete list of contributors, see -http://git-scm.com/about. If you have a clone of git.git itself, the +<git@vger.kernel.org>. http://www.ohloh.net/p/git/contributors/summary +gives you a more complete list of contributors. + +If you have a clone of git.git itself, the output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you the authors for specific parts of the project. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 80120ea14f..2698f63cf9 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -56,6 +56,7 @@ When more than one pattern matches the path, a later line overrides an earlier line. This overriding is done per attribute. The rules how the pattern matches paths are the same as in `.gitignore` files; see linkgit:gitignore[5]. +Unlike `.gitignore`, negative patterns are forbidden. When deciding what attributes are assigned to a path, git consults `$GIT_DIR/info/attributes` file (which has the highest @@ -66,6 +67,11 @@ is from the path in question, the lower its precedence). Finally global and system-wide files are considered (they have the lowest precedence). +When the `.gitattributes` file is missing from the work tree, the +path in the index is used as a fall-back. During checkout process, +`.gitattributes` in the index is used and then the file in the +working tree is used as a fall-back. + If you wish to affect only a single repository (i.e., to assign attributes to files that are particular to one user's workflow for that repository), then @@ -75,6 +81,8 @@ repositories (i.e., attributes of interest to all users) should go into `.gitattributes` files. Attributes that should affect all repositories for a single user should be placed in a file specified by the `core.attributesfile` configuration option (see linkgit:git-config[1]). +Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME +is either not set or empty, $HOME/.config/git/attributes is used instead. Attributes for all users on a system should be placed in the `$(prefix)/etc/gitattributes` file. @@ -509,6 +517,8 @@ configuration file (you still need to enable this with the attribute mechanism, via `.gitattributes`). The following built in patterns are available: +- `ada` suitable for source code in the Ada language. + - `bibtex` suitable for files with BibTeX coded references. - `cpp` suitable for source code in the C and C++ languages. @@ -925,7 +935,7 @@ file at the toplevel (i.e. not in any subdirectory). The built-in macro attribute "binary" is equivalent to: ------------ -[attr]binary -diff -text +[attr]binary -diff -merge -text ------------ diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index f734f97b8e..3bc1500eda 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -25,22 +25,39 @@ arguments. Here are the rules: are paths. * When an argument can be misunderstood as either a revision or a path, - they can be disambiguated by placing `\--` between them. - E.g. `git diff \-- HEAD` is, "I have a file called HEAD in my work + they can be disambiguated by placing `--` between them. + E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work tree. Please show changes between the version I staged in the index and what I have in the work tree for that file". not "show difference between the HEAD commit and the work tree as a whole". You can say - `git diff HEAD \--` to ask for the latter. + `git diff HEAD --` to ask for the latter. - * Without disambiguating `\--`, git makes a reasonable guess, but errors + * Without disambiguating `--`, git makes a reasonable guess, but errors out and asking you to disambiguate when ambiguous. E.g. if you have a file called HEAD in your work tree, `git diff HEAD` is ambiguous, and - you have to say either `git diff HEAD \--` or `git diff \-- HEAD` to + you have to say either `git diff HEAD --` or `git diff -- HEAD` to disambiguate. - ++ When writing a script that is expected to handle random user-input, it is a good practice to make it explicit which arguments are which by placing -disambiguating `\--` at appropriate places. +disambiguating `--` at appropriate places. + + * Many commands allow wildcards in paths, but you need to protect + them from getting globbed by the shell. These two mean different + things: ++ +-------------------------------- +$ git checkout -- *.c +$ git checkout -- \*.c +-------------------------------- ++ +The former lets your shell expand the fileglob, and you are asking +the dot-C files in your working tree to be overwritten with the version +in the index. The latter passes the `*.c` to Git, and you are asking +the paths in the index that match the pattern to be checked out to your +working tree. After running `git add hello.c; rm hello.c`, you will _not_ +see `hello.c` in your working tree with the former, but with the latter +you will. Here are the rules regarding the "flags" that you should follow when you are scripting git: @@ -62,13 +79,21 @@ scripting git: `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. + * many commands allow a long option "--option" to be abbreviated + only to their unique prefix (e.g. if there is no other option + whose name begins with "opt", you may be able to spell "--opt" to + invoke the "--option" flag), but you should fully spell them out + when writing your scripts; later versions of Git may introduce a + new option whose name shares the same prefix, e.g. "--optimize", + to make a short prefix that used to be unique no longer unique. + ENHANCED OPTION PARSER ---------------------- From the git 1.5.4 series and further, many git commands (not all of them at the time of the writing though) come with an enhanced option parser. -Here is an exhaustive list of the facilities provided by this option parser. +Here is a list of the facilities provided by this option parser. Magic Options @@ -112,6 +137,16 @@ options. This means that you can for example use `git rm -rf` or `git clean -fdx`. +Abbreviating long options +~~~~~~~~~~~~~~~~~~~~~~~~~ +Commands that support the enhanced option parser accepts unique +prefix of a long option as if it is fully spelled out, but use this +with a caution. For example, `git commit --amen` behaves as if you +typed `git commit --amend`, but that is true only until a later version +of Git introduces another option that shares the same prefix, +e.g `git commit --amenity" option. + + Separating argument from the option ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can write the mandatory option parameter to an option as a separate diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index fb0d5692a4..5325c5a7d5 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -151,8 +151,8 @@ to your working tree, you use the 'git update-index' program. That program normally just takes a list of filenames you want to update, but to avoid trivial mistakes, it refuses to add new entries to the index (or remove existing ones) unless you explicitly tell it that you're -adding a new entry with the `\--add` flag (or removing an entry with the -`\--remove`) flag. +adding a new entry with the `--add` flag (or removing an entry with the +`--remove`) flag. So to populate the index with the two files you just created, you can do @@ -399,10 +399,10 @@ $ git diff HEAD which ends up doing the above for you. In other words, 'git diff-index' normally compares a tree against the -working tree, but when given the `\--cached` flag, it is told to +working tree, but when given the `--cached` flag, it is told to instead compare against just the index cache contents, and ignore the current working tree state entirely. Since we just wrote the index -file to HEAD, doing `git diff-index \--cached -p HEAD` should thus return +file to HEAD, doing `git diff-index --cached -p HEAD` should thus return an empty set of differences, and that's exactly what it does. [NOTE] @@ -411,7 +411,7 @@ an empty set of differences, and that's exactly what it does. comparisons, and saying that it compares a tree against the working tree is thus not strictly accurate. In particular, the list of files to compare (the "meta-data") *always* comes from the index file, -regardless of whether the `\--cached` flag is used or not. The `\--cached` +regardless of whether the `--cached` flag is used or not. The `--cached` flag really only determines whether the file *contents* to be compared come from the working tree or not. @@ -433,7 +433,7 @@ update the index cache: $ git update-index hello ------------------------------------------------ -(note how we didn't need the `\--add` flag this time, since git knew +(note how we didn't need the `--add` flag this time, since git knew about the file already). Note what happens to the different 'git diff-{asterisk}' versions here. @@ -560,7 +560,7 @@ short history. When using the above two commands, the initial commit will be shown. If this is a problem because it is huge, you can hide it by setting the log.showroot configuration variable to false. Having this, you -can still show it for each command just adding the `\--root` option, +can still show it for each command just adding the `--root` option, which is a flag for 'git diff-tree' accepted by both commands. With that, you should now be having some inkling of what git does, and @@ -881,7 +881,7 @@ helps you view what's going on: $ gitk --all ---------------- -will show you graphically both of your branches (that's what the `\--all` +will show you graphically both of your branches (that's what the `--all` means: normally it will just show you your current `HEAD`) and their histories. You can also see exactly how they came to be from a common source. @@ -935,7 +935,7 @@ which will very loudly warn you that you're now committing a merge (which is correct, so never mind), and you can write a small merge message about your adventures in 'git merge'-land. -After you're done, start up `gitk \--all` to see graphically what the +After you're done, start up `gitk --all` to see graphically what the history looks like. Notice that `mybranch` still exists, and you can switch to it, and continue to work with it if you want to. The `mybranch` branch will not contain the merge, but next time you merge it @@ -956,13 +956,12 @@ $ git show-branch --topo-order --more=1 master mybranch ------------------------------------------------ The first two lines indicate that it is showing the two branches -and the first line of the commit log message from their -top-of-the-tree commits, you are currently on `master` branch -(notice the asterisk `{asterisk}` character), and the first column for -the later output lines is used to show commits contained in the +with the titles of their top-of-the-tree commits, you are currently on +`master` branch (notice the asterisk `*` character), and the first +column for the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` -branch. Three commits are shown along with their log messages. -All of them have non blank characters in the first column (`{asterisk}` +branch. Three commits are shown along with their titles. +All of them have non blank characters in the first column (`*` shows an ordinary commit on the current branch, `-` is a merge commit), which means they are now part of the `master` branch. Only the "Some work" commit has the plus `+` character in the second column, @@ -1002,8 +1001,8 @@ would be different) ---------------- Updating from ae3a2da... to a80b4aa.... Fast-forward (no commit created; -m option ignored) - example | 1 + - hello | 1 + + example | 1 + + hello | 1 + 2 files changed, 2 insertions(+) ---------------- @@ -1013,7 +1012,7 @@ not actually do a merge. Instead, it just updated the top of the tree of your branch to that of the `master` branch. This is often called 'fast-forward' merge. -You can run `gitk \--all` again to see how the commit ancestry +You can run `gitk --all` again to see how the commit ancestry looks like, or run 'show-branch', which tells you this. ------------------------------------------------ @@ -1257,7 +1256,7 @@ this 'collapsing' tends to trivially merge most of the paths fairly quickly, leaving only a handful of real changes in non-zero stages. -To look at only non-zero stages, use `\--unmerged` flag: +To look at only non-zero stages, use `--unmerged` flag: ------------ $ git ls-files --unmerged @@ -1420,7 +1419,7 @@ packed, and stores the packed file in `.git/objects/pack` directory. [NOTE] -You will see two files, `pack-{asterisk}.pack` and `pack-{asterisk}.idx`, +You will see two files, `pack-*.pack` and `pack-*.idx`, in `.git/objects/pack` directory. They are closely related to each other, and if you ever copy them by hand to a different repository for whatever reason, you should make sure you copy diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 066f825f2e..7dfffc0046 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -143,8 +143,8 @@ 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 +`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: diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 370624c171..daf1782a31 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -168,11 +168,11 @@ a similarity score different from the default of 50% by giving a number after the "-M" or "-C" option (e.g. "-M8" to tell it to use 8/10 = 80%). -Note. When the "-C" option is used with `\--find-copies-harder` +Note. When the "-C" option is used with `--find-copies-harder` option, 'git diff-{asterisk}' commands feed unmodified filepairs to diffcore mechanism as well as modified ones. This lets the copy detector consider unmodified files as copy source candidates at -the expense of making it slower. Without `\--find-copies-harder`, +the expense of making it slower. Without `--find-copies-harder`, 'git diff-{asterisk}' commands can detect copies only if the file that was copied happened to have been modified in the same changeset. @@ -224,7 +224,7 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String This transformation is used to find filepairs that represent changes that touch a specified string, and is controlled by the --S option and the `\--pickaxe-all` option to the 'git diff-{asterisk}' +-S option and the `--pickaxe-all` option to the 'git diff-*' commands. When diffcore-pickaxe is in use, it checks if there are @@ -233,9 +233,9 @@ different number of specified string. Such a filepair represents "the string appeared in this changeset". It also checks for the opposite case that loses the specified string. -When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves +When `--pickaxe-all` is not in effect, diffcore-pickaxe leaves only such filepairs that touch the specified string in its -output. When `\--pickaxe-all` is used, diffcore-pickaxe leaves all +output. When `--pickaxe-all` is used, diffcore-pickaxe leaves all filepairs intact if there is such a filepair, or makes the output empty otherwise. The latter behaviour is designed to make reviewing of the changes in the context of the whole diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 28edefa202..b9003fed24 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -73,7 +73,7 @@ pre-commit ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed -with `\--no-verify` option. It takes no parameter, and is +with `--no-verify` option. It takes no parameter, and is invoked before obtaining the proposed commit log message and making a commit. Exiting with non-zero status from this script causes the 'git commit' to abort. @@ -99,12 +99,12 @@ given); `template` (if a `-t` option was given or the configuration option `commit.template` is set); `merge` (if the commit is a merge or a `.git/MERGE_MSG` file exists); `squash` (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by -a commit SHA1 (if a `-c`, `-C` or `\--amend` option was given). +a commit SHA1 (if a `-c`, `-C` or `--amend` option was given). If the exit status is non-zero, 'git commit' will abort. The purpose of the hook is to edit the message file in place, and -it is not suppressed by the `\--no-verify` option. A non-zero exit +it is not suppressed by the `--no-verify` option. A non-zero exit means a failure of the hook and aborts the commit. It should not be used as replacement for pre-commit hook. @@ -115,7 +115,7 @@ commit-msg ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed -with `\--no-verify` option. It takes a single parameter, the +with `--no-verify` option. It takes a single parameter, the name of the file that holds the proposed commit log message. Exiting with non-zero status causes the 'git commit' to abort. diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 2e7328b830..91a6438031 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -41,16 +41,24 @@ precedence, the last matching pattern decides the outcome): variable 'core.excludesfile'. Which file to place a pattern in depends on how the pattern is meant to -be used. Patterns which should be version-controlled and distributed to -other repositories via clone (i.e., files that all developers will want -to ignore) should go into a `.gitignore` file. Patterns which are -specific to a particular repository but which do not need to be shared -with other related repositories (e.g., auxiliary files that live inside -the repository but are specific to one user's workflow) should go into -the `$GIT_DIR/info/exclude` file. Patterns which a user wants git to -ignore in all situations (e.g., backup or temporary files generated by -the user's editor of choice) generally go into a file specified by -`core.excludesfile` in the user's `~/.gitconfig`. +be used. + + * Patterns which should be version-controlled and distributed to + other repositories via clone (i.e., files that all developers will want + to ignore) should go into a `.gitignore` file. + + * Patterns which are + specific to a particular repository but which do not need to be shared + with other related repositories (e.g., auxiliary files that live inside + the repository but are specific to one user's workflow) should go into + the `$GIT_DIR/info/exclude` file. + + * Patterns which a user wants git to + ignore in all situations (e.g., backup or temporary files generated by + the user's editor of choice) generally go into a file specified by + `core.excludesfile` in the user's `~/.gitconfig`. Its default value is + $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or + empty, $HOME/.config/git/ignore is used instead. The underlying git plumbing tools, such as 'git ls-files' and 'git read-tree', read @@ -66,11 +74,15 @@ PATTERN FORMAT for readability. - A line starting with # serves as a comment. + Put a backslash ("`\`") in front of the first hash for patterns + that begin with a hash. - - An optional prefix '!' which negates the pattern; any + - An optional prefix "`!`" which negates the pattern; any matching file excluded by a previous pattern will become included again. If a negated pattern matches, this will override lower precedence patterns sources. + Put a backslash ("`\`") in front of the first "`!`" for patterns + that begin with a literal "`!`", for example, "`\!important!.txt`". - If the pattern ends with a slash, it is removed for the purpose of the following description, but it would only find @@ -96,6 +108,25 @@ PATTERN FORMAT For example, "/{asterisk}.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c". +Two consecutive asterisks ("`**`") in patterns matched against +full pathname may have special meaning: + + - A leading "`**`" followed by a slash means match in all + directories. For example, "`**/foo`" matches file or directory + "`foo`" anywhere, the same as pattern "`foo`". "**/foo/bar" + matches file or directory "`bar`" anywhere that is directly + under directory "`foo`". + + - A trailing "/**" matches everything inside. For example, + "abc/**" matches all files inside directory "abc", relative + to the location of the `.gitignore` file, with infinite depth. + + - A slash followed by two consecutive asterisks then a slash + matches zero or more directories. For example, "`a/**/b`" + matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on. + + - Other consecutive asterisks are considered invalid. + NOTES ----- diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 4e1fd52e7d..52d7ae4313 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -18,7 +18,9 @@ working tree, is a text file with a syntax matching the requirements of linkgit:git-config[1]. The file contains one subsection per submodule, and the subsection value -is the name of the submodule. Each submodule section also contains the +is the name of the submodule. The name is set to the path where the +submodule has been added unless it was customized with the '--name' +option of 'git submodule add'. Each submodule section also contains the following required keys: submodule.<name>.path:: @@ -41,8 +43,16 @@ submodule.<name>.update:: the commit specified in the superproject. If 'merge', the commit specified in the superproject will be merged into the current branch in the submodule. + If 'none', the submodule with name `$name` will not be updated + by default. + This config option is overridden if 'git submodule update' is given - the '--merge' or '--rebase' options. + the '--merge', '--rebase' or '--checkout' options. + +submodule.<name>.branch:: + A remote branch name for tracking updates in the upstream submodule. + If the option is not specified, it defaults to 'master'. See the + `--remote` documentation in linkgit:git-submodule[1] for details. submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 5c891f1169..9f628862b4 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -93,6 +93,12 @@ refs/remotes/`name`:: records tip-of-the-tree commit objects of branches copied from a remote repository. +refs/replace/`<obj-sha1>`:: + records the SHA1 of the object that replaces `<obj-sha1>`. + This is similar to info/grafts and is internally used and + maintained by linkgit:git-replace[1]. Such refs can be exchanged + between repositories while grafts are not. + packed-refs:: records the same information as refs/heads/, refs/tags/, and friends record in a more efficient way. See diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index dee050567e..f1cb6f3be6 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -139,9 +139,11 @@ them to the index, and commit, all in one step. A note on commit messages: Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more -thorough description. Tools that turn commits into email, for -example, use the first line on the Subject: line and the rest of the -commit in the body. +thorough description. The text up to the first blank line in a commit +message is treated as the commit title, and that title is used +throughout git. For example, linkgit:git-format-patch[1] turns a +commit into email, and it uses the title on the Subject line and the +rest of the commit in the body. Git tracks content not files ---------------------------- diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 4b8d1b1d4c..49474557d8 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -244,7 +244,7 @@ $highlight_bin:: 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. + use syntax highlighting. + *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` @@ -756,14 +756,14 @@ 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 + 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 +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. + diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 5e4f362ff8..8b8c6ae5d3 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -39,8 +39,8 @@ To achieve this, try to split your work into small steps from the very beginning. It is always easier to squash a few commits together than to split one big commit into several. Don't be afraid of making too small or imperfect steps along the way. You can always go back later -and edit the commits with `git rebase \--interactive` before you -publish them. You can use `git stash save \--keep-index` to run the +and edit the commits with `git rebase --interactive` before you +publish them. You can use `git stash save --keep-index` to run the test suite independent of other uncommitted changes; see the EXAMPLES section of linkgit:git-stash[1]. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 3595b586bc..f928b57f90 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -117,7 +117,7 @@ to point at the new commit. [[def_ent]]ent:: Favorite synonym to "<<def_tree-ish,tree-ish>>" by some total geeks. See - `http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth + http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth explanation. Avoid this term, not to confuse people. [[def_evil_merge]]evil merge:: diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index 8823a37067..ea6e4a52c9 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -5,6 +5,10 @@ Abstract: Imagine that git development is racing along as usual, when our friend neighborhood maintainer is struck down by a wayward bus. Out of the hordes of suckers (loyal developers), you have been tricked (chosen) to step up as the new maintainer. This howto will show you "how to" do it. +Content-type: text/asciidoc + +How to maintain Git +=================== The maintainer's git time is spent on three activities. diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt new file mode 100644 index 0000000000..36502f6718 --- /dev/null +++ b/Documentation/howto/new-command.txt @@ -0,0 +1,104 @@ +From: Eric S. Raymond <esr@thyrsus.com> +Abstract: This is how-to documentation for people who want to add extension + commands to git. It should be read alongside api-builtin.txt. +Content-type: text/asciidoc + +How to integrate new subcommands +================================ + +This is how-to documentation for people who want to add extension +commands to git. It should be read alongside api-builtin.txt. + +Runtime environment +------------------- + +git subcommands are standalone executables that live in the git exec +path, normally /usr/lib/git-core. The git executable itself is a +thin wrapper that knows where the subcommands live, and runs them by +passing command-line arguments to them. + +(If "git foo" is not found in the git exec path, the wrapper +will look in the rest of your $PATH for it. Thus, it's possible +to write local git extensions that don't live in system space.) + +Implementation languages +------------------------ + +Most subcommands are written in C or shell. A few are written in +Perl. + +While we strongly encourage coding in portable C for portability, +these specific scripting languages are also acceptable. We won't +accept more without a very strong technical case, as we don't want +to broaden the git suite's required dependencies. Import utilities, +surgical tools, remote helpers and other code at the edges of the +git suite are more lenient and we allow Python (and even Tcl/tk), +but they should not be used for core functions. + +This may change in the future. Especially Python is not allowed in +core because we need better Python integration in the git Windows +installer before we can be confident people in that environment +won't experience an unacceptably large loss of capability. + +C commands are normally written as single modules, named after the +command, that link a collection of functions called libgit. Thus, +your command 'git-foo' would normally be implemented as a single +"git-foo.c" (or "builtin/foo.c" if it is to be linked to the main +binary); this organization makes it easy for people reading the code +to find things. + +See the CodingGuidelines document for other guidance on what we consider +good practice in C and shell, and api-builtin.txt for the support +functions available to built-in commands written in C. + +What every extension command needs +---------------------------------- + +You must have a man page, written in asciidoc (this is what git help +followed by your subcommand name will display). Be aware that there is +a local asciidoc configuration and macros which you should use. It's +often helpful to start by cloning an existing page and replacing the +text content. + +You must have a test, written to report in TAP (Test Anything Protocol). +Tests are executables (usually shell scripts) that live in the 't' +subdirectory of the tree. Each test name begins with 't' and a sequence +number that controls where in the test sequence it will be executed; +conventionally the rest of the name stem is that of the command +being tested. + +Read the file t/README to learn more about the conventions to be used +in writing tests, and the test support library. + +Integrating a command +--------------------- + +Here are the things you need to do when you want to merge a new +subcommand into the git tree. + +1. Don't forget to sign off your patch! + +2. Append your command name to one of the variables BUILTIN_OBJS, +EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON. + +3. Drop its test in the t directory. + +4. If your command is implemented in an interpreted language with a +p-code intermediate form, make sure .gitignore in the main directory +includes a pattern entry that ignores such files. Python .pyc and +.pyo files will already be covered. + +5. If your command has any dependency on a particular version of +your language, document it in the INSTALL file. + +6. There is a file command-list.txt in the distribution main directory +that categorizes commands by type, so they can be listed in appropriate +subsections in the documentation's summary command list. Add an entry +for yours. To understand the categories, look at git-cmmands.txt +in the main directory. + +7. Give the maintainer one paragraph to include in the RelNotes file +to describe the new feature; a good place to do so is in the cover +letter [PATCH 0/n]. + +That's all there is to it. diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt index 74a1c0c4ba..4627ee47f2 100644 --- a/Documentation/howto/rebase-from-internal-branch.txt +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -8,7 +8,12 @@ Abstract: In this article, JC talks about how he rebases the the "master" branch, and how "rebase" works. Also discussed is how this applies to individual developers who sends patches upstream. +Content-type: text/asciidoc +How to rebase from an internal branch +===================================== + +-------------------------------------- Petr Baudis <pasky@suse.cz> writes: > Dear diary, on Sun, Aug 14, 2005 at 09:57:13AM CEST, I got a letter @@ -19,6 +24,7 @@ Petr Baudis <pasky@suse.cz> writes: >> > branch to the real branches. >> > Actually, wouldn't this be also precisely for what StGIT is intended to? +-------------------------------------- Exactly my feeling. I was sort of waiting for Catalin to speak up. With its basing philosophical ancestry on quilt, this is @@ -156,8 +162,3 @@ you continue on starting from the new "master" head, which is the #1' commit. -jc - -- -To unsubscribe from this list: send the line "unsubscribe git" in -the body of a message to majordomo@vger.kernel.org -More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/howto/rebuild-from-update-hook.txt b/Documentation/howto/rebuild-from-update-hook.txt index 48c67568d3..00c1b45b79 100644 --- a/Documentation/howto/rebuild-from-update-hook.txt +++ b/Documentation/howto/rebuild-from-update-hook.txt @@ -5,6 +5,10 @@ Date: Fri, 26 Aug 2005 18:19:10 -0700 Abstract: In this how-to article, JC talks about how he uses the post-update hook to automate git documentation page shown at http://www.kernel.org/pub/software/scm/git/docs/. +Content-type: text/asciidoc + +How to rebuild from update hook +=============================== The pages under http://www.kernel.org/pub/software/scm/git/docs/ are built from Documentation/ directory of the git.git project diff --git a/Documentation/howto/recover-corrupted-blob-object.txt b/Documentation/howto/recover-corrupted-blob-object.txt index 323b513ed0..7484735320 100644 --- a/Documentation/howto/recover-corrupted-blob-object.txt +++ b/Documentation/howto/recover-corrupted-blob-object.txt @@ -3,11 +3,17 @@ From: Linus Torvalds <torvalds@linux-foundation.org> Subject: corrupt object on git-gc Abstract: Some tricks to reconstruct blob objects in order to fix a corrupted repository. +Content-type: text/asciidoc +How to recover a corrupted blob object +====================================== + +----------------------------------------------------------- On Fri, 9 Nov 2007, Yossi Leybovich wrote: > > Did not help still the repository look for this object? > Any one know how can I track this object and understand which file is it +----------------------------------------------------------- So exactly *because* the SHA1 hash is cryptographically secure, the hash itself doesn't actually tell you anything, in order to fix a corrupt @@ -31,19 +37,23 @@ original object, so right now the corrupt object is useless, but it's very interesting for the future, in the hope that you can re-create a non-corrupt version. +----------------------------------------------------------- So: > ib]$ mv .git/objects/4b/9458b3786228369c63936db65827de3cc06200 ../ +----------------------------------------------------------- This is the right thing to do, although it's usually best to save it under it's full SHA1 name (you just dropped the "4b" from the result ;). Let's see what that tells us: +----------------------------------------------------------- > ib]$ git-fsck --full > broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 > to blob 4b9458b3786228369c63936db65827de3cc06200 > missing blob 4b9458b3786228369c63936db65827de3cc06200 +----------------------------------------------------------- Ok, I removed the "dangling commit" messages, because they are just messages about the fact that you probably have rebased etc, so they're not diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt index 6fd711996a..8a685483f4 100644 --- a/Documentation/howto/revert-a-faulty-merge.txt +++ b/Documentation/howto/revert-a-faulty-merge.txt @@ -7,6 +7,10 @@ Abstract: Sometimes a branch that was already merged to the mainline after the offending branch is fixed. Message-ID: <7vocz8a6zk.fsf@gitster.siamese.dyndns.org> References: <alpine.LFD.2.00.0812181949450.14014@localhost.localdomain> +Content-type: text/asciidoc + +How to revert a faulty merge +============================ Alan <alan@clueserver.org> said: diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt index 093c656048..a59ced8d04 100644 --- a/Documentation/howto/revert-branch-rebase.txt +++ b/Documentation/howto/revert-branch-rebase.txt @@ -8,8 +8,8 @@ Date: Mon, 29 Aug 2005 21:39:02 -0700 Content-type: text/asciidoc Message-ID: <7voe7g3uop.fsf@assigned-by-dhcp.cox.net> -Reverting an existing commit -============================ +How to revert an existing commit +================================ One of the changes I pulled into the 'master' branch turns out to break building GIT with GCC 2.95. While they were well intentioned diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt index 6d3eb8ed00..bd1027433b 100644 --- a/Documentation/howto/separating-topic-branches.txt +++ b/Documentation/howto/separating-topic-branches.txt @@ -1,6 +1,10 @@ From: Junio C Hamano <gitster@pobox.com> Subject: Separating topic branches Abstract: In this article, JC describes how to separate topic branches. +Content-type: text/asciidoc + +How to separate topic branches +============================== This text was originally a footnote to a discussion about the behaviour of the git diff commands. diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt index 622ee5c8dd..a695f01f0e 100644 --- a/Documentation/howto/setup-git-server-over-http.txt +++ b/Documentation/howto/setup-git-server-over-http.txt @@ -1,6 +1,10 @@ From: Rutger Nijlunsing <rutger@nospam.com> Subject: Setting up a git repository which can be pushed into and pulled from over HTTP(S). Date: Thu, 10 Aug 2006 22:00:26 +0200 +Content-type: text/asciidoc + +How to setup git server over http +================================= Since Apache is one of those packages people like to compile themselves while others prefer the bureaucrat's dream Debian, it is diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt index b7f8d416d6..a5193b1e5c 100644 --- a/Documentation/howto/update-hook-example.txt +++ b/Documentation/howto/update-hook-example.txt @@ -5,6 +5,10 @@ Message-ID: <7vfypumlu3.fsf@assigned-by-dhcp.cox.net> Abstract: An example hooks/update script is presented to implement repository maintenance policies, such as who can push into which branch and who can make a tag. +Content-type: text/asciidoc + +How to use the update hook +========================== When your developer runs git-push into the repository, git-receive-pack is run (either locally or over ssh) as that @@ -32,8 +36,7 @@ like this as your hooks/update script. [jc: editorial note. This is a much improved version by Carl since I posted the original outline] --- >8 -- beginning of script -- >8 -- - +---------------------------------------------------- #!/bin/bash umask 002 @@ -111,12 +114,12 @@ then info "Found matching head pattern: '$head_pattern'" for user_pattern in $user_patterns; do - info "Checking user: '$username' against pattern: '$user_pattern'" - matchlen=$(expr "$username" : "$user_pattern") - if test "$matchlen" = "${#username}" - then - grant "Allowing user: '$username' with pattern: '$user_pattern'" - fi + info "Checking user: '$username' against pattern: '$user_pattern'" + matchlen=$(expr "$username" : "$user_pattern") + if test "$matchlen" = "${#username}" + then + grant "Allowing user: '$username' with pattern: '$user_pattern'" + fi done deny "The user is not in the access list for this branch" done @@ -149,13 +152,13 @@ then info "Found matching head pattern: '$head_pattern'" for group_pattern in $group_patterns; do - for groupname in $groups; do - info "Checking group: '$groupname' against pattern: '$group_pattern'" - matchlen=$(expr "$groupname" : "$group_pattern") - if test "$matchlen" = "${#groupname}" - then - grant "Allowing group: '$groupname' with pattern: '$group_pattern'" - fi + for groupname in $groups; do + info "Checking group: '$groupname' against pattern: '$group_pattern'" + matchlen=$(expr "$groupname" : "$group_pattern") + if test "$matchlen" = "${#groupname}" + then + grant "Allowing group: '$groupname' with pattern: '$group_pattern'" + fi done done deny "None of the user's groups are in the access list for this branch" @@ -169,24 +172,21 @@ then fi deny >/dev/null "There are no more rules to check. Denying access" - --- >8 -- end of script -- >8 -- +---------------------------------------------------- This uses two files, $GIT_DIR/info/allowed-users and allowed-groups, to describe which heads can be pushed into by whom. The format of each file would look like this: - refs/heads/master junio - +refs/heads/pu junio - refs/heads/cogito$ pasky - refs/heads/bw/.* linus - refs/heads/tmp/.* .* - refs/tags/v[0-9].* junio + refs/heads/master junio + +refs/heads/pu junio + refs/heads/cogito$ pasky + refs/heads/bw/.* linus + refs/heads/tmp/.* .* + refs/tags/v[0-9].* junio With this, Linus can push or create "bw/penguin" or "bw/zebra" or "bw/panda" branches, Pasky can do only "cogito", and JC can do master and pu branches and make versioned tags. And anybody can do tmp/blah branches. The '+' sign at the pu record means that JC can make non-fast-forward pushes on it. - ------------- diff --git a/Documentation/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.txt index 4e2f75cb61..23cdf35435 100644 --- a/Documentation/howto/use-git-daemon.txt +++ b/Documentation/howto/use-git-daemon.txt @@ -1,4 +1,7 @@ +Content-type: text/asciidoc + How to use git-daemon +===================== Git can be run in inetd mode and in stand alone mode. But all you want is let a coworker pull from you, and therefore need to set up a git server diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt index 98c0033a55..00f693bde8 100644 --- a/Documentation/howto/using-signed-tag-in-pull-request.txt +++ b/Documentation/howto/using-signed-tag-in-pull-request.txt @@ -7,8 +7,8 @@ Abstract: Beginning v1.7.9, a contributor can push a signed tag to her later validate it. Content-type: text/asciidoc -Using signed tag in pull requests -================================= +How to use a signed tag in pull requests +======================================== A typical distributed workflow using Git is for a contributor to fork a project, build on it, publish the result to her public repository, and ask diff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt index 288f04e70c..4a8c276529 100644 --- a/Documentation/mailmap.txt +++ b/Documentation/mailmap.txt @@ -1,5 +1,6 @@ If the file `.mailmap` exists at the toplevel of the repository, or at -the location pointed to by the mailmap.file configuration option, it +the location pointed to by the mailmap.file or mailmap.blob +configuration options, it is used to map author and committer names and email addresses to canonical real names and email addresses. @@ -46,7 +47,7 @@ Jane Doe <jane@desktop.(none)> Joe R. Developer <joe@example.com> ------------ -Note how there is no need for an entry for <jane@laptop.(none)>, because the +Note how there is no need for an entry for `<jane@laptop.(none)>`, because the real name of that author is already correct. Example 2: Your repository contains commits from the following diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 861bd6f553..9bb4956ccd 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -9,11 +9,11 @@ merge.conflictstyle:: merge.defaultToUpstream:: If merge is called without any commit argument, merge the upstream branches configured for the current branch by using their last - observed values stored in their remote tracking branches. + observed values stored in their remote-tracking branches. The values of the `branch.<current branch>.merge` that name the branches at the remote named by `branch.<current branch>.remote` are consulted, and then they are mapped via `remote.<remote>.fetch` - to their corresponding remote tracking branches, and the tips of + to their corresponding remote-tracking branches, and the tips of these tracking branches are merged. merge.ff:: diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 595a3cf1a7..66db80296f 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -32,13 +32,14 @@ ours;; This option forces conflicting hunks to be auto-resolved cleanly by favoring 'our' version. Changes from the other tree that do not conflict with our side are reflected to the merge result. + For a binary file, the entire contents are taken from our side. + This should not be confused with the 'ours' merge strategy, which does not even look at what the other tree contains at all. It discards everything the other tree did, declaring 'our' history contains all that happened in it. theirs;; - This is opposite of 'ours'. + This is the opposite of 'ours'. patience;; With this option, 'merge-recursive' spends a little extra time diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 880b6f2e6f..105f18a6f9 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -130,8 +130,11 @@ The placeholders are: - '%b': body - '%B': raw body (unwrapped subject and body) - '%N': commit notes -- '%gD': reflog selector, e.g., `refs/stash@\{1\}` -- '%gd': shortened reflog selector, e.g., `stash@\{1\}` +- '%GG': raw verification message from GPG for a signed commit +- '%G?': show either "G" for Good or "B" for Bad for a signed commit +- '%GS': show the name of the signer for a signed commit +- '%gD': reflog selector, e.g., `refs/stash@{1}` +- '%gd': shortened reflog selector, e.g., `stash@{1}` - '%gn': reflog identity name - '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%ge': reflog identity email @@ -141,7 +144,11 @@ The placeholders are: - '%Cgreen': switch color to green - '%Cblue': switch color to blue - '%Creset': reset color -- '%C(...)': color specification, as described in color.branch.* config option +- '%C(...)': color specification, as described in color.branch.* config option; + adding `auto,` at the beginning will emit color only when colors are + enabled for log output (by `color.diff`, `color.ui`, or `--color`, and + respecting the `auto` settings of the former if we are going to a + terminal) - '%m': left, right or boundary mark - '%n': newline - '%%': a raw '%' @@ -155,7 +162,7 @@ insert an empty string unless we are traversing reflog entries (e.g., by `git log -g`). The `%d` placeholder will use the "short" decoration format if `--decorate` was not already provided on the command line. -If you add a `{plus}` (plus sign) after '%' of a placeholder, a line-feed +If you add a `+` (plus sign) after '%' of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string. diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 2a3dc8664f..5e499421a4 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -66,3 +66,7 @@ being displayed. Examples: "--notes=foo" will show only notes from --[no-]standard-notes:: These options are deprecated. Use the above --notes/--no-notes options instead. + +--show-signature:: + Check the validity of a signed commit object by passing the signature + to `gpg --verify` and show the output. diff --git a/Documentation/pt_BR/gittutorial.txt b/Documentation/pt_BR/gittutorial.txt deleted file mode 100644 index beba065252..0000000000 --- a/Documentation/pt_BR/gittutorial.txt +++ /dev/null @@ -1,675 +0,0 @@ -gittutorial(7) -============== - -NOME ----- -gittutorial - Um tutorial de introdução ao git (para versão 1.5.1 ou mais nova) - -SINOPSE --------- -git * - -DESCRIÇÃO ------------ - -Este tutorial explica como importar um novo projeto para o git, -adicionar mudanças a ele, e compartilhar mudanças com outros -desenvolvedores. - -Se, ao invés disso, você está interessado primariamente em usar git para -obter um projeto, por exemplo, para testar a última versão, você pode -preferir começar com os primeiros dois capÃtulos de -link:user-manual.html[O Manual do Usuário Git]. - -Primeiro, note que você pode obter documentação para um comando como -`git log --graph` com: - ------------------------------------------------- -$ man git-log ------------------------------------------------- - -ou: - ------------------------------------------------- -$ git help log ------------------------------------------------- - -Com a última forma, você pode usar o visualizador de manual de sua -escolha; veja linkgit:git-help[1] para maior informação. - -É uma boa idéia informar ao git seu nome e endereço público de email -antes de fazer qualquer operação. A maneira mais fácil de fazê-lo é: - ------------------------------------------------- -$ git config --global user.name "Seu Nome Vem Aqui" -$ git config --global user.email voce@seudominio.exemplo.com ------------------------------------------------- - - -Importando um novo projeto ------------------------ - -Assuma que você tem um tarball project.tar.gz com seu trabalho inicial. -Você pode colocá-lo sob controle de revisão git da seguinte forma: - ------------------------------------------------- -$ tar xzf project.tar.gz -$ cd project -$ git init ------------------------------------------------- - -Git irá responder - ------------------------------------------------- -Initialized empty Git repository in .git/ ------------------------------------------------- - -Agora que você iniciou seu diretório de trabalho, você deve ter notado que um -novo diretório foi criado com o nome de ".git". - -A seguir, diga ao git para gravar um instantâneo do conteúdo de todos os -arquivos sob o diretório atual (note o '.'), com 'git-add': - ------------------------------------------------- -$ git add . ------------------------------------------------- - -Este instantâneo está agora armazenado em uma área temporária que o git -chama de "index" ou Ãndice. Você pode armazenar permanentemente o -conteúdo do Ãndice no repositório com 'git-commit': - ------------------------------------------------- -$ git commit ------------------------------------------------- - -Isto vai te pedir por uma mensagem de commit. Você agora gravou sua -primeira versão de seu projeto no git. - -Fazendo mudanças --------------- - -Modifique alguns arquivos, e, então, adicione seu conteúdo atualizado ao -Ãndice: - ------------------------------------------------- -$ git add file1 file2 file3 ------------------------------------------------- - -Você está agora pronto para fazer o commit. Você pode ver o que está -para ser gravado usando 'git-diff' com a opção --cached: - ------------------------------------------------- -$ git diff --cached ------------------------------------------------- - -(Sem --cached, o comando 'git-diff' irá te mostrar quaisquer mudanças -que você tenha feito mas ainda não adicionou ao Ãndice.) Você também -pode obter um breve sumário da situação com 'git-status': - ------------------------------------------------- -$ git status -# On branch master -# Changes to be committed: -# (use "git reset HEAD <file>..." to unstage) -# -# modified: file1 -# modified: file2 -# modified: file3 -# ------------------------------------------------- - -Se você precisar fazer qualquer outro ajuste, faça-o agora, e, então, -adicione qualquer conteúdo modificado ao Ãndice. Finalmente, grave suas -mudanças com: - ------------------------------------------------- -$ git commit ------------------------------------------------- - -Ao executar esse comando, ele irá te pedir uma mensagem descrevendo a mudança, -e, então, irá gravar a nova versão do projeto. - -Alternativamente, ao invés de executar 'git-add' antes, você pode usar - ------------------------------------------------- -$ git commit -a ------------------------------------------------- - -o que irá automaticamente notar quaisquer arquivos modificados (mas não -novos), adicioná-los ao Ãndices, e gravar, tudo em um único passo. - -Uma nota em mensagens de commit: Apesar de não ser exigido, é uma boa -idéia começar a mensagem com uma simples e curta (menos de 50 -caracteres) linha sumarizando a mudança, seguida de uma linha em branco -e, então, uma descrição mais detalhada. Ferramentas que transformam -commits em email, por exemplo, usam a primeira linha no campo de -cabeçalho "Subject:" e o resto no corpo. - -Git rastreia conteúdo, não arquivos ----------------------------- - -Muitos sistemas de controle de revisão provêem um comando `add` que diz -ao sistema para começar a rastrear mudanças em um novo arquivo. O -comando `add` do git faz algo mais simples e mais poderoso: 'git-add' é -usado tanto para arquivos novos e arquivos recentemente modificados, e -em ambos os casos, ele tira o instantâneo dos arquivos dados e armazena -o conteúdo no Ãndice, pronto para inclusão do próximo commit. - -Visualizando a história do projeto ------------------------ - -Em qualquer ponto você pode visualizar a história das suas mudanças -usando - ------------------------------------------------- -$ git log ------------------------------------------------- - -Se você também quiser ver a diferença completa a cada passo, use - ------------------------------------------------- -$ git log -p ------------------------------------------------- - -Geralmente, uma visão geral da mudança é útil para ter a sensação de -cada passo - ------------------------------------------------- -$ git log --stat --summary ------------------------------------------------- - -Gerenciando "branches"/ramos ------------------ - -Um simples repositório git pode manter múltiplos ramos de -desenvolvimento. Para criar um novo ramo chamado "experimental", use - ------------------------------------------------- -$ git branch experimental ------------------------------------------------- - -Se você executar agora - ------------------------------------------------- -$ git branch ------------------------------------------------- - -você vai obter uma lista de todos os ramos existentes: - ------------------------------------------------- - experimental -* master ------------------------------------------------- - -O ramo "experimental" é o que você acaba de criar, e o ramo "master" é o -ramo padrão que foi criado pra você automaticamente. O asterisco marca -o ramo em que você está atualmente; digite - ------------------------------------------------- -$ git checkout experimental ------------------------------------------------- - -para mudar para o ramo experimental. Agora edite um arquivo, grave a -mudança, e mude de volta para o ramo master: - ------------------------------------------------- -(edita arquivo) -$ git commit -a -$ git checkout master ------------------------------------------------- - -Verifique que a mudança que você fez não está mais visÃvel, já que ela -foi feita no ramo experimental e você está de volta ao ramo master. - -Você pode fazer uma mudança diferente no ramo master: - ------------------------------------------------- -(edit file) -$ git commit -a ------------------------------------------------- - -neste ponto, os dois ramos divergiram, com diferentes mudanças feitas em -cada um. Para unificar as mudanças feitas no experimental para o -master, execute - ------------------------------------------------- -$ git merge experimental ------------------------------------------------- - -Se as mudanças não conflitarem, estará pronto. Se existirem conflitos, -marcadores serão deixados nos arquivos problemáticos exibindo o -conflito; - ------------------------------------------------- -$ git diff ------------------------------------------------- - -vai exibir isto. Após você editar os arquivos para resolver os -conflitos, - ------------------------------------------------- -$ git commit -a ------------------------------------------------- - -irá gravar o resultado da unificação. Finalmente, - ------------------------------------------------- -$ gitk ------------------------------------------------- - -vai mostrar uma bela representação gráfica da história resultante. - -Neste ponto você pode remover seu ramo experimental com - ------------------------------------------------- -$ git branch -d experimental ------------------------------------------------- - -Este comando garante que as mudanças no ramo experimental já estão no -ramo atual. - -Se você desenvolve em um ramo ideia-louca, e se arrepende, você pode -sempre remover o ramo com - -------------------------------------- -$ git branch -D ideia-louca -------------------------------------- - -Ramos são baratos e fáceis, então isto é uma boa maneira de experimentar -alguma coisa. - -Usando git para colaboração ---------------------------- - -Suponha que Alice começou um novo projeto com um repositório git em -/home/alice/project, e que Bob, que tem um diretório home na mesma -máquina, quer contribuir. - -Bob começa com: - ------------------------------------------------- -bob$ git clone /home/alice/project myrepo ------------------------------------------------- - -Isso cria um novo diretório "myrepo" contendo um clone do repositório de -Alice. O clone está no mesmo pé que o projeto original, possuindo sua -própria cópia da história do projeto original. - -Bob então faz algumas mudanças e as grava: - ------------------------------------------------- -(editar arquivos) -bob$ git commit -a -(repetir conforme necessário) ------------------------------------------------- - -Quanto está pronto, ele diz a Alice para puxar as mudanças do -repositório em /home/bob/myrepo. Ela o faz com: - ------------------------------------------------- -alice$ cd /home/alice/project -alice$ git pull /home/bob/myrepo master ------------------------------------------------- - -Isto unifica as mudanças do ramo "master" do Bob ao ramo atual de Alice. -Se Alice fez suas próprias mudanças no intervalo, ela, então, pode -precisar corrigir manualmente quaisquer conflitos. (Note que o argumento -"master" no comando acima é, de fato, desnecessário, já que é o padrão.) - -O comando "pull" executa, então, duas operações: ele obtém mudanças de -um ramo remoto, e, então, as unifica no ramo atual. - -Note que, em geral, Alice gostaria que suas mudanças locais fossem -gravadas antes de iniciar este "pull". Se o trabalho de Bob conflita -com o que Alice fez desde que suas histórias se ramificaram, Alice irá -usar seu diretório de trabalho e o Ãndice para resolver conflitos, e -mudanças locais existentes irão interferir com o processo de resolução -de conflitos (git ainda irá realizar a obtenção mas irá se recusar a -unificar --- Alice terá que se livrar de suas mudanças locais de alguma -forma e puxar de novo quando isso acontecer). - -Alice pode espiar o que Bob fez sem unificar primeiro, usando o comando -"fetch"; isto permite Alice inspecionar o que Bob fez, usando um sÃmbolo -especial "FETCH_HEAD", com o fim de determinar se ele tem alguma coisa -que vale puxar, assim: - ------------------------------------------------- -alice$ git fetch /home/bob/myrepo master -alice$ git log -p HEAD..FETCH_HEAD ------------------------------------------------- - -Esta operação é segura mesmo se Alice tem mudanças locais não gravadas. -A notação de intervalo "HEAD..FETCH_HEAD" significa mostrar tudo que é -alcançável de FETCH_HEAD mas exclua tudo o que é alcançável de HEAD. -Alice já sabe tudo que leva a seu estado atual (HEAD), e revisa o que Bob -tem em seu estado (FETCH_HEAD) que ela ainda não viu com esse comando. - -Se Alice quer visualizar o que Bob fez desde que suas histórias se -ramificaram, ela pode disparar o seguinte comando: - ------------------------------------------------- -$ gitk HEAD..FETCH_HEAD ------------------------------------------------- - -Isto usa a mesma notação de intervalo que vimos antes com 'git log'. - -Alice pode querer ver o que ambos fizeram desde que ramificaram. Ela -pode usar a forma com três pontos ao invés da forma com dois pontos: - ------------------------------------------------- -$ gitk HEAD...FETCH_HEAD ------------------------------------------------- - -Isto significa "mostre tudo que é alcançável de qualquer um deles, mas -exclua tudo que é alcançável a partir de ambos". - -Por favor, note que essas notações de intervalo podem ser usadas tanto -com gitk quanto com "git log". - -Após inspecionar o que Bob fez, se não há nada urgente, Alice pode -decidir continuar trabalhando sem puxar de Bob. Se a história de Bob -tem alguma coisa que Alice precisa imediatamente, Alice pode optar por -separar seu trabalho em progresso primeiro, fazer um "pull", e, então, -finalmente, retomar seu trabalho em progresso em cima da história -resultante. - -Quando você está trabalhando em um pequeno grupo unido, não é incomum -interagir com o mesmo repositório várias e várias vezes. Definindo um -repositório remoto antes de tudo, você pode fazê-lo mais facilmente: - ------------------------------------------------- -alice$ git remote add bob /home/bob/myrepo ------------------------------------------------- - -Com isso, Alice pode executar a primeira parte da operação "pull" usando -o comando 'git-fetch' sem unificar suas mudanças com seu próprio ramo, -usando: - -------------------------------------- -alice$ git fetch bob -------------------------------------- - -Diferente da forma longa, quando Alice obteve de Bob usando um -repositório remoto antes definido com 'git-remote', o que foi obtido é -armazenado em um ramo remoto, neste caso `bob/master`. Então, após isso: - -------------------------------------- -alice$ git log -p master..bob/master -------------------------------------- - -mostra uma lista de todas as mudanças que Bob fez desde que ramificou do -ramo master de Alice. - -Após examinar essas mudanças, Alice pode unificá-las em seu ramo master: - -------------------------------------- -alice$ git merge bob/master -------------------------------------- - -Esse `merge` pode também ser feito puxando de seu próprio ramo remoto, -assim: - -------------------------------------- -alice$ git pull . remotes/bob/master -------------------------------------- - -Note que 'git pull' sempre unifica ao ramo atual, independente do que -mais foi passado na linha de comando. - -Depois, Bob pode atualizar seu repositório com as últimas mudanças de -Alice, usando - -------------------------------------- -bob$ git pull -------------------------------------- - -Note que ele não precisa dar o caminho do repositório de Alice; quando -Bob clonou seu repositório, o git armazenou a localização de seu -repositório na configuração do mesmo, e essa localização é usada -para puxar: - -------------------------------------- -bob$ git config --get remote.origin.url -/home/alice/project -------------------------------------- - -(A configuração completa criada por 'git-clone' é visÃvel usando `git -config -l`, e a página de manual linkgit:git-config[1] explica o -significado de cada opção.) - -Git também mantém uma cópia limpa do ramo master de Alice sob o nome -"origin/master": - -------------------------------------- -bob$ git branch -r - origin/master -------------------------------------- - -Se Bob decidir depois em trabalhar em um host diferente, ele ainda pode -executar clones e puxar usando o protocolo ssh: - -------------------------------------- -bob$ git clone alice.org:/home/alice/project myrepo -------------------------------------- - -Alternativamente, o git tem um protocolo nativo, ou pode usar rsync ou -http; veja linkgit:git-pull[1] para detalhes. - -Git pode também ser usado em um modo parecido com CVS, com um -repositório central para o qual vários usuários empurram modificações; -veja linkgit:git-push[1] e linkgit:gitcvs-migration[7]. - -Explorando história ------------------ - -A história no git é representada como uma série de commits -interrelacionados. Nós já vimos que o comando 'git-log' pode listar -esses commits. Note que a primeira linha de cada entrada no log também -dá o nome para o commit: - -------------------------------------- -$ git log -commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 -Author: Junio C Hamano <junkio@cox.net> -Date: Tue May 16 17:18:22 2006 -0700 - - merge-base: Clarify the comments on post processing. -------------------------------------- - -Nós podemos dar este nome ao 'git-show' para ver os detalhes sobre este -commit. - -------------------------------------- -$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 -------------------------------------- - -Mas há outras formas de se referir aos commits. Você pode usar qualquer -parte inicial do nome que seja longo o bastante para identificar -unicamente o commit: - -------------------------------------- -$ git show c82a22c39c # os primeiros caracteres do nome são o bastante - # usualmente -$ git show HEAD # a ponta do ramo atual -$ git show experimental # a ponta do ramo "experimental" -------------------------------------- - -Todo commit normalmente tem um commit "pai" que aponta para o estado -anterior do projeto: - -------------------------------------- -$ git show HEAD^ # para ver o pai de HEAD -$ git show HEAD^^ # para ver o avô de HEAD -$ git show HEAD~4 # para ver o trisavô de HEAD -------------------------------------- - -Note que commits de unificação podem ter mais de um pai: - -------------------------------------- -$ git show HEAD^1 # mostra o primeiro pai de HEAD (o mesmo que HEAD^) -$ git show HEAD^2 # mostra o segundo pai de HEAD -------------------------------------- - -Você também pode dar aos commits nomes à sua escolha; após executar - -------------------------------------- -$ git tag v2.5 1b2e1d63ff -------------------------------------- - -você pode se referir a 1b2e1d63ff pelo nome "v2.5". Se você pretende -compartilhar esse nome com outras pessoas (por exemplo, para identificar -uma versão de lançamento), você deveria criar um objeto "tag", e talvez -assiná-lo; veja linkgit:git-tag[1] para detalhes. - -Qualquer comando git que precise conhecer um commit pode receber -quaisquer desses nomes. Por exemplo: - -------------------------------------- -$ git diff v2.5 HEAD # compara o HEAD atual com v2.5 -$ git branch stable v2.5 # inicia um novo ramo chamado "stable" baseado - # em v2.5 -$ git reset --hard HEAD^ # reseta seu ramo atual e seu diretório de - # trabalho a seu estado em HEAD^ -------------------------------------- - -Seja cuidadoso com o último comando: além de perder quaisquer mudanças -em seu diretório de trabalho, ele também remove todos os commits -posteriores desse ramo. Se esse ramo é o único ramo contendo esses -commits, eles serão perdidos. Também, não use 'git-reset' num ramo -publicamente visÃvel de onde outros desenvolvedores puxam, já que vai -forçar unificações desnecessárias para que outros desenvolvedores limpem -a história. Se você precisa desfazer mudanças que você empurrou, use -'git-revert' no lugar. - -O comando 'git-grep' pode buscar strings em qualquer versão de seu -projeto, então - -------------------------------------- -$ git grep "hello" v2.5 -------------------------------------- - -procura por todas as ocorrências de "hello" em v2.5. - -Se você deixar de fora o nome do commit, 'git-grep' irá procurar -quaisquer dos arquivos que ele gerencia no diretório corrente. Então - -------------------------------------- -$ git grep "hello" -------------------------------------- - -é uma forma rápida de buscar somente os arquivos que são rastreados pelo -git. - -Muitos comandos git também recebem um conjunto de commits, o que pode -ser especificado de várias formas. Aqui estão alguns exemplos com 'git-log': - -------------------------------------- -$ git log v2.5..v2.6 # commits entre v2.5 e v2.6 -$ git log v2.5.. # commits desde v2.5 -$ git log --since="2 weeks ago" # commits das últimas 2 semanas -$ git log v2.5.. Makefile # commits desde v2.5 que modificam - # Makefile -------------------------------------- - -Você também pode dar ao 'git-log' um "intervalo" de commits onde o -primeiro não é necessariamente um ancestral do segundo; por exemplo, se -as pontas dos ramos "stable" e "master" divergiram de um commit -comum algum tempo atrás, então - -------------------------------------- -$ git log stable..master -------------------------------------- - -irá listar os commits feitos no ramo "master" mas não no ramo -"stable", enquanto - -------------------------------------- -$ git log master..stable -------------------------------------- - -irá listar a lista de commits feitos no ramo "stable" mas não no ramo -"master". - -O comando 'git-log' tem uma fraqueza: ele precisa mostrar os commits em -uma lista. Quando a história tem linhas de desenvolvimento que -divergiram e então foram unificadas novamente, a ordem em que 'git-log' -apresenta essas mudanças é irrelevante. - -A maioria dos projetos com múltiplos contribuidores (como o kernel -Linux, ou o próprio git) tem unificações frequentes, e 'gitk' faz um -trabalho melhor de visualizar sua história. Por exemplo, - -------------------------------------- -$ gitk --since="2 weeks ago" drivers/ -------------------------------------- - -permite a você navegar em quaisquer commits desde as últimas duas semanas -de commits que modificaram arquivos sob o diretório "drivers". (Nota: -você pode ajustar as fontes do gitk segurando a tecla control enquanto -pressiona "-" ou "+".) - -Finalmente, a maioria dos comandos que recebem nomes de arquivo permitirão -também, opcionalmente, preceder qualquer nome de arquivo por um -commit, para especificar uma versão particular do arquivo: - -------------------------------------- -$ git diff v2.5:Makefile HEAD:Makefile.in -------------------------------------- - -Você pode usar 'git-show' para ver tal arquivo: - -------------------------------------- -$ git show v2.5:Makefile -------------------------------------- - -Próximos passos ----------- - -Este tutorial deve ser o bastante para operar controle de revisão -distribuÃdo básico para seus projetos. No entanto, para entender -plenamente a profundidade e o poder do git você precisa entender duas -idéias simples nas quais ele se baseia: - - * A base de objetos é um sistema bem elegante usado para armazenar a - história de seu projeto--arquivos, diretórios, e commits. - - * O arquivo de Ãndice é um cache do estado de uma árvore de diretório, - usado para criar commits, restaurar diretórios de trabalho, e - armazenar as várias árvores envolvidas em uma unificação. - -A parte dois deste tutorial explica a base de objetos, o arquivo de -Ãndice, e algumas outras coisinhas que você vai precisar pra usar o -máximo do git. Você pode encontrá-la em linkgit:gittutorial-2[7]. - -Se você não quiser continuar com o tutorial agora nesse momento, algumas -outras digressões que podem ser interessantes neste ponto são: - - * linkgit:git-format-patch[1], linkgit:git-am[1]: Estes convertem - séries de commits em patches para email, e vice-versa, úteis para - projetos como o kernel Linux que dependem fortemente de patches - enviados por email. - - * linkgit:git-bisect[1]: Quando há uma regressão em seu projeto, uma - forma de rastrear um bug é procurando pela história para encontrar o - commit culpado. Git bisect pode ajudar a executar uma busca binária - por esse commit. Ele é inteligente o bastante para executar uma - busca próxima da ótima mesmo no caso de uma história complexa - não-linear com muitos ramos unificados. - - * link:everyday.html[GIT diariamente com 20 e tantos comandos] - - * linkgit:gitcvs-migration[7]: Git para usuários de CVS. - -VEJA TAMBÉM --------- -linkgit:gittutorial-2[7], -linkgit:gitcvs-migration[7], -linkgit:gitcore-tutorial[7], -linkgit:gitglossary[7], -linkgit:git-help[1], -link:everyday.html[git diariamente], -link:user-manual.html[O Manual do Usuário git] - -GIT ---- -Parte da suite linkgit:git[1]. diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 5dd6e5a0c7..94a9d32f1d 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -13,7 +13,7 @@ endif::git-pull[] <refspec>:: The format of a <refspec> parameter is an optional plus - `{plus}`, followed by the source ref <src>, followed + `+`, followed by the source ref <src>, followed by a colon `:`, followed by the destination ref <dst>. + The remote ref that matches <src> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 6a4b6355ba..1ec14a068e 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -3,12 +3,20 @@ Commit Limiting Besides specifying a range of commits that should be listed using the special notations explained in the description, additional commit -limiting may be applied. Note that they are applied before commit -ordering and formatting options, such as '--reverse'. +limiting may be applied. + +Using more options generally further limits the output (e.g. +`--since=<date1>` limits to commits newer than `<date1>`, and using it +with `--grep=<pattern>` further limits to commits whose log message +has a line that matches `<pattern>`), unless otherwise noted. + +Note that these are applied before commit +ordering and formatting options, such as `--reverse`. -- --n 'number':: +-<number>:: +-n <number>:: --max-count=<number>:: Limit the number of commits to output. @@ -38,22 +46,44 @@ endif::git-rev-list[] --committer=<pattern>:: Limit the commits output to ones with author/committer - header lines that match the specified pattern (regular expression). + header lines that match the specified pattern (regular + expression). With more than one `--author=<pattern>`, + commits whose author matches any of the given patterns are + chosen (similarly for multiple `--committer=<pattern>`). + +--grep-reflog=<pattern>:: + + Limit the commits output to ones with reflog entries that + match the specified pattern (regular expression). With + more than one `--grep-reflog`, commits whose reflog message + matches any of the given patterns are chosen. It is an + error to use this option unless `--walk-reflogs` is in use. --grep=<pattern>:: Limit the commits output to ones with log message that - matches the specified pattern (regular expression). + matches the specified pattern (regular expression). With + more than one `--grep=<pattern>`, commits whose message + matches any of the given patterns are chosen (but see + `--all-match`). ++ +When `--show-notes` is in effect, the message from the notes as +if it is part of the log message. --all-match:: Limit the commits output to ones that match all given --grep, - --author and --committer instead of ones that match at least one. + instead of ones that match at least one. -i:: --regexp-ignore-case:: Match the regexp limiting patterns without regard to letters case. +--basic-regexp:: + + Consider the limiting patterns to be basic regular expressions; + this is the default. + -E:: --extended-regexp:: @@ -66,6 +96,11 @@ endif::git-rev-list[] Consider the limiting patterns to be fixed strings (don't interpret pattern as a regular expression). +--perl-regexp:: + + Consider the limiting patterns to be Perl-compatible regexp. + Requires libpcre to be compiled in. + --remove-empty:: Stop when a given path disappears from the tree. @@ -198,7 +233,7 @@ excluded from the output. + For example, `--cherry-pick --right-only A...B` omits those commits from `B` which are in `A` or are patch-equivalent to a commit in -`A`. In other words, this lists the `{plus}` commits from `git cherry A B`. +`A`. In other words, this lists the `+` commits from `git cherry A B`. More precisely, `--cherry-pick --right-only --no-merges` gives the exact list. @@ -455,7 +490,7 @@ The effect of this is best shown by way of comparing to `---------' ----------------------------------------------------------------------- + -Note the major differences in `N` and `P` over '\--full-history': +Note the major differences in `N` and `P` over '--full-history': + -- * `N`'s parent list had `I` removed, because it is an ancestor of the @@ -494,7 +529,7 @@ of course). When we want to find out what commits in `M` are contaminated with the bug introduced by `D` and need fixing, however, we might want to view only the subset of 'D..M' that are actually descendants of `D`, i.e. -excluding `C` and `K`. This is exactly what the '\--ancestry-path' +excluding `C` and `K`. This is exactly what the '--ancestry-path' option does. Applied to the 'D..M' range, it results in: + ----------------------------------------------------------------------- @@ -578,16 +613,33 @@ Commit Ordering By default, the commits are shown in reverse chronological order. ---topo-order:: +--date-order:: + Show no parents before all of its children are shown, but + otherwise show commits in the commit timestamp order. - This option makes them appear in topological order (i.e. - descendant commits are shown before their parents). +--topo-order:: + Show no parents before all of its children are shown, and + avoid showing commits on multiple lines of history + intermixed. ++ +For example, in a commit history like this: ++ +---------------------------------------------------------------- ---date-order:: + ---1----2----4----7 + \ \ + 3----5----6----8--- - This option is similar to '--topo-order' in the sense that no - parent comes before all of its children, but otherwise things - are still ordered in the commit timestamp order. +---------------------------------------------------------------- ++ +where the numbers denote the order of commit timestamps, `git +rev-list` and friends with `--date-order` show the commits in the +timestamp order: 8 7 6 5 4 3 2 1. ++ +With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 +3 1); some older commits are shown before newer ones in order to +avoid showing the commits from two parallel development track mixed +together. --reverse:: @@ -619,9 +671,14 @@ These options are mostly targeted for packing of git repositories. Only useful with '--objects'; print the object IDs that are not in packs. ---no-walk:: +--no-walk[=(sorted|unsorted)]:: - Only show the given revs, but do not traverse their ancestors. + Only show the given commits, but do not traverse their ancestors. + This has no effect if a range is specified. If the argument + "unsorted" is given, the commits are show in the order they were + given on the command line. Otherwise (if "sorted" or no argument + was given), the commits are show in reverse chronological order + by commit time. --do-walk:: @@ -759,7 +816,7 @@ options may be given. See linkgit:git-diff-files[1] for more options. --cc:: - This flag implies the '-c' options and further compresses the + This flag implies the '-c' option and further compresses the patch output by omitting uninteresting hunks whose contents in the parents have only two variants and the merge result picks one of them without modification. diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 1725661837..991fcd8f3f 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -24,22 +24,22 @@ blobs contained in a commit. object referenced by 'refs/heads/master'. If you happen to have both 'heads/master' and 'tags/master', you can explicitly say 'heads/master' to tell git which one you mean. - When ambiguous, a '<name>' is disambiguated by taking the + When ambiguous, a '<refname>' is disambiguated by taking the first match in the following rules: - . If '$GIT_DIR/<name>' exists, that is what you mean (this is usually + . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD' and 'CHERRY_PICK_HEAD'); - . otherwise, 'refs/<name>' if it exists; + . otherwise, 'refs/<refname>' if it exists; . otherwise, 'refs/tags/<refname>' if it exists; - . otherwise, 'refs/heads/<name>' if it exists; + . otherwise, 'refs/heads/<refname>' if it exists; - . otherwise, 'refs/remotes/<name>' if it exists; + . otherwise, 'refs/remotes/<refname>' if it exists; - . otherwise, 'refs/remotes/<name>/HEAD' if it exists. + . otherwise, 'refs/remotes/<refname>/HEAD' if it exists. + 'HEAD' names the commit on which you based the changes in the working tree. 'FETCH_HEAD' records the branch which you fetched from a remote repository @@ -55,6 +55,8 @@ when you run `git cherry-pick`. + Note that any of the 'refs/*' cases above may come either from the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. +While the ref name encoding is unspecified, UTF-8 is prefered as +some output processing may assume ref names in UTF-8. '<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: A ref followed by the suffix '@' with a date specification @@ -213,18 +215,56 @@ of 'r1' and 'r2' and is defined as It is the set of commits that are reachable from either one of 'r1' or 'r2' but not from both. +In these two shorthands, you can omit one end and let it default to HEAD. +For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What +did I do since I forked from the origin branch?" Similarly, '..origin' +is a shorthand for 'HEAD..origin' and asks "What did the origin do since +I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an +empty range that is both reachable and unreachable from HEAD. + Two other shorthands for naming a set that is formed by a commit and its parent commits exist. The 'r1{caret}@' notation means all parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes all of its parents. +To summarize: + +'<rev>':: + Include commits that are reachable from (i.e. ancestors of) + <rev>. + +'{caret}<rev>':: + Exclude commits that are reachable from (i.e. ancestors of) + <rev>. + +'<rev1>..<rev2>':: + Include commits that are reachable from <rev2> but exclude + those that are reachable from <rev1>. + +'<rev1>\...<rev2>':: + Include commits that are reachable from either <rev1> or + <rev2> but exclude those that are reachable from both. + +'<rev>{caret}@', e.g. 'HEAD{caret}@':: + A suffix '{caret}' followed by an at sign is the same as listing + all parents of '<rev>' (meaning, include anything reachable from + its parents, but not the commit itself). + +'<rev>{caret}!', e.g. 'HEAD{caret}!':: + A suffix '{caret}' followed by an exclamation mark is the same + as giving commit '<rev>' and then all its parents prefixed with + '{caret}' to exclude them (and their ancestors). + Here are a handful of examples: D G H D D F G H I J D F ^G D H D ^D B E I J F B + B..C C B...C G H D E B C ^D B C E I J F B C + C I J F C C^@ I J F + C^! C F^! D G H D F diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt index 43dbe09f73..542946b1ba 100644 --- a/Documentation/technical/api-allocation-growing.txt +++ b/Documentation/technical/api-allocation-growing.txt @@ -5,7 +5,9 @@ Dynamically growing an array using realloc() is error prone and boring. Define your array with: -* a pointer (`ary`) that points at the array, initialized to `NULL`; +* a pointer (`item`) that points at the array, initialized to `NULL` + (although please name the variable based on its contents, not on its + type); * an integer variable (`alloc`) that keeps track of how big the current allocation is, initialized to `0`; @@ -13,22 +15,22 @@ Define your array with: * another integer variable (`nr`) to keep track of how many elements the array currently has, initialized to `0`. -Then before adding `n`th element to the array, call `ALLOC_GROW(ary, n, +Then before adding `n`th element to the item, call `ALLOC_GROW(item, n, alloc)`. This ensures that the array can hold at least `n` elements by calling `realloc(3)` and adjusting `alloc` variable. ------------ -sometype *ary; +sometype *item; size_t nr; size_t alloc for (i = 0; i < nr; i++) - if (we like ary[i] already) + if (we like item[i] already) return; /* we did not like any existing one, so add one */ -ALLOC_GROW(ary, nr + 1, alloc); -ary[nr++] = value you like; +ALLOC_GROW(item, nr + 1, alloc); +item[nr++] = value you like; ------------ You are responsible for updating the `nr` variable. diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 1b7d8f140c..a959517b23 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -46,6 +46,18 @@ Functions Format a string and push it onto the end of the array. This is a convenience wrapper combining `strbuf_addf` and `argv_array_push`. +`argv_array_pop`:: + Remove the final element from the array. If there are no + elements in the array, do nothing. + `argv_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. + +`argv_array_detach`:: + Detach the argv array from the `struct argv_array`, transfering + ownership of the allocated array and strings. + +`argv_array_free_detached`:: + Free the memory allocated by a `struct argv_array` that was later + detached and is now no longer needed. diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 21ca6a2553..5977b58e57 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider world can take many forms, in this document the word "credential" always refers to a username and password pair). +This document describes two interfaces: the C API that the credential +subsystem provides to the rest of git, and the protocol that git uses to +communicate with system-specific "credential helpers". If you are +writing git code that wants to look up or prompt for credentials, see +the section "C API" below. If you want to write your own helper, see +the section on "Credential Helpers" below. + +Typical setup +------------- + +------------ ++-----------------------+ +| git code (C) |--- to server requiring ---> +| | authentication +|.......................| +| C credential API |--- prompt ---> User ++-----------------------+ + ^ | + | pipe | + | v ++-----------------------+ +| git credential helper | ++-----------------------+ +------------ + +The git code (typically a remote-helper) will call the C API to obtain +credential data like a login/password pair (credential_fill). The +API will itself call a remote helper (e.g. "git credential-cache" or +"git credential-store") that may retrieve credential data from a +store. If the credential helper cannot find the information, the C API +will prompt the user. Then, the caller of the API takes care of +contacting the server, and does the actual authentication. + +C API +----- + +The credential C API is meant to be called by git code which needs to +acquire or store a credential. It is centered around an object +representing a single credential and provides three basic operations: +fill (acquire credentials by calling helpers and/or prompting the user), +approve (mark a credential as successfully used so that it can be stored +for later use), and reject (mark a credential as unsuccessful so that it +can be erased from any persistent storage). + Data Structures ---------------- +~~~~~~~~~~~~~~~ `struct credential`:: @@ -21,14 +65,17 @@ Data Structures 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. +helpers below. This list is filled-in by the API functions +according to the corresponding configuration variables before +consulting helpers, so there usually is no need for a caller to +modify the helpers field at all. + This struct should always be initialized with `CREDENTIAL_INIT` or `credential_init`. Functions ---------- +~~~~~~~~~ `credential_init`:: @@ -72,7 +119,7 @@ Functions 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: @@ -135,8 +182,10 @@ 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: +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:git-config[1]). +The string is transformed by git into a command to be executed using +these rules: 1. If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command. @@ -192,42 +241,9 @@ appended to its command line, which is one of: 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. +stream. The exact format is the same as the input/output format of the +`git credential` plumbing command (see the section `INPUT/OUTPUT +FORMAT` in linkgit:git-credential[7] for a detailed specification). 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 @@ -243,3 +259,10 @@ request. If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older helpers will just ignore the new requests). + +See also +-------- + +linkgit:gitcredentials[7] + +linkgit:git-config[5] (See configuration variables `credential.*`) diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt index add6f435b5..944fc39fac 100644 --- a/Documentation/technical/api-directory-listing.txt +++ b/Documentation/technical/api-directory-listing.txt @@ -9,37 +9,40 @@ Data structure -------------- `struct dir_struct` structure is used to pass directory traversal -options to the library and to record the paths discovered. The notable -options are: +options to the library and to record the paths discovered. A single +`struct dir_struct` is used regardless of whether or not the traversal +recursively descends into subdirectories. + +The notable options are: `exclude_per_dir`:: The name of the file to be read in each directory for excluded files (typically `.gitignore`). -`collect_ignored`:: +`flags`:: - Include paths that are to be excluded in the result. + A bit-field of options: -`show_ignored`:: +`DIR_SHOW_IGNORED`::: The traversal is for finding just ignored files, not unignored files. -`show_other_directories`:: +`DIR_SHOW_OTHER_DIRECTORIES`::: Include a directory that is not tracked. -`hide_empty_directories`:: +`DIR_HIDE_EMPTY_DIRECTORIES`::: Do not include a directory that is not tracked and is empty. -`no_gitlinks`:: +`DIR_NO_GITLINKS`::: If set, recurse into a directory that looks like a git directory. Otherwise it is shown as a directory. -The result of the enumeration is left in these fields:: +The result of the enumeration is left in these fields: `entries[]`:: diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt index d6fc90ac7e..18142b6d29 100644 --- a/Documentation/technical/api-history-graph.txt +++ b/Documentation/technical/api-history-graph.txt @@ -33,11 +33,11 @@ The following utility functions are wrappers around `graph_next_line()` and They can all be called with a NULL graph argument, in which case no graph output will be printed. -* `graph_show_commit()` calls `graph_next_line()` until it returns non-zero. - This prints all graph lines up to, and including, the line containing this - commit. Output is printed to stdout. The last line printed does not contain - a terminating newline. This should not be called if the commit line has - already been printed, or it will loop forever. +* `graph_show_commit()` calls `graph_next_line()` and + `graph_is_commit_finished()` until one of them return non-zero. This prints + all graph lines up to, and including, the line containing this commit. + Output is printed to stdout. The last line printed does not contain a + terminating newline. * `graph_show_oneline()` calls `graph_next_line()` and prints the result to stdout. The line printed does not contain a terminating newline. diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt index af7cc2e395..730cfacf78 100644 --- a/Documentation/technical/api-index-skel.txt +++ b/Documentation/technical/api-index-skel.txt @@ -11,5 +11,3 @@ documents them. //////////////////////////////////////////////////////////////// // table of contents end //////////////////////////////////////////////////////////////// - -2007-11-24 diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 2527b7e8d7..3062389404 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -21,7 +21,7 @@ that allow to change the behavior of a command. * There are basically two forms of options: 'Short options' consist of one dash (`-`) and one alphanumeric character. - 'Long options' begin with two dashes (`\--`) and some + 'Long options' begin with two dashes (`--`) and some alphanumeric characters. * Options are case-sensitive. @@ -31,7 +31,7 @@ The parse-options API allows: * 'sticked' and 'separate form' of options with arguments. `-oArg` is sticked, `-o Arg` is separate form. - `\--option=Arg` is sticked, `\--option Arg` is separate form. + `--option=Arg` is sticked, `--option Arg` is separate form. * Long options may be 'abbreviated', as long as the abbreviation is unambiguous. @@ -39,12 +39,12 @@ The parse-options API allows: * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`. * Boolean long options can be 'negated' (or 'unset') by prepending - `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`. Conversely, + `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely, options that begin with `no-` can be 'negated' by removing it. -* Options and non-option arguments can clearly be separated using the `\--` - option, e.g. `-a -b \--option \-- \--this-is-a-file` indicates that - `\--this-is-a-file` must not be processed as an option. +* Options and non-option arguments can clearly be separated using the `--` + option, e.g. `-a -b --option -- --this-is-a-file` indicates that + `--this-is-a-file` must not be processed as an option. Steps to parse options ---------------------- @@ -76,7 +76,7 @@ before the full parser, which in turn shows the full help message. Flags are the bitwise-or of: `PARSE_OPT_KEEP_DASHDASH`:: - Keep the `\--` that usually separates options from + Keep the `--` that usually separates options from non-option arguments. `PARSE_OPT_STOP_AT_NON_OPTION`:: @@ -114,22 +114,22 @@ say `static struct option builtin_add_options[]`. There are some macros to easily define options: `OPT__ABBREV(&int_var)`:: - Add `\--abbrev[=<n>]`. + Add `--abbrev[=<n>]`. `OPT__COLOR(&int_var, description)`:: - Add `\--color[=<when>]` and `--no-color`. + Add `--color[=<when>]` and `--no-color`. `OPT__DRY_RUN(&int_var, description)`:: - Add `-n, \--dry-run`. + Add `-n, --dry-run`. `OPT__FORCE(&int_var, description)`:: - Add `-f, \--force`. + Add `-f, --force`. `OPT__QUIET(&int_var, description)`:: - Add `-q, \--quiet`. + Add `-q, --quiet`. `OPT__VERBOSE(&int_var, description)`:: - Add `-v, \--verbose`. + Add `-v, --verbose`. `OPT_GROUP(description)`:: Start an option group. `description` is a short string that @@ -216,10 +216,10 @@ The last element of the array must be `OPT_END()`. If not stated otherwise, interpret the arguments as follows: * `short` is a character for the short option - (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit), + (e.g. `'e'` for `-e`, use `0` to omit), * `long` is a string for the long option - (e.g. `"example"` for `\--example`, use `NULL` to omit), + (e.g. `"example"` for `--example`, use `NULL` to omit), * `int_var` is an integer variable, @@ -243,10 +243,10 @@ The function must be defined in this form: The callback mechanism is as follows: * Inside `func`, the only interesting member of the structure - given by `opt` is the void pointer `opt\->value`. - `\*opt\->value` will be the value that is saved into `var`, if you + given by `opt` is the void pointer `opt->value`. + `*opt->value` will be the value that is saved into `var`, if you use `OPT_CALLBACK()`. - For example, do `*(unsigned long *)opt\->value = 42;` to get 42 + For example, do `*(unsigned long *)opt->value = 42;` to get 42 into an `unsigned long` variable. * Return value `0` indicates success and non-zero return diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index f18b4f4817..5d7d7f2d32 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -55,10 +55,8 @@ The functions above do the following: non-zero. . If the program terminated due to a signal, then the return value is the - signal number - 128, ie. it is negative and so indicates an unusual - condition; a diagnostic is printed. This return value can be passed to - exit(2), which will report the same code to the parent process that a - POSIX shell's $? would report for a program that died from the signal. + signal number + 128, ie. the same value that a POSIX shell's $? would + report. A diagnostic is printed. `start_async`:: diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-sha1-array.txt index 4a4bae8109..45d1c517cd 100644 --- a/Documentation/technical/api-sha1-array.txt +++ b/Documentation/technical/api-sha1-array.txt @@ -25,9 +25,6 @@ Functions the array (but note that some operations below may lose this ordering). -`sha1_array_sort`:: - Sort the elements in the array. - `sha1_array_lookup`:: Perform a binary search of the array for a specific sha1. If found, returns the offset (in number of elements) of the diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index 95a8bf3846..84686b5c69 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -279,6 +279,22 @@ same behaviour as well. Strip whitespace from a buffer. The second parameter controls if comments are considered contents to be removed or not. +`strbuf_split_buf`:: +`strbuf_split_str`:: +`strbuf_split_max`:: +`strbuf_split`:: + + Split a string or strbuf into a list of strbufs at a specified + terminator character. The returned substrings include the + terminator characters. Some of these functions take a `max` + parameter, which, if positive, limits the output to that + number of substrings. + +`strbuf_list_free`:: + + Free a list of strbufs (for example, the return values of the + `strbuf_split()` functions). + `launch_editor`:: Launch the user preferred editor to edit a file and fill the buffer diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 5a0c14fceb..20be348834 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -1,8 +1,9 @@ string-list API =============== -The string_list API offers a data structure and functions to handle sorted -and unsorted string lists. +The string_list API offers a data structure and functions to handle +sorted and unsorted string lists. A "sorted" list is one whose +entries are sorted by string value in `strcmp()` order. The 'string_list' struct used to be called 'path_list', but was renamed because it is not specific to paths. @@ -20,8 +21,9 @@ If you need something advanced, you can manually malloc() the `items` member (you need this if you add things later) and you should set the `nr` and `alloc` members in that case, too. -. Adds new items to the list, using `string_list_append` or - `string_list_insert`. +. Adds new items to the list, using `string_list_append`, + `string_list_append_nodup`, `string_list_insert`, + `string_list_split`, and/or `string_list_split_in_place`. . Can check if a string is in the list using `string_list_has_string` or `unsorted_string_list_has_string` and get it from the list using @@ -29,18 +31,24 @@ member (you need this if you add things later) and you should set the . Can sort an unsorted list using `sort_string_list`. +. Can remove duplicate items from a sorted list using + `string_list_remove_duplicates`. + . Can remove individual items of an unsorted list using `unsorted_string_list_delete_item`. +. Can remove items not matching a criterion from a sorted or unsorted + list using `filter_string_list`, or remove empty strings using + `string_list_remove_empty_items`. + . Finally it should free the list using `string_list_clear`. Example: ---- -struct string_list list; +struct string_list list = STRING_LIST_INIT_NODUP; int i; -memset(&list, 0, sizeof(struct string_list)); string_list_append(&list, "foo"); string_list_append(&list, "bar"); for (i = 0; i < list.nr; i++) @@ -60,6 +68,20 @@ Functions * General ones (works with sorted and unsorted lists as well) +`filter_string_list`:: + + Apply a function to each item in a list, retaining only the + items for which the function returns true. If free_util is + true, call free() on the util members of any items that have + to be deleted. Preserve the order of the items that are + retained. + +`string_list_remove_empty_items`:: + + Remove any empty strings from the list. If free_util is true, + call free() on the util members of any items that have to be + deleted. Preserve the order of the items that are retained. + `print_string_list`:: Dump a string_list to stdout, useful mainly for debugging purposes. It @@ -96,15 +118,32 @@ write `string_list_insert(...)->util = ...;`. Look up a given string in the string_list, returning the containing string_list_item. If the string is not found, NULL is returned. +`string_list_remove_duplicates`:: + + Remove all but the first of consecutive entries that have the + same string value. If free_util is true, call free() on the + util members of any items that have to be deleted. + * Functions for unsorted lists only `string_list_append`:: - Append a new string to the end of the string_list. + Append a new string to the end of the string_list. If + `strdup_string` is set, then the string argument is copied; + otherwise the new `string_list_entry` refers to the input + string. + +`string_list_append_nodup`:: + + Append a new string to the end of the string_list. The new + `string_list_entry` always refers to the input string, even if + `strdup_string` is set. This function can be used to hand + ownership of a malloc()ed string to a `string_list` that has + `strdup_string` set. `sort_string_list`:: - Make an unsorted list sorted. + Sort the list's entries by string value in `strcmp()` order. `unsorted_string_list_has_string`:: @@ -124,6 +163,25 @@ counterpart for sorted lists, which performs a binary search. is set. The third parameter controls if the `util` pointer of the items should be freed or not. +`string_list_split`:: +`string_list_split_in_place`:: + + Split a string into substrings on a delimiter character and + append the substrings to a `string_list`. If `maxsplit` is + non-negative, then split at most `maxsplit` times. Return the + number of substrings appended to the list. ++ +`string_list_split` requires a `string_list` that has `strdup_strings` +set to true; it leaves the input string untouched and makes copies of +the substrings in newly-allocated memory. +`string_list_split_in_place` requires a `string_list` that has +`strdup_strings` set to false; it splits the input string in place, +overwriting the delimiter characters with NULs and creating new +string_list_items that point into the original string (the original +string must therefore not be modified or freed while the `string_list` +is in use). + + Data structures --------------- diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 8930b3fabc..7324154838 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -1,7 +1,7 @@ GIT index format ================ -= The git index file has the following format +== The git index file has the following format All binary numbers are in network byte order. Version 2 is described here unless stated otherwise. @@ -113,9 +113,22 @@ GIT index format are encoded in 7-bit ASCII and the encoding cannot contain a NUL byte (iow, this is a UNIX pathname). + (Version 4) In version 4, the entry path name is prefix-compressed + relative to the path name for the previous entry (the very first + entry is encoded as if the path name for the previous entry is an + empty string). At the beginning of an entry, an integer N in the + variable width encoding (the same encoding as the offset is encoded + for OFS_DELTA pack entries; see pack-format.txt) is stored, followed + by a NUL-terminated string S. Removing N bytes from the end of the + path name for the previous entry, and replacing it with the string S + yields the path name for this entry. + 1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes while keeping the name NUL-terminated. + (Version 4) In version 4, the padding after the pathname does not + exist. + == Extensions === Cached tree @@ -148,8 +161,9 @@ GIT index format this span of index as a tree. An entry can be in an invalidated state and is represented by having - -1 in the entry_count field. In this case, there is no object name - and the next entry starts immediately after the newline. + a negative number in the entry_count field. In this case, there is no + object name and the next entry starts immediately after the newline. + When writing an invalid entry, -1 should always be used as entry_count. 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-format.txt b/Documentation/technical/pack-format.txt index 1803e64e46..a7871fb865 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -1,7 +1,7 @@ GIT pack format =============== -= pack-*.pack files have the following format: +== pack-*.pack files have the following format: - A header appears at the beginning and consists of the following: @@ -34,7 +34,7 @@ GIT pack format - The trailer records 20-byte SHA1 checksum of all of the above. -= Original (version 1) pack-*.idx files have the following format: +== Original (version 1) pack-*.idx files have the following format: - The header consists of 256 4-byte network byte order integers. N-th entry of this table records the number of @@ -123,8 +123,8 @@ Pack file entry: <+ -= Version 2 pack-*.idx files support packs larger than 4 GiB, and - have some other reorganizations. They have the format: +== Version 2 pack-*.idx files support packs larger than 4 GiB, and + have some other reorganizations. They have the format: - A 4-byte magic number '\377tOc' which is an unreasonable fanout[0] value. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 546980c0a4..f1a51edf47 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -117,7 +117,7 @@ A few things to remember here: - The repository path is always quoted with single quotes. Fetching Data From a Server -=========================== +--------------------------- When one Git repository wants to get data that a second repository has, the first can 'fetch' from the second. This operation determines @@ -134,7 +134,8 @@ with the object name that each reference currently points to. $ echo -e -n "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" | nc -v example.com 9418 - 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag + 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack + side-band side-band-64k ofs-delta shallow no-progress include-tag 00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration 003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master 003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9 @@ -259,8 +260,10 @@ a positive depth, this step is skipped. ---- If the client has requested a positive depth, the server will compute -the set of commits which are no deeper than the desired depth, starting -at the client's wants. The server writes 'shallow' lines for each +the set of commits which are no deeper than the desired depth. The set +of commits start at the client's wants. + +The server writes 'shallow' lines for each commit whose parents will not be sent as a result. The server writes an 'unshallow' line for each commit which the client has indicated is shallow, but is no longer shallow at the currently requested depth @@ -351,7 +354,7 @@ Then the server will start sending its packfile data. A simple clone may look like this (with no 'have' lines): ---- - C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d\0multi_ack \ + C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \ side-band-64k ofs-delta\n C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n @@ -367,7 +370,7 @@ A simple clone may look like this (with no 'have' lines): An incremental update (fetch) response might look like this: ---- - C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d\0multi_ack \ + C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \ side-band-64k ofs-delta\n C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n @@ -419,7 +422,7 @@ entire packfile without multiplexing. Pushing Data To a Server -======================== +------------------------ Pushing data to a server will invoke the 'receive-pack' process on the server, which will allow the client to tell it which references it should diff --git a/Documentation/technical/protocol-common.txt b/Documentation/technical/protocol-common.txt index d30a1b9510..fb7ff084f8 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/technical/protocol-common.txt @@ -36,7 +36,7 @@ More specifically, they: . 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 `*`, + caret `^`, colon `:`, question-mark `?`, asterisk `*`, or open bracket `[` anywhere. . They cannot end with a slash `/` nor a dot `.`. diff --git a/Documentation/technical/send-pack-pipeline.txt b/Documentation/technical/send-pack-pipeline.txt index 681efe4219..9b5a0bc186 100644 --- a/Documentation/technical/send-pack-pipeline.txt +++ b/Documentation/technical/send-pack-pipeline.txt @@ -1,5 +1,5 @@ -git-send-pack -============= +Git-send-pack internals +======================= Overall operation ----------------- diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt index 559263af48..0502a5471e 100644 --- a/Documentation/technical/shallow.txt +++ b/Documentation/technical/shallow.txt @@ -1,6 +1,12 @@ -Def.: Shallow commits do have parents, but not in the shallow +Shallow commits +=============== + +.Definition +********************************************************* +Shallow commits do have parents, but not in the shallow repo, and therefore grafts are introduced pretending that these commits have no parents. +********************************************************* The basic idea is to write the SHA1s of shallow commits into $GIT_DIR/shallow, and handle its contents like the contents diff --git a/Documentation/technical/trivial-merge.txt b/Documentation/technical/trivial-merge.txt index 24c84100b0..c79d4a7c47 100644 --- a/Documentation/technical/trivial-merge.txt +++ b/Documentation/technical/trivial-merge.txt @@ -74,24 +74,24 @@ For multiple ancestors, a '+' means that this case applies even if only one ancestor or remote fits; a '^' means all of the ancestors must be the same. -case ancest head remote result ----------------------------------------- -1 (empty)+ (empty) (empty) (empty) -2ALT (empty)+ *empty* remote remote -2 (empty)^ (empty) remote no merge -3ALT (empty)+ head *empty* head -3 (empty)^ head (empty) no merge -4 (empty)^ head remote no merge -5ALT * head head head -6 ancest+ (empty) (empty) no merge -8 ancest^ (empty) ancest no merge -7 ancest+ (empty) remote no merge -10 ancest^ ancest (empty) no merge -9 ancest+ head (empty) no merge -16 anc1/anc2 anc1 anc2 no merge -13 ancest+ head ancest head -14 ancest+ ancest remote remote -11 ancest+ head remote no merge + case ancest head remote result + ---------------------------------------- + 1 (empty)+ (empty) (empty) (empty) + 2ALT (empty)+ *empty* remote remote + 2 (empty)^ (empty) remote no merge + 3ALT (empty)+ head *empty* head + 3 (empty)^ head (empty) no merge + 4 (empty)^ head remote no merge + 5ALT * head head head + 6 ancest+ (empty) (empty) no merge + 8 ancest^ (empty) ancest no merge + 7 ancest+ (empty) remote no merge + 10 ancest^ ancest (empty) no merge + 9 ancest+ head (empty) no merge + 16 anc1/anc2 anc1 anc2 no merge + 13 ancest+ head ancest head + 14 ancest+ ancest remote remote + 11 ancest+ head remote no merge Only #2ALT and #3ALT use *empty*, because these are the only cases where there can be conflicts that didn't exist before. Note that we diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 289019478d..1d15ee7e52 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -6,8 +6,12 @@ address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. -Git natively supports ssh, git, http, https, ftp, ftps, and rsync -protocols. The following syntaxes may be used with them: +Git supports ssh, git, http, and https protocols (in addition, ftp, +and ftps can be used for fetching and rsync can be used for fetching +and pushing, but these are inefficient and deprecated; do not use +them). + +The following syntaxes may be used with them: - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/ - git://host.xz{startsb}:port{endsb}/path/to/repo.git/ diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf index 339b30919e..d87294de2f 100644 --- a/Documentation/user-manual.conf +++ b/Documentation/user-manual.conf @@ -14,7 +14,7 @@ ifdef::backend-docbook[] # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> | </literallayout> {title#}</example> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 6c7fee7ef7..1b377dc207 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1136,9 +1136,12 @@ Creating good commit messages Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough -description. Tools that turn commits into email, for example, use -the first line on the Subject line and the rest of the commit in the -body. +description. The text up to the first blank line in a commit +message is treated as the commit title, and that title is used +throughout git. For example, linkgit:git-format-patch[1] turns a +commit into email, and it uses the title on the Subject line and the +rest of the commit in the body. + [[ignoring-files]] Ignoring files @@ -1600,7 +1603,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f You will see informational messages on dangling objects. They are objects that still exist in the repository but are no longer referenced by any of your branches, and can (and will) be removed after a while with "gc". -You can run `git fsck --no-dangling` to supress these messages, and still +You can run `git fsck --no-dangling` to suppress these messages, and still view real errors. [[recovering-lost-changes]] @@ -1611,7 +1614,7 @@ Recovering lost changes Reflogs ^^^^^^^ -Say you modify a branch with `linkgit:git-reset[1] --hard`, and then +Say you modify a branch with +linkgit:git-reset[1] \--hard+, and then realize that the branch was the only reference you had to that point in history. @@ -1784,6 +1787,13 @@ $ git format-patch origin will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD. +`git format-patch` can include an initial "cover letter". You can insert +commentary on individual patches after the three dash line which +`format-patch` places after the commit message but before the patch +itself. If you use `git notes` to track your cover letter material, +`git format-patch --notes` will include the commit's notes in a similar +manner. + You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the linkgit:git-send-email[1] script to automate the process. @@ -2870,7 +2880,7 @@ $ git fetch example You can also add a "+" to force the update each time: ------------------------------------------------- -$ git config remote.example.fetch +master:ref/remotes/example/master +$ git config remote.example.fetch +master:refs/remotes/example/master ------------------------------------------------- Don't do this unless you're sure you won't mind "git fetch" possibly @@ -2966,7 +2976,7 @@ As you can see, a commit is defined by: - a tree: The SHA-1 name of a tree object (as defined below), representing the contents of a directory at a certain point in time. -- parent(s): The SHA-1 name of some number of commits which represent the +- parent(s): The SHA-1 name(s) of some number of commits which represent the immediately previous step(s) in the history of the project. The example above has one parent; merge commits may have more than one. A commit with no parents is called a "root" commit, and @@ -3363,8 +3373,8 @@ Date: :100644 100644 oldsha... 4b9458b... M somedirectory/myfile ------------------------------------------------ -This tells you that the immediately preceding version of the file was -"newsha", and that the immediately following version was "oldsha". +This tells you that the immediately following version of the file was +"newsha", and that the immediately preceding version was "oldsha". You also know the commit messages that went with the change from oldsha to 4b9458b and with the change from 4b9458b to newsha. @@ -4035,8 +4045,8 @@ $ git ls-files --unmerged Each line of the `git ls-files --unmerged` output begins with the blob mode bits, blob SHA-1, 'stage number', and the filename. The 'stage number' is git's way to say which tree it -came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD` -tree, and stage3 `$target` tree. +came from: stage 1 corresponds to the `$orig` tree, stage 2 to +the `HEAD` tree, and stage 3 to the `$target` tree. Earlier we said that trivial merges are done inside `git read-tree -m`. For example, if the file did not change @@ -4207,7 +4217,7 @@ commits one by one with the function `get_revision()`. If you are interested in more details of the revision walking process, just have a look at the first implementation of `cmd_log()`; call -`git show v1.3.0{tilde}155^2{tilde}4` and scroll down to that function (note that you +`git show v1.3.0~155^2~4` and scroll down to that function (note that you no longer need to call `setup_pager()` directly). Nowadays, `git log` is a builtin, which means that it is _contained_ in the @@ -4270,9 +4280,9 @@ Two things are interesting here: negative numbers in case of different errors--and 0 on success. - the variable `sha1` in the function signature of `get_sha1()` is `unsigned - char {asterisk}`, but is actually expected to be a pointer to `unsigned + char *`, but is actually expected to be a pointer to `unsigned char[20]`. This variable will contain the 160-bit SHA-1 of the given - commit. Note that whenever a SHA-1 is passed as `unsigned char {asterisk}`, it + commit. Note that whenever a SHA-1 is passed as `unsigned char *`, it is the binary representation, as opposed to the ASCII representation in hex characters, which is passed as `char *`. |