diff options
Diffstat (limited to 'Documentation')
157 files changed, 6127 insertions, 915 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index c6e536f180..0ddd36879a 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -171,6 +171,11 @@ For C programs: - We try to keep to at most 80 characters per line. + - As a Git developer we assume you have a reasonably modern compiler + and we recommend you to enable the DEVELOPER makefile knob to + ensure your patch is clear of all compiler warnings we care about, + by e.g. "echo DEVELOPER=1 >>config.mak". + - 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. diff --git a/Documentation/Makefile b/Documentation/Makefile index 3e39e2815b..35c1385ef7 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -146,7 +146,7 @@ else ASCIIDOC_EXTRA += -a git-asciidoc-no-roff endif endif -ifdef MAN_BOLD_LITERAL +ifndef NO_MAN_BOLD_LITERAL XMLTO_EXTRA += -m manpage-bold-literal.xsl endif ifdef DOCBOOK_SUPPRESS_SP @@ -204,6 +204,7 @@ ifndef V QUIET_DBLATEX = @echo ' ' DBLATEX $@; QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; QUIET_GEN = @echo ' ' GEN $@; + QUIET_LINT = @echo ' ' LINT $@; QUIET_STDERR = 2> /dev/null QUIET_SUBDIR0 = +@subdir= QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ @@ -427,4 +428,7 @@ quick-install-html: require-htmlrepo print-man1: @for i in $(MAN1_TXT); do echo $$i; done +lint-docs:: + $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl + .PHONY: FORCE diff --git a/Documentation/RelNotes/1.7.7.txt b/Documentation/RelNotes/1.7.7.txt index 7655cccfaa..6eff128c80 100644 --- a/Documentation/RelNotes/1.7.7.txt +++ b/Documentation/RelNotes/1.7.7.txt @@ -84,7 +84,7 @@ Updates since v1.7.6 logic used by "git diff" to determine the hunk header. * Invoking the low-level "git http-fetch" without "-a" option (which - git itself never did---normal users should not have to worry about + git itself never did--normal users should not have to worry about this) is now deprecated. * The "--decorate" option to "git log" and its family learned to diff --git a/Documentation/RelNotes/1.8.3.1.txt b/Documentation/RelNotes/1.8.3.1.txt index fc3ea185a5..986637b755 100644 --- a/Documentation/RelNotes/1.8.3.1.txt +++ b/Documentation/RelNotes/1.8.3.1.txt @@ -1,5 +1,5 @@ Git v1.8.3.1 Release Notes -======================== +========================== Fixes since v1.8.3 ------------------ diff --git a/Documentation/RelNotes/1.8.4.1.txt b/Documentation/RelNotes/1.8.4.1.txt index 3aa25a2743..96090ef599 100644 --- a/Documentation/RelNotes/1.8.4.1.txt +++ b/Documentation/RelNotes/1.8.4.1.txt @@ -1,5 +1,5 @@ Git v1.8.4.1 Release Notes -======================== +========================== Fixes since v1.8.4 ------------------ diff --git a/Documentation/RelNotes/1.8.4.2.txt b/Documentation/RelNotes/1.8.4.2.txt index 9adccb1efb..bf6fb1a023 100644 --- a/Documentation/RelNotes/1.8.4.2.txt +++ b/Documentation/RelNotes/1.8.4.2.txt @@ -1,5 +1,5 @@ Git v1.8.4.2 Release Notes -======================== +========================== Fixes since v1.8.4.1 -------------------- diff --git a/Documentation/RelNotes/1.8.4.3.txt b/Documentation/RelNotes/1.8.4.3.txt index 03f3d17751..267a1b34b4 100644 --- a/Documentation/RelNotes/1.8.4.3.txt +++ b/Documentation/RelNotes/1.8.4.3.txt @@ -1,5 +1,5 @@ Git v1.8.4.3 Release Notes -======================== +========================== Fixes since v1.8.4.2 -------------------- diff --git a/Documentation/RelNotes/1.8.4.4.txt b/Documentation/RelNotes/1.8.4.4.txt index 7bc4c5dcc0..a7c1ce15c0 100644 --- a/Documentation/RelNotes/1.8.4.4.txt +++ b/Documentation/RelNotes/1.8.4.4.txt @@ -1,5 +1,5 @@ Git v1.8.4.4 Release Notes -======================== +========================== Fixes since v1.8.4.3 -------------------- diff --git a/Documentation/RelNotes/1.9.0.txt b/Documentation/RelNotes/1.9.0.txt index 752d79127a..4e4b88aa5c 100644 --- a/Documentation/RelNotes/1.9.0.txt +++ b/Documentation/RelNotes/1.9.0.txt @@ -177,7 +177,7 @@ Performance, Internal Implementation, etc. * The naming convention of the packfiles has been updated; it used to be based on the enumeration of names of the objects that are contained in the pack, but now it also depends on how the packed - result is represented---packing the same set of objects using + result is represented--packing the same set of objects using different settings (or delta order) would produce a pack with different name. diff --git a/Documentation/RelNotes/2.5.0.txt b/Documentation/RelNotes/2.5.0.txt new file mode 100644 index 0000000000..87044504c5 --- /dev/null +++ b/Documentation/RelNotes/2.5.0.txt @@ -0,0 +1,563 @@ +Git 2.5 Release Notes +===================== + +Updates since v2.4 +------------------ + +UI, Workflows & Features + + * The bash completion script (in contrib/) learned a few options that + "git revert" takes. + + * Whitespace breakages in deleted and context lines can also be + painted in the output of "git diff" and friends with the new + --ws-error-highlight option. + + * List of commands shown by "git help" are grouped along the workflow + elements to help early learners. + + * "git p4" now detects the filetype (e.g. binary) correctly even when + the files are opened exclusively. + + * git p4 attempts to better handle branches in Perforce. + + * "git p4" learned "--changes-block-size <n>" to read the changes in + chunks from Perforce, instead of making one call to "p4 changes" + that may trigger "too many rows scanned" error from Perforce. + + * More workaround for Perforce's row number limit in "git p4". + + * Unlike "$EDITOR" and "$GIT_EDITOR" that can hold the path to the + command and initial options (e.g. "/path/to/emacs -nw"), 'git p4' + did not let the shell interpolate the contents of the environment + variable that name the editor "$P4EDITOR" (and "$EDITOR", too). + This release makes it in line with the rest of Git, as well as with + Perforce. + + * A new short-hand <branch>@{push} denotes the remote-tracking branch + that tracks the branch at the remote the <branch> would be pushed + to. + + * "git show-branch --topics HEAD" (with no other arguments) did not + do anything interesting. Instead, contrast the given revision + against all the local branches by default. + + * A replacement for contrib/workdir/git-new-workdir that does not + rely on symbolic links and make sharing of objects and refs safer + by making the borrowee and borrowers aware of each other. + + Consider this as still an experimental feature; its UI is still + likely to change. + + * Tweak the sample "store" backend of the credential helper to honor + XDG configuration file locations when specified. + + * A heuristic we use to catch mistyped paths on the command line + "git <cmd> <revs> <pathspec>" is to make sure that all the non-rev + parameters in the later part of the command line are names of the + files in the working tree, but that means "git grep $str -- \*.c" + must always be disambiguated with "--", because nobody sane will + create a file whose name literally is asterisk-dot-see. Loosen the + heuristic to declare that with a wildcard string the user likely + meant to give us a pathspec. + + * "git merge FETCH_HEAD" learned that the previous "git fetch" could + be to create an Octopus merge, i.e. recording multiple branches + that are not marked as "not-for-merge"; this allows us to lose an + old style invocation "git merge <msg> HEAD $commits..." in the + implementation of "git pull" script; the old style syntax can now + be deprecated (but not removed yet). + + * Filter scripts were run with SIGPIPE disabled on the Git side, + expecting that they may not read what Git feeds them to filter. + We however treated a filter that does not read its input fully + before exiting as an error. We no longer do and ignore EPIPE + when writing to feed the filter scripts. + + This changes semantics, but arguably in a good way. If a filter + can produce its output without fully consuming its input using + whatever magic, we now let it do so, instead of diagnosing it + as a programming error. + + * Instead of dying immediately upon failing to obtain a lock, the + locking (of refs etc) retries after a short while with backoff. + + * Introduce http.<url>.SSLCipherList configuration variable to tweak + the list of cipher suite to be used with libcURL when talking with + https:// sites. + + * "git subtree" script (in contrib/) used "echo -n" to produce + progress messages in a non-portable way. + + * "git subtree" script (in contrib/) does not have --squash option + when pushing, but the documentation and help text pretended as if + it did. + + * The Git subcommand completion (in contrib/) no longer lists credential + helpers among candidates; they are not something the end user would + invoke interactively. + + * The index file can be taught with "update-index --untracked-cache" + to optionally remember already seen untracked files, in order to + speed up "git status" in a working tree with tons of cruft. + + * "git mergetool" learned to drive WinMerge as a backend. + + * "git upload-pack" that serves "git fetch" can be told to serve + commits that are not at the tip of any ref, as long as they are + reachable from a ref, with uploadpack.allowReachableSHA1InWant + configuration variable. + + * "git cat-file --batch(-check)" learned the "--follow-symlinks" + option that follows an in-tree symbolic link when asked about an + object via extended SHA-1 syntax, e.g. HEAD:RelNotes that points at + Documentation/RelNotes/2.5.0.txt. With the new option, the command + behaves as if HEAD:Documentation/RelNotes/2.5.0.txt was given as + input instead. + + Consider this as still an experimental and incomplete feature: + + - We may want to do the same for in-index objects, e.g. + asking for :RelNotes with this option should give + :Documentation/RelNotes/2.5.0.txt, too + + - "git cat-file --follow-symlinks blob HEAD:RelNotes" + may also be something we want to allow in the future. + + * "git send-email" learned the alias file format used by the sendmail + program (in a simplified form; we obviously do not feed pipes). + + * Traditionally, external low-level 3-way merge drivers are expected + to produce their results based solely on the contents of the three + variants given in temporary files named by %O, %A and %B on their + command line. Additionally allow them to look at the final path + (given by %P). + + * "git blame" learned blame.showEmail configuration variable. + + * "git apply" cannot diagnose a patch corruption when the breakage is + to mark the length of the hunk shorter than it really is on the + hunk header line "@@ -l,k +m,n @@"; one special case it could is + when the hunk becomes no-op (e.g. k == n == 2 for two-line context + patch output), and it learned to do so in this special case. + + * Add the "--allow-unknown-type" option to "cat-file" to allow + inspecting loose objects of an experimental or a broken type. + + * Many long-running operations show progress eye-candy, even when + they are later backgrounded. Hide the eye-candy when the process + is sent to the background instead. + (merge a4fb76c lm/squelch-bg-progress later to maint). + + +Performance, Internal Implementation, Development Support etc. + + * "unsigned char [20]" used throughout the code to represent object + names are being converted into a semi-opaque "struct object_id". + This effort is expected to interfere with other topics in flight, + but hopefully will give us one extra level of abstraction in the + end, when completed. + + * for_each_ref() callback functions were taught to name the objects + not with "unsigned char sha1[20]" but with "struct object_id". + + * Catch a programmer mistake to feed a pointer not an array to + ARRAY_SIZE() macro, by using a couple of GCC extensions. + + * Some error messages in "git config" were emitted without calling + the usual error() facility. + + * When "add--interactive" splits a hunk into two overlapping hunks + and then let the user choose only one, it sometimes feeds an + incorrect patch text to "git apply". Add tests to demonstrate + this. + + I have a slight suspicion that this may be $gmane/87202 coming back + and biting us (I seem to have said "let's run with this and see + what happens" back then). + + * More line-ending tests. + + * An earlier rewrite to use strbuf_getwholeline() instead of fgets(3) + to read packed-refs file revealed that the former is unacceptably + inefficient. It has been optimized by using getdelim(3) when + available. + + * The refs API uses ref_lock struct which had its own "int fd", even + though the same file descriptor was in the lock struct it contains. + Clean-up the code to lose this redundant field. + + * There was a dead code that used to handle "git pull --tags" and + show special-cased error message, which was made irrelevant when + the semantics of the option changed back in Git 1.9 days. + (merge 19d122b pt/pull-tags-error-diag later to maint). + + * Help us to find broken test script that splits the body part of the + test by mistaken use of wrong kind of quotes. + (merge d93d5d5 jc/test-prereq-validate later to maint). + + * Developer support to automatically detect broken &&-chain in the + test scripts is now turned on by default. + (merge 92b269f jk/test-chain-lint later to maint). + + * Error reporting mechanism used in "refs" API has been made more + consistent. + + * "git pull" has more test coverage now. + + * "git pull" has become more aware of the options meant for + underlying "git fetch" and then learned to use parse-options + parser. + + * Clarify in the Makefile a guideline to decide use of USE_NSEC. + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.4 +---------------- + +Unless otherwise noted, all the fixes since v2.4 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * Git 2.4 broke setting verbosity and progress levels on "git clone" + with native transports. + (merge 822f0c4 mh/clone-verbosity-fix later to maint). + + * "git add -e" did not allow the user to abort the operation by + killing the editor. + (merge cb64800 jk/add-e-kill-editor later to maint). + + * Memory usage of "git index-pack" has been trimmed by tens of + per-cent. + (merge f0e7f11 nd/slim-index-pack-memory-usage later to maint). + + * "git rev-list --objects $old --not --all" to see if everything that + is reachable from $old is already connected to the existing refs + was very inefficient. + (merge b6e8a3b jk/still-interesting later to maint). + + * "hash-object --literally" introduced in v2.2 was not prepared to + take a really long object type name. + (merge 1427a7f jc/hash-object later to maint). + + * "git rebase --quiet" was not quite quiet when there is nothing to + do. + (merge 22946a9 jk/rebase-quiet-noop later to maint). + + * The completion for "log --decorate=" parameter value was incorrect. + (merge af16bda sg/complete-decorate-full-not-long later to maint). + + * "filter-branch" corrupted commit log message that ends with an + incomplete line on platforms with some "sed" implementations that + munge such a line. Work it around by avoiding to use "sed". + (merge df06201 jk/filter-branch-use-of-sed-on-incomplete-line later to maint). + + * "git daemon" fails to build from the source under NO_IPV6 + configuration (regression in 2.4). + (merge d358f77 jc/daemon-no-ipv6-for-2.4.1 later to maint). + + * Some time ago, "git blame" (incorrectly) lost the convert_to_git() + call when synthesizing a fake "tip" commit that represents the + state in the working tree, which broke folks who record the history + with LF line ending to make their project portable across platforms + while terminating lines in their working tree files with CRLF for + their platform. + (merge 4bf256d tb/blame-resurrect-convert-to-git later to maint). + + * We avoid setting core.worktree when the repository location is the + ".git" directory directly at the top level of the working tree, but + the code misdetected the case in which the working tree is at the + root level of the filesystem (which arguably is a silly thing to + do, but still valid). + (merge 84ccad8 jk/init-core-worktree-at-root later to maint). + + * "git commit --date=now" or anything that relies on approxidate lost + the daylight-saving-time offset. + (merge f6e6362 jc/epochtime-wo-tz later to maint). + + * Access to objects in repositories that borrow from another one on a + slow NFS server unnecessarily got more expensive due to recent code + becoming more cautious in a naive way not to lose objects to pruning. + (merge ee1c6c3 jk/prune-mtime later to maint). + + * The codepaths that read .gitignore and .gitattributes files have been + taught that these files encoded in UTF-8 may have UTF-8 BOM marker at + the beginning; this makes it in line with what we do for configuration + files already. + (merge 27547e5 cn/bom-in-gitignore later to maint). + + * a few helper scripts in the test suite did not report errors + correctly. + (merge de248e9 ep/fix-test-lib-functions-report later to maint). + + * The default $HOME/.gitconfig file created upon "git config --global" + that edits it had incorrectly spelled user.name and user.email + entries in it. + (merge 7e11052 oh/fix-config-default-user-name-section later to maint). + + * "git cat-file bl $blob" failed to barf even though there is no + object type that is "bl". + (merge b7994af jk/type-from-string-gently later to maint). + + * The usual "git diff" when seeing a file turning into a directory + showed a patchset to remove the file and create all files in the + directory, but "git diff --no-index" simply refused to work. Also, + when asked to compare a file and a directory, imitate POSIX "diff" + and compare the file with the file with the same name in the + directory, instead of refusing to run. + (merge 0615173 jc/diff-no-index-d-f later to maint). + + * "git rebase -i" moved the "current" command from "todo" to "done" a + bit too prematurely, losing a step when a "pick" did not even start. + (merge 8cbc57c ph/rebase-i-redo later to maint). + + * The connection initiation code for "ssh" transport tried to absorb + differences between the stock "ssh" and Putty-supplied "plink" and + its derivatives, but the logic to tell that we are using "plink" + variants were too loose and falsely triggered when "plink" appeared + anywhere in the path (e.g. "/home/me/bin/uplink/ssh"). + (merge baaf233 bc/connect-plink later to maint). + + * We have prepended $GIT_EXEC_PATH and the path "git" is installed in + (typically "/usr/bin") to $PATH when invoking subprograms and hooks + for almost eternity, but the original use case the latter tried to + support was semi-bogus (i.e. install git to /opt/foo/git and run it + without having /opt/foo on $PATH), and more importantly it has + become less and less relevant as Git grew more mainstream (i.e. the + users would _want_ to have it on their $PATH). Stop prepending the + path in which "git" is installed to users' $PATH, as that would + interfere the command search order people depend on (e.g. they may + not like versions of programs that are unrelated to Git in /usr/bin + and want to override them by having different ones in /usr/local/bin + and have the latter directory earlier in their $PATH). + (merge a0b4507 jk/git-no-more-argv0-path-munging later to maint). + + * core.excludesfile (defaulting to $XDG_HOME/git/ignore) is supposed + to be overridden by repository-specific .git/info/exclude file, but + the order was swapped from the beginning. This belatedly fixes it. + (merge 099d2d8 jc/gitignore-precedence later to maint). + + * There was a commented-out (instead of being marked to expect + failure) test that documented a breakage that was fixed since the + test was written; turn it into a proper test. + (merge 66d2e04 sb/t1020-cleanup later to maint). + + * The "log --decorate" enhancement in Git 2.4 that shows the commit + at the tip of the current branch e.g. "HEAD -> master", did not + work with --decorate=full. + (merge 429ad20 mg/log-decorate-HEAD later to maint). + + * The ref API did not handle cases where 'refs/heads/xyzzy/frotz' is + removed at the same time as 'refs/heads/xyzzy' is added (or vice + versa) very well. + (merge c628edf mh/ref-directory-file later to maint). + + * Multi-ref transaction support we merged a few releases ago + unnecessarily kept many file descriptors open, risking to fail with + resource exhaustion. This is for 2.4.x track. + (merge 185ce3a mh/write-refs-sooner-2.4 later to maint). + + * "git bundle verify" did not diagnose extra parameters on the + command line. + (merge 7886cfa ps/bundle-verify-arg later to maint). + + * Various documentation mark-up fixes to make the output more + consistent in general and also make AsciiDoctor (an alternative + formatter) happier. + (merge d0258b9 jk/asciidoc-markup-fix later to maint). + (merge ad3967a jk/stripspace-asciidoctor-fix later to maint). + (merge 975e382 ja/tutorial-asciidoctor-fix later to maint). + + * The code to read pack-bitmap wanted to allocate a few hundred + pointers to a structure, but by mistake allocated and leaked memory + enough to hold that many actual structures. Correct the allocation + size and also have it on stack, as it is small enough. + (merge 599dc76 rs/plug-leak-in-pack-bitmaps later to maint). + + * The pull.ff configuration was supposed to override the merge.ff + configuration, but it didn't. + (merge db9bb28 pt/pull-ff-vs-merge-ff later to maint). + + * "git pull --log" and "git pull --no-log" worked as expected, but + "git pull --log=20" did not. + (merge 5061a44 pt/pull-log-n later to maint). + + * "git rerere forget" in a repository without rerere enabled gave a + cryptic error message; it should be a silent no-op instead. + (merge 0544574 jk/rerere-forget-check-enabled later to maint). + + * "git rebase -i" fired post-rewrite hook when it shouldn't (namely, + when it was told to stop sequencing with 'exec' insn). + (merge 141ff8f mm/rebase-i-post-rewrite-exec later to maint). + + * Clarify that "log --raw" and "log --format=raw" are unrelated + concepts. + (merge 92de921 mm/log-format-raw-doc later to maint). + + * Make "git stash something --help" error out, so that users can + safely say "git stash drop --help". + (merge 5ba2831 jk/stash-options later to maint). + + * The clean/smudge interface did not work well when filtering an + empty contents (failed and then passed the empty input through). + It can be argued that a filter that produces anything but empty for + an empty input is nonsense, but if the user wants to do strange + things, then why not? + (merge f6a1e1e jh/filter-empty-contents later to maint). + + * Communication between the HTTP server and http_backend process can + lead to a dead-lock when relaying a large ref negotiation request. + Diagnose the situation better, and mitigate it by reading such a + request first into core (to a reasonable limit). + (merge 636614f jk/http-backend-deadlock later to maint). + + * "git clean pathspec..." tried to lstat(2) and complain even for + paths outside the given pathspec. + (merge 838d6a9 dt/clean-pathspec-filter-then-lstat later to maint). + + * Recent "git prune" traverses young unreachable objects to safekeep + old objects in the reachability chain from them, which sometimes + caused error messages that are unnecessarily alarming. + (merge ce4e7b2 jk/squelch-missing-link-warning-for-unreachable later to maint). + + * The configuration reader/writer uses mmap(2) interface to access + the files; when we find a directory, it barfed with "Out of memory?". + (merge 9ca0aaf jk/diagnose-config-mmap-failure later to maint). + + * "color.diff.plain" was a misnomer; give it 'color.diff.context' as + a more logical synonym. + (merge 8dbf3eb jk/color-diff-plain-is-context later to maint). + + * The setup code used to die when core.bare and core.worktree are set + inconsistently, even for commands that do not need working tree. + (merge fada767 jk/die-on-bogus-worktree-late later to maint). + + * Recent Mac OS X updates breaks the logic to detect that the machine + is on the AC power in the sample pre-auto-gc script. + (merge c54c7b3 pa/auto-gc-mac-osx later to maint). + + * "git commit --cleanup=scissors" was not careful enough to protect + against getting fooled by a line that looked like scissors. + (merge fbfa097 sg/commit-cleanup-scissors later to maint). + + * "Have we lost a race with competing repack?" check was too + expensive, especially while receiving a huge object transfer + that runs index-pack (e.g. "clone" or "fetch"). + (merge 0eeb077 jk/index-pack-reduce-recheck later to maint). + + * The tcsh completion writes a bash scriptlet but that would have + failed for users with noclobber set. + (merge 0b1f688 af/tcsh-completion-noclobber later to maint). + + * "git for-each-ref" reported "missing object" for 0{40} when it + encounters a broken ref. The lack of object whose name is 0{40} is + not the problem; the ref being broken is. + (merge 501cf47 mh/reporting-broken-refs-from-for-each-ref later to maint). + + * Various fixes around "git am" that applies a patch to a history + that is not there yet. + (merge 6ea3b67 pt/am-abort-fix later to maint). + + * "git fsck" used to ignore missing or invalid objects recorded in reflog. + (merge 19bf6c9 mh/fsck-reflog-entries later to maint). + + * "git format-patch --ignore-if-upstream A..B" did not like to be fed + tags as boundary commits. + (merge 9b7a61d jc/do-not-feed-tags-to-clear-commit-marks later to maint). + + * "git fetch --depth=<depth>" and "git clone --depth=<depth>" issued + a shallow transfer request even to an upload-pack that does not + support the capability. + (merge eb86a50 me/fetch-into-shallow-safety later to maint). + + * "git rebase" did not exit with failure when format-patch it invoked + failed for whatever reason. + (merge 60d708b cb/rebase-am-exit-code later to maint). + + * Fix a small bug in our use of umask() return value. + (merge 3096b2e jk/fix-refresh-utime later to maint). + + * An ancient test framework enhancement to allow color was not + entirely correct; this makes it work even when tput needs to read + from the ~/.terminfo under the user's real HOME directory. + (merge d5c1b7c rh/test-color-avoid-terminfo-in-original-home later to maint). + + * A minor bugfix when pack bitmap is used with "rev-list --count". + (merge c8a70d3 jk/rev-list-no-bitmap-while-pruning later to maint). + + * "git config" failed to update the configuration file when the + underlying filesystem is incapable of renaming a file that is still + open. + (merge 7a64592 kb/config-unmap-before-renaming later to maint). + + * Avoid possible ssize_t to int truncation. + (merge 6c8afe4 mh/strbuf-read-file-returns-ssize-t later to maint). + + * When you say "!<ENTER>" while running say "git log", you'd confuse + yourself in the resulting shell, that may look as if you took + control back to the original shell you spawned "git log" from but + that isn't what is happening. To that new shell, we leaked + GIT_PAGER_IN_USE environment variable that was meant as a local + communication between the original "Git" and subprocesses that was + spawned by it after we launched the pager, which caused many + "interesting" things to happen, e.g. "git diff | cat" still paints + its output in color by default. + + Stop leaking that environment variable to the pager's half of the + fork; we only need it on "Git" side when we spawn the pager. + (merge 124b519 jc/unexport-git-pager-in-use-in-pager later to maint). + + * Abandoning an already applied change in "git rebase -i" with + "--continue" left CHERRY_PICK_HEAD and confused later steps. + (merge 0e0aff4 js/rebase-i-clean-up-upon-continue-to-skip later to maint). + + * We used to ask libCURL to use the most secure authentication method + available when talking to an HTTP proxy only when we were told to + talk to one via configuration variables. We now ask libCURL to + always use the most secure authentication method, because the user + can tell libCURL to use an HTTP proxy via an environment variable + without using configuration variables. + (merge 5841520 et/http-proxyauth later to maint). + + * A fix to a minor regression to "git fsck" in v2.2 era that started + complaining about a body-less tag object when it lacks a separator + empty line after its header to separate it with a non-existent body. + (merge 84d18c0 jc/fsck-retire-require-eoh later to maint). + + * Code cleanups and documentation updates. + (merge 0269f96 mm/usage-log-l-can-take-regex later to maint). + (merge 64f2589 nd/t1509-chroot-test later to maint). + (merge d201a1e sb/test-bitmap-free-at-end later to maint). + (merge 05bfc7d sb/line-log-plug-pairdiff-leak later to maint). + (merge 846e5df pt/xdg-config-path later to maint). + (merge 1154aa4 jc/plug-fmt-merge-msg-leak later to maint). + (merge 319b678 jk/sha1-file-reduce-useless-warnings later to maint). + (merge 9a35c14 fg/document-commit-message-stripping later to maint). + (merge bbf431c ps/doc-packfile-vs-pack-file later to maint). + (merge 309a9e3 jk/skip-http-tests-under-no-curl later to maint). + (merge ccd593c dl/branch-error-message later to maint). + (merge 22570b6 rs/janitorial later to maint). + (merge 5c2a581 mc/commit-doc-grammofix later to maint). + (merge ce41720 ah/usage-strings later to maint). + (merge e6a268c sb/glossary-submodule later to maint). + (merge ec48a76 sb/submodule-doc-intro later to maint). + (merge 14f8b9b jk/clone-dissociate later to maint). + (merge 055c7e9 sb/pack-protocol-mention-smart-http later to maint). + (merge 7c37a5d jk/make-fix-dependencies later to maint). + (merge fc0aa39 sg/merge-summary-config later to maint). + (merge 329af6c pt/t0302-needs-sanity later to maint). + (merge d614f07 fk/doc-format-patch-vn later to maint). + (merge 72dbb36 sg/completion-commit-cleanup later to maint). + (merge e654eb2 es/utf8-stupid-compiler-workaround later to maint). + (merge 34b935c es/osx-header-pollutes-mask-macro later to maint). + (merge ab7fade jc/prompt-document-ps1-state-separator later to maint). + (merge 25f600e mm/describe-doc later to maint). + (merge 83fe167 mm/branch-doc-updates later to maint). + (merge 75d2e5a ls/hint-rev-list-count later to maint). + (merge edc8f71 cb/subtree-tests-update later to maint). + (merge 5330e6e sb/p5310-and-chain later to maint). + (merge c4ac525 tb/checkout-doc later to maint). + (merge e479c5f jk/pretty-encoding-doc later to maint). + (merge 7e837c6 ss/clone-guess-dir-name-simplify later to maint). diff --git a/Documentation/RelNotes/2.5.1.txt b/Documentation/RelNotes/2.5.1.txt new file mode 100644 index 0000000000..b70553308a --- /dev/null +++ b/Documentation/RelNotes/2.5.1.txt @@ -0,0 +1,65 @@ +Git v2.5.1 Release Notes +======================== + +Fixes since v2.5 +---------------- + + * Running an aliased command from a subdirectory when the .git thing + in the working tree is a gitfile pointing elsewhere did not work. + + * Often a fast-import stream builds a new commit on top of the + previous commit it built, and it often unconditionally emits a + "from" command to specify the first parent, which can be omitted in + such a case. This caused fast-import to forget the tree of the + previous commit and then re-read it from scratch, which was + inefficient. Optimize for this common case. + + * The "rev-parse --parseopt" mode parsed the option specification + and the argument hint in a strange way to allow '=' and other + special characters in the option name while forbidding them from + the argument hint. This made it impossible to define an option + like "--pair <key>=<value>" with "pair=key=value" specification, + which instead would have defined a "--pair=key <value>" option. + + * A "rebase" replays changes of the local branch on top of something + else, as such they are placed in stage #3 and referred to as + "theirs", while the changes in the new base, typically a foreign + work, are placed in stage #2 and referred to as "ours". Clarify + the "checkout --ours/--theirs". + + * An experimental "untracked cache" feature used uname(2) in a + slightly unportable way. + + * "sparse checkout" misbehaved for a path that is excluded from the + checkout when switching between branches that differ at the path. + + * The low-level "git send-pack" did not honor 'user.signingkey' + configuration variable when sending a signed-push. + + * An attempt to delete a ref by pushing into a repository whose HEAD + symbolic reference points at an unborn branch that cannot be + created due to ref D/F conflict (e.g. refs/heads/a/b exists, HEAD + points at refs/heads/a) failed. + + * "git subtree" (in contrib/) depended on "git log" output to be + stable, which was a no-no. Apply a workaround to force a + particular date format. + + * "git clone $URL" in recent releases of Git contains a regression in + the code that invents a new repository name incorrectly based on + the $URL. This has been corrected. + (merge db2e220 jk/guess-repo-name-regression-fix later to maint). + + * Running tests with the "-x" option to make them verbose had some + unpleasant interactions with other features of the test suite. + (merge 9b5fe78 jk/test-with-x later to maint). + + * "git pull" in recent releases of Git has a regression in the code + that allows custom path to the --upload-pack=<program>. This has + been corrected. + + * pipe() emulation used in Git for Windows looked at a wrong variable + when checking for an error from an _open_osfhandle() call. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.5.2.txt b/Documentation/RelNotes/2.5.2.txt new file mode 100644 index 0000000000..3f749398bb --- /dev/null +++ b/Documentation/RelNotes/2.5.2.txt @@ -0,0 +1,63 @@ +Git v2.5.2 Release Notes +======================== + +Fixes since v2.5.1 +------------------ + + * "git init empty && git -C empty log" said "bad default revision 'HEAD'", + which was found to be a bit confusing to new users. + + * The "interpret-trailers" helper mistook a multi-paragraph title of + a commit log message with a colon in it as the end of the trailer + block. + + * When re-priming the cache-tree opportunistically while committing + the in-core index as-is, we mistakenly invalidated the in-core + index too aggressively, causing the experimental split-index code + to unnecessarily rewrite the on-disk index file(s). + + * "git archive" did not use zip64 extension when creating an archive + with more than 64k entries, which nobody should need, right ;-)? + + * The code in "multiple-worktree" support that attempted to recover + from an inconsistent state updated an incorrect file. + + * "git rev-list" does not take "--notes" option, but did not complain + when one is given. + + * Because the configuration system does not allow "alias.0foo" and + "pager.0foo" as the configuration key, the user cannot use '0foo' + as a custom command name anyway, but "git 0foo" tried to look these + keys up and emitted useless warnings before saying '0foo is not a + git command'. These warning messages have been squelched. + + * We recently rewrote one of the build scripts in Perl, which made it + necessary to have Perl to build Git. Reduced Perl dependency by + rewriting it again using sed. + + * t1509 test that requires a dedicated VM environment had some + bitrot, which has been corrected. + + * strbuf_read() used to have one extra iteration (and an unnecessary + strbuf_grow() of 8kB), which was eliminated. + + * The codepath to produce error messages had a hard-coded limit to + the size of the message, primarily to avoid memory allocation while + calling die(). + + * When trying to see that an object does not exist, a state errno + leaked from our "first try to open a packfile with O_NOATIME and + then if it fails retry without it" logic on a system that refuses + O_NOATIME. This confused us and caused us to die, saying that the + packfile is unreadable, when we should have just reported that the + object does not exist in that packfile to the caller. + + * An off-by-one error made "git remote" to mishandle a remote with a + single letter nickname. + + * A handful of codepaths that used to use fixed-sized arrays to hold + pathnames have been corrected to use strbuf and other mechanisms to + allow longer pathnames without fearing overflows. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.5.3.txt b/Documentation/RelNotes/2.5.3.txt new file mode 100644 index 0000000000..d1436857cb --- /dev/null +++ b/Documentation/RelNotes/2.5.3.txt @@ -0,0 +1,17 @@ +Git v2.5.3 Release Notes +======================== + +Fixes since v2.5.2 +------------------ + + * The experimental untracked-cache feature were buggy when paths with + a few levels of subdirectories are involved. + + * Recent versions of scripted "git am" has a performance regression + in "git am --skip" codepath, which no longer exists in the + built-in version on the 'master' front. Fix the regression in + the last scripted version that appear in 2.5.x maintenance track + and older. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.5.4.txt b/Documentation/RelNotes/2.5.4.txt new file mode 100644 index 0000000000..a5e8477a4a --- /dev/null +++ b/Documentation/RelNotes/2.5.4.txt @@ -0,0 +1,18 @@ +Git v2.5.4 Release Notes +======================== + +Fixes since v2.5.4 +------------------ + + * xdiff code we use to generate diffs is not prepared to handle + extremely large files. It uses "int" in many places, which can + overflow if we have a very large number of lines or even bytes in + our input files, for example. Cap the input size to soemwhere + around 1GB for now. + + * Some protocols (like git-remote-ext) can execute arbitrary code + found in the URL. The URLs that submodules use may come from + arbitrary sources (e.g., .gitmodules files in a remote + repository), and can hurt those who blindly enable recursive + fetch. Restrict the allowed protocols to well known and safe + ones. diff --git a/Documentation/RelNotes/2.5.5.txt b/Documentation/RelNotes/2.5.5.txt new file mode 100644 index 0000000000..37eae9a2d9 --- /dev/null +++ b/Documentation/RelNotes/2.5.5.txt @@ -0,0 +1,11 @@ +Git v2.5.5 Release Notes +======================== + +Fixes since v2.5.4 +------------------ + + * Bugfix patches were backported from the 'master' front to plug heap + corruption holes, to catch integer overflow in the computation of + pathname lengths, and to get rid of the name_path API. Both of + these would have resulted in writing over an under-allocated buffer + when formulating pathnames while tree traversal. diff --git a/Documentation/RelNotes/2.6.0.txt b/Documentation/RelNotes/2.6.0.txt new file mode 100644 index 0000000000..7288aaf716 --- /dev/null +++ b/Documentation/RelNotes/2.6.0.txt @@ -0,0 +1,370 @@ +Git 2.6 Release Notes +===================== + +Updates since v2.5 +------------------ + +UI, Workflows & Features + + * An asterisk as a substring (as opposed to the entirety) of a path + component for both side of a refspec, e.g. + "refs/heads/o*:refs/remotes/heads/i*", is now allowed. + + * New userdiff pattern definition for fountain screenwriting markup + format has been added. + + * "git log" and friends learned a new "--date=format:..." option to + format timestamps using system's strftime(3). + + * "git fast-import" learned to respond to the get-mark command via + its cat-blob-fd interface. + + * "git rebase -i" learned "drop commit-object-name subject" command + as another way to skip replaying of a commit. + + * A new configuration variable can enable "--follow" automatically + when "git log" is run with one pathspec argument. + + * "git status" learned to show a more detailed information regarding + the "rebase -i" session in progress. + + * "git cat-file" learned "--batch-all-objects" option to enumerate all + available objects in the repository more quickly than "rev-list + --all --objects" (the output includes unreachable objects, though). + + * "git fsck" learned to ignore errors on a set of known-to-be-bad + objects, and also allows the warning levels of various kinds of + non-critical breakages to be tweaked. + + * "git rebase -i"'s list of todo is made configurable. + + * "git send-email" now performs alias-expansion on names that are + given via --cccmd, etc. + + * An environment variable GIT_REPLACE_REF_BASE tells Git to look into + refs hierarchy other than refs/replace/ for the object replacement + data. + + * Allow untracked cache (experimental) to be used when sparse + checkout (experimental) is also in use. + + * "git pull --rebase" has been taught to pay attention to + rebase.autostash configuration. + + * The command-line completion script (in contrib/) has been updated. + + * A negative !ref entry in multi-value transfer.hideRefs + configuration can be used to say "don't hide this one". + + * After "git am" without "-3" stops, running "git am -3" pays attention + to "-3" only for the patch that caused the original invocation + to stop. + + * When linked worktree is used, simultaneous "notes merge" instances + for the same ref in refs/notes/* are prevented from stomping on + each other. + + * "git send-email" learned a new option --smtp-auth to limit the SMTP + AUTH mechanisms to be used to a subset of what the system library + supports. + + * A new configuration variable http.sslVersion can be used to specify + what specific version of SSL/TLS to use to make a connection. + + * "git notes merge" can be told with "--strategy=<how>" option how to + automatically handle conflicts; this can now be configured by + setting notes.mergeStrategy configuration variable. + + * "git log --cc" did not show any patch, even though most of the time + the user meant "git log --cc -p -m" to see patch output for commits + with a single parent, and combined diff for merge commits. The + command is taught to DWIM "--cc" (without "--raw" and other forms + of output specification) to "--cc -p -m". + + * "git config --list" output was hard to parse when values consist of + multiple lines. "--name-only" option is added to help this. + + * A handful of usability & cosmetic fixes to gitk and l10n updates. + + * A completely empty e-mail address <> is now allowed in the authors + file used by git-svn, to match the way it accepts the output from + authors-prog. + + +Performance, Internal Implementation, Development Support etc. + + * In preparation for allowing different "backends" to store the refs + in a way different from the traditional "one ref per file in + $GIT_DIR or in a $GIT_DIR/packed-refs file" filesystem storage, + direct filesystem access to ref-like things like CHERRY_PICK_HEAD + from scripts and programs has been reduced. + + * Computation of untracked status indicator by bash prompt + script (in contrib/) has been optimized. + + * Memory use reduction when commit-slab facility is used to annotate + sparsely (which is not recommended in the first place). + + * Clean up refs API and make "git clone" less intimate with the + implementation detail. + + * "git pull" was reimplemented in C. + + * The packet tracing machinery allows to capture an incoming pack + data to a file for debugging. + + * Move machinery to parse human-readable scaled numbers like 1k, 4M, + and 2G as an option parameter's value from pack-objects to + parse-options API, to make it available to other codepaths. + + * "git verify-tag" and "git verify-commit" have been taught to share + more code, and then learned to optionally show the verification + message from the underlying GPG implementation. + + * Various enhancements around "git am" reading patches generated by + foreign SCM have been made. + + * Ref listing by "git branch -l" and "git tag -l" commands has + started to be rebuilt, based on the for-each-ref machinery. + + * The code to perform multi-tree merges has been taught to repopulate + the cache-tree upon a successful merge into the index, so that + subsequent "diff-index --cached" (hence "status") and "write-tree" + (hence "commit") will go faster. + + The same logic in "git checkout" may now be removed, but that is a + separate issue. + + * Tests that assume how reflogs are represented on the filesystem too + much have been corrected. + + * "git am" has been rewritten in "C". + + * git_path() and mkpath() are handy helper functions but it is easy + to misuse, as the callers need to be careful to keep the number of + active results below 4. Their uses have been reduced. + + * The "lockfile" API has been rebuilt on top of a new "tempfile" API. + + * To prepare for allowing a different "ref" backend to be plugged in + to the system, update_ref()/delete_ref() have been taught about + ref-like things like MERGE_HEAD that are per-worktree (they will + always be written to the filesystem inside $GIT_DIR). + + * The gitmodules API that is accessed from the C code learned to + cache stuff lazily. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.5 +---------------- + +Unless otherwise noted, all the fixes since v2.5 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git subtree" (in contrib/) depended on "git log" output to be + stable, which was a no-no. Apply a workaround to force a + particular date format. + (merge e7aac44 da/subtree-date-confusion later to maint). + + * An attempt to delete a ref by pushing into a repository whose HEAD + symbolic reference points at an unborn branch that cannot be + created due to ref D/F conflict (e.g. refs/heads/a/b exists, HEAD + points at refs/heads/a) failed. + (merge b112b14 jx/do-not-crash-receive-pack-wo-head later to maint). + + * The low-level "git send-pack" did not honor 'user.signingkey' + configuration variable when sending a signed-push. + (merge d830d39 db/send-pack-user-signingkey later to maint). + + * "sparse checkout" misbehaved for a path that is excluded from the + checkout when switching between branches that differ at the path. + (merge 7d78241 as/sparse-checkout-removal later to maint). + + * An experimental "untracked cache" feature used uname(2) in a + slightly unportable way. + (merge 100e433 cb/uname-in-untracked later to maint). + + * A "rebase" replays changes of the local branch on top of something + else, as such they are placed in stage #3 and referred to as + "theirs", while the changes in the new base, typically a foreign + work, are placed in stage #2 and referred to as "ours". Clarify + the "checkout --ours/--theirs". + (merge f303016 se/doc-checkout-ours-theirs later to maint). + + * The "rev-parse --parseopt" mode parsed the option specification + and the argument hint in a strange way to allow '=' and other + special characters in the option name while forbidding them from + the argument hint. This made it impossible to define an option + like "--pair <key>=<value>" with "pair=key=value" specification, + which instead would have defined a "--pair=key <value>" option. + (merge 2d893df ib/scripted-parse-opt-better-hint-string later to maint). + + * Often a fast-import stream builds a new commit on top of the + previous commit it built, and it often unconditionally emits a + "from" command to specify the first parent, which can be omitted in + such a case. This caused fast-import to forget the tree of the + previous commit and then re-read it from scratch, which was + inefficient. Optimize for this common case. + (merge 0df3245 mh/fast-import-optimize-current-from later to maint). + + * Running an aliased command from a subdirectory when the .git thing + in the working tree is a gitfile pointing elsewhere did not work. + (merge d95138e nd/export-worktree later to maint). + + * "Is this subdirectory a separate repository that should not be + touched?" check "git clean" was inefficient. This was replaced + with a more optimized check. + (merge fbf2fec ee/clean-remove-dirs later to maint). + + * The "new-worktree-mode" hack in "checkout" that was added in + nd/multiple-work-trees topic has been removed by updating the + implementation of new "worktree add". + (merge 65f9b75 es/worktree-add-cleanup later to maint). + + * Remove remaining cruft from "git checkout --to", which + transitioned to "git worktree add". + (merge 114ff88 es/worktree-add later to maint). + + * An off-by-one error made "git remote" to mishandle a remote with a + single letter nickname. + (merge bc598c3 mh/get-remote-group-fix later to maint). + + * "git clone $URL", when cloning from a site whose sole purpose is to + host a single repository (hence, no path after <scheme>://<site>/), + tried to use the site name as the new repository name, but did not + remove username or password when <site> part was of the form + <user>@<pass>:<host>. The code is taught to redact these. + (merge adef956 ps/guess-repo-name-at-root later to maint). + + * Running tests with the "-x" option to make them verbose had some + unpleasant interactions with other features of the test suite. + (merge 9b5fe78 jk/test-with-x later to maint). + + * t1509 test that requires a dedicated VM environment had some + bitrot, which has been corrected. + (merge faacc5a ps/t1509-chroot-test-fixup later to maint). + + * "git pull" in recent releases of Git has a regression in the code + that allows custom path to the --upload-pack=<program>. This has + been corrected. + + Note that this is irrelevant for 'master' with "git pull" rewritten + in C. + (merge 13e0e28 mm/pull-upload-pack later to maint). + + * When trying to see that an object does not exist, a state errno + leaked from our "first try to open a packfile with O_NOATIME and + then if it fails retry without it" logic on a system that refuses + O_NOATIME. This confused us and caused us to die, saying that the + packfile is unreadable, when we should have just reported that the + object does not exist in that packfile to the caller. + (merge dff6f28 cb/open-noatime-clear-errno later to maint). + + * The codepath to produce error messages had a hard-coded limit to + the size of the message, primarily to avoid memory allocation while + calling die(). + (merge f4c3edc jk/long-error-messages later to maint). + + * strbuf_read() used to have one extra iteration (and an unnecessary + strbuf_grow() of 8kB), which was eliminated. + (merge 3ebbd00 jh/strbuf-read-use-read-in-full later to maint). + + * We rewrote one of the build scripts in Perl but this reimplements + in Bourne shell. + (merge 57cee8a sg/help-group later to maint). + + * The experimental untracked-cache feature were buggy when paths with + a few levels of subdirectories are involved. + (merge 73f9145 dt/untracked-subdir later to maint). + + * "interpret-trailers" helper mistook a single-liner log message that + has a colon as the end of existing trailer. + + * The "interpret-trailers" helper mistook a multi-paragraph title of + a commit log message with a colon in it as the end of the trailer + block. + (merge 5c99995 cc/trailers-corner-case-fix later to maint). + + * "git describe" without argument defaulted to describe the HEAD + commit, but "git describe --contains" didn't. Arguably, in a + repository used for active development, such defaulting would not + be very useful as the tip of branch is typically not tagged, but it + is better to be consistent. + (merge 2bd0706 sg/describe-contains later to maint). + + * The client side codepaths in "git push" have been cleaned up + and the user can request to perform an optional "signed push", + i.e. sign only when the other end accepts signed push. + (merge 68c757f db/push-sign-if-asked later to maint). + + * Because the configuration system does not allow "alias.0foo" and + "pager.0foo" as the configuration key, the user cannot use '0foo' + as a custom command name anyway, but "git 0foo" tried to look these + keys up and emitted useless warnings before saying '0foo is not a + git command'. These warning messages have been squelched. + (merge 9e9de18 jk/fix-alias-pager-config-key-warnings later to maint). + + * "git rev-list" does not take "--notes" option, but did not complain + when one is given. + (merge 2aea7a5 jk/rev-list-has-no-notes later to maint). + + * When re-priming the cache-tree opportunistically while committing + the in-core index as-is, we mistakenly invalidated the in-core + index too aggressively, causing the experimental split-index code + to unnecessarily rewrite the on-disk index file(s). + (merge 475a344 dt/commit-preserve-base-index-upon-opportunistic-cache-tree-update later to maint). + + * "git archive" did not use zip64 extension when creating an archive + with more than 64k entries, which nobody should need, right ;-)? + (merge 88329ca rs/archive-zip-many later to maint). + + * The code in "multiple-worktree" support that attempted to recover + from an inconsistent state updated an incorrect file. + (merge 82fde87 nd/fixup-linked-gitdir later to maint). + + * On case insensitive systems, "git p4" did not work well with client + specs. + + * "git init empty && git -C empty log" said "bad default revision 'HEAD'", + which was found to be a bit confusing to new users. + (merge ce11360 jk/log-missing-default-HEAD later to maint). + + * Recent versions of scripted "git am" has a performance regression in + "git am --skip" codepath, which no longer exists in the built-in + version on the 'master' front. Fix the regression in the last + scripted version that appear in 2.5.x maintenance track and older. + (merge b9d6689 js/maint-am-skip-performance-regression later to maint). + + * The branch descriptions that are set with "git branch --edit-description" + option were used in many places but they weren't clearly documented. + (merge 561d2b7 po/doc-branch-desc later to maint). + + * Code cleanups and documentation updates. + (merge 1c601af es/doc-clean-outdated-tools later to maint). + (merge 3581304 kn/tag-doc-fix later to maint). + (merge 3a59e59 kb/i18n-doc later to maint). + (merge 45abdee sb/remove-unused-var-from-builtin-add later to maint). + (merge 14691e3 sb/parse-options-codeformat later to maint). + (merge 4a6ada3 ad/bisect-cleanup later to maint). + (merge da4c5ad ta/docfix-index-format-tech later to maint). + (merge ae25fd3 sb/check-return-from-read-ref later to maint). + (merge b3325df nd/dwim-wildcards-as-pathspecs later to maint). + (merge 7aa9b9b sg/wt-status-header-inclusion later to maint). + (merge f04c690 as/docfix-reflog-expire-unreachable later to maint). + (merge 1269847 sg/t3020-typofix later to maint). + (merge 8b54c23 jc/calloc-pathspec later to maint). + (merge a6926b8 po/po-readme later to maint). + (merge 54d160e ss/fix-config-fd-leak later to maint). + (merge b80fa84 ah/submodule-typofix-in-error later to maint). + (merge 99885bc ah/reflog-typofix-in-error later to maint). + (merge 9476c2c ah/read-tree-usage-string later to maint). + (merge b8c1d27 ah/pack-objects-usage-strings later to maint). + (merge 486e1e1 br/svn-doc-include-paths-config later to maint). + (merge 1733ed3 ee/clean-test-fixes later to maint). + (merge 5fcadc3 gb/apply-comment-typofix later to maint). + (merge b894d3e mp/t7060-diff-index-test later to maint). + (merge d238710 as/config-doc-markup-fix later to maint). diff --git a/Documentation/RelNotes/2.6.1.txt b/Documentation/RelNotes/2.6.1.txt new file mode 100644 index 0000000000..1e51363e3c --- /dev/null +++ b/Documentation/RelNotes/2.6.1.txt @@ -0,0 +1,18 @@ +Git v2.6.1 Release Notes +======================== + +Fixes since v2.6 +---------------- + + * xdiff code we use to generate diffs is not prepared to handle + extremely large files. It uses "int" in many places, which can + overflow if we have a very large number of lines or even bytes in + our input files, for example. Cap the input size to soemwhere + around 1GB for now. + + * Some protocols (like git-remote-ext) can execute arbitrary code + found in the URL. The URLs that submodules use may come from + arbitrary sources (e.g., .gitmodules files in a remote + repository), and can hurt those who blindly enable recursive + fetch. Restrict the allowed protocols to well known and safe + ones. diff --git a/Documentation/RelNotes/2.6.2.txt b/Documentation/RelNotes/2.6.2.txt new file mode 100644 index 0000000000..5b65e35245 --- /dev/null +++ b/Documentation/RelNotes/2.6.2.txt @@ -0,0 +1,65 @@ +Git v2.6.2 Release Notes +======================== + +Fixes since v2.6.1 +------------------ + + * There were some classes of errors that "git fsck" diagnosed to its + standard error that did not cause it to exit with non-zero status. + + * A test script for the HTTP service had a timing dependent bug, + which was fixed. + + * Performance-measurement tests did not work without an installed Git. + + * On a case insensitive filesystems, setting GIT_WORK_TREE variable + using a random cases that does not agree with what the filesystem + thinks confused Git that it wasn't inside the working tree. + + * When "git am" was rewritten as a built-in, it stopped paying + attention to user.signingkey, which was fixed. + + * After "git checkout --detach", "git status" reported a fairly + useless "HEAD detached at HEAD", instead of saying at which exact + commit. + + * "git rebase -i" had a minor regression recently, which stopped + considering a line that begins with an indented '#' in its insn + sheet not a comment, which is now fixed. + + * Description of the "log.follow" configuration variable in "git log" + documentation is now also copied to "git config" documentation. + + * Allocation related functions and stdio are unsafe things to call + inside a signal handler, and indeed killing the pager can cause + glibc to deadlock waiting on allocation mutex as our signal handler + tries to free() some data structures in wait_for_pager(). Reduce + these unsafe calls. + + * The way how --ref/--notes to specify the notes tree reference are + DWIMmed was not clearly documented. + + * Customization to change the behaviour with "make -w" and "make -s" + in our Makefile was broken when they were used together. + + * The Makefile always runs the library archiver with hardcoded "crs" + options, which was inconvenient for exotic platforms on which + people want to use programs with totally different set of command + line options. + + * The ssh transport, just like any other transport over the network, + did not clear GIT_* environment variables, but it is possible to + use SendEnv and AcceptEnv to leak them to the remote invocation of + Git, which is not a good idea at all. Explicitly clear them just + like we do for the local transport. + + * "git blame --first-parent v1.0..v2.0" was not rejected but did not + limit the blame to commits on the first parent chain. + + * Very small number of options take a parameter that is optional + (which is not a great UI element as they can only appear at the end + of the command line). Add notice to documentation of each and + every one of them. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.6.3.txt b/Documentation/RelNotes/2.6.3.txt new file mode 100644 index 0000000000..fc6fe1711f --- /dev/null +++ b/Documentation/RelNotes/2.6.3.txt @@ -0,0 +1,111 @@ +Git v2.6.3 Release Notes +======================== + +Fixes since v2.6.2 +------------------ + + * The error message from "git blame --contents --reverse" incorrectly + talked about "--contents --children". + + * "git merge-file" tried to signal how many conflicts it found, which + obviously would not work well when there are too many of them. + + * The name-hash subsystem that is used to cope with case insensitive + filesystems keeps track of directories and their on-filesystem + cases for all the paths in the index by holding a pointer to a + randomly chosen cache entry that is inside the directory (for its + ce->ce_name component). This pointer was not updated even when the + cache entry was removed from the index, leading to use after free. + This was fixed by recording the path for each directory instead of + borrowing cache entries and restructuring the API somewhat. + + * When the "git am" command was reimplemented in C, "git am -3" had a + small regression where it is aborted in its error handling codepath + when underlying merge-recursive failed in some ways. + + * The synopsis text and the usage string of subcommands that read + list of things from the standard input are often shown as if they + only take input from a file on a filesystem, which was misleading. + + * A couple of commands still showed "[options]" in their usage string + to note where options should come on their command line, but we + spell that "[<options>]" in most places these days. + + * The submodule code has been taught to work better with separate + work trees created via "git worktree add". + + * When "git gc --auto" is backgrounded, its diagnosis message is + lost. It now is saved to a file in $GIT_DIR and is shown next time + the "gc --auto" is run. + + * Work around "git p4" failing when the P4 depot records the contents + in UTF-16 without UTF-16 BOM. + + * Recent update to "rebase -i" that tries to sanity check the edited + insn sheet before it uses it has become too picky on Windows where + CRLF left by the editor is turned into a trailing CR on the line + read via the "read" built-in command. + + * "git clone --dissociate" runs a big "git repack" process at the + end, and it helps to close file descriptors that are open on the + packs and their idx files before doing so on filesystems that + cannot remove a file that is still open. + + * Correct "git p4 --detect-labels" so that it does not fail to create + a tag that points at a commit that is also being imported. + + * The internal stripspace() function has been moved to where it + logically belongs to, i.e. strbuf API, and the command line parser + of "git stripspace" has been updated to use the parse_options API. + + * Prepare for Git on-disk repository representation to undergo + backward incompatible changes by introducing a new repository + format version "1", with an extension mechanism. + + * "git gc" used to barf when a symbolic ref has gone dangling + (e.g. the branch that used to be your upstream's default when you + cloned from it is now gone, and you did "fetch --prune"). + + * The normalize_ceiling_entry() function does not muck with the end + of the path it accepts, and the real world callers do rely on that, + but a test insisted that the function drops a trailing slash. + + * "git gc" is safe to run anytime only because it has the built-in + grace period to protect young objects. In order to run with no + grace period, the user must make sure that the repository is + quiescent. + + * A recent "filter-branch --msg-filter" broke skipping of the commit + object header, which is fixed. + + * "git --literal-pathspecs add -u/-A" without any command line + argument misbehaved ever since Git 2.0. + + * Merging a branch that removes a path and another that changes the + mode bits on the same path should have conflicted at the path, but + it didn't and silently favoured the removal. + + * "git imap-send" did not compile well with older version of cURL library. + + * The linkage order of libraries was wrong in places around libcurl. + + * It was not possible to use a repository-lookalike created by "git + worktree add" as a local source of "git clone". + + * When "git send-email" wanted to talk over Net::SMTP::SSL, + Net::Cmd::datasend() did not like to be fed too many bytes at the + same time and failed to send messages. Send the payload one line + at a time to work around the problem. + + * We peek objects from submodule's object store by linking it to the + list of alternate object databases, but the code to do so forgot to + correctly initialize the list. + + * "git status --branch --short" accessed beyond the constant string + "HEAD", which has been corrected. + + * "git daemon" uses "run_command()" without "finish_command()", so it + needs to release resources itself, which it forgot to do. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.6.4.txt b/Documentation/RelNotes/2.6.4.txt new file mode 100644 index 0000000000..b0256a2dc9 --- /dev/null +++ b/Documentation/RelNotes/2.6.4.txt @@ -0,0 +1,63 @@ +Git v2.6.4 Release Notes +======================== + +Fixes since v2.6.3 +------------------ + + * The "configure" script did not test for -lpthread correctly, which + upset some linkers. + + * Add support for talking http/https over socks proxy. + + * Portability fix for Windows, which may rewrite $SHELL variable using + non-POSIX paths. + + * We now consistently allow all hooks to ignore their standard input, + rather than having git complain of SIGPIPE. + + * Fix shell quoting in contrib script. + + * Test portability fix for a topic in v2.6.1. + + * Allow tilde-expansion in some http config variables. + + * Give a useful special case "diff/show --word-diff-regex=." as an + example in the documentation. + + * Fix for a corner case in filter-branch. + + * Make git-p4 work on a detached head. + + * Documentation clarification for "check-ignore" without "--verbose". + + * Just like the working tree is cleaned up when the user cancelled + submission in P4Submit.applyCommit(), clean up the mess if "p4 + submit" fails. + + * Having a leftover .idx file without corresponding .pack file in + the repository hurts performance; "git gc" learned to prune them. + + * The code to prepare the working tree side of temporary directory + for the "dir-diff" feature forgot that symbolic links need not be + copied (or symlinked) to the temporary area, as the code already + special cases and overwrites them. Besides, it was wrong to try + computing the object name of the target of symbolic link, which may + not even exist or may be a directory. + + * There was no way to defeat a configured rebase.autostash variable + from the command line, as "git rebase --no-autostash" was missing. + + * Allow "git interpret-trailers" to run outside of a Git repository. + + * Produce correct "dirty" marker for shell prompts, even when we + are on an orphan or an unborn branch. + + * Some corner cases have been fixed in string-matching done in "git + status". + + * Apple's common crypto implementation of SHA1_Update() does not take + more than 4GB at a time, and we now have a compile-time workaround + for it. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.6.5.txt b/Documentation/RelNotes/2.6.5.txt new file mode 100644 index 0000000000..f0924b62e0 --- /dev/null +++ b/Documentation/RelNotes/2.6.5.txt @@ -0,0 +1,58 @@ +Git v2.6.5 Release Notes +======================== + +Fixes since v2.6.4 +------------------ + + * Because "test_when_finished" in our test framework queues the + clean-up tasks to be done in a shell variable, it should not be + used inside a subshell. Add a mechanism to allow 'bash' to catch + such uses, and fix the ones that were found. + + * Update "git subtree" (in contrib/) so that it can take whitespaces + in the pathnames, not only in the in-tree pathname but the name of + the directory that the repository is in. + + * Cosmetic improvement to lock-file error messages. + + * mark_tree_uninteresting() has code to handle the case where it gets + passed a NULL pointer in its 'tree' parameter, but the function had + 'object = &tree->object' assignment before checking if tree is + NULL. This gives a compiler an excuse to declare that tree will + never be NULL and apply a wrong optimization. Avoid it. + + * The helper used to iterate over loose object directories to prune + stale objects did not closedir() immediately when it is done with a + directory--a callback such as the one used for "git prune" may want + to do rmdir(), but it would fail on open directory on platforms + such as WinXP. + + * "git p4" used to import Perforce CLs that touch only paths outside + the client spec as empty commits. It has been corrected to ignore + them instead, with a new configuration git-p4.keepEmptyCommits as a + backward compatibility knob. + + * The exit code of git-fsck did not reflect some types of errors + found in packed objects, which has been corrected. + + * The completion script (in contrib/) used to list "git column" + (which is not an end-user facing command) as one of the choices + + * Improve error reporting when SMTP TLS fails. + + * When getpwuid() on the system returned NULL (e.g. the user is not + in the /etc/passwd file or other uid-to-name mappings), the + codepath to find who the user is to record it in the reflog barfed + and died. Loosen the check in this codepath, which already accepts + questionable ident string (e.g. host part of the e-mail address is + obviously bogus), and in general when we operate fmt_ident() function + in non-strict mode. + + * "git symbolic-ref" forgot to report a failure with its exit status. + + * History traversal with "git log --source" that starts with an + annotated tag failed to report the tag as "source", due to an + old regression in the command line parser back in v2.2 days. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.6.6.txt b/Documentation/RelNotes/2.6.6.txt new file mode 100644 index 0000000000..023ad85ec6 --- /dev/null +++ b/Documentation/RelNotes/2.6.6.txt @@ -0,0 +1,11 @@ +Git v2.6.6 Release Notes +======================== + +Fixes since v2.6.5 +------------------ + + * Bugfix patches were backported from the 'master' front to plug heap + corruption holes, to catch integer overflow in the computation of + pathname lengths, and to get rid of the name_path API. Both of + these would have resulted in writing over an under-allocated buffer + when formulating pathnames while tree traversal. diff --git a/Documentation/RelNotes/2.7.0.txt b/Documentation/RelNotes/2.7.0.txt new file mode 100644 index 0000000000..563dadc57e --- /dev/null +++ b/Documentation/RelNotes/2.7.0.txt @@ -0,0 +1,414 @@ +Git 2.7 Release Notes +===================== + +Updates since v2.6 +------------------ + +UI, Workflows & Features + + * The appearance of "gitk", particularly on high DPI monitors, have + been improved. "gitk" also comes with an undated translation for + Swedish and Japanese. + + * "git remote" learned "get-url" subcommand to show the URL for a + given remote name used for fetching and pushing. + + * There was no way to defeat a configured rebase.autostash variable + from the command line, as "git rebase --no-autostash" was missing. + + * "git log --date=local" used to only show the normal (default) + format in the local timezone. The command learned to take 'local' + as an instruction to use the local timezone with other formats, + + * The refs used during a "git bisect" session is now per-worktree so + that independent bisect sessions can be done in different worktrees + created with "git worktree add". + + * Users who are too busy to type three extra keystrokes to ask for + "git stash show -p" can now set stash.showPatch configuration + variable to true to always see the actual patch, not just the list + of paths affected with feel for the extent of damage via diffstat. + + * "quiltimport" allows to specify the series file by honoring the + $QUILT_SERIES environment and also --series command line option. + + * The use of 'good/bad' in "git bisect" made it confusing to use when + hunting for a state change that is not a regression (e.g. bugfix). + The command learned 'old/new' and then allows the end user to + say e.g. "bisect start --term-old=fast --term-new=slow" to find a + performance regression. + + * "git interpret-trailers" can now run outside of a Git repository. + + * "git p4" learned to reencode the pathname it uses to communicate + with the p4 depot with a new option. + + * Give progress meter to "git filter-branch". + + * Allow a later "!/abc/def" to override an earlier "/abc" that + appears in the same .gitignore file to make it easier to express + "everything in /abc directory is ignored, except for ...". + + * Teach "git p4" to send large blobs outside the repository by + talking to Git LFS. + + * Prepare for Git on-disk repository representation to undergo + backward incompatible changes by introducing a new repository + format version "1", with an extension mechanism. + + * "git worktree" learned a "list" subcommand. + + * "git clone --dissociate" learned that it can be used even when + "--reference" was not used at the same time. + + * "git blame" learnt to take "--first-parent" and "--reverse" at the + same time when it makes sense. + + * "git checkout" did not follow the usual "--[no-]progress" + convention and implemented only "--quiet" that is essentially + a superset of "--no-progress". Extend the command to support the + usual "--[no-]progress". + + * The semantics of transfer.hideRefs configuration variable have been + extended to work better with the ref "namespace" feature that lets + you throw unrelated bunches of repositories in a single physical + repository and virtually serve them as separate ones. + + * send-email config variables whose values are pathnames now go + through the ~username/ expansion. + + * bash completion learnt to TAB-complete recipient addresses given + to send-email. + + * The credential-cache daemon can be told to ignore SIGHUP to work + around issue when running Git from inside emacs. + + * "git push" learned new configuration for doing "--recurse-submodules" + on each push. + + * "format-patch" has learned a new option to zero-out the commit + object name on the mbox "From " line. + + +Performance, Internal Implementation, Development Support etc. + + * The infrastructure to rewrite "git submodule" in C is being built + incrementally. Let's polish these early parts well enough and make + them graduate to 'next' and 'master', so that the more involved + follow-up can start cooking on a solid ground. + + * Some features from "git tag -l" and "git branch -l" have been made + available to "git for-each-ref" so that eventually the unified + implementation can be shared across all three. The version merged + to the 'master' branch earlier had a performance regression in "tag + --contains", which has since been corrected. + + * Because "test_when_finished" in our test framework queues the + clean-up tasks to be done in a shell variable, it should not be + used inside a subshell. Add a mechanism to allow 'bash' to catch + such uses, and fix the ones that were found. + + * The debugging infrastructure for pkt-line based communication has + been improved to mark the side-band communication specifically. + + * Update "git branch" that list existing branches, using the + ref-filter API that is shared with "git tag" and "git + for-each-ref". + + * The test for various line-ending conversions has been enhanced. + + * A few test scripts around "git p4" have been improved for + portability. + + * Many allocations that is manually counted (correctly) that are + followed by strcpy/sprintf have been replaced with a less error + prone constructs such as xstrfmt. + + * The internal stripspace() function has been moved to where it + logically belongs to, i.e. strbuf API, and the command line parser + of "git stripspace" has been updated to use the parse_options API. + + * "git am" used to spawn "git mailinfo" via run_command() API once + per each patch, but learned to make a direct call to mailinfo() + instead. + + * The implementation of "git mailinfo" was refactored so that a + mailinfo() function can be directly called from inside a process. + + * With a "debug" helper, debugging of a single "git" invocation in + our test scripts has become a lot easier. + + * The "configure" script did not test for -lpthread correctly, which + upset some linkers. + + * Cross completed task off of subtree project's todo list. + + * Test cleanups for the subtree project. + + * Clean up style in an ancient test t9300. + + * Work around some test flakiness with p4d. + + * Fsck did not correctly detect a NUL-truncated header in a tag. + + * Use a safer behavior when we hit errors verifying remote certificates. + + * Speed up filter-branch for cases where we only care about rewriting + commits, not tree data. + + * The parse-options API has been updated to make "-h" command line + option work more consistently in all commands. + + * "git svn rebase/mkdirs" got optimized by keeping track of empty + directories better. + + * Fix some racy client/server tests by treating SIGPIPE the same as a + normal non-zero exit. + + * The necessary infrastructure to build topics using the free Travis + CI has been added. Developers forking from this topic (and enabling + Travis) can do their own builds, and we can turn on auto-builds for + git/git (including build-status for pull requests that people + open). + + * The write(2) emulation for Windows learned to set errno to EPIPE + when necessary. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.6 +---------------- + +Unless otherwise noted, all the fixes since v2.6 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * Very small number of options take a parameter that is optional + (which is not a great UI element as they can only appear at the end + of the command line). Add notice to documentation of each and + every one of them. + + * "git blame --first-parent v1.0..v2.0" was not rejected but did not + limit the blame to commits on the first parent chain. + + * "git subtree" (in contrib/) now can take whitespaces in the + pathnames, not only in the in-tree pathname but the name of the + directory that the repository is in. + + * The ssh transport, just like any other transport over the network, + did not clear GIT_* environment variables, but it is possible to + use SendEnv and AcceptEnv to leak them to the remote invocation of + Git, which is not a good idea at all. Explicitly clear them just + like we do for the local transport. + + * Correct "git p4 --detect-labels" so that it does not fail to create + a tag that points at a commit that is also being imported. + + * The Makefile always runs the library archiver with hardcoded "crs" + options, which was inconvenient for exotic platforms on which + people want to use programs with totally different set of command + line options. + + * Customization to change the behaviour with "make -w" and "make -s" + in our Makefile was broken when they were used together. + + * Allocation related functions and stdio are unsafe things to call + inside a signal handler, and indeed killing the pager can cause + glibc to deadlock waiting on allocation mutex as our signal handler + tries to free() some data structures in wait_for_pager(). Reduce + these unsafe calls. + + * The way how --ref/--notes to specify the notes tree reference are + DWIMmed was not clearly documented. + + * "git gc" used to barf when a symbolic ref has gone dangling + (e.g. the branch that used to be your upstream's default when you + cloned from it is now gone, and you did "fetch --prune"). + + * "git clone --dissociate" runs a big "git repack" process at the + end, and it helps to close file descriptors that are open on the + packs and their idx files before doing so on filesystems that + cannot remove a file that is still open. + + * Description of the "log.follow" configuration variable in "git log" + documentation is now also copied to "git config" documentation. + + * "git rebase -i" had a minor regression recently, which stopped + considering a line that begins with an indented '#' in its insn + sheet not a comment. Further, the code was still too picky on + Windows where CRLF left by the editor is turned into a trailing CR + on the line read via the "read" built-in command of bash. Both of + these issues are now fixed. + + * After "git checkout --detach", "git status" reported a fairly + useless "HEAD detached at HEAD", instead of saying at which exact + commit. + + * When "git send-email" wanted to talk over Net::SMTP::SSL, + Net::Cmd::datasend() did not like to be fed too many bytes at the + same time and failed to send messages. Send the payload one line + at a time to work around the problem. + + * When "git am" was rewritten as a built-in, it stopped paying + attention to user.signingkey, which was fixed. + + * It was not possible to use a repository-lookalike created by "git + worktree add" as a local source of "git clone". + + * On a case insensitive filesystems, setting GIT_WORK_TREE variable + using a random cases that does not agree with what the filesystem + thinks confused Git that it wasn't inside the working tree. + + * Performance-measurement tests did not work without an installed Git. + + * A test script for the HTTP service had a timing dependent bug, + which was fixed. + + * There were some classes of errors that "git fsck" diagnosed to its + standard error that did not cause it to exit with non-zero status. + + * Work around "git p4" failing when the P4 depot records the contents + in UTF-16 without UTF-16 BOM. + + * When "git gc --auto" is backgrounded, its diagnosis message is + lost. Save it to a file in $GIT_DIR and show it next time the "gc + --auto" is run. + + * The submodule code has been taught to work better with separate + work trees created via "git worktree add". + + * "git gc" is safe to run anytime only because it has the built-in + grace period to protect young objects. In order to run with no + grace period, the user must make sure that the repository is + quiescent. + + * A recent "filter-branch --msg-filter" broke skipping of the commit + object header, which is fixed. + + * The normalize_ceiling_entry() function does not muck with the end + of the path it accepts, and the real world callers do rely on that, + but a test insisted that the function drops a trailing slash. + + * A test for interaction between untracked cache and sparse checkout + added in Git 2.5 days were flaky. + + * A couple of commands still showed "[options]" in their usage string + to note where options should come on their command line, but we + spell that "[<options>]" in most places these days. + + * The synopsis text and the usage string of subcommands that read + list of things from the standard input are often shown as if they + only take input from a file on a filesystem, which was misleading. + + * "git am -3" had a small regression where it is aborted in its error + handling codepath when underlying merge-recursive failed in certain + ways, as it assumed that the internal call to merge-recursive will + never die, which is not the case (yet). + + * The linkage order of libraries was wrong in places around libcurl. + + * The name-hash subsystem that is used to cope with case insensitive + filesystems keeps track of directories and their on-filesystem + cases for all the paths in the index by holding a pointer to a + randomly chosen cache entry that is inside the directory (for its + ce->ce_name component). This pointer was not updated even when the + cache entry was removed from the index, leading to use after free. + This was fixed by recording the path for each directory instead of + borrowing cache entries and restructuring the API somewhat. + + * "git merge-file" tried to signal how many conflicts it found, which + obviously would not work well when there are too many of them. + + * The error message from "git blame --contents --reverse" incorrectly + talked about "--contents --children". + + * "git imap-send" did not compile well with older version of cURL library. + + * Merging a branch that removes a path and another that changes the + mode bits on the same path should have conflicted at the path, but + it didn't and silently favoured the removal. + + * "git --literal-pathspecs add -u/-A" without any command line + argument misbehaved ever since Git 2.0. + + * "git daemon" uses "run_command()" without "finish_command()", so it + needs to release resources itself, which it forgot to do. + + * "git status --branch --short" accessed beyond the constant string + "HEAD", which has been corrected. + + * We peek objects from submodule's object store by linking it to the + list of alternate object databases, but the code to do so forgot to + correctly initialize the list. + + * The code to prepare the working tree side of temporary directory + for the "dir-diff" feature forgot that symbolic links need not be + copied (or symlinked) to the temporary area, as the code already + special cases and overwrites them. Besides, it was wrong to try + computing the object name of the target of symbolic link, which may + not even exist or may be a directory. + + * A Range: request can be responded with a full response and when + asked properly libcurl knows how to strip the result down to the + requested range. However, we were hand-crafting a range request + and it did not kick in. + + * Having a leftover .idx file without corresponding .pack file in + the repository hurts performance; "git gc" learned to prune them. + + * Apple's common crypto implementation of SHA1_Update() does not take + more than 4GB at a time, and we now have a compile-time workaround + for it. + + * Produce correct "dirty" marker for shell prompts, even when we + are on an orphan or an unborn branch. + + * A build without NO_IPv6 used to use gethostbyname() when guessing + user's hostname, instead of getaddrinfo() that is used in other + codepaths in such a build. + + * The exit code of git-fsck did not reflect some types of errors + found in packed objects, which has been corrected. + + * The helper used to iterate over loose object directories to prune + stale objects did not closedir() immediately when it is done with a + directory--a callback such as the one used for "git prune" may want + to do rmdir(), but it would fail on open directory on platforms + such as WinXP. + + * "git p4" used to import Perforce CLs that touch only paths outside + the client spec as empty commits. It has been corrected to ignore + them instead, with a new configuration git-p4.keepEmptyCommits as a + backward compatibility knob. + + * The completion script (in contrib/) used to list "git column" + (which is not an end-user facing command) as one of the choices + (merge 160fcdb sg/completion-no-column later to maint). + + * The error reporting from "git send-email", when SMTP TLS fails, has + been improved. + (merge 9d60524 jk/send-email-ssl-errors later to maint). + + * When getpwuid() on the system returned NULL (e.g. the user is not + in the /etc/passwd file or other uid-to-name mappings), the + codepath to find who the user is to record it in the reflog barfed + and died. Loosen the check in this codepath, which already accepts + questionable ident string (e.g. host part of the e-mail address is + obviously bogus), and in general when we operate fmt_ident() function + in non-strict mode. + (merge 92bcbb9 jk/ident-loosen-getpwuid later to maint). + + * "git symbolic-ref" forgot to report a failure with its exit status. + (merge f91b273 jk/symbolic-ref-maint later to maint). + + * History traversal with "git log --source" that starts with an + annotated tag failed to report the tag as "source", due to an + old regression in the command line parser back in v2.2 days. + (merge 728350b jk/pending-keep-tag-name later to maint). + + * "git p4" when interacting with multiple depots at the same time + used to incorrectly drop changes. + + * Code clean-up, minor fixes etc. diff --git a/Documentation/RelNotes/2.7.1.txt b/Documentation/RelNotes/2.7.1.txt new file mode 100644 index 0000000000..6553d69e33 --- /dev/null +++ b/Documentation/RelNotes/2.7.1.txt @@ -0,0 +1,87 @@ +Git v2.7.1 Release Notes +======================== + +Fixes since v2.7 +---------------- + + * An earlier change in 2.5.x-era broke users' hooks and aliases by + exporting GIT_WORK_TREE to point at the root of the working tree, + interfering when they tried to use a different working tree without + setting GIT_WORK_TREE environment themselves. + + * The "exclude_list" structure has the usual "alloc, nr" pair of + fields to be used by ALLOC_GROW(), but clear_exclude_list() forgot + to reset 'alloc' to 0 when it cleared 'nr' to discard the managed + array. + + * "git send-email" was confused by escaped quotes stored in the alias + files saved by "mutt", which has been corrected. + + * A few unportable C construct have been spotted by clang compiler + and have been fixed. + + * The documentation has been updated to hint the connection between + the '--signoff' option and DCO. + + * "git reflog" incorrectly assumed that all objects that used to be + at the tip of a ref must be commits, which caused it to segfault. + + * The ignore mechanism saw a few regressions around untracked file + listing and sparse checkout selection areas in 2.7.0; the change + that is responsible for the regression has been reverted. + + * Some codepaths used fopen(3) when opening a fixed path in $GIT_DIR + (e.g. COMMIT_EDITMSG) that is meant to be left after the command is + done. This however did not work well if the repository is set to + be shared with core.sharedRepository and the umask of the previous + user is tighter. They have been made to work better by calling + unlink(2) and retrying after fopen(3) fails with EPERM. + + * Asking gitweb for a nonexistent commit left a warning in the server + log. + + * "git rebase", unlike all other callers of "gc --auto", did not + ignore the exit code from "gc --auto". + + * Many codepaths that run "gc --auto" before exiting kept packfiles + mapped and left the file descriptors to them open, which was not + friendly to systems that cannot remove files that are open. They + now close the packs before doing so. + + * A recent optimization to filter-branch in v2.7.0 introduced a + regression when --prune-empty filter is used, which has been + corrected. + + * The description for SANITY prerequisite the test suite uses has + been clarified both in the comment and in the implementation. + + * "git tag" started listing a tag "foo" as "tags/foo" when a branch + named "foo" exists in the same repository; remove this unnecessary + disambiguation, which is a regression introduced in v2.7.0. + + * The way "git svn" uses auth parameter was broken by Subversion + 1.9.0 and later. + + * The "split" subcommand of "git subtree" (in contrib/) incorrectly + skipped merges when it shouldn't, which was corrected. + + * A few options of "git diff" did not work well when the command was + run from a subdirectory. + + * dirname() emulation has been added, as Msys2 lacks it. + + * The underlying machinery used by "ls-files -o" and other commands + have been taught not to create empty submodule ref cache for a + directory that is not a submodule. This removes a ton of wasted + CPU cycles. + + * Drop a few old "todo" items by deciding that the change one of them + suggests is not such a good idea, and doing the change the other + one suggested to do. + + * Documentation for "git fetch --depth" has been updated for clarity. + + * The command line completion learned a handful of additional options + and command specific syntax. + +Also includes a handful of documentation and test updates. diff --git a/Documentation/RelNotes/2.7.2.txt b/Documentation/RelNotes/2.7.2.txt new file mode 100644 index 0000000000..4feef76704 --- /dev/null +++ b/Documentation/RelNotes/2.7.2.txt @@ -0,0 +1,41 @@ +Git v2.7.2 Release Notes +======================== + +Fixes since v2.7.1 +------------------ + + * The low-level merge machinery has been taught to use CRLF line + termination when inserting conflict markers to merged contents that + are themselves CRLF line-terminated. + + * "git worktree" had a broken code that attempted to auto-fix + possible inconsistency that results from end-users moving a + worktree to different places without telling Git (the original + repository needs to maintain backpointers to its worktrees, but + "mv" run by end-users who are not familiar with that fact will + obviously not adjust them), which actually made things worse + when triggered. + + * "git push --force-with-lease" has been taught to report if the push + needed to force (or fast-forwarded). + + * The emulated "yes" command used in our test scripts has been + tweaked not to spend too much time generating unnecessary output + that is not used, to help those who test on Windows where it would + not stop until it fills the pipe buffer due to lack of SIGPIPE. + + * The vimdiff backend for "git mergetool" has been tweaked to arrange + and number buffers in the order that would match the expectation of + majority of people who read left to right, then top down and assign + buffers 1 2 3 4 "mentally" to local base remote merge windows based + on that order. + + * The documentation for "git clean" has been corrected; it mentioned + that .git/modules/* are removed by giving two "-f", which has never + been the case. + + * Paths that have been told the index about with "add -N" are not + quite yet in the index, but a few commands behaved as if they + already are in a harmful way. + +Also includes tiny documentation and test updates. diff --git a/Documentation/RelNotes/2.7.3.txt b/Documentation/RelNotes/2.7.3.txt new file mode 100644 index 0000000000..6adf038915 --- /dev/null +++ b/Documentation/RelNotes/2.7.3.txt @@ -0,0 +1,62 @@ +Git v2.7.3 Release Notes +======================== + +Fixes since v2.7.2 +------------------ + + * Traditionally, the tests that try commands that work on the + contents in the working tree were named with "worktree" in their + filenames, but with the recent addition of "git worktree" + subcommand, whose tests are also named similarly, it has become + harder to tell them apart. The traditional tests have been renamed + to use "work-tree" instead in an attempt to differentiate them. + + * Many codepaths forget to check return value from git_config_set(); + the function is made to die() to make sure we do not proceed when + setting a configuration variable failed. + + * Handling of errors while writing into our internal asynchronous + process has been made more robust, which reduces flakiness in our + tests. + + * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a + rev, i.e. the object named by the the pathname with wildcard + characters in a tree object. + + * "git rev-parse --git-common-dir" used in the worktree feature + misbehaved when run from a subdirectory. + + * The "v(iew)" subcommand of the interactive "git am -i" command was + broken in 2.6.0 timeframe when the command was rewritten in C. + + * "git merge-tree" used to mishandle "both sides added" conflict with + its own "create a fake ancestor file that has the common parts of + what both sides have added and do a 3-way merge" logic; this has + been updated to use the usual "3-way merge with an empty blob as + the fake common ancestor file" approach used in the rest of the + system. + + * The memory ownership rule of fill_textconv() API, which was a bit + tricky, has been documented a bit better. + + * The documentation did not clearly state that the 'simple' mode is + now the default for "git push" when push.default configuration is + not set. + + * Recent versions of GNU grep are pickier when their input contains + arbitrary binary data, which some of our tests uses. Rewrite the + tests to sidestep the problem. + + * A helper function "git submodule" uses since v2.7.0 to list the + modules that match the pathspec argument given to its subcommands + (e.g. "submodule add <repo> <path>") has been fixed. + + * "git config section.var value" to set a value in per-repository + configuration file failed when it was run outside any repository, + but didn't say the reason correctly. + + * The code to read the pack data using the offsets stored in the pack + idx file has been made more carefully check the validity of the + data in the idx. + +Also includes documentation and test updates. diff --git a/Documentation/RelNotes/2.7.4.txt b/Documentation/RelNotes/2.7.4.txt new file mode 100644 index 0000000000..883ae896fe --- /dev/null +++ b/Documentation/RelNotes/2.7.4.txt @@ -0,0 +1,11 @@ +Git v2.7.4 Release Notes +======================== + +Fixes since v2.7.3 +------------------ + + * Bugfix patches were backported from the 'master' front to plug heap + corruption holes, to catch integer overflow in the computation of + pathname lengths, and to get rid of the name_path API. Both of + these would have resulted in writing over an under-allocated buffer + when formulating pathnames while tree traversal. diff --git a/Documentation/RelNotes/2.8.0.txt b/Documentation/RelNotes/2.8.0.txt new file mode 100644 index 0000000000..25079710fa --- /dev/null +++ b/Documentation/RelNotes/2.8.0.txt @@ -0,0 +1,439 @@ +Git 2.8 Release Notes +===================== + +Backward compatibility note +--------------------------- + +The rsync:// transport has been removed. + + +Updates since v2.7 +------------------ + +UI, Workflows & Features + + * It turns out "git clone" over rsync transport has been broken when + the source repository has packed references for a long time, and + nobody noticed nor complained about it. + + * "push" learned that its "--delete" option can be shortened to + "-d", just like "branch --delete" and "branch -d" are the same + thing. + + * "git blame" learned to produce the progress eye-candy when it takes + too much time before emitting the first line of the result. + + * "git grep" can now be configured (or told from the command line) + how many threads to use when searching in the working tree files. + + * Some "git notes" operations, e.g. "git log --notes=<note>", should + be able to read notes from any tree-ish that is shaped like a notes + tree, but the notes infrastructure required that the argument must + be a ref under refs/notes/. Loosen it to require a valid ref only + when the operation would update the notes (in which case we must + have a place to store the updated notes tree, iow, a ref). + + * "git grep" by default does not fall back to its "--no-index" + behavior outside a directory under Git's control (otherwise the + user may by mistake end up running a huge recursive search); with a + new configuration (set in $HOME/.gitconfig--by definition this + cannot be set in the config file per project), this safety can be + disabled. + + * "git pull --rebase" has been extended to allow invoking + "rebase -i". + + * "git p4" learned to cope with the type of a file getting changed. + + * "git format-patch" learned to notice format.outputDirectory + configuration variable. This allows "-o <dir>" option to be + omitted on the command line if you always use the same directory in + your workflow. + + * "interpret-trailers" has been taught to optionally update a file in + place, instead of always writing the result to the standard output. + + * Many commands that read files that are expected to contain text + that is generated (or can be edited) by the end user to control + their behavior (e.g. "git grep -f <filename>") have been updated + to be more tolerant to lines that are terminated with CRLF (they + used to treat such a line to contain payload that ends with CR, + which is usually not what the users expect). + + * "git notes merge" used to limit the source of the merged notes tree + to somewhere under refs/notes/ hierarchy, which was too limiting + when inventing a workflow to exchange notes with remote + repositories using remote-tracking notes trees (located in e.g. + refs/remote-notes/ or somesuch). + + * "git ls-files" learned a new "--eol" option to help diagnose + end-of-line problems. + + * "ls-remote" learned an option to show which branch the remote + repository advertises as its primary by pointing its HEAD at. + + * New http.proxyAuthMethod configuration variable can be used to + specify what authentication method to use, as a way to work around + proxies that do not give error response expected by libcurl when + CURLAUTH_ANY is used. Also, the codepath for proxy authentication + has been taught to use credential API to store the authentication + material in user's keyrings. + + * Update the untracked cache subsystem and change its primary UI from + "git update-index" to "git config". + + * There were a few "now I am doing this thing" progress messages in + the TCP connection code that can be triggered by setting a verbose + option internally in the code, but "git fetch -v" and friends never + passed the verbose option down to that codepath. + + * Clean/smudge filters defined in a configuration file of lower + precedence can now be overridden to be a pass-through no-op by + setting the variable to an empty string. + + * A new "<branch>^{/!-<pattern>}" notation can be used to name a + commit that is reachable from <branch> that does not match the + given <pattern>. + + * The "user.useConfigOnly" configuration variable can be used to + force the user to always set user.email & user.name configuration + variables, serving as a reminder for those who work on multiple + projects and do not want to put these in their $HOME/.gitconfig. + + * "git fetch" and friends that make network connections can now be + told to only use ipv4 (or ipv6). + + * Some authentication methods do not need username or password, but + libcurl needs some hint that it needs to perform authentication. + Supplying an empty username and password string is a valid way to + do so, but you can set the http.[<url>.]emptyAuth configuration + variable to achieve the same, if you find it cleaner. + + * You can now set http.[<url>.]pinnedpubkey to specify the pinned + public key when building with recent enough versions of libcURL. + + * The configuration system has been taught to phrase where it found a + bad configuration variable in a better way in its error messages. + "git config" learnt a new "--show-origin" option to indicate where + the values come from. + + * The "credential-cache" daemon process used to run in whatever + directory it happened to start in, but this made umount(2)ing the + filesystem that houses the repository harder; now the process + chdir()s to the directory that house its own socket on startup. + + * When "git submodule update" did not result in fetching the commit + object in the submodule that is referenced by the superproject, the + command learned to retry another fetch, specifically asking for + that commit that may not be connected to the refs it usually + fetches. + + * "git merge-recursive" learned "--no-renames" option to disable its + rename detection logic. + + * Across the transition at around Git version 2.0, the user used to + get a pretty loud warning when running "git push" without setting + push.default configuration variable. We no longer warn because the + transition was completed a long time ago. + + * README has been renamed to README.md and its contents got tweaked + slightly to make it easier on the eyes. + + +Performance, Internal Implementation, Development Support etc. + + * Add a framework to spawn a group of processes in parallel, and use + it to run "git fetch --recurse-submodules" in parallel. + + * A slight update to the Makefile to mark ".PHONY" targets as such + correctly. + + * In-core storage of the reverse index for .pack files (which lets + you go from a pack offset to an object name) has been streamlined. + + * d95138e6 (setup: set env $GIT_WORK_TREE when work tree is set, like + $GIT_DIR, 2015-06-26) attempted to work around a glitch in alias + handling by overwriting GIT_WORK_TREE environment variable to + affect subprocesses when set_git_work_tree() gets called, which + resulted in a rather unpleasant regression to "clone" and "init". + Try to address the same issue by always restoring the environment + and respawning the real underlying command when handling alias. + + * The low-level code that is used to create symbolic references has + been updated to share more code with the code that deals with + normal references. + + * strbuf_getline() and friends have been redefined to make it easier + to identify which callsite of (new) strbuf_getline_lf() should + allow and silently ignore carriage-return at the end of the line to + help users on DOSsy systems. + + * "git shortlog" used to accumulate various pieces of information + regardless of what was asked to be shown in the final output. It + has been optimized by noticing what need not to be collected + (e.g. there is no need to collect the log messages when showing + only the number of changes). + + * "git checkout $branch" (and other operations that share the same + underlying machinery) has been optimized. + + * Automated tests in Travis CI environment has been optimized by + persisting runtime statistics of previous "prove" run, executing + tests that take longer before other ones; this reduces the total + wallclock time. + + * Test scripts have been updated to remove assumptions that are not + portable between Git for POSIX and Git for Windows, or to skip ones + with expectations that are not satisfiable on Git for Windows. + + * Some calls to strcpy(3) triggers a false warning from static + analyzers that are less intelligent than humans, and reducing the + number of these false hits helps us notice real issues. A few + calls to strcpy(3) in a couple of protrams that are already safe + has been rewritten to avoid false warnings. + + * The "name_path" API was an attempt to reduce the need to construct + the full path out of a series of path components while walking a + tree hierarchy, but over time made less efficient because the path + needs to be flattened, e.g. to be compared with another path that + is already flat. The API has been removed and its users have been + rewritten to simplify the overall code complexity. + + * Help those who debug http(s) part of the system. + (merge 0054045 sp/remote-curl-ssl-strerror later to maint). + + * The internal API to interact with "remote.*" configuration + variables has been streamlined. + + * The ref-filter's format-parsing code has been refactored, in + preparation for "branch --format" and friends. + + * Traditionally, the tests that try commands that work on the + contents in the working tree were named with "worktree" in their + filenames, but with the recent addition of "git worktree" + subcommand, whose tests are also named similarly, it has become + harder to tell them apart. The traditional tests have been renamed + to use "work-tree" instead in an attempt to differentiate them. + (merge 5549029 mg/work-tree-tests later to maint). + + * Many codepaths forget to check return value from git_config_set(); + the function is made to die() to make sure we do not proceed when + setting a configuration variable failed. + (merge 3d18064 ps/config-error later to maint). + + * Handling of errors while writing into our internal asynchronous + process has been made more robust, which reduces flakiness in our + tests. + (merge 43f3afc jk/epipe-in-async later to maint). + + * There is a new DEVELOPER knob that enables many compiler warning + options in the Makefile. + + * The way the test scripts configure the Apache web server has been + updated to work also for Apache 2.4 running on RedHat derived + distros. + + * Out of maintenance gcc on OSX 10.6 fails to compile the code in + 'master'; work it around by using clang by default on the platform. + + * The "name_path" API was an attempt to reduce the need to construct + the full path out of a series of path components while walking a + tree hierarchy, but over time made less efficient because the path + needs to be flattened, e.g. to be compared with another path that + is already flat, in many cases. The API has been removed and its + users have been rewritten to simplify the overall code complexity. + This incidentally also closes some heap-corruption holes. + + * Recent versions of GNU grep is pickier than before to decide if a + file is "binary" and refuse to give line-oriented hits when we + expect it to, unless explicitly told with "-a" option. As our + scripted Porcelains use sane_grep wrapper for line-oriented data, + even when the line may contain non-ASCII payload we took from + end-user data, use "grep -a" to implement sane_grep wrapper when + using an implementation of "grep" that takes the "-a" option. + + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.7 +---------------- + +Unless otherwise noted, all the fixes since v2.7 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * An earlier change in 2.5.x-era broke users' hooks and aliases by + exporting GIT_WORK_TREE to point at the root of the working tree, + interfering when they tried to use a different working tree without + setting GIT_WORK_TREE environment themselves. + + * The "exclude_list" structure has the usual "alloc, nr" pair of + fields to be used by ALLOC_GROW(), but clear_exclude_list() forgot + to reset 'alloc' to 0 when it cleared 'nr' to discard the managed + array. + + * Paths that have been told the index about with "add -N" are not + quite yet in the index, but a few commands behaved as if they + already are in a harmful way. + + * "git send-email" was confused by escaped quotes stored in the alias + files saved by "mutt", which has been corrected. + + * A few non-portable C construct have been spotted by clang compiler + and have been fixed. + + * The documentation has been updated to hint the connection between + the '--signoff' option and DCO. + + * "git reflog" incorrectly assumed that all objects that used to be + at the tip of a ref must be commits, which caused it to segfault. + + * The ignore mechanism saw a few regressions around untracked file + listing and sparse checkout selection areas in 2.7.0; the change + that is responsible for the regression has been reverted. + + * Some codepaths used fopen(3) when opening a fixed path in $GIT_DIR + (e.g. COMMIT_EDITMSG) that is meant to be left after the command is + done. This however did not work well if the repository is set to + be shared with core.sharedRepository and the umask of the previous + user is tighter. They have been made to work better by calling + unlink(2) and retrying after fopen(3) fails with EPERM. + + * Asking gitweb for a nonexistent commit left a warning in the server + log. + + Somebody may want to follow this up with an additional test, perhaps? + IIRC, we do test that no Perl warnings are given to the server log, + so this should have been caught if our test coverage were good. + + * "git rebase", unlike all other callers of "gc --auto", did not + ignore the exit code from "gc --auto". + + * Many codepaths that run "gc --auto" before exiting kept packfiles + mapped and left the file descriptors to them open, which was not + friendly to systems that cannot remove files that are open. They + now close the packs before doing so. + + * A recent optimization to filter-branch in v2.7.0 introduced a + regression when --prune-empty filter is used, which has been + corrected. + + * The description for SANITY prerequisite the test suite uses has + been clarified both in the comment and in the implementation. + + * "git tag" started listing a tag "foo" as "tags/foo" when a branch + named "foo" exists in the same repository; remove this unnecessary + disambiguation, which is a regression introduced in v2.7.0. + + * The way "git svn" uses auth parameter was broken by Subversion + 1.9.0 and later. + + * The "split" subcommand of "git subtree" (in contrib/) incorrectly + skipped merges when it shouldn't, which was corrected. + + * A few options of "git diff" did not work well when the command was + run from a subdirectory. + + * The command line completion learned a handful of additional options + and command specific syntax. + + * dirname() emulation has been added, as Msys2 lacks it. + + * The underlying machinery used by "ls-files -o" and other commands + has been taught not to create empty submodule ref cache for a + directory that is not a submodule. This removes a ton of wasted + CPU cycles. + + * "git worktree" had a broken code that attempted to auto-fix + possible inconsistency that results from end-users moving a + worktree to different places without telling Git (the original + repository needs to maintain back-pointers to its worktrees, + but "mv" run by end-users who are not familiar with that fact + will obviously not adjust them), which actually made things + worse when triggered. + + * The low-level merge machinery has been taught to use CRLF line + termination when inserting conflict markers to merged contents that + are themselves CRLF line-terminated. + + * "git push --force-with-lease" has been taught to report if the push + needed to force (or fast-forwarded). + + * The emulated "yes" command used in our test scripts has been + tweaked not to spend too much time generating unnecessary output + that is not used, to help those who test on Windows where it would + not stop until it fills the pipe buffer due to lack of SIGPIPE. + + * The documentation for "git clean" has been corrected; it mentioned + that .git/modules/* are removed by giving two "-f", which has never + been the case. + + * The vimdiff backend for "git mergetool" has been tweaked to arrange + and number buffers in the order that would match the expectation of + majority of people who read left to right, then top down and assign + buffers 1 2 3 4 "mentally" to local base remote merge windows based + on that order. + + * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a + rev, i.e. the object named by the the pathname with wildcard + characters in a tree object. + (merge aac4fac nd/dwim-wildcards-as-pathspecs later to maint). + + * "git rev-parse --git-common-dir" used in the worktree feature + misbehaved when run from a subdirectory. + (merge 17f1365 nd/git-common-dir-fix later to maint). + + * "git worktree add -B <branchname>" did not work. + + * The "v(iew)" subcommand of the interactive "git am -i" command was + broken in 2.6.0 timeframe when the command was rewritten in C. + (merge 708b8cc jc/am-i-v-fix later to maint). + + * "git merge-tree" used to mishandle "both sides added" conflict with + its own "create a fake ancestor file that has the common parts of + what both sides have added and do a 3-way merge" logic; this has + been updated to use the usual "3-way merge with an empty blob as + the fake common ancestor file" approach used in the rest of the + system. + (merge 907681e jk/no-diff-emit-common later to maint). + + * The memory ownership rule of fill_textconv() API, which was a bit + tricky, has been documented a bit better. + (merge a64e6a4 jk/more-comments-on-textconv later to maint). + + * Update various codepaths to avoid manually-counted malloc(). + (merge 08c95df jk/tighten-alloc later to maint). + + * The documentation did not clearly state that the 'simple' mode is + now the default for "git push" when push.default configuration is + not set. + (merge f6b1fb3 mm/push-simple-doc later to maint). + + * Recent versions of GNU grep are pickier when their input contains + arbitrary binary data, which some of our tests uses. Rewrite the + tests to sidestep the problem. + (merge 3b1442d jk/grep-binary-workaround-in-test later to maint). + + * A helper function "git submodule" uses since v2.7.0 to list the + modules that match the pathspec argument given to its subcommands + (e.g. "submodule add <repo> <path>") has been fixed. + (merge 2b56bb7 sb/submodule-module-list-fix later to maint). + + * "git config section.var value" to set a value in per-repository + configuration file failed when it was run outside any repository, + but didn't say the reason correctly. + (merge 638fa62 js/config-set-in-non-repository later to maint). + + * The code to read the pack data using the offsets stored in the pack + idx file has been made more carefully check the validity of the + data in the idx. + (merge 7465feb jk/pack-idx-corruption-safety later to maint). + + * Other minor clean-ups and documentation updates + (merge f459823 ak/extract-argv0-last-dir-sep later to maint). + (merge 63ca1c0 ak/git-strip-extension-from-dashed-command later to maint). + (merge 4867f11 ps/plug-xdl-merge-leak later to maint). + (merge 4938686 dt/initial-ref-xn-commit-doc later to maint). + (merge 9537f21 ma/update-hooks-sample-typofix later to maint). diff --git a/Documentation/RelNotes/2.8.1.txt b/Documentation/RelNotes/2.8.1.txt new file mode 100644 index 0000000000..ef6d80b008 --- /dev/null +++ b/Documentation/RelNotes/2.8.1.txt @@ -0,0 +1,9 @@ +Git v2.8.1 Release Notes +======================== + +Fixes since v2.8 +---------------- + + * "make rpmbuild" target was broken as its input, git.spec.in, was + not updated to match a file it describes that has been renamed + recently. This has been fixed. diff --git a/Documentation/RelNotes/2.8.2.txt b/Documentation/RelNotes/2.8.2.txt new file mode 100644 index 0000000000..447b1933a8 --- /dev/null +++ b/Documentation/RelNotes/2.8.2.txt @@ -0,0 +1,70 @@ +Git v2.8.2 Release Notes +======================== + +Fixes since v2.8.1 +------------------ + + * The embedded args argv-array in the child process is used to build + the command line to run pack-objects instead of using a separate + array of strings. + + * Bunch of tests on "git clone" has been renumbered for better + organization. + + * The tests that involve running httpd leaked the system-wide + configuration in /etc/gitconfig to the tested environment. + + * "index-pack --keep=<msg>" was broken since v2.1.0 timeframe. + + * "git config --get-urlmatch", unlike other variants of the "git + config --get" family, did not signal error with its exit status + when there was no matching configuration. + + * The "--local-env-vars" and "--resolve-git-dir" options of "git + rev-parse" failed to work outside a repository when the command's + option parsing was rewritten in 1.8.5 era. + + * Fetching of history by naming a commit object name directly didn't + work across remote-curl transport. + + * A small memory leak in an error codepath has been plugged in xdiff + code. + + * strbuf_getwholeline() did not NUL-terminate the buffer on certain + corner cases in its error codepath. + + * The startup_info data, which records if we are working inside a + repository (among other things), are now uniformly available to Git + subcommand implementations, and Git avoids attempting to touch + references when we are not in a repository. + + * "git mergetool" did not work well with conflicts that both sides + deleted. + + * "git send-email" had trouble parsing alias file in mailrc format + when lines in it had trailing whitespaces on them. + + * When "git merge --squash" stopped due to conflict, the concluding + "git commit" failed to read in the SQUASH_MSG that shows the log + messages from all the squashed commits. + + * "git merge FETCH_HEAD" dereferenced NULL pointer when merging + nothing into an unborn history (which is arguably unusual usage, + which perhaps was the reason why nobody noticed it). + + * Build updates for MSVC. + + * "git diff -M" used to work better when two originally identical + files A and B got renamed to X/A and X/B by pairing A to X/A and B + to X/B, but this was broken in the 2.0 timeframe. + + * "git send-pack --all <there>" was broken when its command line + option parsing was written in the 2.6 timeframe. + + * When running "git blame $path" with unnormalized data in the index + for the path, the data in the working tree was blamed, even though + "git add" would not have changed what is already in the index, due + to "safe crlf" that disables the line-end conversion. It has been + corrected. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.8.3.txt b/Documentation/RelNotes/2.8.3.txt new file mode 100644 index 0000000000..fedd9968e5 --- /dev/null +++ b/Documentation/RelNotes/2.8.3.txt @@ -0,0 +1,101 @@ +Git v2.8.3 Release Notes +======================== + +Fixes since v2.8.2 +------------------ + + * "git send-email" now uses a more readable timestamps when + formulating a message ID. + + * The repository set-up sequence has been streamlined (the biggest + change is that there is no longer git_config_early()), so that we + do not attempt to look into refs/* when we know we do not have a + Git repository. + + * When "git worktree" feature is in use, "git branch -d" allowed + deletion of a branch that is checked out in another worktree + + * When "git worktree" feature is in use, "git branch -m" renamed a + branch that is checked out in another worktree without adjusting + the HEAD symbolic ref for the worktree. + + * "git format-patch --help" showed `-s` and `--no-patch` as if these + are valid options to the command. We already hide `--patch` option + from the documentation, because format-patch is about showing the + diff, and the documentation now hides these options as well. + + * A change back in version 2.7 to "git branch" broke display of a + symbolic ref in a non-standard place in the refs/ hierarchy (we + expect symbolic refs to appear in refs/remotes/*/HEAD to point at + the primary branch the remote has, and as .git/HEAD to point at the + branch we locally checked out). + + * A partial rewrite of "git submodule" in the 2.7 timeframe changed + the way the gitdir: pointer in the submodules point at the real + repository location to use absolute paths by accident. This has + been corrected. + + * "git commit" misbehaved in a few minor ways when an empty message + is given via -m '', all of which has been corrected. + + * Support for CRAM-MD5 authentication method in "git imap-send" did + not work well. + + * The socks5:// proxy support added back in 2.6.4 days was not aware + that socks5h:// proxies behave differently. + + * "git config" had a codepath that tried to pass a NULL to + printf("%s"), which nobody seems to have noticed. + + * On Cygwin, object creation uses the "create a temporary and then + rename it to the final name" pattern, not "create a temporary, + hardlink it to the final name and then unlink the temporary" + pattern. + + This is necessary to use Git on Windows shared directories, and is + already enabled for the MinGW and plain Windows builds. It also + has been used in Cygwin packaged versions of Git for quite a while. + See http://thread.gmane.org/gmane.comp.version-control.git/291853 + and http://thread.gmane.org/gmane.comp.version-control.git/275680. + + * "git replace -e" did not honour "core.editor" configuration. + + * Upcoming OpenSSL 1.1.0 will break compilation b updating a few APIs + we use in imap-send, which has been adjusted for the change. + + * "git submodule" reports the paths of submodules the command + recurses into, but this was incorrect when the command was not run + from the root level of the superproject. + + * The test scripts for "git p4" (but not "git p4" implementation + itself) has been updated so that they would work even on a system + where the installed version of Python is python 3. + + * The "user.useConfigOnly" configuration variable makes it an error + if users do not explicitly set user.name and user.email. However, + its check was not done early enough and allowed another error to + trigger, reporting that the default value we guessed from the + system setting was unusable. This was a suboptimal end-user + experience as we want the users to set user.name/user.email without + relying on the auto-detection at all. + + * "git mv old new" did not adjust the path for a submodule that lives + as a subdirectory inside old/ directory correctly. + + * "git push" from a corrupt repository that attempts to push a large + number of refs deadlocked; the thread to relay rejection notices + for these ref updates blocked on writing them to the main thread, + after the main thread at the receiving end notices that the push + failed and decides not to read these notices and return a failure. + + * A question by "git send-email" to ask the identity of the sender + has been updated. + + * Recent update to Git LFS broke "git p4" by changing the output from + its "lfs pointer" subcommand. + + * Some multi-byte encoding can have a backslash byte as a later part + of one letter, which would confuse "highlight" filter used in + gitweb. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.8.4.txt b/Documentation/RelNotes/2.8.4.txt new file mode 100644 index 0000000000..f4e2552836 --- /dev/null +++ b/Documentation/RelNotes/2.8.4.txt @@ -0,0 +1,69 @@ +Git v2.8.4 Release Notes +======================== + +Fixes since v2.8.3 +------------------ + + * Documentation for "git merge --verify-signatures" has been updated + to clarify that the signature of only the commit at the tip is + verified. Also the phrasing used for signature and key validity is + adjusted to align with that used by OpenPGP. + + * On Windows, .git and optionally any files whose name starts with a + dot are now marked as hidden, with a core.hideDotFiles knob to + customize this behaviour. + + * Portability enhancement for "rebase -i" to help platforms whose + shell does not like "for i in <empty>" (which is not POSIX-kosher). + + * "git fsck" learned to catch NUL byte in a commit object as + potential error and warn. + + * CI test was taught to build documentation pages. + + * Many 'linkgit:<git documentation page>' references were broken, + which are all fixed with this. + + * "git describe --contains" often made a hard-to-justify choice of + tag to give name to a given commit, because it tried to come up + with a name with smallest number of hops from a tag, causing an old + commit whose close descendant that is recently tagged were not + described with respect to an old tag but with a newer tag. It did + not help that its computation of "hop" count was further tweaked to + penalize being on a side branch of a merge. The logic has been + updated to favor using the tag with the oldest tagger date, which + is a lot easier to explain to the end users: "We describe a commit + in terms of the (chronologically) oldest tag that contains the + commit." + + * Running tests with '-x' option to trace the individual command + executions is a useful way to debug test scripts, but some tests + that capture the standard error stream and check what the command + said can be broken with the trace output mixed in. When running + our tests under "bash", however, we can redirect the trace output + to another file descriptor to keep the standard error of programs + being tested intact. + + * "http.cookieFile" configuration variable clearly wants a pathname, + but we forgot to treat it as such by e.g. applying tilde expansion. + + * When de-initialising all submodules, "git submodule deinit" gave a + faulty recommendation to use "git submodule deinit .", which would + result in a strange error message in a pathological corner case. + This has been corrected to suggest "submodule deinit --all" instead. + + * Many commands normalize command line arguments from NFD to NFC + variant of UTF-8 on OSX, but commands in the "diff" family did + not, causing "git diff $path" to complain that no such path is + known to Git. They have been taught to do the normalization. + + * A couple of bugs around core.autocrlf have been fixed. + + * "git difftool" learned to handle unmerged paths correctly in + dir-diff mode. + + * The "are we talking with TTY, doing an interactive session?" + detection has been updated to work better for "Git for Windows". + + +Also contains other minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.9.0.txt b/Documentation/RelNotes/2.9.0.txt new file mode 100644 index 0000000000..b61d36712f --- /dev/null +++ b/Documentation/RelNotes/2.9.0.txt @@ -0,0 +1,512 @@ +Git 2.9 Release Notes +===================== + +Backward compatibility notes +---------------------------- + +The end-user facing Porcelain level commands in the "git diff" and +"git log" family by default enable the rename detection; you can still +use "diff.renames" configuration variable to disable this. + +Merging two branches that have no common ancestor with "git merge" is +by default forbidden now to prevent creating such an unusual merge by +mistake. + +The output formats of "git log" that indents the commit log message by +4 spaces now expands HT in the log message by default. You can use +the "--no-expand-tabs" option to disable this. + +"git commit-tree" plumbing command required the user to always sign +its result when the user sets the commit.gpgsign configuration +variable, which was an ancient mistake, which this release corrects. +A script that drives commit-tree, if it relies on this mistake, now +needs to read commit.gpgsign and pass the -S option as necessary. + + +Updates since v2.8 +------------------ + +UI, Workflows & Features + + * Comes with git-multimail 1.3.1 (in contrib/). + + * The end-user facing commands like "git diff" and "git log" + now enable the rename detection by default. + + * The credential.helper configuration variable is cumulative and + there is no good way to override it from the command line. As + a special case, giving an empty string as its value now serves + as the signal to clear the values specified in various files. + + * A new "interactive.diffFilter" configuration can be used to + customize the diff shown in "git add -i" sessions. + + * "git p4" now allows P4 author names to be mapped to Git author + names. + + * "git rebase -x" can be used without passing "-i" option. + + * "git -c credential.<var>=<value> submodule" can now be used to + propagate configuration variables related to credential helper + down to the submodules. + + * "git tag" can create an annotated tag without explicitly given an + "-a" (or "-s") option (i.e. when a tag message is given). A new + configuration variable, tag.forceSignAnnotated, can be used to tell + the command to create signed tag in such a situation. + + * "git merge" used to allow merging two branches that have no common + base by default, which led to a brand new history of an existing + project created and then get pulled by an unsuspecting maintainer, + which allowed an unnecessary parallel history merged into the + existing project. The command has been taught not to allow this by + default, with an escape hatch "--allow-unrelated-histories" option + to be used in a rare event that merges histories of two projects + that started their lives independently. + + * "git pull" has been taught to pass the "--allow-unrelated-histories" + option to underlying "git merge". + + * "git apply -v" learned to report paths in the patch that were + skipped via --include/--exclude mechanism or being outside the + current working directory. + + * Shell completion (in contrib/) updates. + + * The commit object name reported when "rebase -i" stops has been + shortened. + + * "git worktree add" can be given "--no-checkout" option to only + create an empty worktree without checking out the files. + + * "git mergetools" learned to drive ExamDiff. + + * "git pull --rebase" learned "--[no-]autostash" option, so that + the rebase.autostash configuration variable set to true can be + overridden from the command line. + + * When "git log" shows the log message indented by 4-spaces, the + remainder of a line after a HT does not align in the way the author + originally intended. The command now expands tabs by default to help + such a case, and allows the users to override it with a new option, + "--no-expand-tabs". + + * "git send-email" now uses a more readable timestamps when + formulating a message ID. + + * "git rerere" can encounter two or more files with the same conflict + signature that have to be resolved in different ways, but there was + no way to record these separate resolutions. + + * "git p4" learned to record P4 jobs in Git commit that imports from + the history in Perforce. + + * "git describe --contains" often made a hard-to-justify choice of + tag to name a given commit, because it tried to come up + with a name with smallest number of hops from a tag, causing an old + commit whose close descendant that is recently tagged were not + described with respect to an old tag but with a newer tag. It did + not help that its computation of "hop" count was further tweaked to + penalize being on a side branch of a merge. The logic has been + updated to favor using the tag with the oldest tagger date, which + is a lot easier to explain to the end users: "We describe a commit + in terms of the (chronologically) oldest tag that contains the + commit." + + * "git clone" learned the "--shallow-submodules" option. + + * HTTP transport clients learned to throw extra HTTP headers at the + server, specified via http.extraHeader configuration variable. + + * The "--compaction-heuristic" option to "git diff" family of + commands enables a heuristic to make the patch output more readable + by using a blank line as a strong hint that the contents before and + after it belong to logically separate units. It is still + experimental. + + * A new configuration variable core.hooksPath allows customizing + where the hook directory is. + + * An earlier addition of "sanitize_submodule_env" with 14111fc4 (git: + submodule honor -c credential.* from command line, 2016-02-29) + turned out to be a convoluted no-op; implement what it wanted to do + correctly, and stop filtering settings given via "git -c var=val". + + * "git commit --dry-run" reported "No, no, you cannot commit." in one + case where "git commit" would have allowed you to commit, and this + improves it a little bit ("git commit --dry-run --short" still does + not give you the correct answer, for example). This is a stop-gap + measure in that "commit --short --dry-run" still gives an incorrect + result. + + * The experimental "multiple worktree" feature gains more safety to + forbid operations on a branch that is checked out or being actively + worked on elsewhere, by noticing that e.g. it is being rebased. + + * "git format-patch" learned a new "--base" option to record what + (public, well-known) commit the original series was built on in + its output. + + * "git commit" learned to pay attention to the "commit.verbose" + configuration variable and act as if the "--verbose" option + was given from the command line. + + * Updated documentation gives hints to GMail users with two-factor + auth enabled that they need app-specific-password when using + "git send-email". + + * The manpage output of our documentation did not render well in + terminal; typeset literals in bold by default to make them stand + out more. + + * The mark-up in the top-level README.md file has been updated to + typeset CLI command names differently from the body text. + + +Performance, Internal Implementation, Development Support etc. + + * The embedded args argv-array in the child process is used to build + the command line to run pack-objects instead of using a separate + array of strings. + + * A test for tags has been restructured so that more parts of it can + easily be run on a platform without a working GnuPG. + + * The startup_info data, which records if we are working inside a + repository (among other things), are now uniformly available to Git + subcommand implementations, and Git avoids attempting to touch + references when we are not in a repository. + + * The command line argument parser for "receive-pack" has been + rewritten to use parse-options. + + * A major part of "git submodule update" has been ported to C to take + advantage of the recently added framework to run download tasks in + parallel. Other updates to "git submodule" that move pieces of + logic to C continues. + + * Rename bunch of tests on "git clone" for better organization. + + * The tests that involve running httpd leaked the system-wide + configuration in /etc/gitconfig to the tested environment. + + * Build updates for MSVC. + + * The repository set-up sequence has been streamlined (the biggest + change is that there is no longer git_config_early()), so that we + do not attempt to look into refs/* when we know we do not have a + Git repository. + + * Code restructuring around the "refs" API to prepare for pluggable + refs backends. + + * Sources to many test helper binaries and the generated helpers + have been moved to t/helper/ subdirectory to reduce clutter at the + top level of the tree. + + * Unify internal logic between "git tag -v" and "git verify-tag" + commands by making one directly call into the other. + + * "merge-recursive" strategy incorrectly checked if a path that is + involved in its internal merge exists in the working tree. + + * The test scripts for "git p4" (but not "git p4" implementation + itself) has been updated so that they would work even on a system + where the installed version of Python is python 3. + + * As nobody maintains our in-tree git.spec.in and distros use their + own spec file, we stopped pretending that we support "make rpm". + + * Move from "unsigned char[20]" to "struct object_id" continues. + + * The code for warning_errno/die_errno has been refactored and a new + error_errno() reporting helper is introduced. + (merge 1da045f nd/error-errno later to maint). + + * Running tests with '-x' option to trace the individual command + executions is a useful way to debug test scripts, but some tests + that capture the standard error stream and check what the command + said can be broken with the trace output mixed in. When running + our tests under "bash", however, we can redirect the trace output + to another file descriptor to keep the standard error of programs + being tested intact. + + * t0040 had too many unnecessary repetitions in its test data. Teach + test-parse-options program so that a caller can tell what it + expects in its output, so that these repetitions can be cleaned up. + + * Add perf test for "rebase -i". + + * Common mistakes when writing gitlink: in our documentation are + found by "make check-docs". + + * t9xxx series has been updated primarily for readability, while + fixing small bugs in it. A few scripted Porcelain commands have + also been updated to fix possible bugs around their use of + "test -z" and "test -n". + + * CI test was taught to run git-svn tests. + + * "git cat-file --batch-all" has been sped up, by taking advantage + of the fact that it does not have to read a list of objects, in two + ways. + + * test updates to make it more readable and maintainable. + (merge e6273f4 es/t1500-modernize later to maint). + + * "make DEVELOPER=1" worked as expected; setting DEVELOPER=1 in + config.mak didn't. + (merge 51dd3e8 mm/makefile-developer-can-be-in-config-mak later to maint). + + * The way how "submodule--helper list" signals unmatch error to its + callers has been updated. + + * A bash-ism "local" has been removed from "git submodule" scripted + Porcelain. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.8 +---------------- + +Unless otherwise noted, all the fixes since v2.8 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git config --get-urlmatch", unlike other variants of the "git + config --get" family, did not signal error with its exit status + when there was no matching configuration. + + * The "--local-env-vars" and "--resolve-git-dir" options of "git + rev-parse" failed to work outside a repository when the command's + option parsing was rewritten in 1.8.5 era. + + * "git index-pack --keep[=<msg>] pack-$name.pack" simply did not work. + + * Fetching of history by naming a commit object name directly didn't + work across remote-curl transport. + + * A small memory leak in an error codepath has been plugged in xdiff + code. + + * strbuf_getwholeline() did not NUL-terminate the buffer on certain + corner cases in its error codepath. + + * "git mergetool" did not work well with conflicts that both sides + deleted. + + * "git send-email" had trouble parsing alias file in mailrc format + when lines in it had trailing whitespaces on them. + + * When "git merge --squash" stopped due to conflict, the concluding + "git commit" failed to read in the SQUASH_MSG that shows the log + messages from all the squashed commits. + + * "git merge FETCH_HEAD" dereferenced NULL pointer when merging + nothing into an unborn history (which is arguably unusual usage, + which perhaps was the reason why nobody noticed it). + + * When "git worktree" feature is in use, "git branch -d" allowed + deletion of a branch that is checked out in another worktree, + which was wrong. + + * When "git worktree" feature is in use, "git branch -m" renamed a + branch that is checked out in another worktree without adjusting + the HEAD symbolic ref for the worktree. + + * "git diff -M" used to work better when two originally identical + files A and B got renamed to X/A and X/B by pairing A to X/A and B + to X/B, but this was broken in the 2.0 timeframe. + + * "git send-pack --all <there>" was broken when its command line + option parsing was written in the 2.6 timeframe. + + * "git format-patch --help" showed `-s` and `--no-patch` as if these + are valid options to the command. We already hide `--patch` option + from the documentation, because format-patch is about showing the + diff, and the documentation now hides these options as well. + + * When running "git blame $path" with unnormalized data in the index + for the path, the data in the working tree was blamed, even though + "git add" would not have changed what is already in the index, due + to "safe crlf" that disables the line-end conversion. It has been + corrected. + + * A change back in version 2.7 to "git branch" broke display of a + symbolic ref in a non-standard place in the refs/ hierarchy (we + expect symbolic refs to appear in refs/remotes/*/HEAD to point at + the primary branch the remote has, and as .git/HEAD to point at the + branch we locally checked out). + + * A partial rewrite of "git submodule" in the 2.7 timeframe changed + the way the gitdir: pointer in the submodules point at the real + repository location to use absolute paths by accident. This has + been corrected. + + * "git commit" misbehaved in a few minor ways when an empty message + is given via -m '', all of which has been corrected. + + * Support for CRAM-MD5 authentication method in "git imap-send" did + not work well. + + * Upcoming OpenSSL 1.1.0 will break compilation by updating a few API + elements we use in imap-send, which has been adjusted for the change. + + * The socks5:// proxy support added back in 2.6.4 days was not aware + that socks5h:// proxies behave differently from socks5:// proxies. + + * "git config" had a codepath that tried to pass a NULL to + printf("%s"), which nobody seems to have noticed. + + * On Cygwin, object creation uses the "create a temporary and then + rename it to the final name" pattern, not "create a temporary, + hardlink it to the final name and then unlink the temporary" + pattern. + + This is necessary to use Git on Windows shared directories, and is + already enabled for the MinGW and plain Windows builds. It also + has been used in Cygwin packaged versions of Git for quite a while. + See http://thread.gmane.org/gmane.comp.version-control.git/291853 + + * "merge-octopus" strategy did not ensure that the index is clean + when merge begins. + + * When "git merge" notices that the merge can be resolved purely at + the tree level (without having to merge blobs) and the resulting + tree happens to already exist in the object store, it forgot to + update the index, which left an inconsistent state that would + break later operations. + + * "git submodule" reports the paths of submodules the command + recurses into, but these paths were incorrectly reported when + the command was not run from the root level of the superproject. + + * The "user.useConfigOnly" configuration variable makes it an error + if users do not explicitly set user.name and user.email. However, + its check was not done early enough and allowed another error to + trigger, reporting that the default value we guessed from the + system setting was unusable. This was a suboptimal end-user + experience as we want the users to set user.name/user.email without + relying on the auto-detection at all. + + * "git mv old new" did not adjust the path for a submodule that lives + as a subdirectory inside old/ directory correctly. + + * "git replace -e" did not honour "core.editor" configuration. + + * "git push" from a corrupt repository that attempts to push a large + number of refs deadlocked; the thread to relay rejection notices + for these ref updates blocked on writing them to the main thread, + after the main thread at the receiving end notices that the push + failed and decides not to read these notices and return a failure. + + * mmap emulation on Windows has been optimized and work better without + consuming paging store when not needed. + + * A question by "git send-email" to ask the identity of the sender + has been updated. + + * UI consistency improvements for "git mergetool". + + * "git rebase -m" could be asked to rebase an entire branch starting + from the root, but failed by assuming that there always is a parent + commit to the first commit on the branch. + + * Fix a broken "p4 lfs" test. + + * Recent update to Git LFS broke "git p4" by changing the output from + its "lfs pointer" subcommand. + + * "git fetch" test t5510 was flaky while running a (forced) automagic + garbage collection. + + * Documentation updates to help contributors setting up Travis CI + test for their patches. + + * Some multi-byte encoding can have a backslash byte as a later part + of one letter, which would confuse "highlight" filter used in + gitweb. + + * "git commit-tree" plumbing command required the user to always sign + its result when the user sets the commit.gpgsign configuration + variable, which was an ancient mistake. Rework "git rebase" that + relied on this mistake so that it reads commit.gpgsign and pass (or + not pass) the -S option to "git commit-tree" to keep the end-user + expectation the same, while teaching "git commit-tree" to ignore + the configuration variable. This will stop requiring the users to + sign commit objects used internally as an implementation detail of + "git stash". + + * "http.cookieFile" configuration variable clearly wants a pathname, + but we forgot to treat it as such by e.g. applying tilde expansion. + + * Consolidate description of tilde-expansion that is done to + configuration variables that take pathname to a single place. + + * Correct faulty recommendation to use "git submodule deinit ." when + de-initialising all submodules, which would result in a strange + error message in a pathological corner case. + + * Many 'linkgit:<git documentation page>' references were broken, + which are all fixed with this. + + * "git rerere" can get confused by conflict markers deliberately left + by the inner merge step, because they are indistinguishable from + the real conflict markers left by the outermost merge which are + what the end user and "rerere" need to look at. This was fixed by + making the conflict markers left by the inner merges a bit longer. + (merge 0f9fd5c jc/ll-merge-internal later to maint). + + * CI test was taught to build documentation pages. + + * "git fsck" learned to catch NUL byte in a commit object as + potential error and warn. + + * Portability enhancement for "rebase -i" to help platforms whose + shell does not like "for i in <empty>" (which is not POSIX-kosher). + + * On Windows, .git and optionally any files whose name starts with a + dot are now marked as hidden, with a core.hideDotFiles knob to + customize this behaviour. + + * Documentation for "git merge --verify-signatures" has been updated + to clarify that the signature of only the commit at the tip is + verified. Also the phrasing used for signature and key validity is + adjusted to align with that used by OpenPGP. + + * A couple of bugs around core.autocrlf have been fixed. + + * Many commands normalize command line arguments from NFD to NFC + variant of UTF-8 on OSX, but commands in the "diff" family did + not, causing "git diff $path" to complain that no such path is + known to Git. They have been taught to do the normalization. + + * "git difftool" learned to handle unmerged paths correctly in + dir-diff mode. + + * The "are we talking with TTY, doing an interactive session?" + detection has been updated to work better for "Git for Windows". + + * We forgot to add "git log --decorate=auto" to documentation when we + added the feature back in v2.1.0 timeframe. + (merge 462cbb4 rj/log-decorate-auto later to maint). + + * "git fast-import --export-marks" would overwrite the existing marks + file even when it makes a dump from its custom die routine. + Prevent it from doing so when we have an import-marks file but + haven't finished reading it. + (merge f4beed6 fc/fast-import-broken-marks-file later to maint). + + * "git rebase -i", after it fails to auto-resolve the conflict, had + an unnecessary call to "git rerere" from its very early days, which + was spotted recently; the call has been removed. + (merge 7063693 js/rebase-i-dedup-call-to-rerere later to maint). + + * Other minor clean-ups and documentation updates + (merge cd82b7a pa/cherry-pick-doc-typo later to maint). + (merge 2bb73ae rs/patch-id-use-skip-prefix later to maint). + (merge aa20cbc rs/apply-name-terminate later to maint). + (merge fe17fc0 jc/t2300-setup later to maint). + (merge e256eec jk/shell-portability later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 98fc4cc1d0..e8ad978824 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -61,23 +61,28 @@ Make sure that you have tests for the bug you are fixing. See t/README for guidance. 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. - -Speaking of the documentation, it is currently a liberal mixture of US -and UK English norms for spelling and grammar, which is somewhat -unfortunate. A huge patch that touches the files all over the place -only to correct the inconsistency is not welcome, though. Potential -clashes with other changes that can result from such a patch are not -worth it. We prefer to gradually reconcile the inconsistencies in -favor of US English, with small and easily digestible patches, as a -side effect of doing some other real work in the vicinity (e.g. -rewriting a paragraph for clarity, while turning en_UK spelling to -en_US). Obvious typographical fixes are much more welcomed ("teh -> -"the"), preferably submitted as independent patches separate from -other documentation changes. +the feature triggers the new behavior when it should, and to show the +feature does not trigger when it shouldn't. After any code change, make +sure that the entire test suite passes. + +If you have an account at GitHub (and you can get one for free to work +on open source projects), you can use their Travis CI integration to +test your changes on Linux, Mac (and hopefully soon Windows). See +GitHub-Travis CI hints section for details. + +Do not forget to update the documentation to describe the updated +behavior and make sure that the resulting documentation set formats +well. It is currently a liberal mixture of US and UK English norms for +spelling and grammar, which is somewhat unfortunate. A huge patch that +touches the files all over the place only to correct the inconsistency +is not welcome, though. Potential clashes with other changes that can +result from such a patch are not worth it. We prefer to gradually +reconcile the inconsistencies in favor of US English, with small and +easily digestible patches, as a side effect of doing some other real +work in the vicinity (e.g. rewriting a paragraph for clarity, while +turning en_UK spelling to en_US). Obvious typographical fixes are much +more welcomed ("teh -> "the"), preferably submitted as independent +patches separate from other documentation changes. Oh, another thing. We are picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped @@ -370,6 +375,47 @@ Know the status of your patch after submission entitled "What's cooking in git.git" and "What's in git.git" giving the status of various proposed changes. +-------------------------------------------------- +GitHub-Travis CI hints + +With an account at GitHub (you can get one for free to work on open +source projects), you can use Travis CI to test your changes on Linux, +Mac (and hopefully soon Windows). You can find a successful example +test build here: https://travis-ci.org/git/git/builds/120473209 + +Follow these steps for the initial setup: + + (1) Fork https://github.com/git/git to your GitHub account. + You can find detailed instructions how to fork here: + https://help.github.com/articles/fork-a-repo/ + + (2) Open the Travis CI website: https://travis-ci.org + + (3) Press the "Sign in with GitHub" button. + + (4) Grant Travis CI permissions to access your GitHub account. + You can find more information about the required permissions here: + https://docs.travis-ci.com/user/github-oauth-scopes + + (5) Open your Travis CI profile page: https://travis-ci.org/profile + + (6) Enable Travis CI builds for your Git fork. + +After the initial setup, Travis CI will run whenever you push new changes +to your fork of Git on GitHub. You can monitor the test state of all your +branches here: https://travis-ci.org/<Your GitHub handle>/git/branches + +If a branch did not pass all test cases then it is marked with a red +cross. In that case you can click on the failing Travis CI job and +scroll all the way down in the log. Find the line "<-- Click here to see +detailed test output!" and click on the triangle next to the log line +number to expand the detailed test output. Here is such a failing +example: https://travis-ci.org/git/git/jobs/122676187 + +Fix the problem and push your fix to your Git fork. This will trigger +a new Travis CI build to ensure all tests pass. + + ------------------------------------------------ MUA specific hints diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index a09969ba08..02cb6845cd 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -63,13 +63,19 @@ include::line-range-format.txt[] `-` to make the command read from the standard input). --date <format>:: - The value is one of the following alternatives: - {relative,local,default,iso,rfc,short}. If --date is not + Specifies the format used to output dates. If --date is not provided, the value of the blame.date config variable is used. If the blame.date config variable is also not set, the - iso format is used. For more information, See the discussion + iso format is used. For supported values, see the discussion of the --date option at linkgit:git-log[1]. +--[no-]progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal. This flag + enables progress reporting even if not attached to a + terminal. Can't use `--progress` together with `--porcelain` + or `--incremental`. + -M|<num>|:: Detect moved or copied lines within a file. When a commit moves or copies a block of lines (e.g. the original file diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 04f99778d8..5aa73cfe45 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -38,6 +38,10 @@ sub format_one { } } +while (<>) { + last if /^### command list/; +} + my %cmds = (); for (sort <>) { next if /^#/; diff --git a/Documentation/config.txt b/Documentation/config.txt index 2e919f0df8..2e1b2e486e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -81,13 +81,16 @@ Includes You can include one config file from another by setting the special `include.path` variable to the name of the file to be included. The +variable takes a pathname as its value, and is subject to tilde +expansion. + +The included file is expanded immediately, as if its contents had been found at the location of the include directive. If the value of the `include.path` variable is a relative path, the path is considered to be relative to the configuration file in which the include directive was -found. The value of `include.path` is subject to tilde expansion: `~/` -is expanded to the value of `$HOME`, and `~user/` to the specified -user's home directory. See below for examples. +found. See below for examples. + Example ~~~~~~~ @@ -114,7 +117,7 @@ Example [include] path = /path/to/foo.inc ; include by absolute path path = foo ; expand "foo" relative to the current file - path = ~/foo ; expand "foo" in your $HOME directory + path = ~/foo ; expand "foo" in your `$HOME` directory Values @@ -169,6 +172,13 @@ thing on the same output line (e.g. opening parenthesis before the list of branch names in `log --decorate` output) is set to be painted with `bold` or some other attribute. +pathname:: + A variable that takes a pathname value can be given a + string that begins with "`~/`" or "`~user/`", and the usual + tilde expansion happens to such a string: `~/` + is expanded to the value of `$HOME`, and `~user/` to the + specified user's home directory. + Variables ~~~~~~~~~ @@ -269,6 +279,12 @@ See linkgit:git-update-index[1]. + The default is true (when core.filemode is not specified in the config file). +core.hideDotFiles:: + (Windows-only) If true, mark newly-created directories and files whose + name starts with a dot as hidden. If 'dotGitOnly', only the `.git/` + directory is hidden, but no other files starting with a dot. The + default mode is 'dotGitOnly'. + core.ignoreCase:: If true, this option enables various workarounds to enable Git to work better on filesystems that are not case sensitive, @@ -308,6 +324,15 @@ core.trustctime:: crawlers and some backup systems). See linkgit:git-update-index[1]. True by default. +core.untrackedCache:: + Determines what to do about the untracked cache feature of the + index. It will be kept, if this variable is unset or set to + `keep`. It will automatically be added if set to `true`. And + it will automatically be removed, if set to `false`. Before + setting it to `true`, you should check that mtime is working + properly on your system. + See linkgit:git-update-index[1]. `keep` by default. + core.checkStat:: Determines which stat fields to match between the index and work tree. The user can set this to 'default' or @@ -328,9 +353,9 @@ core.quotePath:: core.eol:: Sets the line ending type to use in the working directory for - files that have the `text` property set. Alternatives are - 'lf', 'crlf' and 'native', which uses the platform's native - line ending. The default value is `native`. See + files that have the `text` property set when core.autocrlf is false. + Alternatives are 'lf', 'crlf' and 'native', which uses the platform's + native line ending. The default value is `native`. See linkgit:gitattributes[5] for more information on end-of-line conversion. @@ -453,6 +478,8 @@ false), while all other repositories are assumed to be bare (bare core.worktree:: Set the path to the root of the working tree. + If GIT_COMMON_DIR environment variable is set, core.worktree + is ignored and not used for determining the root of working tree. This can be overridden by the GIT_WORK_TREE environment variable and the '--work-tree' command-line option. The value can be an absolute path or relative to the path to @@ -475,10 +502,10 @@ repository's usual working tree). core.logAllRefUpdates:: Enable the reflog. Updates to a ref <ref> is logged to the file - "$GIT_DIR/logs/<ref>", by appending the new and old + "`$GIT_DIR/logs/<ref>`", by appending the new and old SHA-1, the date/time and the reason of the update, but only when the file exists. If this configuration - variable is set to true, missing "$GIT_DIR/logs/<ref>" + variable is set to true, missing "`$GIT_DIR/logs/<ref>`" file is automatically created for branch heads (i.e. under refs/heads/), remote refs (i.e. under refs/remotes/), note refs (i.e. under refs/notes/), and the symbolic ref HEAD. @@ -582,12 +609,11 @@ be delta compressed, but larger binary media files won't be. Common unit suffixes of 'k', 'm', or 'g' are supported. core.excludesFile:: - In addition to '.gitignore' (per-directory) and - '.git/info/exclude', Git looks into this file for patterns - of files which are not meant to be tracked. "`~/`" 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 + Specifies the pathname to the file that contains patterns to + describe paths that are not meant to be tracked, in addition + to '.gitignore' (per-directory) and '.git/info/exclude'. + Defaults to `$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:: @@ -604,8 +630,25 @@ core.attributesFile:: '.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`. 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. + `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not + set or empty, `$HOME/.config/git/attributes` is used instead. + +core.hooksPath:: + By default Git will look for your hooks in the + '$GIT_DIR/hooks' directory. Set this to different path, + e.g. '/etc/git/hooks', and Git will try to find your hooks in + that directory, e.g. '/etc/git/hooks/pre-receive' instead of + in '$GIT_DIR/hooks/pre-receive'. ++ +The path can be either absolute or relative. A relative path is +taken as relative to the directory where the hooks are run (see +the "DESCRIPTION" section of linkgit:githooks[5]). ++ +This configuration variable is useful in cases where you'd like to +centrally configure your Git hooks instead of configuring them on a +per-repository basis, or as a more flexible and centralized +alternative to having an `init.templateDir` where you've changed +default hooks. core.editor:: Commands such as `commit` and `tag` that lets you edit @@ -622,6 +665,12 @@ core.commentChar:: If set to "auto", `git-commit` would select a character that is not the beginning character of any line in existing commit messages. +core.packedRefsTimeout:: + The length of time, in milliseconds, to retry when trying to + lock the `packed-refs` file. Value 0 means not to retry at + all; -1 means to try indefinitely. Default is 1000 (i.e., + retry for 1 second). + sequence.editor:: Text editor used by `git rebase -i` for editing the rebase instruction file. The value is meant to be interpreted by the shell when it is used. @@ -761,6 +810,14 @@ am.keepcr:: by giving '--no-keep-cr' from the command line. See linkgit:git-am[1], linkgit:git-mailsplit[1]. +am.threeWay:: + By default, `git am` will fail if the patch does not apply cleanly. When + set to true, this setting tells `git am` to 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 (equivalent to giving the `--3way` + option from the command line). Defaults to `false`. + See linkgit:git-am[1]. + apply.ignoreWhitespace:: When set to 'change', tells 'git apply' to ignore changes in whitespace, in the same way as the '--ignore-space-change' @@ -850,9 +907,11 @@ branch.<name>.rebase:: "git pull" is run. See "pull.rebase" for doing this in a non branch-specific manner. + - When preserve, also pass `--preserve-merges` along to 'git rebase' - so that locally committed merge commits will not be flattened - by running 'git pull'. +When preserve, also pass `--preserve-merges` along to 'git rebase' +so that locally committed merge commits will not be flattened +by running 'git pull'. ++ +When the value is `interactive`, the rebase is run in interactive mode. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] @@ -1079,15 +1138,19 @@ commit.status:: message. Defaults to true. commit.template:: - Specify a file to use as the template for new commit messages. - "`~/`" is expanded to the value of `$HOME` and "`~user/`" to the - specified user's home directory. + Specify the pathname of a file to use as the template for + new commit messages. + +commit.verbose:: + A boolean or int to specify the level of verbose with `git commit`. + See linkgit:git-commit[1]. credential.helper:: Specify an external helper to be called when a username or password credential is needed; the helper may consult external - storage to avoid prompting the user for the credentials. See - linkgit:gitcredentials[7] for details. + storage to avoid prompting the user for the credentials. Note + that multiple helpers may be defined. See linkgit:gitcredentials[7] + for details. credential.useHttpPath:: When acquiring credentials, consider the "path" component of an http @@ -1106,6 +1169,9 @@ credential.<url>.*:: example.com. See linkgit:gitcredentials[7] for details on how URLs are matched. +credentialCache.ignoreSIGHUP:: + Tell git-credential-cache--daemon to ignore SIGHUP, instead of quitting. + include::diff-config.txt[] difftool.<tool>.path:: @@ -1224,6 +1290,14 @@ format.coverLetter:: format-patch is invoked, but in addition can be set to "auto", to generate a cover-letter only when there's more than one patch. +format.outputDirectory:: + Set a custom directory to store the resulting files instead of the + current working directory. + +format.useAutoBase:: + A boolean value which lets you enable the `--base=auto` option of + format-patch by default. + filter.<driver>.clean:: The command which is used to convert the content of a worktree file to a blob upon checkin. See linkgit:gitattributes[5] for @@ -1234,6 +1308,25 @@ filter.<driver>.smudge:: object to a worktree file upon checkout. See linkgit:gitattributes[5] for details. +fsck.<msg-id>:: + Allows overriding the message type (error, warn or ignore) of a + specific message ID such as `missingEmail`. ++ +For convenience, fsck prefixes the error/warning with the message ID, +e.g. "missingEmail: invalid author/committer line - missing email" means +that setting `fsck.missingEmail = ignore` will hide that issue. ++ +This feature is intended to support working with legacy repositories +which cannot be repaired without disruptive changes. + +fsck.skipList:: + The path to a sorted list of object names (i.e. one SHA-1 per + line) that are known to be broken in a non-fatal way and should + be ignored. This feature is useful when an established project + should be accepted despite early commits containing errors that + can be safely ignored such as invalid committer email addresses. + Note: corrupt objects cannot be skipped with this setting. + gc.aggressiveDepth:: The depth parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults @@ -1272,21 +1365,34 @@ gc.packRefs:: gc.pruneExpire:: When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'. Override the grace period with this config variable. The value - "now" may be used to disable this grace period and always prune - unreachable objects immediately. + "now" may be used to disable this grace period and always prune + unreachable objects immediately, or "never" may be used to + suppress pruning. + +gc.worktreePruneExpire:: + When 'git gc' is run, it calls + 'git worktree prune --expire 3.months.ago'. + This config variable can be used to set a different grace + period. The value "now" may be used to disable the grace + period and prune `$GIT_DIR/worktrees` immediately, or "never" + may be used to suppress pruning. gc.reflogExpire:: gc.<pattern>.reflogExpire:: 'git reflog expire' removes reflog entries older than - this time; defaults to 90 days. With "<pattern>" (e.g. + this time; defaults to 90 days. The value "now" expires all + entries immediately, and "never" suppresses expiration + altogether. With "<pattern>" (e.g. "refs/stash") in the middle the setting applies only to the refs that match the <pattern>. gc.reflogExpireUnreachable:: -gc.<ref>.reflogExpireUnreachable:: +gc.<pattern>.reflogExpireUnreachable:: 'git reflog expire' removes reflog entries older than this time and are not reachable from the current tip; - defaults to 30 days. With "<pattern>" (e.g. "refs/stash") + defaults to 30 days. The value "now" expires all entries + immediately, and "never" suppresses expiration altogether. + With "<pattern>" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the <pattern>. @@ -1399,14 +1505,22 @@ grep.extendedRegexp:: option is ignored when the 'grep.patternType' option is set to a value other than 'default'. +grep.threads:: + Number of grep worker threads to use. + See `grep.threads` in linkgit:git-grep[1] for more information. + +grep.fallbackToNoIndex:: + If set to true, fall back to git grep --no-index if git grep + is executed outside of a git repository. Defaults to false. + gpg.program:: - Use this custom program instead of "gpg" found on $PATH when + Use this custom program instead of "`gpg`" found on `$PATH` when making or verifying a PGP signature. The program must support the same command-line interface as GPG, namely, to verify a detached - signature, "gpg --verify $file - <$signature" is run, and the + signature, "`gpg --verify $file - <$signature`" is run, and the program is expected to signal a good signature by exiting with code 0, and to generate an ASCII-armored detached signature, the - standard input of "gpg -bsau $key" is fed with the contents to be + standard input of "`gpg -bsau $key`" is fed with the contents to be signed, and the program is expected to send the result to its standard output. @@ -1419,7 +1533,7 @@ gui.diffContext:: made by the linkgit:git-gui[1]. The default is "5". gui.displayUntracked:: - Determines if linkgit::git-gui[1] shows untracked files + Determines if linkgit:git-gui[1] shows untracked files in the file list. The default is "true". gui.encoding:: @@ -1545,22 +1659,96 @@ help.htmlPath:: http.proxy:: Override the HTTP proxy, normally configured using the 'http_proxy', - 'https_proxy', and 'all_proxy' environment variables (see - `curl(1)`). This can be overridden on a per-remote basis; see - remote.<name>.proxy + 'https_proxy', and 'all_proxy' environment variables (see `curl(1)`). In + addition to the syntax understood by curl, it is possible to specify a + proxy string with a user name but no password, in which case git will + attempt to acquire one in the same way it does for other credentials. See + linkgit:gitcredentials[7] for more information. The syntax thus is + '[protocol://][user[:password]@]proxyhost[:port]'. This can be overridden + on a per-remote basis; see remote.<name>.proxy + +http.proxyAuthMethod:: + Set the method with which to authenticate against the HTTP proxy. This + only takes effect if the configured proxy string contains a user name part + (i.e. is of the form 'user@host' or 'user@host:port'). This can be + overridden on a per-remote basis; see `remote.<name>.proxyAuthMethod`. + Both can be overridden by the 'GIT_HTTP_PROXY_AUTHMETHOD' environment + variable. Possible values are: ++ +-- +* `anyauth` - Automatically pick a suitable authentication method. It is + assumed that the proxy answers an unauthenticated request with a 407 + status code and one or more Proxy-authenticate headers with supported + authentication methods. This is the default. +* `basic` - HTTP Basic authentication +* `digest` - HTTP Digest authentication; this prevents the password from being + transmitted to the proxy in clear text +* `negotiate` - GSS-Negotiate authentication (compare the --negotiate option + of `curl(1)`) +* `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`) +-- + +http.emptyAuth:: + Attempt authentication without seeking a username or password. This + can be used to attempt GSS-Negotiate authentication without specifying + a username in the URL, as libcurl normally requires a username for + authentication. + +http.extraHeader:: + Pass an additional HTTP header when communicating with a server. If + more than one such entry exists, all of them are added as extra + headers. To allow overriding the settings inherited from the system + config, an empty value will reset the extra headers to the empty list. http.cookieFile:: - File containing previously stored cookie lines which should be used + The pathname of a file containing previously stored cookie lines, + which should be used in the Git http session, if they match the server. The file format of the file to read cookies from should be plain HTTP headers or - the Netscape/Mozilla cookie file format (see linkgit:curl[1]). - NOTE that the file specified with http.cookieFile is only used as + the Netscape/Mozilla cookie file format (see `curl(1)`). + NOTE that the file specified with http.cookieFile is used only as input unless http.saveCookies is set. http.saveCookies:: If set, store cookies received during requests to the file specified by http.cookieFile. Has no effect if http.cookieFile is unset. +http.sslVersion:: + The SSL version to use when negotiating an SSL connection, if you + want to force the default. The available and default version + depend on whether libcurl was built against NSS or OpenSSL and the + particular configuration of the crypto library in use. Internally + this sets the 'CURLOPT_SSL_VERSION' option; see the libcurl + documentation for more details on the format of this option and + for the ssl version supported. Actually the possible values of + this option are: + + - sslv2 + - sslv3 + - tlsv1 + - tlsv1.0 + - tlsv1.1 + - tlsv1.2 + ++ +Can be overridden by the 'GIT_SSL_VERSION' environment variable. +To force git to use libcurl's default ssl version and ignore any +explicit http.sslversion option, set 'GIT_SSL_VERSION' to the +empty string. + +http.sslCipherList:: + A list of SSL ciphers to use when negotiating an SSL connection. + The available ciphers depend on whether libcurl was built against + NSS or OpenSSL and the particular configuration of the crypto + library in use. Internally this sets the 'CURLOPT_SSL_CIPHER_LIST' + option; see the libcurl documentation for more details on the format + of this list. ++ +Can be overridden by the 'GIT_SSL_CIPHER_LIST' environment variable. +To force git to use libcurl's default cipher list and ignore any +explicit http.sslCipherList option, set 'GIT_SSL_CIPHER_LIST' to the +empty string. + http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment @@ -1592,6 +1780,14 @@ http.sslCAPath:: with when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_CAPATH' environment variable. +http.pinnedpubkey:: + Public key of the https service. It may either be the filename of + a PEM or DER encoded public key file or a string starting with + 'sha256//' followed by the base64 encoded sha256 hash of the + public key. See also libcurl 'CURLOPT_PINNEDPUBLICKEY'. git will + exit with an error if this option is set but not supported by + cURL. + http.sslTry:: Attempt to use AUTH SSL/TLS and encrypted data transfers when connecting via regular FTP protocol. This might be needed @@ -1737,6 +1933,14 @@ interactive.singleKey:: setting is silently ignored if portable keystroke input is not available; requires the Perl module Term::ReadKey. +interactive.diffFilter:: + When an interactive command (such as `git add --patch`) shows + a colorized diff, git will pipe the diff through the shell + command defined by this configuration variable. The command may + mark up the diff further for human consumption, provided that it + retains a one-to-one correspondence with the lines in the + original diff. Defaults to disabled (no filtering). + log.abbrevCommit:: If true, makes linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may @@ -1745,16 +1949,23 @@ log.abbrevCommit:: 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`, - `default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1] - for details. + `--date` option. See linkgit:git-log[1] for details. log.decorate:: Print out the ref names of any commits that are shown by the log command. If 'short' is specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is specified, the full ref name (including prefix) will be printed. - This is the same as the log commands '--decorate' option. + If 'auto' is specified, then if the output is going to a terminal, + the ref names are shown as if 'short' were given, otherwise no ref + names are shown. This is the same as the '--decorate' option + of the `git log`. + +log.follow:: + If `true`, `git log` will act as if the `--follow` option was used when + a single <path> is given. This has the same limitations as `--follow`, + i.e. it cannot be used to follow multiple files and does not work well + on non-linear history. log.showRoot:: If true, the initial commit will be shown as a big creation event. @@ -1858,6 +2069,18 @@ mergetool.writeToTemp:: mergetool.prompt:: Prompt before each invocation of the merge resolution program. +notes.mergeStrategy:: + Which merge strategy to choose by default when resolving notes + conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or + `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" + section of linkgit:git-notes[1] for more information on each strategy. + +notes.<name>.mergeStrategy:: + Which merge strategy to choose when doing a notes merge into + refs/notes/<name>. This overrides the more general + "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in + linkgit:git-notes[1] for more information on the available strategies. + notes.displayRef:: The (fully qualified) refname from which to show notes when showing commit messages. The value of this variable can be set @@ -1886,8 +2109,8 @@ notes.rewriteMode:: When copying notes during a rewrite (see the "notes.rewrite.<command>" option), determines what to do if the target commit already has a note. Must be one of - `overwrite`, `concatenate`, or `ignore`. Defaults to - `concatenate`. + `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. + Defaults to `concatenate`. + This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` environment variable. @@ -1971,7 +2194,7 @@ pack.indexVersion:: larger than 2 GB. + If you have an old Git that does not understand the version 2 `*.idx` file, -cloning or fetching over a non native protocol (e.g. "http" and "rsync") +cloning or fetching over a non native protocol (e.g. "http") that will copy both `*.pack` file and corresponding `*.idx` file from the other side may give you a repository that cannot be accessed with your older version of Git. If the `*.pack` file is smaller than 2 GB, however, @@ -1982,8 +2205,11 @@ 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` - option of linkgit:git-repack[1]. The minimum size allowed is - limited to 1 MiB. The default is unlimited. + option of linkgit:git-repack[1]. Reaching this limit results + in the creation of multiple packfiles; which in turn prevents + bitmaps from being created. + The minimum size allowed is limited to 1 MiB. + The default is unlimited. Common unit suffixes of 'k', 'm', or 'g' are supported. @@ -2042,9 +2268,11 @@ pull.rebase:: pull" is run. See "branch.<name>.rebase" for setting this on a per-branch basis. + - When preserve, also pass `--preserve-merges` along to 'git rebase' - so that locally committed merge commits will not be flattened - by running 'git pull'. +When preserve, also pass `--preserve-merges` along to 'git rebase' +so that locally committed merge commits will not be flattened +by running 'git pull'. ++ +When the value is `interactive`, the rebase is run in interactive mode. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] @@ -2117,6 +2345,28 @@ push.followTags:: may override this configuration at time of push by specifying '--no-follow-tags'. +push.gpgSign:: + May be set to a boolean value, or the string 'if-asked'. A true + value causes all pushes to be GPG signed, as if '--signed' is + passed to linkgit:git-push[1]. The string 'if-asked' causes + pushes to be signed if the server supports it, as if + '--signed=if-asked' is passed to 'git push'. A false value may + override a value from a lower-priority config file. An explicit + command-line flag always overrides this config option. + +push.recurseSubmodules:: + Make sure all submodule commits used by the revisions to be pushed + are available on a remote-tracking branch. If the value is 'check' + then Git will verify that all submodule commits that changed in the + revisions to be pushed are available on at least one remote of the + submodule. If any commits are missing, the push will be aborted and + exit with non-zero status. If the value is 'on-demand' then all + submodules that changed in the revisions to be pushed will be + pushed. If on-demand was not able to push all necessary revisions + it will also be aborted and exit with non-zero status. If the value + is 'no' then default behavior of ignoring submodules when pushing + is retained. You may override this configuration at time of push by + specifying '--recurse-submodules=check|on-demand|no'. rebase.stat:: Whether to show a diffstat of what changed upstream since the last @@ -2133,6 +2383,22 @@ rebase.autoStash:: successful rebase might result in non-trivial conflicts. Defaults to false. +rebase.missingCommitsCheck:: + If set to "warn", git rebase -i will print a warning if some + commits are removed (e.g. a line was deleted), however the + rebase will still proceed. If set to "error", it will print + the previous warning and stop the rebase, 'git rebase + --edit-todo' can then be used to correct the error. If set to + "ignore", no checking is done. + To drop a commit without warning or error, use the `drop` + command in the todo-list. + Defaults to "ignore". + +rebase.instructionFormat + A format string, as specified in linkgit:git-log[1], to be used for + the instruction list during an interactive rebase. The format will automatically + have the long commit hash prepended to the format. + receive.advertiseAtomic:: By default, git-receive-pack will advertise the atomic push capability to its clients. If you don't want to this capability @@ -2169,6 +2435,28 @@ receive.fsckObjects:: Defaults to false. If not set, the value of `transfer.fsckObjects` is used instead. +receive.fsck.<msg-id>:: + When `receive.fsckObjects` is set to true, errors can be switched + to warnings and vice versa by configuring the `receive.fsck.<msg-id>` + setting where the `<msg-id>` is the fsck message ID and the value + is one of `error`, `warn` or `ignore`. For convenience, fsck prefixes + the error/warning with the message ID, e.g. "missingEmail: invalid + author/committer line - missing email" means that setting + `receive.fsck.missingEmail = ignore` will hide that issue. ++ +This feature is intended to support working with legacy repositories +which would not pass pushing when `receive.fsckObjects = true`, allowing +the host to accept repositories with certain known issues but still catch +other issues. + +receive.fsck.skipList:: + The path to a sorted list of object names (i.e. one SHA-1 per + line) that are known to be broken in a non-fatal way and should + be ignored. This feature is useful when an established project + should be accepted despite early commits containing errors that + can be safely ignored such as invalid committer email addresses. + Note: corrupt objects cannot be skipped with this setting. + receive.unpackLimit:: If the number of objects received in a push is below this limit then the objects will be unpacked into loose object @@ -2214,13 +2502,10 @@ receive.denyNonFastForwards:: set when initializing a shared repository. receive.hideRefs:: - String(s) `receive-pack` uses to decide which refs to omit - from its initial advertisement. Use more than one - definitions to specify multiple prefix strings. A ref that - are under the hierarchies listed on the value of this - variable is excluded, and is hidden when responding to `git - push`, and an attempt to update or delete a hidden ref by - `git push` is rejected. + This variable is the same as `transfer.hideRefs`, but applies + only to `receive-pack` (and so affects pushes, but not fetches). + An attempt to update or delete a hidden ref by `git push` is + rejected. receive.updateServerInfo:: If set to true, git-receive-pack will run git-update-server-info @@ -2247,6 +2532,11 @@ remote.<name>.proxy:: the proxy to use for that remote. Set to the empty string to disable proxying for that remote. +remote.<name>.proxyAuthMethod:: + For remotes that require curl (http, https and ftp), the method to use for + authenticating against the proxy in use (probably set in + `remote.<name>.proxy`). See `http.proxyAuthMethod`. + remote.<name>.fetch:: The default set of "refspec" for linkgit:git-fetch[1]. See linkgit:git-fetch[1]. @@ -2319,8 +2609,9 @@ repack.writeBitmaps:: objects to disk (e.g., when `git repack -a` is run). This index can speed up the "counting objects" phase of subsequent packs created for clones and fetches, at the cost of some disk - space and extra time spent on the initial repack. Defaults to - false. + space and extra time spent on the initial repack. This has + no effect if multiple packfiles are created. + Defaults to false. rerere.autoUpdate:: When set to true, `git-rerere` updates the index with the @@ -2448,6 +2739,16 @@ status.submoduleSummary:: submodule summary' command, which shows a similar output but does not honor these settings. +stash.showPatch:: + If this is set to true, the `git stash show` command without an + option will show the stash in patch form. Defaults to false. + See description of 'show' command in linkgit:git-stash[1]. + +stash.showStat:: + If this is set to true, the `git stash show` command without an + option will show diffstat of the stash. Defaults to true. + See description of 'show' command in linkgit:git-stash[1]. + submodule.<name>.path:: submodule.<name>.url:: The path within this project and URL for a submodule. These @@ -2490,6 +2791,17 @@ submodule.<name>.ignore:: "--ignore-submodules" option. The 'git submodule' commands are not affected by this setting. +submodule.fetchJobs:: + Specifies how many submodules are fetched/cloned at the same time. + A positive integer allows up to that number of submodules fetched + in parallel. A value of 0 will give some reasonable default. + If unset, it defaults to 1. + +tag.forceSignAnnotated:: + A boolean to specify whether annotated tags created should be GPG signed. + If `--annotate` is specified on the command line, it takes + precedence over this option. + tag.sort:: This variable controls the sort ordering of tags when displayed by linkgit:git-tag[1]. Without the "--sort=<value>" option provided, the @@ -2508,9 +2820,27 @@ transfer.fsckObjects:: Defaults to false. transfer.hideRefs:: - This variable can be used to set both `receive.hideRefs` - and `uploadpack.hideRefs` at the same time to the same - values. See entries for these other variables. + String(s) `receive-pack` and `upload-pack` use to decide which + refs to omit from their initial advertisements. Use more than + one definition to specify multiple prefix strings. A ref that is + under the hierarchies listed in the value of this variable is + excluded, and is hidden when responding to `git push` or `git + fetch`. See `receive.hideRefs` and `uploadpack.hideRefs` for + program-specific versions of this config. ++ +You may also include a `!` in front of the ref name to negate the entry, +explicitly exposing it, even if an earlier entry marked it as hidden. +If you have multiple hideRefs values, later entries override earlier ones +(and entries in more-specific config files override less-specific ones). ++ +If a namespace is in use, the namespace prefix is stripped from each +reference before it is matched against `transfer.hiderefs` patterns. +For example, if `refs/heads/master` is specified in `transfer.hideRefs` and +the current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master` +is omitted from the advertisements but `refs/heads/master` and +`refs/namespaces/bar/refs/heads/master` are still advertised as so-called +"have" lines. In order to match refs before stripping, add a `^` in front of +the ref name. If you combine `!` and `^`, `!` must be specified first. transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are @@ -2525,20 +2855,23 @@ uploadarchive.allowUnreachable:: `false`. uploadpack.hideRefs:: - String(s) `upload-pack` uses to decide which refs to omit - from its initial advertisement. Use more than one - definitions to specify multiple prefix strings. A ref that - are under the hierarchies listed on the value of this - variable is excluded, and is hidden from `git ls-remote`, - `git fetch`, etc. An attempt to fetch a hidden ref by `git - fetch` will fail. See also `uploadpack.allowtipsha1inwant`. - -uploadpack.allowtipsha1inwant:: + This variable is the same as `transfer.hideRefs`, but applies + only to `upload-pack` (and so affects only fetches, not pushes). + An attempt to fetch a hidden ref by `git fetch` will fail. See + also `uploadpack.allowTipSHA1InWant`. + +uploadpack.allowTipSHA1InWant:: When `uploadpack.hideRefs` is in effect, allow `upload-pack` to accept a fetch request that asks for an object at the tip of a hidden ref (by default, such a request is rejected). see also `uploadpack.hideRefs`. +uploadpack.allowReachableSHA1InWant:: + Allow `upload-pack` to accept a fetch request that asks for an + object that is reachable from any ref tip. However, note that + calculating object reachability is computationally expensive. + Defaults to `false`. + uploadpack.keepAlive:: When `upload-pack` has started `pack-objects`, there may be a quiet period while `pack-objects` prepares the pack. Normally @@ -2584,6 +2917,16 @@ user.name:: Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME' environment variables. See linkgit:git-commit-tree[1]. +user.useConfigOnly:: + Instruct Git to avoid trying to guess defaults for 'user.email' + and 'user.name', and instead retrieve the values only from the + configuration. For example, if you have multiple email addresses + and would like to use a different one for each repository, then + with this configuration option set to `true` in the global config + along with a name, Git will prompt you to set up an email before + making new commits in a newly cloned repository. + Defaults to `false`. + user.signingKey:: If linkgit:git-tag[1] or linkgit:git-commit[1] is not selecting the key you want it to automatically when creating a signed tag or diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 6eaa45271c..d78cfc5a37 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -108,9 +108,13 @@ diff.renameLimit:: detection; equivalent to the 'git diff' option '-l'. diff.renames:: - Tells Git to detect renames. If set to any boolean value, it - will enable basic rename detection. If set to "copies" or - "copy", it will detect copies, as well. + Whether and how Git detects renames. If set to "false", + rename detection is disabled. If set to "true", basic rename + detection is enabled. If set to "copies" or "copy", Git will + detect copies, as well. Defaults to true. Note that this + affects only 'git diff' Porcelain like linkgit:git-diff[1] and + linkgit:git-log[1], and not lower level commands such as + linkgit:git-diff-files[1]. diff.suppressBlankEmpty:: A boolean to inhibit the standard behavior of printing a space @@ -166,6 +170,11 @@ diff.tool:: include::mergetools-diff.txt[] +diff.compactionHeuristic:: + Set this option to `true` to enable an experimental heuristic that + shifts the hunk boundary in an attempt to make the resulting + patch easier to read. + diff.algorithm:: Choose a diff algorithm. The variants are as follows: + diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 3ad6404dbc..d9ae681d8f 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -26,12 +26,12 @@ ifndef::git-format-patch[] ifdef::git-diff[] This is the default. endif::git-diff[] -endif::git-format-patch[] -s:: --no-patch:: Suppress diff output. Useful for commands like `git show` that show the patch by default, or to cancel the effect of `--patch`. +endif::git-format-patch[] -U<n>:: --unified=<n>:: @@ -63,6 +63,13 @@ ifndef::git-format-patch[] Synonym for `-p --raw`. endif::git-format-patch[] +--compaction-heuristic:: +--no-compaction-heuristic:: + These are to help debugging and tuning an experimental + heuristic (which is off by default) that shifts the hunk + boundary in an attempt to make the resulting patch easier + to read. + --minimal:: Spend extra time to make sure the smallest possible diff is produced. @@ -267,8 +274,11 @@ expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline. + +For example, `--word-diff-regex=.` will treat each character as a word +and, correspondingly, show differences character by character. ++ The regex can also be set via a diff driver or configuration option, see -linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly +linkgit:gitattributes[5] or linkgit:git-config[1]. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings. @@ -283,14 +293,24 @@ endif::git-format-patch[] ifndef::git-format-patch[] --check:: - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by `core.whitespace` + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by `core.whitespace` configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the initial indent of the line are considered whitespace errors. Exits with non-zero status if problems are found. Not compatible with --exit-code. + +--ws-error-highlight=<kind>:: + Highlight whitespace errors on lines specified by <kind> + in the color specified by `color.diff.whitespace`. <kind> + is a comma separated list of `old`, `new`, `context`. When + this option is not given, only whitespace errors in `new` + lines are highlighted. E.g. `--ws-error-highlight=new,old` + highlights whitespace errors on both deleted and added lines. + `all` can be used as a short-hand for `old,new,context`. + endif::git-format-patch[] --full-index:: diff --git a/Documentation/everyday.txto b/Documentation/everyday.txto index c5047d8f9b..ae555bd47e 100644 --- a/Documentation/everyday.txto +++ b/Documentation/everyday.txto @@ -1,7 +1,7 @@ Everyday Git With 20 Commands Or So =================================== -This document has been moved to linkgit:giteveryday[1]. +This document has been moved to linkgit:giteveryday[7]. Please let the owners of the referring site know so that they can update the link you clicked to get here. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 45583d8454..036edfb099 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -8,10 +8,11 @@ option old data in `.git/FETCH_HEAD` will be overwritten. --depth=<depth>:: - Deepen or shorten the history of a 'shallow' repository created by - `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) - to the specified number of commits from the tip of each remote - branch history. Tags for the deepened commits are not fetched. + Limit fetching to the specified number of commits from the tip of + each remote branch history. If fetching to a 'shallow' repository + created by `git clone` with `--depth=<depth>` option (see + linkgit:git-clone[1]), deepen or shorten the history to the specified + number of commits. Tags for the deepened commits are not fetched. --unshallow:: If the source repository is complete, convert a shallow @@ -100,6 +101,13 @@ ifndef::git-pull[] reference to a commit that isn't already in the local submodule clone. +-j:: +--jobs=<n>:: + Number of parallel children to be used for fetching submodules. + Each will fetch from different submodules, such that fetching many + submodules will be faster. By default submodules will be fetched + one at a time. + --no-recurse-submodules:: Disable recursive fetching of submodules (this has the same effect as using the '--recurse-submodules=no' option). @@ -150,3 +158,11 @@ endif::git-pull[] by default when it is attached to a terminal, unless -q is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. + +-4:: +--ipv4:: + Use IPv4 addresses only, ignoring IPv6 addresses. + +-6:: +--ipv6:: + Use IPv6 addresses only, ignoring IPv4 addresses. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index fe5282f130..6a96a669c2 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -24,7 +24,7 @@ remove paths that do not exist in the working tree anymore. The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus -after making any changes to the working directory, and before running +after making any changes to the working tree, and before running the commit command, you must use the `add` command to add any new or modified files to the index. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 0d8ba48f79..13cdd7f3b6 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] - [--3way] [--interactive] [--committer-date-is-author-date] + [--[no-]3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] @@ -35,6 +35,7 @@ OPTIONS --signoff:: Add a `Signed-off-by:` line to the commit message, using the committer identity of yourself. + See the signoff option in linkgit:git-commit[1] for more information. -k:: --keep:: @@ -90,10 +91,13 @@ default. You can use `--no-utf8` to override this. -3:: --3way:: +--no-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. + available locally. `--no-3way` can be used to override + am.threeWay configuration variable. For more information, + see am.threeWay in linkgit:git-config[1]. --ignore-space-change:: --ignore-whitespace:: @@ -138,7 +142,9 @@ default. You can use `--no-utf8` to override this. -S[<keyid>]:: --gpg-sign[=<keyid>]:: - GPG-sign commits. + GPG-sign commits. The `keyid` argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. --continue:: -r:: diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index d9ed6a1a4e..8ddb207409 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -13,7 +13,7 @@ SYNOPSIS [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached] - [--ignore-space-change | --ignore-whitespace ] + [--ignore-space-change | --ignore-whitespace] [--whitespace=(nowarn|warn|fix|error|error-all)] [--exclude=<path>] [--include=<path>] [--directory=<root>] [--verbose] [--unsafe-paths] [<patch>...] @@ -21,6 +21,8 @@ SYNOPSIS DESCRIPTION ----------- Reads the supplied diff output (i.e. "a patch") and applies it to files. +When running from a subdirectory in a repository, patched paths +outside the directory are ignored. With the `--index` option the patch is also applied to the index, and with the `--cached` option the patch is only applied to the index. Without these options, the command applies the patch only to files, diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 0f0c6ff082..c06efbd42a 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -1321,7 +1321,7 @@ So git bisect is unconditional goodness - and feel free to quote that _____________ Acknowledgments ----------------- +--------------- Many thanks to Junio Hamano for his help in reviewing this paper, for reviewing the patches I sent to the Git mailing list, for discussing diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 4cb52a7302..7e79aaedeb 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -3,7 +3,7 @@ git-bisect(1) NAME ---- -git-bisect - Find by binary search the change that introduced a bug +git-bisect - Use binary search to find the commit that introduced a bug SYNOPSIS @@ -16,74 +16,89 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: - git bisect help - git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] - git bisect bad [<rev>] - git bisect good [<rev>...] + git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>] + [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] + git bisect (bad|new) [<rev>] + git bisect (good|old) [<rev>...] + git bisect terms [--term-good | --term-bad] git bisect skip [(<rev>|<range>)...] git bisect reset [<commit>] git bisect visualize git bisect replay <logfile> git bisect log git bisect run <cmd>... + git bisect help -This command uses 'git rev-list --bisect' to help drive the -binary search process to find which change introduced a bug, given an -old "good" commit object name and a later "bad" commit object name. - -Getting help -~~~~~~~~~~~~ - -Use "git bisect" to get a short usage description, and "git bisect -help" or "git bisect -h" to get a long usage description. +This command uses a binary search algorithm to find which commit in +your project's history introduced a bug. You use it by first telling +it a "bad" commit that is known to contain the bug, and a "good" +commit that is known to be before the bug was introduced. Then `git +bisect` picks a commit between those two endpoints and asks you +whether the selected commit is "good" or "bad". It continues narrowing +down the range until it finds the exact commit that introduced the +change. + +In fact, `git bisect` can be used to find the commit that changed +*any* property of your project; e.g., the commit that fixed a bug, or +the commit that caused a benchmark's performance to improve. To +support this more general usage, the terms "old" and "new" can be used +in place of "good" and "bad", or you can choose your own terms. See +section "Alternate terms" below for more information. Basic bisect commands: start, bad, good ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Using the Linux kernel tree as an example, basic use of the bisect -command is as follows: +As an example, suppose you are trying to find the commit that broke a +feature that was known to work in version `v2.6.13-rc2` of your +project. You start a bisect session as follows: ------------------------------------------------ $ git bisect start $ git bisect bad # Current version is bad -$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version - # tested that was good +$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 is known to be good +------------------------------------------------ + +Once you have specified at least one bad and one good commit, `git +bisect` selects a commit in the middle of that range of history, +checks it out, and outputs something similar to the following: + +------------------------------------------------ +Bisecting: 675 revisions left to test after this (roughly 10 steps) ------------------------------------------------ -When you have specified at least one bad and one good version, the -command bisects the revision tree and outputs something similar to -the following: +You should now compile the checked-out version and test it. If that +version works correctly, type ------------------------------------------------ -Bisecting: 675 revisions left to test after this +$ git bisect good ------------------------------------------------ -The state in the middle of the set of revisions is then checked out. -You would now compile that kernel and boot it. If the booted kernel -works correctly, you would then issue the following command: +If that version is broken, type ------------------------------------------------ -$ git bisect good # this one is good +$ git bisect bad ------------------------------------------------ -The output of this command would be something similar to the following: +Then `git bisect` will respond with something like ------------------------------------------------ -Bisecting: 337 revisions left to test after this +Bisecting: 337 revisions left to test after this (roughly 9 steps) ------------------------------------------------ -You keep repeating this process, compiling the tree, testing it, and -depending on whether it is good or bad issuing the command "git bisect good" -or "git bisect bad" to ask for the next bisection. +Keep repeating the process: compile the tree, test it, and depending +on whether it is good or bad run `git bisect good` or `git bisect bad` +to ask for the next commit that needs testing. + +Eventually there will be no more revisions left to inspect, and the +command will print out a description of the first bad commit. The +reference `refs/bisect/bad` will be left pointing at that commit. -Eventually there will be no more revisions left to bisect, and you -will have been left with the first bad kernel revision in "refs/bisect/bad". Bisect reset ~~~~~~~~~~~~ After a bisect session, to clean up the bisection state and return to -the original HEAD (i.e., to quit bisecting), issue the following command: +the original HEAD, issue the following command: ------------------------------------------------ $ git bisect reset @@ -100,9 +115,83 @@ instead: $ git bisect reset <commit> ------------------------------------------------ -For example, `git bisect reset HEAD` will leave you on the current -bisection commit and avoid switching commits at all, while `git bisect -reset bisect/bad` will check out the first bad revision. +For example, `git bisect reset bisect/bad` will check out the first +bad revision, while `git bisect reset HEAD` will leave you on the +current bisection commit and avoid switching commits at all. + + +Alternate terms +~~~~~~~~~~~~~~~ + +Sometimes you are not looking for the commit that introduced a +breakage, but rather for a commit that caused a change between some +other "old" state and "new" state. For example, you might be looking +for the commit that introduced a particular fix. Or you might be +looking for the first commit in which the source-code filenames were +finally all converted to your company's naming standard. Or whatever. + +In such cases it can be very confusing to use the terms "good" and +"bad" to refer to "the state before the change" and "the state after +the change". So instead, you can use the terms "old" and "new", +respectively, in place of "good" and "bad". (But note that you cannot +mix "good" and "bad" with "old" and "new" in a single session.) + +In this more general usage, you provide `git bisect` with a "new" +commit has some property and an "old" commit that doesn't have that +property. Each time `git bisect` checks out a commit, you test if that +commit has the property. If it does, mark the commit as "new"; +otherwise, mark it as "old". When the bisection is done, `git bisect` +will report which commit introduced the property. + +To use "old" and "new" instead of "good" and bad, you must run `git +bisect start` without commits as argument and then run the following +commands to add the commits: + +------------------------------------------------ +git bisect old [<rev>] +------------------------------------------------ + +to indicate that a commit was before the sought change, or + +------------------------------------------------ +git bisect new [<rev>...] +------------------------------------------------ + +to indicate that it was after. + +To get a reminder of the currently used terms, use + +------------------------------------------------ +git bisect terms +------------------------------------------------ + +You can get just the old (respectively new) term with `git bisect term +--term-old` or `git bisect term --term-good`. + +If you would like to use your own terms instead of "bad"/"good" or +"new"/"old", you can choose any names you like (except existing bisect +subcommands like `reset`, `start`, ...) by starting the +bisection using + +------------------------------------------------ +git bisect start --term-old <term-old> --term-new <term-new> +------------------------------------------------ + +For example, if you are looking for a commit that introduced a +performance regression, you might use + +------------------------------------------------ +git bisect start --term-old fast --term-new slow +------------------------------------------------ + +Or if you are looking for the commit that fixed a bug, you might use + +------------------------------------------------ +git bisect start --term-new fixed --term-old broken +------------------------------------------------ + +Then, use `git bisect <term-old>` and `git bisect <term-new>` instead +of `git bisect good` and `git bisect bad` to mark commits. Bisect visualize ~~~~~~~~~~~~~~~~ @@ -147,17 +236,17 @@ $ git bisect replay that-file Avoiding testing a commit ~~~~~~~~~~~~~~~~~~~~~~~~~ -If, in the middle of a bisect session, you know that the next suggested -revision is not a good one to test (e.g. the change the commit -introduces is known not to work in your environment and you know it -does not have anything to do with the bug you are chasing), you may -want to find a nearby commit and try that instead. +If, in the middle of a bisect session, you know that the suggested +revision is not a good one to test (e.g. it fails to build and you +know that the failure does not have anything to do with the bug you +are chasing), you can manually select a nearby commit and test that +one instead. For example: ------------ $ git bisect good/bad # previous round was good or bad. -Bisecting: 337 revisions left to test after this +Bisecting: 337 revisions left to test after this (roughly 9 steps) $ git bisect visualize # oops, that is uninteresting. $ git reset --hard HEAD~3 # try 3 revisions before what # was suggested @@ -167,20 +256,21 @@ Then compile and test the chosen revision, and afterwards mark the revision as good or bad in the usual manner. Bisect skip -~~~~~~~~~~~~ +~~~~~~~~~~~ -Instead of choosing by yourself a nearby commit, you can ask Git -to do it for you by issuing the command: +Instead of choosing a nearby commit by yourself, you can ask Git to do +it for you by issuing the command: ------------ $ git bisect skip # Current version cannot be tested ------------ -But Git may eventually be unable to tell the first bad commit among -a bad commit and one or more skipped commits. +However, if you skip a commit adjacent to the one you are looking for, +Git will be unable to tell exactly which of those commits was the +first bad one. -You can even skip a range of commits, instead of just one commit, -using the "'<commit1>'..'<commit2>'" notation. For example: +You can also skip a range of commits, instead of just one commit, +using range notation. For example: ------------ $ git bisect skip v2.5..v2.6 @@ -196,8 +286,8 @@ would issue the command: $ git bisect skip v2.5 v2.5..v2.6 ------------ -This tells the bisect process that the commits between `v2.5` included -and `v2.6` included should be skipped. +This tells the bisect process that the commits between `v2.5` and +`v2.6` (inclusive) should be skipped. Cutting down bisection by giving more parameters to bisect start @@ -231,23 +321,23 @@ or bad, you can bisect by issuing the command: $ git bisect run my_script arguments ------------ -Note that the script (`my_script` in the above example) should -exit with code 0 if the current source code is good, and exit with a -code between 1 and 127 (inclusive), except 125, if the current -source code is bad. +Note that the script (`my_script` in the above example) should exit +with code 0 if the current source code is good/old, and exit with a +code between 1 and 127 (inclusive), except 125, if the current source +code is bad/new. Any other exit code will abort the bisect process. It should be noted -that a program that terminates via "exit(-1)" leaves $? = 255, (see the -exit(3) manual page), as the value is chopped with "& 0377". +that a program that terminates via `exit(-1)` leaves $? = 255, (see the +exit(3) manual page), as the value is chopped with `& 0377`. The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current revision will be skipped (see `git bisect skip` above). 125 was chosen as the highest sensible value to use for this purpose, because 126 and 127 are used by POSIX shells to signal specific error status (127 is for -command not found, 126 is for command found but not executable---these +command not found, 126 is for command found but not executable--these details do not matter, as they are normal errors in the script, as far as -"bisect run" is concerned). +`bisect run` is concerned). You may often find that during a bisect session you want to have temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a @@ -260,7 +350,7 @@ next revision to test, the script can apply the patch before compiling, run the real test, and afterwards decide if the revision (possibly with the needed patch) passed the test and then rewind the tree to the pristine state. Finally the script should exit -with the status of the real test to let the "git bisect run" command loop +with the status of the real test to let the `git bisect run` command loop determine the eventual outcome of the bisect session. OPTIONS @@ -307,12 +397,12 @@ $ git bisect run ~/test.sh $ git bisect reset # quit the bisect session ------------ + -Here we use a "test.sh" custom script. In this script, if "make" +Here we use a `test.sh` custom script. In this script, if `make` fails, we skip the current commit. -"check_test_case.sh" should "exit 0" if the test case passes, -and "exit 1" otherwise. +`check_test_case.sh` should `exit 0` if the test case passes, +and `exit 1` otherwise. + -It is safer if both "test.sh" and "check_test_case.sh" are +It is safer if both `test.sh` and `check_test_case.sh` are outside the repository to prevent interactions between the bisect, make and test processes and the scripts. @@ -379,6 +469,26 @@ In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit has at least one parent whose reachable graph is fully traversable in the sense required by 'git pack objects'. +* Look for a fix instead of a regression in the code ++ +------------ +$ git bisect start +$ git bisect new HEAD # current commit is marked as new +$ git bisect old HEAD~10 # the tenth commit from now is marked as old +------------ ++ +or: +------------ +$ git bisect start --term-old broken --term-new fixed +$ git bisect fixed +$ git bisect broken HEAD~10 +------------ + +Getting help +~~~~~~~~~~~~ + +Use `git bisect` to get a short usage description, and `git bisect +help` or `git bisect -h` to get a long usage description. SEE ALSO -------- diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 9f23a861ce..ba5417567c 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -10,7 +10,8 @@ SYNOPSIS [verse] 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] - [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file> + [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] + [--] <file> DESCRIPTION ----------- @@ -76,6 +77,8 @@ include::blame-options.txt[] -e:: --show-email:: Show the author email instead of author name (Default: off). + This can also be controlled via the `blame.showEmail` config + option. -w:: Ignore whitespace when comparing the parent's version and diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index a67138a022..4a7037f1c8 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -11,7 +11,8 @@ SYNOPSIS 'git branch' [--color[=<when>] | --no-color] [-r | -a] [--list] [-v [--abbrev=<length> | --no-abbrev]] [--column[=<options>] | --no-column] - [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] + [(--merged | --no-merged | --contains) [<commit>]] [--sort=<key>] + [--points-at <object>] [<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>] @@ -197,7 +198,9 @@ start-point is either a local or remote-tracking 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`). + for, to be used by various other commands (e.g. `format-patch`, + `request-pull`, and `merge` (if enabled)). Multi-line explanations + may be used. --contains [<commit>]:: Only list branches which contain the specified commit (HEAD @@ -229,6 +232,19 @@ start-point is either a local or remote-tracking branch. The new name for an existing branch. The same restrictions as for <branchname> apply. +--sort=<key>:: + Sort based on the key given. Prefix `-` to sort in descending + order of the value. You may use the --sort=<key> option + multiple times, in which case the last key becomes the primary + key. The keys supported are the same as those in `git + for-each-ref`. Sort order defaults to sorting based on the + full refname (including `refs/...` prefix). This lists + detached HEAD (if present) first, then local branches and + finally remote-tracking branches. + + +--points-at <object>:: + Only list branches of the given object. Examples -------- diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 0417562eb7..3a8120c3b3 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -20,7 +20,7 @@ DESCRIPTION Some workflows require that one or more branches of development on one machine be replicated on another machine, but the two machines cannot be directly connected, and therefore the interactive Git protocols (git, -ssh, rsync, http) cannot be used. This command provides support for +ssh, http) cannot be used. This command provides support for 'git fetch' and 'git pull' to operate by packaging objects and references in an archive at the originating machine, then importing those into another repository using 'git fetch' and 'git pull' diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index f6a16f4300..eb3d6945a9 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -9,8 +9,8 @@ git-cat-file - Provide content or type and size information for repository objec SYNOPSIS -------- [verse] -'git cat-file' (-t | -s | -e | -p | <type> | --textconv ) <object> -'git cat-file' (--batch | --batch-check) < <list-of-objects> +'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv ) <object> +'git cat-file' (--batch | --batch-check) [--follow-symlinks] DESCRIPTION ----------- @@ -69,6 +69,79 @@ OPTIONS not be combined with any other options or arguments. See the section `BATCH OUTPUT` below for details. +--batch-all-objects:: + Instead of reading a list of objects on stdin, perform the + requested batch operation on all objects in the repository and + any alternate object stores (not just reachable objects). + Requires `--batch` or `--batch-check` be specified. Note that + the objects are visited in order sorted by their hashes. + +--buffer:: + Normally batch output is flushed after each object is output, so + that a process can interactively read and write from + `cat-file`. With this option, the output uses normal stdio + buffering; this is much more efficient when invoking + `--batch-check` on a large number of objects. + +--allow-unknown-type:: + Allow -s or -t to query broken/corrupt objects of unknown type. + +--follow-symlinks:: + With --batch or --batch-check, follow symlinks inside the + repository when requesting objects with extended SHA-1 + expressions of the form tree-ish:path-in-tree. Instead of + providing output about the link itself, provide output about + the linked-to object. If a symlink points outside the + tree-ish (e.g. a link to /foo or a root-level link to ../foo), + the portion of the link which is outside the tree will be + printed. ++ +This option does not (currently) work correctly when an object in the +index is specified (e.g. `:link` instead of `HEAD:link`) rather than +one in the tree. ++ +This option cannot (currently) be used unless `--batch` or +`--batch-check` is used. ++ +For example, consider a git repository containing: ++ +-- + f: a file containing "hello\n" + link: a symlink to f + dir/link: a symlink to ../f + plink: a symlink to ../f + alink: a symlink to /etc/passwd +-- ++ +For a regular file `f`, `echo HEAD:f | git cat-file --batch` would print ++ +-- + ce013625030ba8dba906f756967f9e9ca394464a blob 6 +-- ++ +And `echo HEAD:link | git cat-file --batch --follow-symlinks` would +print the same thing, as would `HEAD:dir/link`, as they both point at +`HEAD:f`. ++ +Without `--follow-symlinks`, these would print data about the symlink +itself. In the case of `HEAD:link`, you would see ++ +-- + 4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1 +-- ++ +Both `plink` and `alink` point outside the tree, so they would +respectively print: ++ +-- + symlink 4 + ../f + + symlink 11 + /etc/passwd +-- + + OUTPUT ------ If '-t' is specified, one of the <type>. @@ -148,6 +221,47 @@ the repository, then `cat-file` will ignore any custom format and print: <object> SP missing LF ------------ +If --follow-symlinks is used, and a symlink in the repository points +outside the repository, then `cat-file` will ignore any custom format +and print: + +------------ +symlink SP <size> LF +<symlink> LF +------------ + +The symlink will either be absolute (beginning with a /), or relative +to the tree root. For instance, if dir/link points to ../../foo, then +<symlink> will be ../foo. <size> is the size of the symlink in bytes. + +If --follow-symlinks is used, the following error messages will be +displayed: + +------------ +<object> SP missing LF +------------ +is printed when the initial symlink requested does not exist. + +------------ +dangling SP <size> LF +<object> LF +------------ +is printed when the initial symlink exists, but something that +it (transitive-of) points to does not. + +------------ +loop SP <size> LF +<object> LF +------------ +is printed for symlink loops (or any symlinks that +require more than 40 link resolutions to resolve). + +------------ +notdir SP <size> LF +<object> LF +------------ +is printed when, during symlink resolution, a file is used as a +directory name. CAVEATS ------- diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 00e2aa2df2..aa3b2bf2fc 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git check-attr' [-a | --all | attr...] [--] pathname... -'git check-attr' --stdin [-z] [-a | --all | attr...] < <list-of-paths> +'git check-attr' --stdin [-z] [-a | --all | attr...] DESCRIPTION ----------- @@ -28,7 +28,8 @@ OPTIONS Consider `.gitattributes` in the index only, ignoring the working tree. --stdin:: - Read file names from stdin instead of from the command-line. + Read pathnames from the standard input, one per line, + instead of from the command-line. -z:: The output format is modified to be machine-parseable. diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index e35cd0489b..611754f10b 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -10,16 +10,15 @@ SYNOPSIS -------- [verse] 'git check-ignore' [options] pathname... -'git check-ignore' [options] --stdin < <list-of-paths> +'git check-ignore' [options] --stdin DESCRIPTION ----------- For each pathname given via the command-line or from a file via -`--stdin`, show the pattern from .gitignore (or other input files to -the exclude mechanism) that decides if the pathname is excluded or -included. Later patterns within a file take precedence over earlier -ones. +`--stdin`, check whether the file is excluded by .gitignore (or other +input files to the exclude mechanism) and output the path if it is +excluded. By default, tracked files are not shown at all since they are not subject to exclude rules; but see `--no-index'. @@ -32,10 +31,12 @@ OPTIONS -v, --verbose:: Also output details about the matching pattern (if any) - for each given pathname. + for each given pathname. For precedence rules within and + between exclude sources, see linkgit:gitignore[5]. --stdin:: - Read file names from stdin instead of from the command-line. + Read pathnames from the standard input, one per line, + instead of from the command-line. -z:: The output format is modified to be machine-parseable (see @@ -111,7 +112,7 @@ EXIT STATUS SEE ALSO -------- linkgit:gitignore[5] -linkgit:gitconfig[5] +linkgit:git-config[1] linkgit:git-ls-files[1] GIT diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index fc02959ba4..91a3622ee4 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -60,7 +60,7 @@ Git imposes the following rules on how references are named: These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used -unquoted (by mistake), and also avoids ambiguities in certain +unquoted (by mistake), and also avoid ambiguities in certain reference name expressions (see linkgit:gitrevisions[7]): . A double-dot `..` is often used as in `ref1..ref2`, and in some @@ -94,8 +94,8 @@ OPTIONS Interpret <refname> as a reference name pattern for a refspec (as used with remote repositories). If this option is enabled, <refname> is allowed to contain a single `*` - in place of a one full pathname component (e.g., - `foo/*/bar` but not `foo/bar*`). + in the refspec (e.g., `foo/bar*/baz` or `foo/bar*baz/` + but not `foo/bar*/baz*`). --normalize:: Normalize 'refname' by removing any leading slash (`/`) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 7540e026f5..5e5273e073 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -107,6 +107,12 @@ OPTIONS --quiet:: Quiet, suppress feedback messages. +--[no-]progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless `--quiet` + is specified. This flag enables progress reporting even if not + attached to a terminal, regardless of `--quiet`. + -f:: --force:: When switching branches, proceed even if the index or the @@ -120,6 +126,21 @@ entries; instead, unmerged entries are ignored. --theirs:: When checking out paths from the index, check out stage #2 ('ours') or #3 ('theirs') for unmerged paths. ++ +Note that during `git rebase` and `git pull --rebase`, 'ours' and +'theirs' may appear swapped; `--ours` gives the version from the +branch the changes are rebased onto, while `--theirs` gives the +version from the branch that holds your work that is being rebased. ++ +This is because `rebase` is used in a workflow that treats the +history at the remote as the shared canonical one, and treats the +work done on the branch you are rebasing as the third-party work to +be integrated, and you are temporarily assuming the role of the +keeper of the canonical history during the rebase. As the keeper of +the canonical history, you need to view the history from the remote +as `ours` (i.e. "our shared canonical history"), while what you did +on your side branch as `theirs` (i.e. "one contributor's work on top +of it"). -b <new_branch>:: Create a new branch named <new_branch> and start it at @@ -229,6 +250,12 @@ 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. +--ignore-other-worktrees:: + `git checkout` refuses when the wanted ref is already checked + out by another worktree. This option makes it check the ref + out anyway. In other words, the ref can be held by more than one + worktree. + <branch>:: Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 1147c71da6..c104a594af 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] - [-S[<key-id>]] <commit>... + [-S[<keyid>]] <commit>... 'git cherry-pick' --continue 'git cherry-pick' --quit 'git cherry-pick' --abort @@ -100,10 +100,13 @@ effect to your index in a row. -s:: --signoff:: Add Signed-off-by line at the end of the commit message. + See the signoff option in linkgit:git-commit[1] for more information. --S[<key-id>]:: ---gpg-sign[=<key-id>]:: - GPG-sign commits. +-S[<keyid>]:: +--gpg-sign[=<keyid>]:: + GPG-sign commits. The `keyid` argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. --ff:: If the current HEAD is the same as the parent of the @@ -125,7 +128,7 @@ effect to your index in a row. --allow-empty-message:: By default, cherry-picking a commit with an empty message will fail. - This option overrides that behaviour, allowing commits with empty + This option overrides that behavior, allowing commits with empty messages to be cherry picked. --keep-redundant-commits:: diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 641681f61a..51a7e26a8e 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -37,9 +37,7 @@ OPTIONS to false, 'git clean' will refuse to delete files or directories unless given -f, -n or -i. Git will refuse to delete directories with .git sub directory or file unless a second -f - is given. This affects also git submodules where the storage area - of the removed submodule under .git/modules/ is not removed until - -f is given twice. + is given. -i:: --interactive:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index f1f2a3f7ea..1b15cd7b16 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -14,8 +14,8 @@ SYNOPSIS [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--dissociate] [--separate-git-dir <git dir>] [--depth <depth>] [--[no-]single-branch] - [--recursive | --recurse-submodules] [--] <repository> - [<directory>] + [--recursive | --recurse-submodules] [--[no-]shallow-submodules] + [--jobs <n>] [--] <repository> [<directory>] DESCRIPTION ----------- @@ -104,14 +104,18 @@ objects from the source repository into a pack in the cloned repository. --dissociate:: Borrow the objects from reference repositories specified with the `--reference` options only to reduce network - transfer and stop borrowing from them after a clone is made - by making necessary local copies of borrowed objects. + transfer, and stop borrowing from them after a clone is made + by making necessary local copies of borrowed objects. This + option can also be used when cloning locally from a + repository that already borrows objects from another + repository--the new repository will borrow objects from the + same repository, and this option can be used to stop the + borrowing. --quiet:: -q:: Operate quietly. Progress is not reported to the standard - error stream. This flag is also passed to the `rsync' - command when given. + error stream. --verbose:: -v:: @@ -185,15 +189,16 @@ objects from the source repository into a pack in the cloned repository. --depth <depth>:: Create a 'shallow' clone with a history truncated to the - specified number of revisions. + specified number of commits. Implies `--single-branch` unless + `--no-single-branch` is given to fetch the histories near the + tips of all branches. This implies `--shallow-submodules`. If + you want to have a shallow superproject clone, but full submodules, + also pass `--no-shallow-submodules`. --[no-]single-branch:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary - branch remote's `HEAD` points at. When creating a shallow - clone with the `--depth` option, this is the default, unless - `--no-single-branch` is given to fetch the histories near the - tips of all branches. + branch remote's `HEAD` points at. 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 @@ -209,6 +214,9 @@ objects from the source repository into a pack in the cloned repository. repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) +--[no-]shallow-submodules:: + All submodules which are cloned will be shallow with a depth of 1. + --separate-git-dir=<git dir>:: Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, @@ -216,6 +224,10 @@ objects from the source repository into a pack in the cloned repository. The result is Git repository can be separated from working tree. +-j <n>:: +--jobs <n>:: + The number of submodules fetched at the same time. + Defaults to the `submodule.fetchJobs` option. <repository>:: The (possibly remote) repository to clone from. See the diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index f5f2a8d326..cb69faab68 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -9,7 +9,7 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- [verse] -'git commit-tree' <tree> [(-p <parent>)...] < changelog +'git commit-tree' <tree> [(-p <parent>)...] 'git commit-tree' [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] [(-F <file>)...] <tree> @@ -56,11 +56,13 @@ OPTIONS -S[<keyid>]:: --gpg-sign[=<keyid>]:: - GPG-sign commit. + GPG-sign commits. The `keyid` argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. --no-gpg-sign:: - Countermand `commit.gpgSign` configuration variable that is - set to force each and every commit to be signed. + Do not GPG-sign commit, to countermand a `--gpg-sign` option + given earlier on the command line. Commit Information diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 904dafa0f7..d474226eb7 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>] [--[no-]status] - [-i | -o] [-S[<key-id>]] [--] [<file>...] + [-i | -o] [-S[<keyid>]] [--] [<file>...] DESCRIPTION ----------- @@ -154,7 +154,11 @@ OPTIONS -s:: --signoff:: Add Signed-off-by line by the committer at the end of the commit - log message. + log message. The meaning of a signoff depends on the project, + but it typically certifies that committer has + the rights to submit this work under the same license and + agrees to a Developer Certificate of Origin + (see http://developercertificate.org/ for more information). -n:: --no-verify:: @@ -286,7 +290,8 @@ configuration variable documented in linkgit:git-config[1]. what changes the commit has. Note that this diff output doesn't have its lines prefixed with '#'. This diff will not be a part - of the commit message. + of the commit message. See the `commit.verbose` configuration + variable in linkgit:git-config[1]. + If specified twice, show in addition the unified diff between what would be committed and the worktree files, i.e. the unstaged @@ -314,7 +319,9 @@ changes to tracked files. -S[<keyid>]:: --gpg-sign[=<keyid>]:: - GPG-sign commit. + GPG-sign commits. The `keyid` argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. --no-gpg-sign:: Countermand `commit.gpgSign` configuration variable that is diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 02ec096faa..6843114fc0 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,18 +9,18 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [type] [-z|--null] name [value [value_regex]] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] name [value [value_regex]] 'git config' [<file-option>] [type] --add name value 'git config' [<file-option>] [type] --replace-all name value [value_regex] -'git config' [<file-option>] [type] [-z|--null] --get name [value_regex] -'git config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] -'git config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] --get name [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] --get-all name [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] 'git config' [<file-option>] [type] [-z|--null] --get-urlmatch name URL 'git config' [<file-option>] --unset name [value_regex] 'git config' [<file-option>] --unset-all name [value_regex] 'git config' [<file-option>] --rename-section old_name new_name 'git config' [<file-option>] --remove-section name -'git config' [<file-option>] [-z|--null] -l | --list +'git config' [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list 'git config' [<file-option>] --get-color name [default] 'git config' [<file-option>] --get-colorbool name [stdout-is-tty] 'git config' [<file-option>] -e | --edit @@ -58,13 +58,13 @@ 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), or -. you try to use an invalid regexp (ret=6). +- The section or key is invalid (ret=1), +- no section or name was provided (ret=2), +- the config file is invalid (ret=3), +- the config file cannot be written (ret=4), +- 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), or +- you try to use an invalid regexp (ret=6). On success, the command returns the exit code 0. @@ -86,8 +86,7 @@ OPTIONS found and the last value if multiple key values were found. --get-all:: - Like get, but does not fail if the number of values for the key - is not exactly one. + Like get, but returns all values for a multi-valued key. --get-regexp:: Like --get-all, but interprets the name as a regular expression and @@ -102,7 +101,7 @@ OPTIONS given URL is returned (if no such key exists, the value for section.key is used as a fallback). When given just the section as name, do so for all the keys in the section and - list them. + list them. Returns error code 1 if no value is found. --global:: For writing options: write to global `~/.gitconfig` file @@ -159,7 +158,7 @@ See also <<FILES>>. -l:: --list:: - List all variables set in config file. + List all variables set in config file, along with their values. --bool:: 'git config' will ensure that the output is "true" or "false" @@ -190,6 +189,16 @@ See also <<FILES>>. output without getting confused e.g. by values that contain line breaks. +--name-only:: + Output only the names of config variables for `--list` or + `--get-regexp`. + +--show-origin:: + Augment the output of all queried config options with the + origin type (file, standard input, blob, command line) and + the actual origin (config file path, ref, or blob id if + applicable). + --get-colorbool name [stdout-is-tty]:: Find the color setting for `name` (e.g. `color.diff`) and output @@ -215,7 +224,9 @@ See also <<FILES>>. --[no-]includes:: Respect `include.*` directives in config files when looking up - values. Defaults to on. + values. Defaults to `off` when a specific file is given (e.g., + using `--file`, `--global`, etc) and `on` when searching all + config files. [[FILES]] FILES diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index 89b730632d..96208f822e 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -36,7 +36,7 @@ OPTIONS cache daemon if one is not started). Defaults to `~/.git-credential-cache/socket`. If your home directory is on a network-mounted filesystem, you may need to change this to a - local filesystem. + local filesystem. You must specify an absolute path. CONTROLLING THE DAEMON ---------------------- diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index e045fc73f8..c8f28c8c86 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -9,7 +9,7 @@ git-describe - Describe a commit using the most recent tag reachable from it SYNOPSIS -------- [verse] -'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <commit-ish>... +'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] DESCRIPTION @@ -27,7 +27,7 @@ see the -a and -s options to linkgit:git-tag[1]. OPTIONS ------- <commit-ish>...:: - Commit-ish object names to describe. + Commit-ish object names to describe. Defaults to HEAD if omitted. --dirty[=<mark>]:: Describe the working tree. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index fd32895255..66910aa2fa 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -54,7 +54,7 @@ Options for Frontends ~~~~~~~~~~~~~~~~~~~~~ --cat-blob-fd=<fd>:: - Write responses to `cat-blob` and `ls` queries to the + Write responses to `get-mark`, `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. @@ -350,6 +350,11 @@ and control the current import process. More detailed discussion unless the `done` feature was requested using the `--done` command-line option or `feature done` command. +`get-mark`:: + Causes fast-import to print the SHA-1 corresponding to a mark + to the file descriptor set with `--cat-blob-fd`, or `stdout` if + unspecified. + `cat-blob`:: Causes fast-import to print a blob in 'cat-file --batch' format to the file descriptor set with `--cat-blob-fd` or @@ -930,6 +935,25 @@ Placing a `progress` command immediately after a `checkpoint` will inform the reader when the `checkpoint` has been completed and it can safely access the refs that fast-import updated. +`get-mark` +~~~~~~~~~~ +Causes fast-import to print the SHA-1 corresponding to a mark to +stdout or to the file descriptor previously arranged with the +`--cat-blob-fd` argument. The command otherwise has no impact on the +current import; its purpose is to retrieve SHA-1s that later commits +might want to refer to in their commit messages. + +.... + 'get-mark' SP ':' <idnum> LF +.... + +This command can be used anywhere in the stream that comments are +accepted. In particular, the `get-mark` command can be used in the +middle of a commit but not in the middle of a `data` command. + +See ``Responses To Commands'' below for details about how to read +this output safely. + `cat-blob` ~~~~~~~~~~ Causes fast-import to print a blob to a file descriptor previously @@ -1000,7 +1024,8 @@ Output uses the same format as `git ls-tree <tree> -- <path>`: ==== The <dataref> represents the blob, tree, or commit object at <path> -and can be used in later 'cat-blob', 'filemodify', or 'ls' commands. +and can be used in later 'get-mark', 'cat-blob', 'filemodify', or +'ls' commands. If there is no file or subtree at that path, 'git fast-import' will instead report @@ -1042,9 +1067,11 @@ import-marks-if-exists:: "feature import-marks-if-exists" like a corresponding command-line option silently skips a nonexistent file. +get-mark:: cat-blob:: ls:: - Require that the backend support the 'cat-blob' or 'ls' command. + Require that the backend support the 'get-mark', 'cat-blob', + or 'ls' command respectively. Versions of fast-import not supporting the specified command will exit with a message indicating so. This lets the import error out early with a clear message, @@ -1124,11 +1151,11 @@ bidirectional pipes: git fast-import >fast-import-output ==== -A frontend set up this way can use `progress`, `ls`, and `cat-blob` -commands to read information from the import in progress. +A frontend set up this way can use `progress`, `get-mark`, `ls`, and +`cat-blob` commands to read information from the import in progress. To avoid deadlock, such frontends must completely consume any -pending output from `progress`, `ls`, and `cat-blob` before +pending output from `progress`, `ls`, `get-mark`, and `cat-blob` before performing writes to fast-import that might block. Crash Reports diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 8680f45f8d..239623cc24 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -104,6 +104,10 @@ be in a separate packet, and the list must end with a flush packet. The remote heads to update from. This is relative to $GIT_DIR (e.g. "HEAD", "refs/heads/master"). When unspecified, update from all heads the remote side has. ++ +If the remote has enabled the options `uploadpack.allowTipSHA1InWant` or +`uploadpack.allowReachableSHA1InWant`, they may alternatively be 40-hex +sha1s present on the remote. SEE ALSO -------- diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index e62d9a0717..efe56e0808 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -71,7 +71,7 @@ This configuration is used in two ways: * When `git fetch` is run without specifying what branches and/or tags to fetch on the command line, e.g. `git fetch origin` or `git fetch`, `remote.<repository>.fetch` values are used as - the refspecs---they specify which refs to fetch and which local refs + the refspecs--they specify which refs to fetch and which local refs to update. The example above will fetch all branches that exist in the `origin` (i.e. any ref that matches the left-hand side of the value, `refs/heads/*`) and update the diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 73fd9e8230..003731f6a9 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -205,7 +205,7 @@ to other tags will be rewritten to point to the underlying commit. Remap to ancestor ~~~~~~~~~~~~~~~~~ -By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the +By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit the set of revisions which get rewritten. However, positive refs on the command line are distinguished: we don't let them be excluded by such limiters. For this purpose, they are instead rewritten to point at the nearest ancestor that diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 55a9a4b93a..6526b178e8 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,7 +9,7 @@ git-fmt-merge-msg - Produce a merge commit message SYNOPSIS -------- [verse] -'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] <$GIT_DIR/FETCH_HEAD +'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] 'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -F <file> DESCRIPTION @@ -57,6 +57,18 @@ merge.summary:: Synonym to `merge.log`; this is deprecated and will be removed in the future. +EXAMPLE +------- + +-- +$ git fetch origin master +$ git fmt-merge-msg --log <$GIT_DIR/FETCH_HEAD +-- + +Print a log message describing a merge of the "master" branch from +the "origin" remote. + + SEE ALSO -------- linkgit:git-merge[1] diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 42408752d0..d9d406dcfb 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -10,6 +10,8 @@ SYNOPSIS [verse] 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] [<pattern>...] + [--points-at <object>] [(--merged | --no-merged) [<object>]] + [--contains [<object>]] DESCRIPTION ----------- @@ -62,6 +64,20 @@ OPTIONS the specified host language. This is meant to produce a scriptlet that can directly be `eval`ed. +--points-at <object>:: + Only list refs which points at the given object. + +--merged [<object>]:: + Only list refs whose tips are reachable from the + specified commit (HEAD if not specified). + +--no-merged [<object>]:: + Only list refs whose tips are not reachable from the + specified commit (HEAD if not specified). + +--contains [<object>]:: + Only list refs which contain the specified commit (HEAD if not + specified). FIELD NAMES ----------- @@ -76,7 +92,11 @@ refname:: The name of the ref (the part after $GIT_DIR/). For a non-ambiguous short name of the ref append `:short`. The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. + abbreviation mode. If `strip=<N>` is appended, strips `<N>` + slash-separated path components from the front of the refname + (e.g., `%(refname:strip=2)` turns `refs/tags/foo` into `foo`. + `<N>` must be a positive integer. If a displayed ref has fewer + components than `<N>`, the command aborts with an error. objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). @@ -97,6 +117,12 @@ upstream:: or "=" (in sync). Has no effect if the ref does not have tracking information associated with it. +push:: + The name of a local ref which represents the `@{push}` location + for the displayed ref. Respects `:short`, `:track`, and + `:trackshort` options as `upstream` does. Produces an empty + string if no `@{push}` ref is configured. + HEAD:: '*' if HEAD matches current ref (the checked out branch), ' ' otherwise. @@ -105,10 +131,30 @@ color:: Change output color. Followed by `:<colorname>`, where names are described in `color.branch.*`. +align:: + Left-, middle-, or right-align the content between + %(align:...) and %(end). The "align:" is followed by + `width=<width>` and `position=<position>` in any order + separated by a comma, where the `<position>` is either left, + right or middle, default being left and `<width>` is the total + length of the content with alignment. For brevity, the + "width=" and/or "position=" prefixes may be omitted, and bare + <width> and <position> used instead. For instance, + `%(align:<width>,<position>)`. If the contents length is more + than the width then no alignment is performed. If used with + '--quote' everything in between %(align:...) and %(end) is + quoted, but if nested then only the topmost level performs + quoting. + In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can be used to specify the value in the header field. +For commit and tag objects, the special `creatordate` and `creator` +fields will correspond to the appropriate date or name-email-date tuple +from the `committer` or `tagger` fields depending on the object type. +These are intended for working on a mix of annotated and lightweight tags. + Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. @@ -117,20 +163,23 @@ The complete message in a commit and tag object is `contents`. 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`. +blank line. The optional GPG signature is `contents:signature`. The +first `N` lines of the message is obtained using `contents:lines=N`. -For sorting purposes, fields with numeric values sort in numeric -order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). +For sorting purposes, fields with numeric values sort in numeric order +(`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`). All other fields are used to sort in their byte-value order. +There is also an option to sort by versions, this can be done by using +the fieldname `version:refname` or its alias `v:refname`. + In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error. It returns an empty string instead. As a special case for the date-type fields, you may specify a format for -the date by adding one of `:default`, `:relative`, `:short`, `:local`, -`:iso8601`, `:rfc2822` or `:raw` to the end of the fieldname; e.g. -`%(taggerdate:relative)`. +the date by adding `:` followed by date format name (see the +values the `--date` option to linkgit:git-rev-list[1] takes). EXAMPLES diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 0dac4e9b86..bdeecd59e0 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -57,7 +57,11 @@ The names of the output files are printed to standard 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. +they are created in the current working directory. The default path +can be set with the 'format.outputDirectory' configuration option. +The `-o` option takes precedence over `format.outputDirectory`. +To store patches in the current working directory even when +`format.outputDirectory` points elsewhere, use `-o .`. 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 @@ -109,6 +113,7 @@ include::diff-options.txt[] --signoff:: Add `Signed-off-by:` line to the commit message, using the committer identity of yourself. + See the signoff option in linkgit:git-commit[1] for more information. --stdout:: Print all commits to the standard output in mbox format, @@ -213,7 +218,7 @@ feeding the result to `git send-email`. --[no-]cover-letter:: In addition to the patches, generate a cover letter file - containing the shortlog and the overall diffstat. You can + containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. --notes[=<ref>]:: @@ -256,6 +261,15 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. using this option cannot be applied properly, but they are still useful for code review. +--zero-commit:: + Output an all-zero hash in each patch's From header instead + of the hash of the commit. + +--base=<commit>:: + Record the base tree information to identify the state the + patch series applies to. See the BASE TREE INFORMATION section + below for details. + --root:: Treat the revision argument as a <revision range>, even if it is just a single commit (that would normally be treated as a @@ -511,6 +525,61 @@ This should help you to submit patches inline using KMail. 5. Back in the compose window: add whatever other text you wish to the message, complete the addressing and subject fields, and press send. +BASE TREE INFORMATION +--------------------- + +The base tree information block is used for maintainers or third party +testers to know the exact state the patch series applies to. It consists +of the 'base commit', which is a well-known commit that is part of the +stable part of the project history everybody else works off of, and zero +or more 'prerequisite patches', which are well-known patches in flight +that is not yet part of the 'base commit' that need to be applied on top +of 'base commit' in topological order before the patches can be applied. + +The 'base commit' is shown as "base-commit: " followed by the 40-hex of +the commit object name. A 'prerequisite patch' is shown as +"prerequisite-patch-id: " followed by the 40-hex 'patch id', which can +be obtained by passing the patch through the `git patch-id --stable` +command. + +Imagine that on top of the public commit P, you applied well-known +patches X, Y and Z from somebody else, and then built your three-patch +series A, B, C, the history would be like: + +................................................ +---P---X---Y---Z---A---B---C +................................................ + +With `git format-patch --base=P -3 C` (or variants thereof, e.g. with +`--cover-letter` of using `Z..C` instead of `-3 C` to specify the +range), the base tree information block is shown at the end of the +first message the command outputs (either the first patch, or the +cover letter), like this: + +------------ +base-commit: P +prerequisite-patch-id: X +prerequisite-patch-id: Y +prerequisite-patch-id: Z +------------ + +For non-linear topology, such as + +................................................ +---P---X---A---M---C + \ / + Y---Z---B +................................................ + +You can also use `git format-patch --base=P -3 C` to generate patches +for A, B and C, and the identifiers for P, X, Y, Z are appended at the +end of the first message. + +If set `--base=auto` in cmdline, it will track base commit automatically, +the base commit will be the merge base of tip commit of the remote-tracking +branch and revision-range specified in cmdline. +For a local branch, you need to track a remote branch by `git branch +--set-upstream-to` before using this option. EXAMPLES -------- diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 25c431d3c5..84ee92e158 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] - [--[no-]dangling] [--[no-]progress] [<object>*] + [--[no-]dangling] [--[no-]progress] [--connectivity-only] [<object>*] DESCRIPTION ----------- @@ -60,6 +60,11 @@ index file, all SHA-1 references in `refs` namespace, and all reflogs object pools. This is now default; you can turn it off with --no-full. +--connectivity-only:: + Check only the connectivity of tags, commits and tree objects. By + avoiding to unpack blobs, this speeds up the operation, at the + expense of missing corrupt objects or other problematic issues. + --strict:: Enable more strict checking, namely to catch a file mode recorded with g+w bit set, which was created by older diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 52234987f9..fa1510480a 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -63,8 +63,11 @@ automatic consolidation of packs. --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, overridable by the config variable `gc.pruneExpire`). - --prune=all prunes loose objects regardless of their age. - --prune is on by default. + --prune=all prunes loose objects regardless of their age (do + not use --prune=all unless you know exactly what you are doing. + Unless the repository is quiescent, you will lose newly created + objects that haven't been anchored with the refs and end up + corrupting your repository). --prune is on by default. --no-prune:: Do not prune any loose objects. diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 1e2a20dd26..ac44d85b0b 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -9,17 +9,19 @@ git-get-tar-commit-id - Extract commit ID from an archive created using git-arch SYNOPSIS -------- [verse] -'git get-tar-commit-id' < <tarfile> +'git get-tar-commit-id' DESCRIPTION ----------- -Acts as a filter, extracting the commit ID stored in archives created by -'git archive'. It reads only the first 1024 bytes of input, thus its -runtime is not influenced by the size of <tarfile> very much. + +Read a tar archive created by 'git archive' from the standard input +and extract the commit ID stored in it. It reads only the first +1024 bytes of input, thus its runtime is not influenced by the size +of the tar archive very much. If no commit ID is found, 'git get-tar-commit-id' quietly exists with a -return code of 1. This can happen if <tarfile> had not been created +return code of 1. This can happen if the archive had not been created using 'git archive' or if the first parameter of 'git archive' had been a tree ID instead of a commit ID or tag. diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 31811f16bd..cb0f6cf678 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -23,6 +23,7 @@ SYNOPSIS [--break] [--heading] [-p | --show-function] [-A <post-context>] [-B <pre-context>] [-C <context>] [-W | --function-context] + [--threads <num>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...] @@ -53,9 +54,17 @@ grep.extendedRegexp:: option is ignored when the 'grep.patternType' option is set to a value other than 'default'. +grep.threads:: + Number of grep worker threads to use. If unset (or set to 0), + 8 threads are used by default (for now). + grep.fullName:: If set to true, enable '--full-name' option by default. +grep.fallbackToNoIndex:: + If set to true, fall back to git grep --no-index if git grep + is executed outside of a git repository. Defaults to false. + OPTIONS ------- @@ -160,12 +169,15 @@ OPTIONS For better compatibility with 'git diff', `--name-only` is a synonym for `--files-with-matches`. --O [<pager>]:: ---open-files-in-pager [<pager>]:: +-O[<pager>]:: +--open-files-in-pager[=<pager>]:: Open the matching files in the pager (not the output of 'grep'). If the pager happens to be "less" or "vi", and the user specified only one pattern, the first file is positioned at - the first match automatically. + the first match automatically. The `pager` argument is + optional; if specified, it must be stuck to the option + without a space. If `pager` is unspecified, the default pager + will be used (see `core.pager` in linkgit:git-config[1]). -z:: --null:: @@ -224,6 +236,10 @@ OPTIONS effectively showing the whole function in which the match was found. +--threads <num>:: + Number of grep worker threads to use. + See `grep.threads` in 'CONFIGURATION' for more information. + -f <file>:: Read patterns from <file>, one per line. diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 0c75f3b610..814e74406a 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>... -'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] < <list-of-paths> +'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] DESCRIPTION ----------- @@ -35,7 +35,8 @@ OPTIONS Read the object from standard input instead of from a file. --stdin-paths:: - Read file names from stdin instead of from the command-line. + Read file names from the standard input, one per line, instead + of from the command-line. --path:: Hash object as it were located at the given path. The location of diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 8174d27efd..6364e5dc45 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -130,7 +130,12 @@ The template directory will be one of the following (in order): - the default template directory: `/usr/share/git-core/templates`. The default template directory includes some directory structure, suggested -"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]). +"exclude patterns" (see linkgit:gitignore[5]), and sample hook files. + +The sample hooks are all disabled by default, To enable one of the +sample hooks rename it by removing its `.sample` suffix. + +See linkgit:githooks[5] for more general info on hook execution. EXAMPLES -------- diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index d6d9231b50..a77b901f1d 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -8,7 +8,7 @@ git-interpret-trailers - help add structured information into commit messages SYNOPSIS -------- [verse] -'git interpret-trailers' [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...] +'git interpret-trailers' [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...] DESCRIPTION ----------- @@ -64,10 +64,13 @@ folding rules, the encoding rules and probably many other rules. OPTIONS ------- +--in-place:: + Edit the files in place. + --trim-empty:: If the <value> part of any trailer contains only whitespace, the whole trailer will be removed from the resulting message. - This apply to existing trailers as well as new trailers. + This applies to existing trailers as well as new trailers. --trailer <token>[(=|:)<value>]:: Specify a (<token>, <value>) pair that should be applied as a @@ -216,6 +219,25 @@ Signed-off-by: Alice <alice@example.com> Signed-off-by: Bob <bob@example.com> ------------ +* Use the '--in-place' option to edit a message file in place: ++ +------------ +$ cat msg.txt +subject + +message + +Signed-off-by: Bob <bob@example.com> +$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt +$ cat msg.txt +subject + +message + +Signed-off-by: Bob <bob@example.com> +Acked-by: Alice <alice@example.com> +------------ + * Extract the last commit as a patch, and add a 'Cc' and a 'Reviewed-by' trailer to it: + diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 5692945a0b..dec379b3e2 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -29,12 +29,14 @@ OPTIONS (works only for a single file). --no-decorate:: ---decorate[=short|full|no]:: +--decorate[=short|full|auto|no]:: Print out the ref names of any commits that are shown. If 'short' is specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is specified, the - full ref name (including prefix) will be printed. The default option - is 'short'. + full ref name (including prefix) will be printed. If 'auto' is + specified, then if the output is going to a terminal, the ref names + are shown as if 'short' were given, otherwise no ref names are + shown. The default option is 'short'. --source:: Print out the ref name given on the command line by which each @@ -184,6 +186,12 @@ log.date:: `--date` option.) Defaults to "default", which means to write dates like `Sat May 8 19:35:34 2010 -0500`. +log.follow:: + If `true`, `git log` will act as if the `--follow` option was used when + a single <path> is given. This has the same limitations as `--follow`, + i.e. it cannot be used to follow multiple files and does not work well + on non-linear history. + log.showRoot:: If `false`, `git log` and related commands will not treat the initial commit as a big creation event. Any root commits in diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index e26f01fb1d..75c3f4157d 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git ls-files' [-z] [-t] [-v] (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (-[c|d|o|i|s|u|k|m])* + [--eol] [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] @@ -147,6 +148,24 @@ a space) at the start of each line: possible for manual inspection; the exact format may change at any time. +--eol:: + Show <eolinfo> and <eolattr> of files. + <eolinfo> is the file content identification used by Git when + the "text" attribute is "auto" (or not set and core.autocrlf is not false). + <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "". ++ +"" means the file is not a regular file, it is not in the index or +not accessible in the working tree. ++ +<eolattr> is the attribute that is used when checking out or committing, +it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". +Note: Currently Git does not support "text=auto eol=lf" or "text=auto eol=crlf", +that may change in the future. ++ +Both the <eolinfo> in the index ("i/<eolinfo>") +and in the working tree ("w/<eolinfo>") are shown for regular files, +followed by the ("attr/<eolattr>"). + \--:: Do not interpret any more arguments as options. @@ -161,6 +180,9 @@ which case it outputs: [<tag> ]<mode> <object> <stage> <file> +'git ls-files --eol' will show + i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file> + 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine detailed information on unmerged paths. diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index 2e22915eb8..5f2628c8f8 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -9,8 +9,9 @@ git-ls-remote - List references in a remote repository SYNOPSIS -------- [verse] -'git ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] - [--exit-code] <repository> [<refs>...] +'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>] + [-q | --quiet] [--exit-code] [--get-url] + [--symref] [<repository> [<refs>...]] DESCRIPTION ----------- @@ -29,7 +30,13 @@ OPTIONS both, references stored in refs/heads and refs/tags are displayed. --u <exec>:: +--refs:: + Do not show peeled tags or pseudorefs like HEAD in the output. + +-q:: +--quiet:: + Do not print remote URL to stderr. + --upload-pack=<exec>:: Specify the full path of 'git-upload-pack' on the remote host. This allows listing references from repositories accessed via @@ -47,6 +54,12 @@ OPTIONS "url.<base>.insteadOf" config setting (See linkgit:git-config[1]) and exit without talking to the remote. +--symref:: + In addition to the object pointed by it, show the underlying + ref pointed by it when showing a symbolic ref. Currently, + upload-pack only shows the symref HEAD, so it will be the only + one shown by ls-remote. + <repository>:: The "remote" repository to query. This parameter can be either a URL or the name of a remote (see the GIT URLS and diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 0947084140..3bbc731f67 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -85,7 +85,7 @@ with comments and suggestions on the message you are responding to, and to conclude it with a patch submission, separating the discussion and the beginning of the proposed commit log message with a scissors line. + -This can enabled by default with the configuration option mailinfo.scissors. +This can be enabled by default with the configuration option mailinfo.scissors. --no-scissors:: Ignore scissors lines. Useful for overriding mailinfo.scissors settings. diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index d2fc12ec77..f856032613 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -41,7 +41,8 @@ lines from `<other-file>`, or lines from both respectively. The length of the conflict markers can be given with the `--marker-size` option. The exit value of this program is negative on error, and the number of -conflicts otherwise. If the merge was clean, the exit value is 0. +conflicts otherwise (truncated to 127 if there are more than that many +conflicts). If the merge was clean, the exit value is 0. 'git merge-file' is designed to be a minimal clone of RCS 'merge'; that is, it implements all of RCS 'merge''s functionality which is needed by diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 1f94908e3c..b758d5556c 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -10,7 +10,8 @@ SYNOPSIS -------- [verse] 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] - [-s <strategy>] [-X <strategy-option>] [-S[<key-id>]] + [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] + [--[no-]allow-unrelated-histories] [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] 'git merge' <msg> HEAD <commit>... 'git merge' --abort @@ -67,7 +68,9 @@ include::merge-options.txt[] -S[<keyid>]:: --gpg-sign[=<keyid>]:: - GPG-sign the resulting merge commit. + GPG-sign the resulting merge commit. The `keyid` argument is + optional and defaults to the committer identity; if specified, + it must be stuck to the option without a space. -m <msg>:: Set the commit message to be used for the merge commit (in @@ -78,7 +81,7 @@ will be appended to the specified message. + The 'git fmt-merge-msg' command can be used to give a good default for automated 'git merge' -invocations. +invocations. The automated message can include the branch description. --[no-]rerere-autoupdate:: Allow the rerere mechanism to update the index with the @@ -104,6 +107,10 @@ commit or stash your changes before running 'git merge'. If no commit is given from the command line, 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. ++ +When `FETCH_HEAD` (and no other commit) is specified, the branches +recorded in the `.git/FETCH_HEAD` file by the previous invocation +of `git fetch` for merging are merged to the current branch. PRE-MERGE CHECKS diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 3ca158b05e..fa6a756123 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -9,7 +9,7 @@ git-mktag - Creates a tag object SYNOPSIS -------- [verse] -'git mktag' < signature_file +'git mktag' DESCRIPTION ----------- @@ -20,7 +20,8 @@ The output is the new tag's <object> identifier. Tag Format ---------- -A tag signature file has a very simple fixed format: four lines of +A tag signature file, to be fed to this command's standard input, +has a very simple fixed format: four lines of object <sha1> type <typename> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 851518d531..9c4fd6812c 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -101,7 +101,7 @@ merge:: any) into the current notes ref (called "local"). + If conflicts arise and a strategy for automatically resolving -conflicting notes (see the -s/--strategy option) is not given, +conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given, the "manual" resolver is used. This resolver checks out the conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to manually resolve the conflicts there. @@ -162,7 +162,9 @@ OPTIONS --ref <ref>:: Manipulate the notes tree in <ref>. This overrides 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref - is taken to be in `refs/notes/` if it is not qualified. + specifies the full refname when it begins with `refs/notes/`; when it + begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed + to form a full name of the ref. --ignore-missing:: Do not consider it an error to request removing notes from an @@ -183,6 +185,7 @@ OPTIONS When merging notes, resolve notes conflicts using the given strategy. The following strategies are recognized: "manual" (default), "ours", "theirs", "union" and "cat_sort_uniq". + This option overrides the "notes.mergeStrategy" configuration setting. See the "NOTES MERGE STRATEGIES" section below for more information on each notes merge strategy. @@ -247,6 +250,9 @@ When done, the user can either finalize the merge with 'git notes merge --commit', or abort the merge with 'git notes merge --abort'. +Users may select an automated merge strategy from among the following using +either -s/--strategy option or configuring notes.mergeStrategy accordingly: + "ours" automatically resolves conflicting notes in favor of the local version (i.e. the current notes ref). @@ -310,6 +316,20 @@ core.notesRef:: This setting can be overridden through the environment and command line. +notes.mergeStrategy:: + Which merge strategy to choose by default when resolving notes + conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or + `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" + section above for more information on each strategy. ++ +This setting can be overridden by passing the `--strategy` option. + +notes.<name>.mergeStrategy:: + Which merge strategy to choose when doing a notes merge into + refs/notes/<name>. This overrides the more general + "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above + for more information on each available strategy. + notes.displayRef:: Which ref (or refs, if a glob or specified more than once), in addition to the default set by `core.notesRef` or @@ -331,7 +351,8 @@ environment variable. notes.rewriteMode:: When copying notes during a rewrite, what to do if the target commit already has a note. Must be one of `overwrite`, - `concatenate`, and `ignore`. Defaults to `concatenate`. + `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to + `concatenate`. + This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` environment variable. @@ -368,7 +389,7 @@ does not match any refs is silently ignored. 'GIT_NOTES_REWRITE_MODE':: When copying notes during a rewrite, what to do if the target commit already has a note. - Must be one of `overwrite`, `concatenate`, and `ignore`. + Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. This overrides the `core.rewriteMode` setting. 'GIT_NOTES_REWRITE_REF':: @@ -381,4 +402,4 @@ on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. GIT --- -Part of the linkgit:git[7] suite +Part of the linkgit:git[1] suite diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index a1664b9f68..88ba42b455 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -225,9 +225,20 @@ Git repository: they can find the p4 branches in refs/heads. --max-changes <n>:: - Limit the number of imported changes to 'n'. Useful to - limit the amount of history when using the '@all' p4 revision - specifier. + Import at most 'n' changes, rather than the entire range of + changes included in the given revision specifier. A typical + usage would be use '@all' as the revision specifier, but then + to use '--max-changes 1000' to import only the last 1000 + revisions rather than the entire revision history. + +--changes-block-size <n>:: + The internal block size to use when converting a revision + specifier such as '@all' into a list of specific change + numbers. Instead of using a single call to 'p4 changes' to + find the full list of changes for the conversion, there are a + sequence of calls to 'p4 changes -m', each of which requests + one block of changes of the given size. The default block size + is 500, which should usually be suitable. --keep-path:: The mapping of file names from the p4 depot path to Git, by @@ -499,6 +510,58 @@ git-p4.useClientSpec:: option '--use-client-spec'. See the "CLIENT SPEC" section above. This variable is a boolean, not the name of a p4 client. +git-p4.pathEncoding:: + Perforce keeps the encoding of a path as given by the originating OS. + Git expects paths encoded as UTF-8. Use this config to tell git-p4 + what encoding Perforce had used for the paths. This encoding is used + to transcode the paths to UTF-8. As an example, Perforce on Windows + often uses "cp1252" to encode path names. + +git-p4.largeFileSystem:: + Specify the system that is used for large (binary) files. Please note + that large file systems do not support the 'git p4 submit' command. + Only Git LFS is implemented right now (see https://git-lfs.github.com/ + for more information). Download and install the Git LFS command line + extension to use this option and configure it like this: ++ +------------- +git config git-p4.largeFileSystem GitLFS +------------- + +git-p4.largeFileExtensions:: + All files matching a file extension in the list will be processed + by the large file system. Do not prefix the extensions with '.'. + +git-p4.largeFileThreshold:: + All files with an uncompressed size exceeding the threshold will be + processed by the large file system. By default the threshold is + defined in bytes. Add the suffix k, m, or g to change the unit. + +git-p4.largeFileCompressedThreshold:: + All files with a compressed size exceeding the threshold will be + processed by the large file system. This option might slow down + your clone/sync process. By default the threshold is defined in + bytes. Add the suffix k, m, or g to change the unit. + +git-p4.largeFilePush:: + Boolean variable which defines if large files are automatically + pushed to a server. + +git-p4.keepEmptyCommits:: + A changelist that contains only excluded files will be imported + as an empty commit if this boolean option is set to true. + +git-p4.mapUser:: + Map a P4 user to a name and email address in Git. Use a string + with the following format to create a mapping: ++ +------------- +git config --add git-p4.mapUser "p4user = First Last <mail@address.com>" +------------- ++ +A mapping will override any user information from P4. Mappings for +multiple P4 user can be defined. + Submit variables ~~~~~~~~~~~~~~~~ git-p4.detectRenames:: diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index bbea5294ca..19cdcd0341 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -110,7 +110,8 @@ base-name:: --max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. - If specified, multiple packfiles may be created. + If specified, multiple packfiles may be created, which also + prevents the creation of a bitmap index. The default is unlimited, unless the config variable `pack.packSizeLimit` is set. diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 31efc587ee..cf71fba1c0 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -8,10 +8,12 @@ git-patch-id - Compute unique ID for a patch SYNOPSIS -------- [verse] -'git patch-id' [--stable | --unstable] < <patch> +'git patch-id' [--stable | --unstable] DESCRIPTION ----------- +Read a patch from the standard input and compute the patch ID for it. + A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a patch, with whitespace and line numbers ignored. As such, it's "reasonably stable", but at the same time also reasonably unique, i.e., two patches that diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 712ab4baed..d033b258e5 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -74,9 +74,6 @@ pulling or stash them away with linkgit:git-stash[1]. OPTIONS ------- -Options meant for 'git pull' itself and the underlying 'git merge' -must be given before the options meant for 'git fetch'. - -q:: --quiet:: This is passed to both underlying git-fetch to squelch reporting of @@ -104,7 +101,7 @@ Options related to merging include::merge-options.txt[] -r:: ---rebase[=false|true|preserve]:: +--rebase[=false|true|preserve|interactive]:: When true, rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to the upstream branch and the upstream branch @@ -116,6 +113,8 @@ to `git rebase` so that locally created merge commits will not be flattened. + When false, merge the current branch into the upstream branch. + +When `interactive`, enable the interactive mode of rebase. ++ See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in linkgit:git-config[1] if you want to make `git pull` always use `--rebase` instead of merging. @@ -129,6 +128,15 @@ unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: Override earlier --rebase. +--autostash:: +--no-autostash:: + Before starting rebase, stash local modifications away (see + linkgit:git-stash[1]) if needed, and apply the stash when + done. `--no-autostash` is useful to override the `rebase.autoStash` + configuration variable (see linkgit:git-config[1]). ++ +This option is only valid when "--rebase" is used. + Options related to fetching ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 135d810b7a..cf6ee4a4df 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -10,8 +10,9 @@ SYNOPSIS -------- [verse] 'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] - [-u | --set-upstream] [--signed] + [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-v | --verbose] + [-u | --set-upstream] + [--[no-]signed|--sign=(true|false|if-asked)] [--force-with-lease[=<refname>[:<expect>]]] [--no-verify] [<repository> [<refspec>...]] @@ -36,6 +37,13 @@ the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide what to push (See linkgit:git-config[1] for the meaning of `push.default`). +When neither the command-line nor the configuration specify what to +push, the default behavior is used, which corresponds to the `simple` +value for `push.default`: the current branch is pushed to the +corresponding upstream branch, but as a safety measure, the push is +aborted if the upstream branch does not have the same name as the +local one. + OPTIONS[[OPTIONS]] ------------------ @@ -61,7 +69,7 @@ be named. If `git push [<repository>]` without any `<refspec>` argument is set to update some ref at the destination with `<src>` with `remote.<repository>.push` configuration variable, `:<dst>` part can -be omitted---such a push will update a ref that `<src>` normally updates +be omitted--such a push will update a ref that `<src>` normally updates without any `<refspec>` on the command line. Otherwise, missing `:<dst>` means to update the same ref as the `<src>`. + @@ -132,12 +140,16 @@ already exists on the remote side. with configuration variable 'push.followTags'. For more information, see 'push.followTags' in linkgit:git-config[1]. - ---signed:: +--[no-]signed:: +--sign=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be - logged. See linkgit:git-receive-pack[1] for the details - on the receiving end. + logged. If `false` or `--no-signed`, no signing will be + attempted. If `true` or `--signed`, the push will fail if the + server does not support signed pushes. If set to `if-asked`, + sign if and only if the server supports signed pushes. The push + will also fail if the actual call to `gpg --sign` fails. See + linkgit:git-receive-pack[1] for the details on the receiving end. --[no-]atomic:: Use an atomic transaction on the remote side if available. @@ -252,22 +264,33 @@ origin +master` to force a push to the `master` branch). See the is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---recurse-submodules=check|on-demand:: - Make sure all submodule commits used by the revisions to be - pushed are available on a remote-tracking branch. If 'check' is - used Git will verify that all submodule commits that changed in - the revisions to be pushed are available on at least one remote - of the submodule. If any commits are missing the push will be - aborted and exit with non-zero status. If 'on-demand' is used - all submodules that changed in the revisions to be pushed will - be pushed. If on-demand was not able to push all necessary - revisions it will also be aborted and exit with non-zero status. +--no-recurse-submodules:: +--recurse-submodules=check|on-demand|no:: + May be used to make sure all submodule commits used by the + revisions to be pushed are available on a remote-tracking branch. + If 'check' is used Git will verify that all submodule commits that + changed in the revisions to be pushed are available on at least one + remote of the submodule. If any commits are missing the push will + be aborted and exit with non-zero status. If 'on-demand' is used + all submodules that changed in the revisions to be pushed will be + pushed. If on-demand was not able to push all necessary revisions + it will also be aborted and exit with non-zero status. A value of + 'no' or using '--no-recurse-submodules' can be used to override the + push.recurseSubmodules configuration variable when no submodule + recursion is required. --[no-]verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The default is --verify, giving the hook a chance to prevent the push. With --no-verify, the hook is bypassed completely. +-4:: +--ipv4:: + Use IPv4 addresses only, ignoring IPv6 addresses. + +-6:: +--ipv6:: + Use IPv6 addresses only, ignoring IPv4 addresses. include::urls-remotes.txt[] diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index d64388cb8e..ff633b0db7 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git quiltimport' [--dry-run | -n] [--author <author>] [--patches <dir>] + [--series <file>] DESCRIPTION @@ -42,13 +43,19 @@ OPTIONS information can be found in the patch description. --patches <dir>:: - The directory to find the quilt patches and the - quilt series file. + The directory to find the quilt patches. + The default for the patch directory is patches or the value of the $QUILT_PATCHES environment variable. +--series <file>:: + The quilt series file. ++ +The default for the series file is <patches>/series +or the value of the $QUILT_SERIES environment +variable. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 1d01baa5fc..0387b40e0a 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -3,7 +3,7 @@ git-rebase(1) NAME ---- -git-rebase - Forward-port local commits to the updated upstream head +git-rebase - Reapply commits on top of another base tip SYNOPSIS -------- @@ -213,6 +213,15 @@ rebase.autoSquash:: rebase.autoStash:: If set to true enable '--autostash' option by default. +rebase.missingCommitsCheck:: + If set to "warn", print warnings about removed commits in + interactive mode. If set to "error", print the warnings and + stop the rebase. If set to "ignore", no checking is + done. "ignore" by default. + +rebase.instructionFormat:: + Custom commit list format to use during an '--interactive' rebase. + OPTIONS ------- --onto <newbase>:: @@ -285,7 +294,9 @@ which makes little sense. -S[<keyid>]:: --gpg-sign[=<keyid>]:: - GPG-sign commits. + GPG-sign commits. The `keyid` argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. -q:: --quiet:: @@ -359,6 +370,10 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. Make a list of the commits which are about to be rebased. Let the user edit that list before rebasing. This mode can also be used to split commits (see SPLITTING COMMITS below). ++ +The commit list format can be changed by setting the configuration option +rebase.instructionFormat. A customized instruction format will automatically +have the long commit hash prepended to the format. -p:: --preserve-merges:: @@ -376,9 +391,6 @@ idea unless you know what you are doing (see BUGS below). 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: + @@ -391,6 +403,9 @@ or by giving more than one `--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. ++ +This uses the `--interactive` machinery internally, but it can be run +without an explicit `--interactive`. --root:: Rebase all commits reachable from <branch>, instead of @@ -419,7 +434,8 @@ If the '--autosquash' option is enabled by default using the configuration variable `rebase.autoSquash`, this option can be used to override and disable this setting. ---[no-]autostash:: +--autostash:: +--no-autostash:: Automatically create a temporary stash before the operation begins, and apply it after the operation ends. This means that you can run rebase on a dirty worktree. However, use @@ -514,6 +530,9 @@ rebasing. If you just want to edit the commit message for a commit, replace the command "pick" with the command "reword". +To drop a commit, replace the command "pick" with "drop", or just +delete the matching line. + If you want to fold two or more commits into one, replace the command "pick" for the second and subsequent commits with "squash" or "fixup". If the commits had different authors, the folded commit will be diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 5e7908e4f7..44c736f1a8 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -23,6 +23,7 @@ depending on the subcommand: [--dry-run] [--verbose] [--all | <refs>...] 'git reflog delete' [--rewrite] [--updateref] [--dry-run] [--verbose] ref@\{specifier\}... +'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches and other references were updated in the local repository. Reflogs are @@ -52,6 +53,9 @@ argument must be an _exact_ entry (e.g. "`git reflog delete master@{2}`"). This subcommand is also typically not used directly by end users. +The "exists" subcommand checks whether a ref has a reflog. It exits +with zero status if the reflog exists, and non-zero status if it does +not. OPTIONS ------- diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 4c6d6de7b7..1d7eceaa93 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -1,5 +1,5 @@ git-remote(1) -============ +============= NAME ---- @@ -15,6 +15,7 @@ SYNOPSIS 'git remote remove' <name> 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>) 'git remote set-branches' [--add] <name> <branch>... +'git remote get-url' [--push] [--all] <name> 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> 'git remote set-url --delete' [--push] <name> <url> @@ -131,6 +132,15 @@ The named branches will be interpreted as if specified with the With `--add`, instead of replacing the list of currently tracked branches, adds to that list. +'get-url':: + +Retrieves the URLs for a remote. Configurations for `insteadOf` and +`pushInsteadOf` are expanded here. By default, only the first URL is listed. ++ +With '--push', push URLs are queried rather than fetch URLs. ++ +With '--all', all URLs for the remote will be listed. + 'set-url':: Changes URLs for the remote. Sets first URL for remote <name> that matches diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 0e0bd363d6..b9c02ce481 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -106,7 +106,8 @@ other objects in that pack they already have locally. --max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. - If specified, multiple packfiles may be created. + If specified, multiple packfiles may be created, which also + prevents the creation of a bitmap index. The default is unlimited, unless the config variable `pack.packSizeLimit` is set. @@ -115,7 +116,8 @@ other objects in that pack they already have locally. Write a reachability bitmap index as part of the repack. This only makes sense when used with `-a` or `-A`, as the bitmaps must be able to refer to all reachable objects. This option - overrides the setting of `pack.writeBitmaps`. + overrides the setting of `repack.writeBitmaps`. This option + has no effect if multiple packfiles are created. --pack-kept-objects:: Include objects in `.keep` files when repacking. Note that we @@ -123,7 +125,7 @@ other objects in that pack they already have locally. This means that we may duplicate objects, but this makes the option safe to use when there are concurrent pushes or fetches. This option is generally only useful if you are writing bitmaps - with `-b` or `pack.writeBitmaps`, as it ensures that the + with `-b` or `repack.writeBitmaps`, as it ensures that the bitmapped packfile has the necessary objects. Configuration @@ -133,7 +135,7 @@ By default, the command passes `--delta-base-offset` option to 'git pack-objects'; this typically results in slightly smaller packs, but the generated packs are incompatible with versions of Git older than version 1.4.4. If you need to share your repository with such ancient Git -versions, either directly or via the dumb http or rsync protocol, then you +versions, either directly or via the dumb http protocol, then you need to set the configuration variable `repack.UseDeltaBaseOffset` to "false" and repack. Access from old Git versions over the native protocol is unaffected by this option as the conversion is performed on the fly diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 283577b0b6..c32cb0bea1 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -14,7 +14,8 @@ DESCRIPTION ----------- Generate a request asking your upstream project to pull changes into -their tree. The request, printed to the standard output, summarizes +their tree. The request, printed to the standard output, +begins with the branch description, summarizes the changes and indicates from where they can be pulled. The upstream project is expected to have the commit named by diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 7b49c85347..ef22f1775b 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -45,7 +45,7 @@ SYNOPSIS [ --regexp-ignore-case | -i ] [ --extended-regexp | -E ] [ --fixed-strings | -F ] - [ --date=(local|relative|default|iso|iso-strict|rfc|short) ] + [ --date=<format>] [ [ --objects | --objects-edge | --objects-edge-aggressive ] [ --unpacked ] ] [ --pretty | --header ] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index bf81b9734e..b6c6326cdc 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -216,6 +216,9 @@ If `$GIT_DIR` is not defined and the current directory is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status. +--git-common-dir:: + Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`. + --is-inside-git-dir:: When the current working directory is below the repository directory print "true", otherwise "false". @@ -233,6 +236,13 @@ print a message to stderr and exit with nonzero status. repository. If <path> is a gitfile then the resolved path to the real repository is printed. +--git-path <path>:: + Resolve "$GIT_DIR/<path>" and takes other path relocation + variables such as $GIT_OBJECT_DIRECTORY, + $GIT_INDEX_FILE... into account. For example, if + $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse + --git-path objects/abc" returns /foo/bar/abc. + --show-cdup:: When the command is invoked from a subdirectory, show the path of the top-level directory relative to the current @@ -301,8 +311,8 @@ Each line of options has this format: `<opt-spec>`:: its format is the short option character, then the long option name separated by a comma. Both parts are not required, though at least one - is necessary. `h,help`, `dry-run` and `f` are all three correct - `<opt-spec>`. + is necessary. May not contain any of the `<flags>` characters. + `h,help`, `dry-run` and `f` are examples of correct `<opt-spec>`. `<flags>`:: `<flags>` are of `*`, `=`, `?` or `!`. diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index cceb5f2f7f..573616a04a 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -8,7 +8,7 @@ git-revert - Revert some existing commits SYNOPSIS -------- [verse] -'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<key-id>]] <commit>... +'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>... 'git revert' --continue 'git revert' --quit 'git revert' --abort @@ -80,13 +80,16 @@ more details. This is useful when reverting more than one commits' effect to your index in a row. --S[<key-id>]:: ---gpg-sign[=<key-id>]:: - GPG-sign commits. +-S[<keyid>]:: +--gpg-sign[=<keyid>]:: + GPG-sign commits. The `keyid` argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. -s:: --signoff:: Add Signed-off-by line at the end of the commit message. + See the signoff option in linkgit:git-commit[1] for more information. --strategy=<strategy>:: Use the given merge strategy. Should only be used once. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 804554609d..a88d18604a 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git send-email' [options] <file|directory|rev-list options>... +'git send-email' --dump-aliases DESCRIPTION @@ -49,17 +50,17 @@ Composing of 'sendemail.annotate'. See the CONFIGURATION section for 'sendemail.multiEdit'. ---bcc=<address>:: +--bcc=<address>,...:: Specify a "Bcc:" value for each email. Default is the value of 'sendemail.bcc'. + -The --bcc option must be repeated for each user you want on the bcc list. +This option may be specified multiple times. ---cc=<address>:: +--cc=<address>,...:: Specify a starting "Cc:" value for each email. Default is the value of 'sendemail.cc'. + -The --cc option must be repeated for each user you want on the cc list. +This option may be specified multiple times. --compose:: Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) @@ -110,13 +111,13 @@ is not set, this will be prompted for. Only necessary if --compose is also set. If --compose is not set, this will be prompted for. ---to=<address>:: +--to=<address>,...:: Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the project involved. Default is the value of the 'sendemail.to' configuration value; if that is unspecified, and --to-cmd is not specified, this will be prompted for. + -The --to option must be repeated for each user you want on the to list. +This option may be specified multiple times. --8bit-encoding=<encoding>:: When encountering a non-ASCII message or subject that does not @@ -171,6 +172,19 @@ Sending to determine your FQDN automatically. Default is the value of 'sendemail.smtpDomain'. +--smtp-auth=<mechanisms>:: + Whitespace-separated list of allowed SMTP-AUTH mechanisms. This setting + forces using only the listed mechanisms. Example: ++ +------ +$ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ... +------ ++ +If at least one of the specified mechanisms matches the ones advertised by the +SMTP server and if it is supported by the utilized SASL library, the mechanism +is used for authentication. If neither 'sendemail.smtpAuth' nor '--smtp-auth' +is specified, all mechanisms supported by the SASL library can be used. + --smtp-pass[=<password>]:: Password for SMTP-AUTH. The argument is optional: If no argument is specified, then the empty string is used as @@ -374,6 +388,16 @@ default to '--validate'. Send emails even if safety checks would prevent it. +Information +~~~~~~~~~~~ + +--dump-aliases:: + Instead of the normal operation, dump the shorthand alias names from + the configured alias file(s), one per line in alphabetical order. Note, + this only includes the alias name and not its expanded email addresses. + See 'sendemail.aliasesfile' for more information about aliases. + + CONFIGURATION ------------- @@ -383,7 +407,24 @@ sendemail.aliasesFile:: sendemail.aliasFileType:: Format of the file(s) specified in sendemail.aliasesFile. Must be - one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus'. + one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'. ++ +What an alias file in each format looks like can be found in +the documentation of the email program of the same name. The +differences and limitations from the standard formats are +described below: ++ +-- +sendmail;; +* Quoted aliases and quoted addresses are not supported: lines that + contain a `"` symbol are ignored. +* Redirection to a file (`/path/name`) or pipe (`|command`) is not + supported. +* File inclusion (`:include: /path/name`) is not supported. +* Warnings are printed on the standard error output for any + explicitly unsupported constructs, and any other lines that are not + recognized by the parser. +-- sendemail.multiEdit:: If true (default), a single editor instance will be spawned to edit @@ -409,6 +450,19 @@ edit ~/.gitconfig to specify your account settings: smtpUser = yourname@gmail.com smtpServerPort = 587 +If you have multifactor authentication setup on your gmail account, you will +need to generate an app-specific password for use with 'git send-email'. Visit +https://security.google.com/settings/security/apppasswords to setup an +app-specific password. Once setup, you can store it with the credentials +helper: + + $ git credential fill + protocol=smtp + host=smtp.gmail.com + username=youname@gmail.com + password=app-password + + Once your commits are ready to be sent to the mailing list, run the following commands: diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index b5d09f79ee..6aa91e830c 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -9,7 +9,10 @@ git-send-pack - Push objects over Git protocol to another repository SYNOPSIS -------- [verse] -'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [--atomic] [<host>:]<directory> [<ref>...] +'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] + [--verbose] [--thin] [--atomic] + [--[no-]signed|--sign=(true|false|if-asked)] + [<host>:]<directory> [<ref>...] DESCRIPTION ----------- @@ -67,6 +70,17 @@ be in a separate packet, and the list must end with a flush packet. fails to update then the entire push will fail without changing any refs. +--[no-]signed:: +--sign=(true|false|if-asked):: + GPG-sign the push request to update refs on the receiving + side, to allow it to be checked by the hooks and/or be + logged. If `false` or `--no-signed`, no signing will be + attempted. If `true` or `--signed`, the push will fail if the + server does not support signed pushes. If set to `if-asked`, + sign if and only if the server supports signed pushes. The push + will also fail if the actual call to `gpg --sign` fails. See + linkgit:git-receive-pack[1] for the details on the receiving end. + <host>:: A remote host to house the repository. When this part is specified, 'git-receive-pack' is invoked via diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index fbdc8adae5..a8a9509e0e 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -9,13 +9,14 @@ git-show-index - Show packed archive index SYNOPSIS -------- [verse] -'git show-index' < idx-file +'git show-index' DESCRIPTION ----------- -Reads given idx file for packed Git archive created with -'git pack-objects' command, and dumps its contents. +Read the idx file for a Git packfile created with +'git pack-objects' command from the standard input, and +dump its contents. The information it outputs is subset of what you can get from 'git verify-pack -v'; this command only shows the packfile diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 2a6f89b235..3a32451984 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -11,7 +11,7 @@ SYNOPSIS 'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference] [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...] -'git show-ref' --exclude-existing[=<pattern>] < ref-list +'git show-ref' --exclude-existing[=<pattern>] DESCRIPTION ----------- @@ -23,8 +23,9 @@ particular ref exists. By default, shows the tags, heads, and remote refs. -The --exclude-existing form is a filter that does the inverse, it shows the -refs from stdin that don't exist in the local repository. +The --exclude-existing form is a filter that does the inverse. It reads +refs from stdin, one ref per line, and shows those that don't exist in +the local repository. Use of this utility is encouraged in favor of directly accessing files under the `.git` directory. diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 375213fe46..92df596e5f 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -95,6 +95,8 @@ show [<stash>]:: 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). + You can use stash.showStat and/or stash.showPatch config variables + to change the default behavior. pop [--index] [-q|--quiet] [<stash>]:: diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 5221f950ce..e1e8f57cdd 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -53,8 +53,9 @@ OPTIONS --untracked-files[=<mode>]:: Show untracked files. + -The mode parameter is optional (defaults to 'all'), and is used to -specify the handling of untracked files. +The mode parameter is used to specify the handling of untracked files. +It is optional: it defaults to 'all', and if specified, it must be +stuck to the option (e.g. `-uno`, but not `-u no`). + The possible options are: + @@ -66,7 +67,10 @@ When `-u` option is not used, untracked files and directories are shown (i.e. the same as specifying `normal`), to help you avoid forgetting to add newly created files. Because it takes extra work to find untracked files in the filesystem, this mode may take some -time in a large working tree. You can use `no` to have `git status` +time in a large working tree. +Consider enabling untracked cache and split index if supported (see +`git update-index --untracked-cache` and `git update-index +--split-index`), Otherwise you can use `no` to have `git status` return more quickly without showing untracked files. + The default can be changed using the status.showUntrackedFiles diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 60328d5d08..2438f76da0 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -9,14 +9,15 @@ git-stripspace - Remove unnecessary whitespace SYNOPSIS -------- [verse] -'git stripspace' [-s | --strip-comments] < input -'git stripspace' [-c | --comment-lines] < input +'git stripspace' [-s | --strip-comments] +'git stripspace' [-c | --comment-lines] DESCRIPTION ----------- -Clean the input in the manner used by Git for text such as commit -messages, notes, tags and branch descriptions. +Read text, such as commit messages, notes, tags and branch +descriptions, from the standard input and clean it in the manner +used by Git. With no arguments, this will: diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index f17687e09d..9226c4380c 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -13,10 +13,10 @@ SYNOPSIS [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] -'git submodule' [--quiet] deinit [-f|--force] [--] <path>... +'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...) 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase|--merge] [--reference <repository>] - [--depth <depth>] [--recursive] [--] [<path>...] + [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> @@ -140,12 +140,15 @@ deinit:: tree. Further calls to `git submodule update`, `git submodule foreach` and `git submodule sync` will skip any unregistered submodules until they are initialized again, so use this command if you don't want to - have a local checkout of the submodule in your work tree anymore. If + have a local checkout of the submodule in your working tree anymore. If you really want to remove a submodule from the repository and commit that use linkgit:git-rm[1] instead. + -If `--force` is specified, the submodule's work tree will be removed even if -it contains local modifications. +When the command is run without pathspec, it errors out, +instead of deinit-ing everything, to prevent mistakes. ++ +If `--force` is specified, the submodule's working tree will +be removed even if it contains local modifications. update:: + @@ -237,6 +240,9 @@ sync:: + "git submodule sync" synchronizes all submodules while "git submodule sync \-- A" synchronizes submodule "A" only. ++ +If `--recursive` is specified, this command will recurse into the +registered submodules, and sync any nested submodules within. OPTIONS ------- @@ -244,6 +250,10 @@ OPTIONS --quiet:: Only print error messages. +--all:: + This option is only valid for the deinit command. Unregister all + submodules in the working tree. + -b:: --branch:: Branch of repository to add as submodule. @@ -254,8 +264,8 @@ OPTIONS --force:: This option is only valid for add, deinit and update commands. When running add, allow adding an otherwise ignored submodule path. - When running deinit the submodule work trees will be removed even if - they contain local changes. + When running deinit the submodule working trees will be removed even + if they contain local changes. When running update (only effective with the checkout procedure), throw away local changes in submodules when switching to a different commit; and always run a checkout operation in the @@ -364,7 +374,7 @@ the submodule itself. for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. --recursive:: - This option is only valid for foreach, update and status commands. + This option is only valid for foreach, update, status and sync commands. Traverse submodules recursively. The operation is performed not only in the submodules of the current repo, but also in any nested submodules inside those submodules (and so on). @@ -374,6 +384,11 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. clone with a history truncated to the specified number of revisions. See linkgit:git-clone[1] +-j <n>:: +--jobs <n>:: + This option is only valid for the update command. + Clone new submodules in parallel with as many jobs. + Defaults to the `submodule.fetchJobs` option. <path>...:: Paths to submodule(s). When specified this will restrict the command diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 11d1e2fc66..fb23a98a17 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -174,6 +174,9 @@ Skip "branches" and "tags" of first level directories;; (including automatic fetches due to 'clone', 'dcommit', 'rebase', etc) on a given repository. '--ignore-paths' takes precedence over '--include-paths'. ++ +[verse] +config key: svn-remote.<name>.include-paths --log-window-size=<n>;; Fetch <n> log entries per request when scanning Subversion history. @@ -1031,6 +1034,8 @@ listed below are allowed: url = http://server.org/svn fetch = trunk/project-a:refs/remotes/project-a/trunk branches = branches/*/project-a:refs/remotes/project-a/branches/* + branches = branches/release_*:refs/remotes/project-a/branches/release_* + branches = branches/re*se:refs/remotes/project-a/branches/* tags = tags/*/project-a:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ @@ -1041,6 +1046,16 @@ independent path component (surrounded by '/' or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'. +Also note that only one asterisk is allowed per word. For example: + + branches = branches/re*se:refs/remotes/project-a/branches/* + +will match branches 'release', 'rese', 're123se', however + + branches = branches/re*s*e:refs/remotes/project-a/branches/* + +will produce an error. + It is also possible to fetch a subset of branches or tags by using a comma-separated list of names within braces. For example: diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 034d10d633..abab4814ec 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -9,12 +9,12 @@ git-tag - Create, list, delete or verify a tag object signed with GPG SYNOPSIS -------- [verse] -'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] +'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>] - [--column[=<options>] | --no-column] [<pattern>...] - [<pattern>...] + [--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>] + [--format=<format>] [--[no-]merged [<commit>]] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION @@ -25,19 +25,19 @@ to delete, list or verify tags. Unless `-f` is given, the named tag must not yet exist. -If one of `-a`, `-s`, or `-u <key-id>` is passed, the command +If one of `-a`, `-s`, or `-u <keyid>` is passed, the command creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. -If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` +If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>` are absent, `-a` is implied. Otherwise just a tag reference for the SHA-1 object name of the commit object is created (i.e. a lightweight tag). A GnuPG signed tag object will be created when `-s` or `-u -<key-id>` is used. When `-u <key-id>` is not used, the +<keyid>` is used. When `-u <keyid>` is not used, the committer identity for the current user is used to find the GnuPG key for signing. The configuration variable `gpg.program` is used to specify custom GnuPG binary. @@ -64,8 +64,8 @@ OPTIONS --sign:: Make a GPG-signed tag, using the default e-mail address's key. --u <key-id>:: ---local-user=<key-id>:: +-u <keyid>:: +--local-user=<keyid>:: Make a GPG-signed tag, using the given key. -f:: @@ -95,14 +95,16 @@ OPTIONS using fnmatch(3)). Multiple patterns may be given; if any of them matches, the tag is shown. ---sort=<type>:: - Sort in a specific order. Supported type is "refname" - (lexicographic order), "version:refname" or "v:refname" (tag +--sort=<key>:: + Sort based on the key given. Prefix `-` to sort in + descending order of the value. You may use the --sort=<key> option + multiple times, in which case the last key becomes the primary + key. Also supports "version:refname" or "v:refname" (tag names are treated as versions). The "version:refname" sort order can also be affected by the - "versionsort.prereleaseSuffix" configuration variable. Prepend - "-" to reverse sort order. When this option is not given, the - sort order defaults to the value configured for the 'tag.sort' + "versionsort.prereleaseSuffix" configuration variable. + The keys supported are the same as those in `git for-each-ref`. + Sort order defaults to the value configured for the 'tag.sort' variable if it exists, or lexicographic order otherwise. See linkgit:git-config[1]. @@ -126,14 +128,14 @@ This option is only applicable when listing tags without annotation lines. Use the given tag message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. - Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` + Implies `-a` if none of `-a`, `-s`, or `-u <keyid>` is given. -F <file>:: --file=<file>:: Take the tag message from the given file. Use '-' to read the message from the standard input. - Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` + Implies `-a` if none of `-a`, `-s`, or `-u <keyid>` is given. --cleanup=<mode>:: @@ -143,6 +145,9 @@ This option is only applicable when listing tags without annotation lines. all, 'whitespace' removes just leading/trailing whitespace lines and 'strip' removes both whitespace and commentary. +--create-reflog:: + Create a reflog for the tag. + <tagname>:: The name of the tag to create, delete, or describe. The new tag name must pass all checks defined by @@ -154,6 +159,16 @@ This option is only applicable when listing tags without annotation lines. The object that the new tag will refer to, usually a commit. Defaults to HEAD. +<format>:: + A string that interpolates `%(fieldname)` from the object + pointed at by a ref being shown. The format is the same as + that of linkgit:git-for-each-ref[1]. When unspecified, + defaults to `%(refname:strip=2)`. + +--[no-]merged [<commit>]:: + Only list tags whose tips are reachable, or not reachable + if '--no-merged' is used, from the specified commit ('HEAD' + if not specified). CONFIGURATION ------------- @@ -164,7 +179,7 @@ it in the repository configuration as follows: ------------------------------------- [user] - signingKey = <gpg-key-id> + signingKey = <gpg-keyid> ------------------------------------- diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt index 78a0d955ec..2f4ff50156 100644 --- a/Documentation/git-tools.txt +++ b/Documentation/git-tools.txt @@ -1,118 +1,10 @@ -A short Git tools survey -======================== +Git Tools +========= +When Git was young, people looking for third-party Git-related tools came +to the Git project itself to find them, thus a list of such tools was +maintained here. These days, however, search engines fill that role much +more efficiently, so this manually-maintained list has been retired. -Introduction ------------- - -Apart from Git contrib/ area there are some others third-party tools -you may want to look. - -This document presents a brief summary of each tool and the corresponding -link. - - -Alternative/Augmentative Porcelains ------------------------------------ - - - *Cogito* (http://www.kernel.org/pub/software/scm/cogito/) - - Cogito is a version control system layered on top of the Git tree history - storage system. It aims at seamless user interface and ease of use, - providing generally smoother user experience than the "raw" Core Git - itself and indeed many other version control systems. - - Cogito is no longer maintained as most of its functionality - is now in core Git. - - - - *pg* (http://www.spearce.org/category/projects/scm/pg/) - - pg is a shell script wrapper around Git to help the user manage a set of - patches to files. pg is somewhat like quilt or StGit, but it does have a - slightly different feature set. - - - - *StGit* (http://www.procode.org/stgit/) - - Stacked Git provides a quilt-like patch management functionality in the - Git environment. You can easily manage your patches in the scope of Git - until they get merged upstream. - - -History Viewers ---------------- - - - *gitk* (shipped with git-core) - - gitk is a simple Tk GUI for browsing history of Git repositories easily. - - - - *gitview* (contrib/) - - gitview is a GTK based repository browser for Git - - - - *gitweb* (shipped with git-core) - - Gitweb provides full-fledged web interface for Git repositories. - - - - *qgit* (http://digilander.libero.it/mcostalba/) - - QGit is a git/StGit GUI viewer built on Qt/C++. QGit could be used - to browse history and directory tree, view annotated files, commit - changes cherry picking single files or applying patches. - Currently it is the fastest and most feature rich among the Git - viewers and commit tools. - - - *tig* (http://jonas.nitro.dk/tig/) - - tig by Jonas Fonseca is a simple Git repository browser - written using ncurses. Basically, it just acts as a front-end - for git-log and git-show/git-diff. Additionally, you can also - use it as a pager for Git commands. - - -Foreign SCM interface ---------------------- - - - *git-svn* (shipped with git-core) - - git-svn is a simple conduit for changesets between a single Subversion - branch and Git. - - - - *quilt2git / git2quilt* (http://home-tj.org/wiki/index.php/Misc) - - These utilities convert patch series in a quilt repository and commit - series in Git back and forth. - - - - *hg-to-git* (contrib/) - - hg-to-git converts a Mercurial repository into a Git one, and - preserves the full branch history in the process. hg-to-git can - also be used in an incremental way to keep the Git repository - in sync with the master Mercurial repository. - - -Others ------- - - - *(h)gct* (http://www.cyd.liu.se/users/~freku045/gct/) - - Commit Tool or (h)gct is a GUI enabled commit tool for Git and - Mercurial (hg). It allows the user to view diffs, select which files - to committed (or ignored / reverted) write commit messages and - perform the commit itself. - - - *git.el* (contrib/) - - This is an Emacs interface for Git. The user interface is modelled on - pcl-cvs. It has been developed on Emacs 21 and will probably need some - tweaking to work on XEmacs. - - -http://git.or.cz/gitwiki/InterfacesFrontendsAndTools has more -comprehensive list. +See also the `contrib/` area, and the Git wiki: +http://git.or.cz/gitwiki/InterfacesFrontendsAndTools diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index 07d432988f..3e887d1610 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -9,7 +9,7 @@ git-unpack-objects - Unpack objects from a packed archive SYNOPSIS -------- [verse] -'git unpack-objects' [-n] [-q] [-r] [--strict] < <packfile> +'git unpack-objects' [-n] [-q] [-r] [--strict] DESCRIPTION diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index aff01798cd..c6cbed189c 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -17,6 +17,8 @@ SYNOPSIS [--[no-]assume-unchanged] [--[no-]skip-worktree] [--ignore-submodules] + [--[no-]split-index] + [--[no-|test-|force-]untracked-cache] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] [-z] [--stdin] [--index-version <n>] @@ -170,6 +172,33 @@ may not support it yet. the shared index file. This mode is designed for very large indexes that take a significant amount of time to read or write. +--untracked-cache:: +--no-untracked-cache:: + Enable or disable untracked cache feature. Please use + `--test-untracked-cache` before enabling it. ++ +These options take effect whatever the value of the `core.untrackedCache` +configuration variable (see linkgit:git-config[1]). But a warning is +emitted when the change goes against the configured value, as the +configured value will take effect next time the index is read and this +will remove the intended effect of the option. + +--test-untracked-cache:: + Only perform tests on the working directory to make sure + untracked cache can be used. You have to manually enable + untracked cache using `--untracked-cache` or + `--force-untracked-cache` or the `core.untrackedCache` + configuration variable afterwards if you really want to use + it. If a test fails the exit code is 1 and a message + explains what is not working as needed, otherwise the exit + code is 0 and OK is printed. + +--force-untracked-cache:: + Same as `--untracked-cache`. Provided for backwards + compatibility with older versions of Git where + `--untracked-cache` used to imply `--test-untracked-cache` but + this option would enable the extension unconditionally. + \--:: Do not interpret any more arguments as options. @@ -359,6 +388,37 @@ Although this bit looks similar to assume-unchanged bit, its goal is different from assume-unchanged bit's. Skip-worktree also takes precedence over assume-unchanged bit when both are set. +Untracked cache +--------------- + +This cache is meant to speed up commands that involve determining +untracked files such as `git status`. + +This feature works by recording the mtime of the working tree +directories and then omitting reading directories and stat calls +against files in those directories whose mtime hasn't changed. For +this to work the underlying operating system and file system must +change the `st_mtime` field of directories if files in the directory +are added, modified or deleted. + +You can test whether the filesystem supports that with the +`--test-untracked-cache` option. The `--untracked-cache` option used +to implicitly perform that test in older versions of Git, but that's +no longer the case. + +If you want to enable (or disable) this feature, it is easier to use +the `core.untrackedCache` configuration variable (see +linkgit:git-config[1]) than using the `--untracked-cache` option to +`git update-index` in each repository, especially if you want to do so +across all repositories you use, because you can set the configuration +variable to `true` (or `false`) in your `$HOME/.gitconfig` just once +and have it affect all repositories you touch. + +When the `core.untrackedCache` configuration variable is changed, the +untracked cache is added to or removed from the index the next time a +command reads the index; while when `--[no-|force-]untracked-cache` +are used, the untracked cache is immediately added to or removed from +the index. Configuration ------------- @@ -384,6 +444,9 @@ It can be useful when the inode change time is regularly modified by something outside Git (file system crawlers and backup systems use ctime for marking files processed) (see linkgit:git-config[1]). +The untracked cache extension can be enabled by the +`core.untrackedCache` configuration variable (see +linkgit:git-config[1]). SEE ALSO -------- diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index c8f5ae5cb3..969bfab2ab 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -8,7 +8,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- [verse] -'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) +'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) DESCRIPTION ----------- @@ -67,6 +67,9 @@ performs all modifications together. Specify commands of the form: verify SP <ref> [SP <oldvalue>] LF option SP <opt> LF +With `--create-reflog`, update-ref will create a reflog for each ref +even if one would not ordinarily be created. + Quote fields containing whitespace as if they were strings in C source code; i.e., surrounded by double-quotes and with backslash escapes. Use 40 "0" characters or the empty string to specify a zero value. To diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt index cbef61ba88..fba0f1c1b2 100644 --- a/Documentation/git-upload-archive.txt +++ b/Documentation/git-upload-archive.txt @@ -1,5 +1,5 @@ git-upload-archive(1) -==================== +===================== NAME ---- diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt index 9413e2802a..ecf4da16cf 100644 --- a/Documentation/git-verify-commit.txt +++ b/Documentation/git-verify-commit.txt @@ -16,6 +16,10 @@ Validates the gpg signature created by 'git commit -S'. OPTIONS ------- +--raw:: + Print the raw gpg status output to standard error instead of the normal + human-readable output. + -v:: --verbose:: Print the contents of the commit object before validating it. diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index f88ba96f02..d590edcebd 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -16,6 +16,10 @@ Validates the gpg signature created by 'git tag'. OPTIONS ------- +--raw:: + Print the raw gpg status output to standard error instead of the normal + human-readable output. + -v:: --verbose:: Print the contents of the tag object before validating it. diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt new file mode 100644 index 0000000000..c62234538b --- /dev/null +++ b/Documentation/git-worktree.txt @@ -0,0 +1,234 @@ +git-worktree(1) +=============== + +NAME +---- +git-worktree - Manage multiple working trees + + +SYNOPSIS +-------- +[verse] +'git worktree add' [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>] +'git worktree prune' [-n] [-v] [--expire <expire>] +'git worktree list' [--porcelain] + +DESCRIPTION +----------- + +Manage multiple working trees attached to the same repository. + +A git repository can support multiple working trees, allowing you to check +out more than one branch at a time. With `git worktree add` a new working +tree is associated with the repository. This new working tree is called a +"linked working tree" as opposed to the "main working tree" prepared by "git +init" or "git clone". A repository has one main working tree (if it's not a +bare repository) and zero or more linked working trees. + +When you are done with a linked working tree you can simply delete it. +The working tree's administrative files in the repository (see +"DETAILS" below) will eventually be removed automatically (see +`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run +`git worktree prune` in the main or any linked working tree to +clean up any stale administrative files. + +If you move a linked working tree, you need to manually update the +administrative files so that they do not get pruned automatically. See +section "DETAILS" for more information. + +If a linked working tree is stored on a portable device or network share +which is not always mounted, you can prevent its administrative files from +being pruned by creating a file named 'locked' alongside the other +administrative files, optionally containing a plain text reason that +pruning should be suppressed. See section "DETAILS" for more information. + +COMMANDS +-------- +add <path> [<branch>]:: + +Create `<path>` and checkout `<branch>` into it. The new working directory +is linked to the current repository, sharing everything except working +directory specific files such as HEAD, index, etc. ++ +If `<branch>` is omitted and neither `-b` nor `-B` nor `--detached` used, +then, as a convenience, a new branch based at HEAD is created automatically, +as if `-b $(basename <path>)` was specified. + +prune:: + +Prune working tree information in $GIT_DIR/worktrees. + +list:: + +List details of each worktree. The main worktree is listed first, followed by +each of the linked worktrees. The output details include if the worktree is +bare, the revision currently checked out, and the branch currently checked out +(or 'detached HEAD' if none). + +OPTIONS +------- + +-f:: +--force:: + By default, `add` refuses to create a new working tree when `<branch>` + is already checked out by another working tree. This option overrides + that safeguard. + +-b <new-branch>:: +-B <new-branch>:: + With `add`, create a new branch named `<new-branch>` starting at + `<branch>`, and check out `<new-branch>` into the new working tree. + If `<branch>` is omitted, it defaults to HEAD. + By default, `-b` refuses to create a new branch if it already + exists. `-B` overrides this safeguard, resetting `<new-branch>` to + `<branch>`. + +--detach:: + With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" + in linkgit:git-checkout[1]. + +--[no-]checkout:: + By default, `add` checks out `<branch>`, however, `--no-checkout` can + be used to suppress checkout in order to make customizations, + such as configuring sparse-checkout. See "Sparse checkout" + in linkgit:git-read-tree[1]. + +-n:: +--dry-run:: + With `prune`, do not remove anything; just report what it would + remove. + +--porcelain:: + With `list`, output in an easy-to-parse format for scripts. + This format will remain stable across Git versions and regardless of user + configuration. See below for details. + +-v:: +--verbose:: + With `prune`, report all removals. + +--expire <time>:: + With `prune`, only expire unused working trees older than <time>. + +DETAILS +------- +Each linked working tree has a private sub-directory in the repository's +$GIT_DIR/worktrees directory. The private sub-directory's name is usually +the base name of the linked working tree's path, possibly appended with a +number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the +command `git worktree add /path/other/test-next next` creates the linked +working tree in `/path/other/test-next` and also creates a +`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` +if `test-next` is already taken). + +Within a linked working tree, $GIT_DIR is set to point to this private +directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and +$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR +(e.g. `/path/main/.git`). These settings are made in a `.git` file located at +the top directory of the linked working tree. + +Path resolution via `git rev-parse --git-path` uses either +$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the +linked working tree `git rev-parse --git-path HEAD` returns +`/path/main/.git/worktrees/test-next/HEAD` (not +`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git +rev-parse --git-path refs/heads/master` uses +$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, +since refs are shared across all working trees. + +See linkgit:gitrepository-layout[5] for more information. The rule of +thumb is do not make any assumption about whether a path belongs to +$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something +inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. + +If you move a linked working tree, you need to update the 'gitdir' file +in the entry's directory. For example, if a linked working tree is moved +to `/newpath/test-next` and its `.git` file points to +`/path/main/.git/worktrees/test-next`, then update +`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` +instead. + +To prevent a $GIT_DIR/worktrees entry from being pruned (which +can be useful in some situations, such as when the +entry's working tree is stored on a portable device), add a file named +'locked' to the entry's directory. The file contains the reason in +plain text. For example, if a linked working tree's `.git` file points +to `/path/main/.git/worktrees/test-next` then a file named +`/path/main/.git/worktrees/test-next/locked` will prevent the +`test-next` entry from being pruned. See +linkgit:gitrepository-layout[5] for details. + +LIST OUTPUT FORMAT +------------------ +The worktree list command has two output formats. The default format shows the +details on a single line with columns. For example: + +------------ +S git worktree list +/path/to/bare-source (bare) +/path/to/linked-worktree abcd1234 [master] +/path/to/other-linked-worktree 1234abc (detached HEAD) +------------ + +Porcelain Format +~~~~~~~~~~~~~~~~ +The porcelain format has a line per attribute. Attributes are listed with a +label and value separated by a single space. Boolean attributes (like 'bare' +and 'detached') are listed as a label only, and are only present if and only +if the value is true. An empty line indicates the end of a worktree. For +example: + +------------ +S git worktree list --porcelain +worktree /path/to/bare-source +bare + +worktree /path/to/linked-worktree +HEAD abcd1234abcd1234abcd1234abcd1234abcd1234 +branch refs/heads/master + +worktree /path/to/other-linked-worktree +HEAD 1234abc1234abc1234abc1234abc1234abc1234a +detached + +------------ + +EXAMPLES +-------- +You are in the middle of a refactoring session and your boss comes in and +demands that you fix something immediately. You might typically use +linkgit:git-stash[1] to store your changes away temporarily, however, your +working tree is in such a state of disarray (with new, moved, and removed +files, and other bits and pieces strewn around) that you don't want to risk +disturbing any of it. Instead, you create a temporary linked working tree to +make the emergency fix, remove it when done, and then resume your earlier +refactoring session. + +------------ +$ git worktree add -b emergency-fix ../temp master +$ pushd ../temp +# ... hack hack hack ... +$ git commit -a -m 'emergency fix for boss' +$ popd +$ rm -rf ../temp +$ git worktree prune +------------ + +BUGS +---- +Multiple checkout in general is still experimental, and the support +for submodules is incomplete. It is NOT recommended to make multiple +checkouts of a superproject. + +git-worktree could provide more automation for tasks currently +performed manually, such as: + +- `remove` to remove a linked working tree and its administrative files (and + warn if the working tree is dirty) +- `mv` to move or rename a working tree and update its administrative files +- `lock` to prevent automatic pruning of administrative files (for instance, + for a working tree on a portable device) + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index 889fa51f90..5490d3c601 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,6 +43,49 @@ unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: +* link:v2.9.0/git.html[documentation for release 2.9] + +* release notes for + link:RelNotes/2.9.0.txt[2.9]. + +* link:v2.8.4/git.html[documentation for release 2.8.4] + +* release notes for + link:RelNotes/2.8.4.txt[2.8.4], + link:RelNotes/2.8.3.txt[2.8.3], + link:RelNotes/2.8.2.txt[2.8.2], + link:RelNotes/2.8.1.txt[2.8.1], + link:RelNotes/2.8.0.txt[2.8]. + +* link:v2.7.3/git.html[documentation for release 2.7.3] + +* release notes for + link:RelNotes/2.7.3.txt[2.7.3], + link:RelNotes/2.7.2.txt[2.7.2], + link:RelNotes/2.7.1.txt[2.7.1], + link:RelNotes/2.7.0.txt[2.7]. + +* link:v2.6.6/git.html[documentation for release 2.6.6] + +* release notes for + link:RelNotes/2.6.6.txt[2.6.6], + link:RelNotes/2.6.5.txt[2.6.5], + link:RelNotes/2.6.4.txt[2.6.4], + link:RelNotes/2.6.3.txt[2.6.3], + link:RelNotes/2.6.2.txt[2.6.2], + link:RelNotes/2.6.1.txt[2.6.1], + link:RelNotes/2.6.0.txt[2.6]. + +* link:v2.5.5/git.html[documentation for release 2.5.5] + +* release notes for + link:RelNotes/2.5.5.txt[2.5.5], + link:RelNotes/2.5.4.txt[2.5.4], + link:RelNotes/2.5.3.txt[2.5.3], + link:RelNotes/2.5.2.txt[2.5.2], + link:RelNotes/2.5.1.txt[2.5.1], + link:RelNotes/2.5.0.txt[2.5]. + * link:v2.4.11/git.html[documentation for release 2.4.11] * release notes for @@ -782,7 +825,7 @@ The Git Repository ~~~~~~~~~~~~~~~~~~ These environment variables apply to 'all' core Git commands. Nb: it is worth noting that they may be used/overridden by SCMS sitting above -Git so take care if using Cogito etc. +Git so take care if using a foreign front-end. 'GIT_INDEX_FILE':: This environment allows the specification of an alternate @@ -848,6 +891,15 @@ Git so take care if using Cogito etc. an explicit repository directory set via 'GIT_DIR' or on the command line. +'GIT_COMMON_DIR':: + If this variable is set to a path, non-worktree files that are + normally in $GIT_DIR will be taken from this path + instead. Worktree-specific files such as HEAD or index are + taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and + linkgit:git-worktree[1] for + details. This variable has lower precedence than other path + variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY... + Git Commits ~~~~~~~~~~~ 'GIT_AUTHOR_NAME':: @@ -1002,9 +1054,20 @@ Unsetting the variable, or setting it to empty, "0" or Enables trace messages for all packets coming in or out of a given program. This can help with debugging object negotiation or other protocol issues. Tracing is turned off at a packet - starting with "PACK". + starting with "PACK" (but see 'GIT_TRACE_PACKFILE' below). See 'GIT_TRACE' for available trace output options. +'GIT_TRACE_PACKFILE':: + Enables tracing of packfiles sent or received by a + given program. Unlike other trace output, this trace is + verbatim: no headers, and no quoting of binary data. You almost + certainly want to direct into a file (e.g., + `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on + the terminal or mixing it with other trace output. ++ +Note that this is currently only implemented for the client side +of clones and fetches. + 'GIT_TRACE_PERFORMANCE':: Enables performance related trace messages, e.g. total execution time of each Git command. @@ -1020,7 +1083,7 @@ Unsetting the variable, or setting it to empty, "0" or cloning of shallow repositories. See 'GIT_TRACE' for available trace output options. -GIT_LITERAL_PATHSPECS:: +'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 @@ -1029,15 +1092,15 @@ GIT_LITERAL_PATHSPECS:: literal paths to Git (e.g., paths previously given to you by `git ls-tree`, `--raw` diff output, etc). -GIT_GLOB_PATHSPECS:: +'GIT_GLOB_PATHSPECS':: Setting this variable to `1` will cause Git to treat all pathspecs as glob patterns (aka "glob" magic). -GIT_NOGLOB_PATHSPECS:: +'GIT_NOGLOB_PATHSPECS':: Setting this variable to `1` will cause Git to treat all pathspecs as literal (aka "literal" magic). -GIT_ICASE_PATHSPECS:: +'GIT_ICASE_PATHSPECS':: Setting this variable to `1` will cause Git to treat all pathspecs as case-insensitive. @@ -1051,7 +1114,7 @@ GIT_ICASE_PATHSPECS:: variable when it is invoked as the top level command by the end user, to be recorded in the body of the reflog. -`GIT_REF_PARANOIA`:: +'GIT_REF_PARANOIA':: If set to `1`, include broken or badly named refs when iterating over lists of refs. In a normal, non-corrupted repository, this does nothing. However, enabling it may help git to detect and @@ -1062,7 +1125,7 @@ GIT_ICASE_PATHSPECS:: an operation has touched every ref (e.g., because you are cloning a repository to make a backup). -`GIT_ALLOW_PROTOCOL`:: +'GIT_ALLOW_PROTOCOL':: If set, provide a colon-separated list of protocols which are allowed to be used with fetch/push/clone. This is useful to restrict recursive submodule initialization from an untrusted @@ -1078,9 +1141,7 @@ GIT_ICASE_PATHSPECS:: connection (or proxy, if configured) - `ssh`: git over ssh (including `host:path` syntax, - `git+ssh://`, etc). - - - `rsync`: git over rsync + `ssh://`, etc). - `http`: git over http, both "smart http" and "dumb http". Note that this does _not_ include `https`; if you want both, diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 70899b3023..e3b1de8033 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -527,6 +527,8 @@ patterns are available: - `fortran` suitable for source code in the Fortran language. +- `fountain` suitable for Fountain documents. + - `html` suitable for HTML/XHTML documents. - `java` suitable for source code in the Java language. @@ -774,7 +776,7 @@ To define a custom merge driver `filfre`, add a section to your ---------------------------------------------------------------- [merge "filfre"] name = feel-free merge driver - driver = filfre %O %A %B + driver = filfre %O %A %B %L %P recursive = binary ---------------------------------------------------------------- @@ -800,6 +802,9 @@ merge between common ancestors, when there are more than one. When left unspecified, the driver itself is used for both internal merge and the final merge. +The merge driver can learn the pathname in which the merged result +will be stored via placeholder `%P`. + `conflict-marker-size` ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 36e9ab3e16..15b3bfa8db 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -710,7 +710,7 @@ files). Again, this can all be simplified with ---------------- -$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git +$ git clone git://git.kernel.org/pub/scm/git/git.git/ my-git $ cd my-git $ git checkout ---------------- @@ -1011,20 +1011,6 @@ $ git fetch <remote-repository> One of the following transports can be used to name the repository to download from: -Rsync:: - `rsync://remote.machine/path/to/repo.git/` -+ -Rsync transport is usable for both uploading and downloading, -but is completely unaware of what git does, and can produce -unexpected results when you download from the public repository -while the repository owner is uploading into it via `rsync` -transport. Most notably, it could update the files under -`refs/` which holds the object name of the topmost commits -before uploading the files in `objects/` -- the downloader would -obtain head commit object name while that object itself is still -not available in the repository. For this reason, it is -considered deprecated. - SSH:: `remote.machine:/path/to/repo.git/` or + @@ -1430,7 +1416,7 @@ while, depending on how active your project is. When a repository is synchronized via `git push` and `git pull` objects packed in the source repository are usually stored -unpacked in the destination, unless rsync transport is used. +unpacked in the destination. While this allows you to use different packing strategies on both ends, it also means you may need to repack both repositories every once in a while. diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 1c75be0803..f3a75d1ce1 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -106,6 +106,11 @@ variable, each helper will be tried in turn, and may provide a username, password, or nothing. Once Git has acquired both a username and a password, no more helpers will be tried. +If `credential.helper` is configured to the empty string, this resets +the helper list to empty (so you may override a helper set by a +lower-priority config file by configuring the empty-string helper, +followed by whatever set of helpers you would like). + CREDENTIAL CONTEXTS ------------------- diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt index 7be6e64846..35473ad02f 100644 --- a/Documentation/giteveryday.txt +++ b/Documentation/giteveryday.txt @@ -1,5 +1,5 @@ giteveryday(7) -=============== +============== NAME ---- diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 7ba0ac965d..d82e912e55 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -7,24 +7,35 @@ githooks - Hooks used by Git SYNOPSIS -------- -$GIT_DIR/hooks/* +$GIT_DIR/hooks/* (or \`git config core.hooksPath`/*) DESCRIPTION ----------- -Hooks are little scripts you can place in `$GIT_DIR/hooks` -directory to trigger action at certain points. When -'git init' is run, a handful of example hooks are copied into the -`hooks` directory of the new repository, but by default they are -all disabled. To enable a hook, rename it by removing its `.sample` -suffix. +Hooks are programs you can place in a hooks directory to trigger +actions at certain points in git's execution. Hooks that don't have +the executable bit set are ignored. -NOTE: It is also a requirement for a given hook to be executable. -However - in a freshly initialized repository - the `.sample` files are -executable by default. +By default the hooks directory is `$GIT_DIR/hooks`, but that can be +changed via the `core.hooksPath` configuration variable (see +linkgit:git-config[1]). -This document describes the currently defined hooks. +Before Git invokes a hook, it changes its working directory to either +the root of the working tree in a non-bare repository, or to the +$GIT_DIR in a bare repository. + +Hooks can get their arguments via the environment, command-line +arguments, and stdin. See the documentation for each hook below for +details. + +'git init' may copy hooks to the new repository, depending on its +configuration. See the "TEMPLATE DIRECTORY" section in +linkgit:git-init[1] for details. When the rest of this document refers +to "default hooks" it's talking about the default template shipped +with Git. + +The currently supported hooks are described below. HOOKS ----- @@ -32,15 +43,15 @@ HOOKS applypatch-msg ~~~~~~~~~~~~~~ -This hook is invoked by 'git am' script. It takes a single +This hook is invoked by 'git am'. It takes a single parameter, the name of the file that holds the proposed commit -log message. Exiting with non-zero status causes -'git am' to abort before applying the patch. +log message. Exiting with a non-zero status causes 'git am' to abort +before applying the patch. The hook is allowed to edit the message file in place, and can be used to normalize the message into some project standard -format (if the project has one). It can also be used to refuse -the commit after inspecting the message file. +format. It can also be used to refuse the commit after inspecting +the message file. The default 'applypatch-msg' hook, when enabled, runs the 'commit-msg' hook, if the latter is enabled. @@ -73,10 +84,10 @@ pre-commit ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed -with `--no-verify` option. It takes no parameter, and is +with the `--no-verify` option. It takes no parameters, 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. +making a commit. Exiting with a non-zero status from this script +causes the 'git commit' command to abort before creating a commit. The default 'pre-commit' hook, when enabled, catches introduction of lines with trailing whitespaces and aborts the commit when @@ -115,15 +126,15 @@ commit-msg ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed -with `--no-verify` option. It takes a single parameter, the +with the `--no-verify` option. It takes a single parameter, the name of the file that holds the proposed commit log message. -Exiting with non-zero status causes the 'git commit' to +Exiting with a non-zero status causes the 'git commit' to abort. -The hook is allowed to edit the message file in place, and can -be used to normalize the message into some project standard -format (if the project has one). It can also be used to refuse -the commit after inspecting the message file. +The hook is allowed to edit the message file in place, and can be used +to normalize the message into some project standard format. It +can also be used to refuse the commit after inspecting the message +file. The default 'commit-msg' hook, when enabled, detects duplicate "Signed-off-by" lines, and aborts the commit if one is found. @@ -131,8 +142,8 @@ The default 'commit-msg' hook, when enabled, detects duplicate post-commit ~~~~~~~~~~~ -This hook is invoked by 'git commit'. It takes no -parameter, and is invoked after a commit is made. +This hook is invoked by 'git commit'. It takes no parameters, and is +invoked after a commit is made. This hook is meant primarily for notification, and cannot affect the outcome of 'git commit'. @@ -267,9 +278,11 @@ does not know the entire set of branches, so it would end up firing one e-mail per ref when used naively, though. The <<post-receive,'post-receive'>> hook is more suited to that. -Another use suggested on the mailing list is to use this hook to -implement access control which is finer grained than the one -based on filesystem group. +In an environment that restricts the users' access only to git +commands over the wire, this hook can be used to implement access +control without relying on filesystem ownership and group +membership. See linkgit:git-shell[1] for how you might use the login +shell to restrict the user's access to only git commands. Both standard output and standard error output are forwarded to 'git send-pack' on the other end, so you can simply `echo` messages @@ -397,7 +410,7 @@ preceding SP is also omitted. Currently, no commands pass any 'extra-info'. The hook always runs after the automatic note copying (see -"notes.rewrite.<command>" in linkgit:git-config.txt[1]) has happened, and +"notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and thus has access to these notes. The following command-specific comments apply: diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 82e2d15435..78e0b27c18 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -448,6 +448,9 @@ set by Git if the remote helper has the 'option' capability. 'option update-shallow {'true'|'false'}:: Allow to extend .git/shallow if the new refs require it. +'option pushcert {'true'|'false'}:: + GPG sign pushes. + SEE ALSO -------- linkgit:git-remote[1] diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 79653f3134..577ee844e0 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -46,6 +46,9 @@ of incomplete object store is not suitable to be published for use with dumb transports but otherwise is OK as long as `objects/info/alternates` points at the object stores it borrows from. ++ +This directory is ignored if $GIT_COMMON_DIR is set and +"$GIT_COMMON_DIR/objects" will be used instead. objects/[0-9a-f][0-9a-f]:: A newly created object is stored in its own file. @@ -92,7 +95,8 @@ refs:: References are stored in subdirectories of this directory. The 'git prune' command knows to preserve objects reachable from refs found in this directory and - its subdirectories. + its subdirectories. This directory is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/refs" will be used instead. refs/heads/`name`:: records tip-of-the-tree commit objects of branch `name` @@ -114,7 +118,8 @@ refs/replace/`<obj-sha1>`:: packed-refs:: records the same information as refs/heads/, refs/tags/, and friends record in a more efficient way. See - linkgit:git-pack-refs[1]. + linkgit:git-pack-refs[1]. This file is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/packed-refs" will be used instead. HEAD:: A symref (see glossary) to the `refs/heads/` namespace @@ -133,6 +138,11 @@ being a symref to point at the current branch. Such a state is often called 'detached HEAD.' See linkgit:git-checkout[1] for details. +config:: + Repository specific configuration file. This file is ignored + if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be + used instead. + branches:: A slightly deprecated way to store shorthands to be used to specify a URL to 'git fetch', 'git pull' and 'git push'. @@ -140,7 +150,10 @@ branches:: 'name' can be given to these commands in place of 'repository' argument. See the REMOTES section in linkgit:git-fetch[1] for details. This mechanism is legacy - and not likely to be found in modern repositories. + and not likely to be found in modern repositories. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/branches" will be used instead. + hooks:: Hooks are customization scripts used by various Git @@ -149,7 +162,9 @@ hooks:: default. To enable, the `.sample` suffix has to be removed from the filename by renaming. Read linkgit:githooks[5] for more details about - each hook. + each hook. This directory is ignored if $GIT_COMMON_DIR is set + and "$GIT_COMMON_DIR/hooks" will be used instead. + index:: The current index file for the repository. It is @@ -161,7 +176,8 @@ sharedindex.<SHA-1>:: info:: Additional information about the repository is recorded - in this directory. + in this directory. This directory is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/index" will be used instead. info/refs:: This file helps dumb transports discover what refs are @@ -201,12 +217,15 @@ remotes:: when interacting with remote repositories via 'git fetch', 'git pull' and 'git push' commands. See the REMOTES section in linkgit:git-fetch[1] for details. This mechanism is legacy - and not likely to be found in modern repositories. + and not likely to be found in modern repositories. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/remotes" will be used instead. logs:: - Records of changes made to refs are stored in this - directory. See linkgit:git-update-ref[1] - for more information. + Records of changes made to refs are stored in this directory. + See linkgit:git-update-ref[1] for more information. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/logs" will be used instead. logs/refs/heads/`name`:: Records all changes made to the branch tip named `name`. @@ -217,11 +236,46 @@ logs/refs/tags/`name`:: shallow:: This is similar to `info/grafts` but is internally used and maintained by shallow clone mechanism. See `--depth` - option to linkgit:git-clone[1] and linkgit:git-fetch[1]. + option to linkgit:git-clone[1] and linkgit:git-fetch[1]. This + file is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/shallow" will be used instead. + +commondir:: + If this file exists, $GIT_COMMON_DIR (see linkgit:git[1]) will + be set to the path specified in this file if it is not + explicitly set. If the specified path is relative, it is + relative to $GIT_DIR. The repository with commondir is + incomplete without the repository pointed by "commondir". modules:: Contains the git-repositories of the submodules. +worktrees:: + Contains administrative data for linked + working trees. Each subdirectory contains the working tree-related + part of a linked working tree. This directory is ignored if + $GIT_COMMON_DIR is set, in which case + "$GIT_COMMON_DIR/worktrees" will be used instead. + +worktrees/<id>/gitdir:: + A text file containing the absolute path back to the .git file + that points to here. This is used to check if the linked + repository has been manually removed and there is no need to + keep this directory any more. The mtime of this file should be + updated every time the linked repository is accessed. + +worktrees/<id>/locked:: + If this file exists, the linked working tree may be on a + portable device and not available. The presence of this file + prevents `worktrees/<id>` from being pruned either automatically + or manually by `git worktree prune`. The file may contain a string + explaining why the repository is locked. + +worktrees/<id>/link:: + If this file exists, it is a hard link to the linked .git + file. It is used to detect if the linked repository is + manually removed. + SEE ALSO -------- linkgit:git-init[1], diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt index c0ed6d1925..e903eb7860 100644 --- a/Documentation/gitrevisions.txt +++ b/Documentation/gitrevisions.txt @@ -1,5 +1,5 @@ gitrevisions(7) -================ +=============== NAME ---- diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index b00c67df46..b3b58d324e 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -451,7 +451,7 @@ perform clones and pulls using the ssh protocol: bob$ git clone alice.org:/home/alice/project myrepo ------------------------------------- -Alternatively, Git has a native protocol, or can use rsync or http; +Alternatively, Git has a native protocol, or can use http; see linkgit:git-pull[1] for details. Git can also be used in a CVS-like mode, with a central repository diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index a096e7ddf7..8a42270074 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -487,7 +487,7 @@ By default it is set to (), i.e. an empty list. This means that gitweb would not try to create project URL (to fetch) from project name. $projects_list_group_categories:: - Whether to enables the grouping of projects by category on the project + Whether to enable the grouping of projects by category on the project list page. The category of a project is determined by the `$GIT_DIR/category` file or the `gitweb.category` variable in each repository's configuration. Disabled by default (set to 0). diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index ab18f4baca..8ad29e61a9 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -145,7 +145,7 @@ current branch integrates with) obviously do not work, as there is no A fast-forward is a special type of <<def_merge,merge>> where you have a <<def_revision,revision>> and you are "merging" another <<def_branch,branch>>'s changes that happen to be a descendant of what - you have. In such these cases, you do not make a new <<def_merge,merge>> + you have. In such a case, you do not make a new <<def_merge,merge>> <<def_commit,commit>> but instead just update to his revision. This will happen frequently on a <<def_remote_tracking_branch,remote-tracking branch>> of a remote @@ -411,6 +411,28 @@ exclude;; core Git. Porcelains expose more of a <<def_SCM,SCM>> interface than the <<def_plumbing,plumbing>>. +[[def_per_worktree_ref]]per-worktree ref:: + Refs that are per-<<def_working_tree,worktree>>, rather than + global. This is presently only <<def_HEAD,HEAD>> and any refs + that start with `refs/bisect/`, but might later include other + unusual refs. + +[[def_pseudoref]]pseudoref:: + Pseudorefs are a class of files under `$GIT_DIR` which behave + like refs for the purposes of rev-parse, but which are treated + specially by git. Pseudorefs both have names that are all-caps, + and always start with a line consisting of a + <<def_SHA1,SHA-1>> followed by whitespace. So, HEAD is not a + pseudoref, because it is sometimes a symbolic ref. They might + optionally contain some additional data. `MERGE_HEAD` and + `CHERRY_PICK_HEAD` are examples. Unlike + <<def_per_worktree_ref,per-worktree refs>>, these files cannot + be symbolic refs, and never have reflogs. They also cannot be + updated through the normal ref update machinery. Instead, + they are updated by directly writing to the files. However, + they can be read as if they were refs, so `git rev-parse + MERGE_HEAD` will work. + [[def_pull]]pull:: Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and <<def_merge,merge>> it. See also linkgit:git-pull[1]. @@ -509,6 +531,11 @@ The most notable example is `HEAD`. "Secure Hash Algorithm 1"; a cryptographic hash function. In the context of Git used as a synonym for <<def_object_name,object name>>. +[[def_shallow_clone]]shallow clone:: + Mostly a synonym to <<def_shallow_repository,shallow repository>> + but the phrase makes it more explicit that it was created by + running `git clone --depth=...` command. + [[def_shallow_repository]]shallow repository:: A shallow <<def_repository,repository>> has an incomplete history some of whose <<def_commit,commits>> have <<def_parent,parents>> cauterized away (in other diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt index d7de5a3e9e..6d772bd927 100644 --- a/Documentation/howto/new-command.txt +++ b/Documentation/howto/new-command.txt @@ -95,7 +95,9 @@ your language, document it in the INSTALL file. 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-commands.txt -in the main directory. +in the main directory. If the new command is part of the typical Git +workflow and you believe it common enough to be mentioned in 'git help', +map this command to a common group in the column [common]. 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 diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index e9a1d5d25a..2dd79db5cb 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -1,18 +1,31 @@ -At the core level, Git is character encoding agnostic. - - - The pathnames recorded in the index and in the tree objects - are treated as uninterpreted sequences of non-NUL bytes. - What readdir(2) returns are what are recorded and compared - with the data Git keeps track of, which in turn are expected - to be what lstat(2) and creat(2) accepts. There is no such - thing as pathname encoding translation. +Git is to some extent character encoding agnostic. - The contents of the blob objects are uninterpreted sequences of bytes. There is no encoding translation at the core level. - - The commit log messages are uninterpreted sequences of non-NUL - bytes. + - Path names are encoded in UTF-8 normalization form C. This + applies to tree objects, the index file, ref names, as well as + path names in command line arguments, environment variables + and config files (`.git/config` (see linkgit:git-config[1]), + linkgit:gitignore[5], linkgit:gitattributes[5] and + linkgit:gitmodules[5]). ++ +Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly. + + - Commit log messages are typically encoded in UTF-8, but other + extended ASCII encodings are also supported. This includes + ISO-8859-x, CP125x and many others, but _not_ UTF-16/32, + EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, + EUC-x, CP9xx etc.). Although we encourage that the commit log messages are encoded in UTF-8, both the core and Git Porcelain are designed not to diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl new file mode 100755 index 0000000000..476cc30b83 --- /dev/null +++ b/Documentation/lint-gitlink.perl @@ -0,0 +1,71 @@ +#!/usr/bin/perl + +use File::Find; +use Getopt::Long; + +my $basedir = "."; +GetOptions("basedir=s" => \$basedir) + or die("Cannot parse command line arguments\n"); + +my $found_errors = 0; + +sub report { + my ($where, $what, $error) = @_; + print "$where: $error: $what\n"; + $found_errors = 1; +} + +sub grab_section { + my ($page) = @_; + open my $fh, "<", "$basedir/$page.txt"; + my $firstline = <$fh>; + chomp $firstline; + close $fh; + my ($section) = ($firstline =~ /.*\((\d)\)$/); + return $section; +} + +sub lint { + my ($file) = @_; + open my $fh, "<", $file + or return; + while (<$fh>) { + my $where = "$file:$."; + while (s/linkgit:((.*?)\[(\d)\])//) { + my ($target, $page, $section) = ($1, $2, $3); + + # De-AsciiDoc + $page =~ s/{litdd}/--/g; + + if ($page !~ /^git/) { + report($where, $target, "nongit link"); + next; + } + if (! -f "$basedir/$page.txt") { + report($where, $target, "no such source"); + next; + } + $real_section = grab_section($page); + if ($real_section != $section) { + report($where, $target, + "wrong section (should be $real_section)"); + next; + } + } + } + close $fh; +} + +sub lint_it { + lint($File::Find::name) if -f && /\.txt$/; +} + +if (!@ARGV) { + find({ wanted => \&lint_it, no_chdir => 1 }, $basedir); +} else { + for (@ARGV) { + lint($_); + } +} + +exit $found_errors; diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index f08e9b80c5..5b4a62e936 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -89,8 +89,11 @@ option can be used to override --squash. --verify-signatures:: --no-verify-signatures:: - Verify that the commits being merged have good and trusted GPG signatures - and abort the merge in case they do not. + Verify that the tip commit of the side branch being merged is + signed with a valid key, i.e. a key that has a valid uid: in the + default trust model, this means the signing key has been signed by + a trusted key. If the tip commit of the side branch is not signed + with a valid key, the merge is aborted. --summary:: --no-summary:: @@ -114,3 +117,11 @@ ifndef::git-pull[] reporting. endif::git-pull[] + +--allow-unrelated-histories:: + By default, `git merge` command refuses to merge histories + that do not share a common ancestor. This option can be + used to override this safety when merging histories of two + projects that started their lives independently. As that is + a very rare occasion, no configuration variable to enable + this by default exists and will not be added. diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 7bbd19b300..2eb92b9327 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -81,9 +81,17 @@ no-renormalize;; Disables the `renormalize` option. This overrides the `merge.renormalize` configuration variable. +no-renames;; + Turn off rename detection. + See also linkgit:git-diff[1] `--no-renames`. + +find-renames[=<n>];; + Turn on rename detection, optionally setting the similarity + threshold. This is the default. + See also linkgit:git-diff[1] `--find-renames`. + rename-threshold=<n>;; - Controls the similarity threshold used for rename detection. - See also linkgit:git-diff[1] `-M`. + Deprecated synonym for `find-renames=<n>`. subtree[=<path>];; This option is a more advanced form of 'subtree' strategy, where diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index dc865cbb27..29b19b992f 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -139,10 +139,12 @@ The placeholders are: - '%f': sanitized subject line, suitable for a filename - '%b': body - '%B': raw body (unwrapped subject and body) +ifndef::git-rev-list[] - '%N': commit notes +endif::git-rev-list[] - '%GG': raw verification message from GPG for a signed commit -- '%G?': show "G" for a Good signature, "B" for a Bad signature, "U" for a good, - untrusted signature and "N" for no signature +- '%G?': show "G" for a good (valid) signature, "B" for a bad signature, + "U" for a good signature with unknown validity and "N" for no signature - '%GS': show the name of the signer for a signed commit - '%GK': show the key used to sign a signed commit - '%gD': reflog selector, e.g., `refs/stash@{1}` diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 642af6e426..6c67182728 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -42,7 +42,22 @@ people using 80-column terminals. verbatim; this means that invalid sequences in the original commit may be copied to the output. ---notes[=<ref>]:: +--expand-tabs=<n>:: +--expand-tabs:: +--no-expand-tabs:: + Perform a tab expansion (replace each tab with enough spaces + to fill to the next display column that is multiple of '<n>') + in the log message before showing it in the output. + `--expand-tabs` is a short-hand for `--expand-tabs=8`, and + `--no-expand-tabs` is a short-hand for `--expand-tabs=0`, + which disables tab expansion. ++ +By default, tabs are expanded in pretty formats that indent the log +message by 4 spaces (i.e. 'medium', which is the default, 'full', +and 'fuller'). + +ifndef::git-rev-list[] +--notes[=<treeish>]:: Show the notes (see linkgit:git-notes[1]) that annotate the commit, when showing the commit log message. This is the default for `git log`, `git show` and `git whatchanged` commands when @@ -53,9 +68,10 @@ By default, the notes shown are from the notes refs listed in the 'core.notesRef' and 'notes.displayRef' variables (or corresponding environment overrides). See linkgit:git-config[1] for more details. + -With an optional '<ref>' argument, show this notes ref instead of the -default notes ref(s). The ref is taken to be in `refs/notes/` if it -is not qualified. +With an optional '<treeish>' argument, use the treeish to find the notes +to display. The treeish can specify the full refname when it begins +with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise +`refs/notes/` is prefixed to form a full name of the ref. + Multiple --notes options can be combined to control which notes are being displayed. Examples: "--notes=foo" will show only notes from @@ -69,10 +85,11 @@ being displayed. Examples: "--notes=foo" will show only notes from "--notes --notes=foo --no-notes --notes=bar" will only show notes from "refs/notes/bar". ---show-notes[=<ref>]:: +--show-notes[=<treeish>]:: --[no-]standard-notes:: These options are deprecated. Use the above --notes/--no-notes options instead. +endif::git-rev-list[] --show-signature:: Check the validity of a signed commit object by passing the signature diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 77ac439234..4f009d4424 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -58,9 +58,11 @@ endif::git-rev-list[] more than one `--grep=<pattern>`, commits whose message matches any of the given patterns are chosen (but see `--all-match`). +ifndef::git-rev-list[] + When `--show-notes` is in effect, the message from the notes is matched as if it were part of the log message. +endif::git-rev-list[] --all-match:: Limit the commits output to ones that match all given `--grep`, @@ -699,15 +701,19 @@ include::pretty-options.txt[] --relative-date:: Synonym for `--date=relative`. ---date=(relative|local|default|iso|iso-strict|rfc|short|raw):: +--date=<format>:: Only takes effect for dates shown in human-readable format, such as when using `--pretty`. `log.date` config variable sets a default - value for the log command's `--date` option. + value for the log command's `--date` option. By default, dates + are shown in the original time zone (either committer's or + author's). If `-local` is appended to the format (e.g., + `iso-local`), the user's local time zone is used instead. + `--date=relative` shows dates relative to the current time, -e.g. ``2 hours ago''. +e.g. ``2 hours ago''. The `-local` option cannot be used with +`--raw` or `--relative`. + -`--date=local` shows timestamps in user's local time zone. +`--date=local` is an alias for `--date=default-local`. + `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. The differences to the strict ISO 8601 format are: @@ -727,8 +733,18 @@ format, often found in email messages. + `--date=raw` shows the date in the internal raw Git format `%s %z` format. + -`--date=default` shows timestamps in the original time zone -(either committer's or author's). +`--date=format:...` feeds the format `...` to your system `strftime`. +Use `--date=format:%c` to show the date in your system locale's +preferred format. See the `strftime` manual for a complete list of +format placeholders. When using `-local`, the correct syntax is +`--date=format-local:...`. ++ +`--date=default` is the default format, and is similar to +`--date=rfc2822`, with a few exceptions: + + - there is no comma after the day-of-week + + - the time zone is omitted when the local time zone is used ifdef::git-rev-list[] --header:: diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 07961185fe..19314e3b7f 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -61,11 +61,11 @@ some output processing may assume ref names in UTF-8. '@':: '@' alone is a shortcut for 'HEAD'. -'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: +'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: A ref followed by the suffix '@' with a date specification enclosed in a brace - pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 - second ago\}' or '\{1979-02-26 18:30:00\}') specifies the value + pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1 + second ago}' or '{1979-02-26 18:30:00}') specifies the value of the ref at a prior point in time. This suffix may only be used immediately following a ref name and the ref must have an existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state @@ -73,7 +73,7 @@ some output processing may assume ref names in UTF-8. 'master' branch last week. If you want to look at commits made during certain times, see '--since' and '--until'. -'<refname>@\{<n>\}', e.g. 'master@\{1\}':: +'<refname>@{<n>}', e.g. 'master@\{1\}':: A ref followed by the suffix '@' with an ordinal specification enclosed in a brace pair (e.g. '\{1\}', '\{15\}') specifies the n-th prior value of that ref. For example 'master@\{1\}' @@ -82,13 +82,13 @@ some output processing may assume ref names in UTF-8. immediately following a ref name and the ref must have an existing log ('$GIT_DIR/logs/<refname>'). -'@\{<n>\}', e.g. '@\{1\}':: +'@{<n>}', e.g. '@\{1\}':: You can use the '@' construct with an empty ref part to get at a reflog entry of the current branch. For example, if you are on branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'. -'@\{-<n>\}', e.g. '@\{-1\}':: - The construct '@\{-<n>\}' means the <n>th branch/commit checked out +'@{-<n>}', e.g. '@{-1}':: + The construct '@{-<n>}' means the <n>th branch/commit checked out before the current one. '<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: @@ -98,6 +98,31 @@ some output processing may assume ref names in UTF-8. `branch.<name>.merge`). A missing branchname defaults to the current one. +'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: + The suffix '@\{push}' reports the branch "where we would push to" if + `git push` were run while `branchname` was checked out (or the current + 'HEAD' if no branchname is specified). Since our push destination is + in a remote repository, of course, we report the local tracking branch + that corresponds to that branch (i.e., something in 'refs/remotes/'). ++ +Here's an example to make it more clear: ++ +------------------------------ +$ git config push.default current +$ git config remote.pushdefault myfork +$ git checkout -b mybranch origin/master + +$ git rev-parse --symbolic-full-name @{upstream} +refs/remotes/origin/master + +$ git rev-parse --symbolic-full-name @{push} +refs/remotes/myfork/mybranch +------------------------------ ++ +Note in the example that we set up a triangular workflow, where we pull +from one location and push to another. In a non-triangular workflow, +'@\{push}' is the same as '@\{upstream}', and there is no need for it. + '<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of that commit object. '{caret}<n>' means the <n>th parent (i.e. @@ -114,7 +139,7 @@ some output processing may assume ref names in UTF-8. '<rev>{caret}1{caret}1{caret}1'. See below for an illustration of the usage of this form. -'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}':: +'<rev>{caret}{<type>}', e.g. 'v0.99.8{caret}\{commit\}':: A suffix '{caret}' followed by an object type name enclosed in brace pair means dereference the object at '<rev>' recursively until an object of type '<type>' is found or the object cannot be @@ -134,13 +159,13 @@ it does not have to be dereferenced even once to get to an object. 'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an existing tag object. -'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}':: +'<rev>{caret}{}', e.g. 'v0.99.8{caret}{}':: A suffix '{caret}' followed by an empty brace pair means the object could be a tag, and dereference the tag recursively until a non-tag object is found. -'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}':: +'<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}':: A suffix '{caret}' to a revision parameter, followed by a brace pair that contains a text led by a slash, is the same as the ':/fix nasty bug' syntax below except that @@ -151,11 +176,12 @@ existing tag object. A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is - reachable from any ref. If the commit message starts with a - '!' you have to repeat that; the special sequence ':/!', - followed by something else than '!', is reserved for now. - The regular expression can match any part of the commit message. To - match messages starting with a string, one can use e.g. ':/^foo'. + reachable from any ref. The regular expression can match any part of the + commit message. To match messages starting with a string, one can use + e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what + is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a + literal '!' character, followed by 'foo'. Any other sequence beginning with + ':/!' is reserved for now. '<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README':: A suffix ':' followed by a path names the blob or tree diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 1a797812fb..cfc063018c 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -46,6 +46,9 @@ 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_pushv`:: + Push a null-terminated array of strings onto the end of the array. + `argv_array_pop`:: Remove the final element from the array. If there are no elements in the array, do nothing. @@ -53,3 +56,10 @@ Functions `argv_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. + +`argv_array_detach`:: + Disconnect the `argv` member from the `argv_array` struct and + return it. The caller is responsible for freeing the memory used + by the array, and by the strings it references. After detaching, + the `argv_array` is in a reinitialized state and can be pushed + into again. diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index 0d8b99b368..20741f345e 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -63,13 +63,6 @@ parse for configuration, rather than looking in the usual files. Regular Specify whether include directives should be followed in parsed files. Regular `git_config` defaults to `1`. -There is a special version of `git_config` called `git_config_early`. -This version takes an additional parameter to specify the repository -config, instead of having it looked up via `git_path`. This is useful -early in a Git program before the repository has been found. Unless -you're working with early setup code, you probably don't want to use -this. - Reading Specific Files ---------------------- diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index e44426dd04..75368f26ca 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -243,7 +243,7 @@ appended to its command line, which is one of: The details of the credential will be provided on the helper's stdin 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). +FORMAT` in linkgit:git-credential[1] 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 @@ -268,4 +268,4 @@ See also linkgit:gitcredentials[7] -linkgit:git-config[5] (See configuration variables `credential.*`) +linkgit:git-config[1] (See configuration variables `credential.*`) diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt deleted file mode 100644 index 93b5f23e4c..0000000000 --- a/Documentation/technical/api-lockfile.txt +++ /dev/null @@ -1,220 +0,0 @@ -lockfile API -============ - -The lockfile API serves two purposes: - -* Mutual exclusion and atomic file updates. When we want to change a - file, we create a lockfile `<filename>.lock`, write the new file - contents into it, and then rename the lockfile to its final - destination `<filename>`. We create the `<filename>.lock` file with - `O_CREAT|O_EXCL` so that we can notice and fail if somebody else has - already locked the file, then atomically rename the lockfile to its - final destination to commit the changes and unlock the file. - -* Automatic cruft removal. If the program exits after we lock a file - but before the changes have been committed, we want to make sure - that we remove the lockfile. This is done by remembering the - lockfiles we have created in a linked list and setting up an - `atexit(3)` handler and a signal handler that clean up the - lockfiles. This mechanism ensures that outstanding lockfiles are - cleaned up if the program exits (including when `die()` is called) - or if the program dies on a signal. - -Please note that lockfiles only block other writers. Readers do not -block, but they are guaranteed to see either the old contents of the -file or the new contents of the file (assuming that the filesystem -implements `rename(2)` atomically). - - -Calling sequence ----------------- - -The caller: - -* Allocates a `struct lock_file` either as a static variable or on the - heap, initialized to zeros. Once you use the structure to call the - `hold_lock_file_*` family of functions, it belongs to the lockfile - subsystem and its storage must remain valid throughout the life of - the program (i.e. you cannot use an on-stack variable to hold this - structure). - -* Attempts to create a lockfile by passing that variable and the path - of the final destination (e.g. `$GIT_DIR/index`) to - `hold_lock_file_for_update` or `hold_lock_file_for_append`. - -* Writes new content for the destination file by either: - - * writing to the file descriptor returned by the `hold_lock_file_*` - functions (also available via `lock->fd`). - - * calling `fdopen_lock_file` to get a `FILE` pointer for the open - file and writing to the file using stdio. - -When finished writing, the caller can: - -* Close the file descriptor and rename the lockfile to its final - destination by calling `commit_lock_file` or `commit_lock_file_to`. - -* Close the file descriptor and remove the lockfile by calling - `rollback_lock_file`. - -* Close the file descriptor without removing or renaming the lockfile - by calling `close_lock_file`, and later call `commit_lock_file`, - `commit_lock_file_to`, `rollback_lock_file`, or `reopen_lock_file`. - -Even after the lockfile is committed or rolled back, the `lock_file` -object must not be freed or altered by the caller. However, it may be -reused; just pass it to another call of `hold_lock_file_for_update` or -`hold_lock_file_for_append`. - -If the program exits before you have called one of `commit_lock_file`, -`commit_lock_file_to`, `rollback_lock_file`, or `close_lock_file`, an -`atexit(3)` handler will close and remove the lockfile, rolling back -any uncommitted changes. - -If you need to close the file descriptor you obtained from a -`hold_lock_file_*` function yourself, do so by calling -`close_lock_file`. You should never call `close(2)` or `fclose(3)` -yourself! Otherwise the `struct lock_file` structure would still think -that the file descriptor needs to be closed, and a commit or rollback -would result in duplicate calls to `close(2)`. Worse yet, if you close -and then later open another file descriptor for a completely different -purpose, then a commit or rollback might close that unrelated file -descriptor. - - -Error handling --------------- - -The `hold_lock_file_*` functions return a file descriptor on success -or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see below). On -errors, `errno` describes the reason for failure. Errors can be -reported by passing `errno` to one of the following helper functions: - -unable_to_lock_message:: - - Append an appropriate error message to a `strbuf`. - -unable_to_lock_error:: - - Emit an appropriate error message using `error()`. - -unable_to_lock_die:: - - Emit an appropriate error message and `die()`. - -Similarly, `commit_lock_file`, `commit_lock_file_to`, and -`close_lock_file` return 0 on success. On failure they set `errno` -appropriately, do their best to roll back the lockfile, and return -1. - - -Flags ------ - -The following flags can be passed to `hold_lock_file_for_update` or -`hold_lock_file_for_append`: - -LOCK_NO_DEREF:: - - Usually symbolic links in the destination path are resolved - and the lockfile is created by adding ".lock" to the resolved - path. If `LOCK_NO_DEREF` is set, then the lockfile is created - by adding ".lock" to the path argument itself. This option is - used, for example, when locking a symbolic reference, which - for backwards-compatibility reasons can be a symbolic link - containing the name of the referred-to-reference. - -LOCK_DIE_ON_ERROR:: - - If a lock is already taken for the file, `die()` with an error - message. If this option is not specified, trying to lock a - file that is already locked returns -1 to the caller. - - -The functions -------------- - -hold_lock_file_for_update:: - - Take a pointer to `struct lock_file`, the path of the file to - be locked (e.g. `$GIT_DIR/index`) and a flags argument (see - above). Attempt to create a lockfile for the destination and - return the file descriptor for writing to the file. - -hold_lock_file_for_append:: - - Like `hold_lock_file_for_update`, but before returning copy - the existing contents of the file (if any) to the lockfile and - position its write pointer at the end of the file. - -fdopen_lock_file:: - - Associate a stdio stream with the lockfile. Return NULL - (*without* rolling back the lockfile) on error. The stream is - closed automatically when `close_lock_file` is called or when - the file is committed or rolled back. - -get_locked_file_path:: - - Return the path of the file that is locked by the specified - lock_file object. The caller must free the memory. - -commit_lock_file:: - - Take a pointer to the `struct lock_file` initialized with an - earlier call to `hold_lock_file_for_update` or - `hold_lock_file_for_append`, close the file descriptor, and - rename the lockfile to its final destination. Return 0 upon - success. On failure, roll back the lock file and return -1, - with `errno` set to the value from the failing call to - `close(2)` or `rename(2)`. It is a bug to call - `commit_lock_file` for a `lock_file` object that is not - currently locked. - -commit_lock_file_to:: - - Like `commit_lock_file()`, except that it takes an explicit - `path` argument to which the lockfile should be renamed. The - `path` must be on the same filesystem as the lock file. - -rollback_lock_file:: - - Take a pointer to the `struct lock_file` initialized with an - earlier call to `hold_lock_file_for_update` or - `hold_lock_file_for_append`, close the file descriptor and - remove the lockfile. It is a NOOP to call - `rollback_lock_file()` for a `lock_file` object that has - already been committed or rolled back. - -close_lock_file:: - - Take a pointer to the `struct lock_file` initialized with an - earlier call to `hold_lock_file_for_update` or - `hold_lock_file_for_append`. Close the file descriptor (and - the file pointer if it has been opened using - `fdopen_lock_file`). Return 0 upon success. On failure to - `close(2)`, return a negative value and roll back the lock - file. Usually `commit_lock_file`, `commit_lock_file_to`, or - `rollback_lock_file` should eventually be called if - `close_lock_file` succeeds. - -reopen_lock_file:: - - Re-open a lockfile that has been closed (using - `close_lock_file`) but not yet committed or rolled back. This - can be used to implement a sequence of operations like the - following: - - * Lock file. - - * Write new contents to lockfile, then `close_lock_file` to - cause the contents to be written to disk. - - * Pass the name of the lockfile to another program to allow it - (and nobody else) to inspect the contents you wrote, while - still holding the lock yourself. - - * `reopen_lock_file` to reopen the lockfile. Make further - updates to the contents. - - * `commit_lock_file` to make the final version permanent. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 1f2db31312..27bd701c0d 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -144,8 +144,12 @@ There are some macros to easily define options: `OPT_COUNTUP(short, long, &int_var, description)`:: Introduce a count-up option. - `int_var` is incremented on each use of `--option`, and - reset to zero with `--no-option`. + Each use of `--option` increments `int_var`, starting from zero + (even if initially negative), and `--no-option` resets it to + zero. To determine if `--option` or `--no-option` was encountered at + all, initialize `int_var` to a negative value, and if it is still + negative after parse_options(), then neither `--option` nor + `--no-option` was seen. `OPT_BIT(short, long, &int_var, description, mask)`:: Introduce a boolean option. @@ -168,6 +172,12 @@ There are some macros to easily define options: Introduce an option with integer argument. The integer is put into `int_var`. +`OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`:: + Introduce an option with a size argument. The argument must be a + non-negative integer and may include a suffix of 'k', 'm' or 'g' to + scale the provided value by 1024, 1024^2 or 1024^3 respectively. + The scaled value is put into `unsigned_long_var`. + `OPT_DATE(short, long, &int_var, description)`:: Introduce an option with date argument, see `approxidate()`. The timestamp is put into `int_var`. @@ -212,6 +222,26 @@ There are some macros to easily define options: Use it to hide deprecated options that are still to be recognized and ignored silently. +`OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`:: + Introduce an option that will be reconstructed into a char* string, + which must be initialized to NULL. This is useful when you need to + pass the command-line option to another command. Any previous value + will be overwritten, so this should only be used for options where + the last one specified on the command line wins. + +`OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`:: + Introduce an option where all instances of it on the command-line will + be reconstructed into an argv_array. This is useful when you need to + pass the command-line option, which can be specified multiple times, + to another command. + +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`:: + Define an "operation mode" option, only one of which in the same + group of "operating mode" options that share the same `int_var` + can be given by the user. `enum_val` is set to `int_var` when the + option is used, but an error is reported if other "operating mode" + option has already set its value to the same `int_var`. + The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt index 02adfd45d3..37379d8337 100644 --- a/Documentation/technical/api-ref-iteration.txt +++ b/Documentation/technical/api-ref-iteration.txt @@ -6,7 +6,7 @@ Iteration of refs is done by using an iterate function which will call a callback function for every ref. The callback function has this signature: - int handle_one_ref(const char *refname, const unsigned char *sha1, + int handle_one_ref(const char *refname, const struct object_id *oid, int flags, void *cb_data); There are different kinds of iterate functions which all take a diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt index 5d245aa9d1..f10941b2e8 100644 --- a/Documentation/technical/api-remote.txt +++ b/Documentation/technical/api-remote.txt @@ -51,6 +51,10 @@ struct remote The proxy to use for curl (http, https, ftp, etc.) URLs. +`http_proxy_authmethod`:: + + The method used for authenticating against `http_proxy`. + struct remotes can be found by name with remote_get(), and iterated through with for_each_remote(). remote_get(NULL) will return the default remote, given the current branch and configuration. @@ -97,10 +101,6 @@ It contains: The name of the remote listed in the configuration. -`remote`:: - - The struct remote for that remote. - `merge_name`:: An array of the "merge" lines in the configuration. diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index a9fdb45b93..8bf3e37f53 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -46,6 +46,13 @@ Functions The argument dir corresponds the member .dir. The argument env corresponds to the member .env. +`child_process_clear`:: + + Release the memory associated with the struct child_process. + Most users of the run-command API don't need to call this + function explicitly because `start_command` invokes it on + failure and `finish_command` calls it automatically already. + The functions above do the following: . If a system call failed, errno is set and -1 is returned. A diagnostic diff --git a/Documentation/technical/api-submodule-config.txt b/Documentation/technical/api-submodule-config.txt new file mode 100644 index 0000000000..941fa178dd --- /dev/null +++ b/Documentation/technical/api-submodule-config.txt @@ -0,0 +1,62 @@ +submodule config cache API +========================== + +The submodule config cache API allows to read submodule +configurations/information from specified revisions. Internally +information is lazily read into a cache that is used to avoid +unnecessary parsing of the same .gitmodule files. Lookups can be done by +submodule path or name. + +Usage +----- + +To initialize the cache with configurations from the worktree the caller +typically first calls `gitmodules_config()` to read values from the +worktree .gitmodules and then to overlay the local git config values +`parse_submodule_config_option()` from the config parsing +infrastructure. + +The caller can look up information about submodules by using the +`submodule_from_path()` or `submodule_from_name()` functions. They return +a `struct submodule` which contains the values. The API automatically +initializes and allocates the needed infrastructure on-demand. If the +caller does only want to lookup values from revisions the initialization +can be skipped. + +If the internal cache might grow too big or when the caller is done with +the API, all internally cached values can be freed with submodule_free(). + +Data Structures +--------------- + +`struct submodule`:: + + This structure is used to return the information about one + submodule for a certain revision. It is returned by the lookup + functions. + +Functions +--------- + +`void submodule_free()`:: + + Use these to free the internally cached values. + +`int parse_submodule_config_option(const char *var, const char *value)`:: + + Can be passed to the config parsing infrastructure to parse + local (worktree) submodule configurations. + +`const struct submodule *submodule_from_path(const unsigned char *commit_sha1, const char *path)`:: + + Lookup values for one submodule by its commit_sha1 and path. + +`const struct submodule *submodule_from_name(const unsigned char *commit_sha1, const char *name)`:: + + The same as above but lookup by name. + +If given the null_sha1 as commit_sha1 the local configuration of a +submodule will be returned (e.g. consolidated values from local git +configuration and the .gitmodules file in the worktree). + +For an example usage see test-submodule-config.c. diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt index 097a651d96..fadb5979c4 100644 --- a/Documentation/technical/api-trace.txt +++ b/Documentation/technical/api-trace.txt @@ -28,7 +28,7 @@ static struct trace_key trace_foo = TRACE_KEY_INIT(FOO); static void trace_print_foo(const char *message) { - trace_print_key(&trace_foo, message); + trace_printf_key(&trace_foo, "%s", message); } ------------ + @@ -95,3 +95,46 @@ for (;;) { } trace_performance(t, "frotz"); ------------ + +Bugs & Caveats +-------------- + +GIT_TRACE_* environment variables can be used to tell Git to show +trace output to its standard error stream. Git can often spawn a pager +internally to run its subcommand and send its standard output and +standard error to it. + +Because GIT_TRACE_PERFORMANCE trace is generated only at the very end +of the program with atexit(), which happens after the pager exits, it +would not work well if you send its log to the standard error output +and let Git spawn the pager at the same time. + +As a work around, you can for example use '--no-pager', or set +GIT_TRACE_PERFORMANCE to another file descriptor which is redirected +to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its +absolute path. + +For example instead of the following command which by default may not +print any performance information: + +------------ +GIT_TRACE_PERFORMANCE=2 git log -1 +------------ + +you may want to use: + +------------ +GIT_TRACE_PERFORMANCE=2 git --no-pager log -1 +------------ + +or: + +------------ +GIT_TRACE_PERFORMANCE=3 3>&2 git log -1 +------------ + +or: + +------------ +GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1 +------------ diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index 229f845dfa..1c561bdd92 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -319,7 +319,8 @@ Servers SHOULD support all capabilities defined here. Clients MUST send at least one "want" command in the request body. Clients MUST NOT reference an id in a "want" command which did not appear in the response obtained through ref discovery unless the -server advertises capability `allow-tip-sha1-in-want`. +server advertises capability `allow-tip-sha1-in-want` or +`allow-reachable-sha1-in-want`. compute_request = want_list have_list diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 35112e4966..ade0b0c445 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -170,7 +170,7 @@ Git index format The entries are written out in the top-down, depth-first order. The first entry represents the root level of the repository, followed by the - first subtree---let's call this A---of the root level (with its name + first subtree--let's call this A--of the root level (with its name relative to the root level), followed by the first subtree of A (with its name relative to A), ... @@ -233,3 +233,65 @@ Git index format The remaining index entries after replaced ones will be added to the final index. These added entries are also sorted by entry name then stage. + +== Untracked cache + + Untracked cache saves the untracked file list and necessary data to + verify the cache. The signature for this extension is { 'U', 'N', + 'T', 'R' }. + + The extension starts with + + - A sequence of NUL-terminated strings, preceded by the size of the + sequence in variable width encoding. Each string describes the + environment where the cache can be used. + + - Stat data of $GIT_DIR/info/exclude. See "Index entry" section from + ctime field until "file size". + + - Stat data of core.excludesfile + + - 32-bit dir_flags (see struct dir_struct) + + - 160-bit SHA-1 of $GIT_DIR/info/exclude. Null SHA-1 means the file + does not exist. + + - 160-bit SHA-1 of core.excludesfile. Null SHA-1 means the file does + not exist. + + - NUL-terminated string of per-dir exclude file name. This usually + is ".gitignore". + + - The number of following directory blocks, variable width + encoding. If this number is zero, the extension ends here with a + following NUL. + + - A number of directory blocks in depth-first-search order, each + consists of + + - The number of untracked entries, variable width encoding. + + - The number of sub-directory blocks, variable width encoding. + + - The directory name terminated by NUL. + + - A number of untracked file/dir names terminated by NUL. + +The remaining data of each directory block is grouped by type: + + - An ewah bitmap, the n-th bit marks whether the n-th directory has + valid untracked cache entries. + + - An ewah bitmap, the n-th bit records "check-only" bit of + read_directory_recursive() for the n-th directory. + + - An ewah bitmap, the n-th bit indicates whether SHA-1 and stat data + is valid for the n-th directory and exists in the next data. + + - An array of stat data. The n-th data corresponds with the n-th + "one" bit in the previous ewah bitmap. + + - An array of SHA-1. The n-th SHA-1 corresponds with the n-th "one" bit + in the previous ewah bitmap. + + - One NUL. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 4064fc796f..8b36343802 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -14,6 +14,14 @@ data. The protocol functions to have a server tell a client what is currently on the server, then for the two to negotiate the smallest amount of data to send in order to fully update one or the other. +pkt-line Format +--------------- + +The descriptions below build on the pkt-line format described in +protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless +otherwise noted the usual pkt-line LF rules apply: the sender SHOULD +include a LF, but the receiver MUST NOT complain if it is not present. + Transports ---------- There are three transports over which the packfile protocol is @@ -143,9 +151,6 @@ with the object name that each reference currently points to. 003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{} 0000 -Server SHOULD terminate each non-flush line using LF ("\n") terminator; -client MUST NOT complain if there is no terminator. - The returned response is a pkt-line stream describing each ref and its current value. The stream MUST be sorted by name according to the C locale ordering. @@ -165,15 +170,15 @@ MUST peel the ref if it's an annotated tag. flush-pkt no-refs = PKT-LINE(zero-id SP "capabilities^{}" - NUL capability-list LF) + NUL capability-list) list-of-refs = first-ref *other-ref first-ref = PKT-LINE(obj-id SP refname - NUL capability-list LF) + NUL capability-list) other-ref = PKT-LINE(other-tip / other-peeled) - other-tip = obj-id SP refname LF - other-peeled = obj-id SP refname "^{}" LF + other-tip = obj-id SP refname + other-peeled = obj-id SP refname "^{}" shallow = PKT-LINE("shallow" SP obj-id) @@ -216,8 +221,8 @@ out of what the server said it could do with the first 'want' line. depth-request = PKT-LINE("deepen" SP depth) - first-want = PKT-LINE("want" SP obj-id SP capability-list LF) - additional-want = PKT-LINE("want" SP obj-id LF) + first-want = PKT-LINE("want" SP obj-id SP capability-list) + additional-want = PKT-LINE("want" SP obj-id) depth = 1*DIGIT ---- @@ -284,7 +289,7 @@ so that there is always a block of 32 "in-flight on the wire" at a time. compute-end have-list = *have-line - have-line = PKT-LINE("have" SP obj-id LF) + have-line = PKT-LINE("have" SP obj-id) compute-end = flush-pkt / PKT-LINE("done") ---- @@ -348,10 +353,10 @@ Then the server will start sending its packfile data. ---- server-response = *ack_multi ack / nak - ack_multi = PKT-LINE("ACK" SP obj-id ack_status LF) + ack_multi = PKT-LINE("ACK" SP obj-id ack_status) ack_status = "continue" / "common" / "ready" - ack = PKT-LINE("ACK SP obj-id LF) - nak = PKT-LINE("NAK" LF) + ack = PKT-LINE("ACK" SP obj-id) + nak = PKT-LINE("NAK") ---- A simple clone may look like this (with no 'have' lines): @@ -467,10 +472,10 @@ references. ---- update-request = *shallow ( command-list | push-cert ) [packfile] - shallow = PKT-LINE("shallow" SP obj-id LF) + shallow = PKT-LINE("shallow" SP obj-id) - command-list = PKT-LINE(command NUL capability-list LF) - *PKT-LINE(command LF) + command-list = PKT-LINE(command NUL capability-list) + *PKT-LINE(command) flush-pkt command = create / delete / update @@ -521,7 +526,8 @@ Push Certificate A push certificate begins with a set of header lines. After the header and an empty line, the protocol commands follow, one per -line. +line. Note that the trailing LF in push-cert PKT-LINEs is _not_ +optional; it must be present. Currently, the following header fields are defined: @@ -560,12 +566,12 @@ update was successful, or 'ng [refname] [error]' if the update was not. 1*(command-status) flush-pkt - unpack-status = PKT-LINE("unpack" SP unpack-result LF) + unpack-status = PKT-LINE("unpack" SP unpack-result) unpack-result = "ok" / error-msg command-status = command-ok / command-fail - command-ok = PKT-LINE("ok" SP refname LF) - command-fail = PKT-LINE("ng" SP refname SP error-msg LF) + command-ok = PKT-LINE("ok" SP refname) + command-fail = PKT-LINE("ng" SP refname SP error-msg) error-msg = 1*(OCTECT) ; where not "ok" ---- diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 4f8a7bfb4c..eaab6b4ac7 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -260,6 +260,13 @@ If the upload-pack server advertises this capability, fetch-pack may send "want" lines with SHA-1s that exist at the server but are not advertised by upload-pack. +allow-reachable-sha1-in-want +---------------------------- + +If the upload-pack server advertises this capability, fetch-pack may +send "want" lines with SHA-1s that exist at the server but are not +advertised by upload-pack. + push-cert=<nonce> ----------------- diff --git a/Documentation/technical/protocol-common.txt b/Documentation/technical/protocol-common.txt index 889985f707..bf30167ae3 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/technical/protocol-common.txt @@ -62,7 +62,10 @@ A pkt-line MAY contain binary data, so implementors MUST ensure pkt-line parsing/formatting routines are 8-bit clean. A non-binary line SHOULD BE terminated by an LF, which if present -MUST be included in the total length. +MUST be included in the total length. Receivers MUST treat pkt-lines +with non-binary data the same whether or not they contain the trailing +LF (stripping the LF if present, and not complaining when it is +missing). The maximum length of a pkt-line's data component is 65520 bytes. Implementations MUST NOT send pkt-line whose length exceeds 65524 diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 242a044db9..4a8be4d144 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -41,13 +41,17 @@ With a `USE_STDEV` compile-time option, `st_dev` is also compared, but this is not enabled by default because this member is not stable on network filesystems. With `USE_NSEC` compile-time option, `st_mtim.tv_nsec` and `st_ctim.tv_nsec` -members are also compared, but this is not enabled by default +members are also compared. On Linux, this is not enabled by default because in-core timestamps can have finer granularity than on-disk timestamps, resulting in meaningless changes when an inode is evicted from the inode cache. See commit 8ce13b0 of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git ([PATCH] Sync in core time granularity with filesystems, -2005-01-04). +2005-01-04). This patch is included in kernel 2.6.11 and newer, but +only fixes the issue for file systems with exactly 1 ns or 1 s +resolution. Other file systems are still broken in current Linux +kernels (e.g. CEPH, CIFS, NTFS, UDF), see +https://lkml.org/lkml/2015/6/9/714 Racy Git -------- diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt new file mode 100644 index 0000000000..00ad37986e --- /dev/null +++ b/Documentation/technical/repository-version.txt @@ -0,0 +1,88 @@ +Git Repository Format Versions +============================== + +Every git repository is marked with a numeric version in the +`core.repositoryformatversion` key of its `config` file. This version +specifies the rules for operating on the on-disk repository data. An +implementation of git which does not understand a particular version +advertised by an on-disk repository MUST NOT operate on that repository; +doing so risks not only producing wrong results, but actually losing +data. + +Because of this rule, version bumps should be kept to an absolute +minimum. Instead, we generally prefer these strategies: + + - bumping format version numbers of individual data files (e.g., + index, packfiles, etc). This restricts the incompatibilities only to + those files. + + - introducing new data that gracefully degrades when used by older + clients (e.g., pack bitmap files are ignored by older clients, which + simply do not take advantage of the optimization they provide). + +A whole-repository format version bump should only be part of a change +that cannot be independently versioned. For instance, if one were to +change the reachability rules for objects, or the rules for locking +refs, that would require a bump of the repository format version. + +Note that this applies only to accessing the repository's disk contents +directly. An older client which understands only format `0` may still +connect via `git://` to a repository using format `1`, as long as the +server process understands format `1`. + +The preferred strategy for rolling out a version bump (whether whole +repository or for a single file) is to teach git to read the new format, +and allow writing the new format with a config switch or command line +option (for experimentation or for those who do not care about backwards +compatibility with older gits). Then after a long period to allow the +reading capability to become common, we may switch to writing the new +format by default. + +The currently defined format versions are: + +Version `0` +----------- + +This is the format defined by the initial version of git, including but +not limited to the format of the repository directory, the repository +configuration file, and the object and ref storage. Specifying the +complete behavior of git is beyond the scope of this document. + +Version `1` +----------- + +This format is identical to version `0`, with the following exceptions: + + 1. When reading the `core.repositoryformatversion` variable, a git + implementation which supports version 1 MUST also read any + configuration keys found in the `extensions` section of the + configuration file. + + 2. If a version-1 repository specifies any `extensions.*` keys that + the running git has not implemented, the operation MUST NOT + proceed. Similarly, if the value of any known key is not understood + by the implementation, the operation MUST NOT proceed. + +Note that if no extensions are specified in the config file, then +`core.repositoryformatversion` SHOULD be set to `0` (setting it to `1` +provides no benefit, and makes the repository incompatible with older +implementations of git). + +This document will serve as the master list for extensions. Any +implementation wishing to define a new extension should make a note of +it here, in order to claim the name. + +The defined extensions are: + +`noop` +~~~~~~ + +This extension does not change git's behavior at all. It is useful only +for testing format-1 compatibility. + +`preciousObjects` +~~~~~~~~~~~~~~~~~ + +When the config key `extensions.preciousObjects` is set to `true`, +objects in the repository MUST NOT be deleted (e.g., by `git-prune` or +`git repack -d`). diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index 282758e768..bd184cd653 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -36,7 +36,7 @@ The `<pushurl>` is used for pushes only. It is optional and defaults to `<url>`. Named file in `$GIT_DIR/remotes` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can choose to provide the name of a file in `$GIT_DIR/remotes`. The URL diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 9ccb24677e..b05da95788 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -7,9 +7,8 @@ Depending on the transport protocol, some of this information may be absent. 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). +and ftps can be used for fetching, but this is inefficient and +deprecated; do not use it). The native transport (i.e. git:// URL) does no authentication and should be used with caution on unsecured networks. @@ -20,7 +19,6 @@ The following syntaxes may be used with them: - git://host.xz{startsb}:port{endsb}/path/to/repo.git/ - http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ - ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- rsync://host.xz/path/to/repo.git/ An alternative scp-like syntax may also be used with the ssh protocol: diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 68978f5338..5e07454572 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1431,11 +1431,11 @@ differently. Normally, a merge results in a merge commit, with two parents, one pointing at each of the two lines of development that were merged. -However, if the current branch is a descendant of the other--so every -commit present in the one is already contained in the other--then Git -just performs a "fast-forward"; the head of the current branch is moved -forward to point at the head of the merged-in branch, without any new -commits being created. +However, if the current branch is an ancestor of the other--so every commit +present in the current branch is already contained in the other branch--then Git +just performs a "fast-forward"; the head of the current branch is moved forward +to point at the head of the merged-in branch, without any new commits being +created. [[fixing-mistakes]] Fixing mistakes @@ -1491,7 +1491,7 @@ resolving a merge>>. [[fixing-a-mistake-by-rewriting-history]] Fixing a mistake by rewriting history -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the problematic commit is the most recent commit, and you have not yet made that commit public, then you may just @@ -2125,8 +2125,37 @@ Allowing web browsing of a repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The gitweb cgi script provides users an easy way to browse your -project's files and history without having to install Git; see the file -gitweb/INSTALL in the Git source tree for instructions on setting it up. +project's revisions, file contents and logs without having to install +Git. Features like RSS/Atom feeds and blame/annotation details may +optionally be enabled. + +The linkgit:git-instaweb[1] command provides a simple way to start +browsing the repository using gitweb. The default server when using +instaweb is lighttpd. + +See the file gitweb/INSTALL in the Git source tree and +linkgit:gitweb[1] for instructions on details setting up a permanent +installation with a CGI or Perl capable server. + +[[how-to-get-a-git-repository-with-minimal-history]] +How to get a Git repository with minimal history +------------------------------------------------ + +A <<def_shallow_clone,shallow clone>>, with its truncated +history, is useful when one is interested only in recent history +of a project and getting full history from the upstream is +expensive. + +A <<def_shallow_clone,shallow clone>> is created by specifying +the linkgit:git-clone[1] `--depth` switch. The depth can later be +changed with the linkgit:git-fetch[1] `--depth` switch, or full +history restored with `--unshallow`. + +Merging inside a <<def_shallow_clone,shallow clone>> will work as long +as a merge base is in the recent history. +Otherwise, it will be like merging unrelated histories and may +have to result in huge conflicts. This limitation may make such +a repository unsuitable to be used in merge based workflows. [[sharing-development-examples]] Examples @@ -3424,7 +3453,7 @@ just missing one particular blob version. [[the-index]] The index ------------ +--------- The index is a binary file (generally kept in `.git/index`) containing a sorted list of path names, each with permissions and the SHA-1 of a blob @@ -4636,23 +4665,15 @@ Scan email archives for other stuff left out Scan man pages to see if any assume more background than this manual provides. -Simplify beginning by suggesting disconnected head instead of -temporary branch creation? - Add more good examples. Entire sections of just cookbook examples might be a good idea; maybe make an "advanced examples" section a standard end-of-chapter section? Include cross-references to the glossary, where appropriate. -Document shallow clones? See draft 1.5.0 release notes for some -documentation. - Add a section on working with other version control systems, including CVS, Subversion, and just imports of series of release tarballs. -More details on gitweb? - Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. |