diff options
Diffstat (limited to 'Documentation')
89 files changed, 2511 insertions, 677 deletions
diff --git a/Documentation/RelNotes/2.3.8.txt b/Documentation/RelNotes/2.3.8.txt new file mode 100644 index 0000000000..0b67268a96 --- /dev/null +++ b/Documentation/RelNotes/2.3.8.txt @@ -0,0 +1,22 @@ +Git v2.3.8 Release Notes +======================== + +Fixes since v2.3.7 +------------------ + + * 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. + + * The default $HOME/.gitconfig file created upon "git config --global" + that edits it had incorrectly spelled user.name and user.email + entries in it. + + * "git commit --date=now" or anything that relies on approxidate lost + the daylight-saving-time offset. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.1.txt b/Documentation/RelNotes/2.4.1.txt new file mode 100644 index 0000000000..a65a6c5829 --- /dev/null +++ b/Documentation/RelNotes/2.4.1.txt @@ -0,0 +1,40 @@ +Git v2.4.1 Release Notes +======================== + +Fixes since v2.4 +---------------- + + * 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. + + * The default $HOME/.gitconfig file created upon "git config --global" + that edits it had incorrectly spelled user.name and user.email + entries in it. + + * "git commit --date=now" or anything that relies on approxidate lost + the daylight-saving-time offset. + + * "git cat-file bl $blob" failed to barf even though there is no + object type that is "bl". + + * Teach the codepaths that read .gitignore and .gitattributes files + 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. + + * 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. + + * 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). + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.2.txt b/Documentation/RelNotes/2.4.2.txt new file mode 100644 index 0000000000..250cdc423c --- /dev/null +++ b/Documentation/RelNotes/2.4.2.txt @@ -0,0 +1,45 @@ +Git v2.4.2 Release Notes +======================== + +Fixes since v2.4.1 +------------------ + + * "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. + + * "hash-object --literally" introduced in v2.2 was not prepared to + take a really long object type name. + + * "git rebase --quiet" was not quite quiet when there is nothing to + do. + + * The completion for "log --decorate=" parameter value was incorrect. + + * "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". + + * "git daemon" fails to build from the source under NO_IPV6 + configuration (regression in 2.4). + + * "git stash pop/apply" forgot to make sure that not just the working + tree is clean but also the index is clean. The latter is important + as a stash application can conflict and the index will be used for + conflict resolution. + + * 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). + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.3.txt b/Documentation/RelNotes/2.4.3.txt new file mode 100644 index 0000000000..914d2c1860 --- /dev/null +++ b/Documentation/RelNotes/2.4.3.txt @@ -0,0 +1,76 @@ +Git v2.4.3 Release Notes +======================== + +Fixes since v2.4.3 +------------------ + + * Error messages from "git branch" called remote-tracking branches as + "remote branches". + + * "git rerere forget" in a repository without rerere enabled gave a + cryptic error message; it should be a silent no-op instead. + + * "git pull --log" and "git pull --no-log" worked as expected, but + "git pull --log=20" did not. + + * The pull.ff configuration was supposed to override the merge.ff + configuration, but it didn't. + + * 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. + + * Various documentation mark-up fixes to make the output more + consistent in general and also make AsciiDoctor (an alternative + formatter) happier. + + * "git bundle verify" did not diagnose extra parameters on the + command line. + + * Multi-ref transaction support we merged a few releases ago + unnecessarily kept many file descriptors open, risking to fail with + resource exhaustion. + + * 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. + + * 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. + + * 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. + + * 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. + + * 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"). + + * "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. + + * "git add -e" did not allow the user to abort the operation by + killing the editor. + + * Git 2.4 broke setting verbosity and progress levels on "git clone" + with native transports. + + * 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 portabile across + platforms while terminating lines in their working tree files with + CRLF for their platform. + + * Code clean-up for xdg configuration path support. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.4.txt b/Documentation/RelNotes/2.4.4.txt new file mode 100644 index 0000000000..f1ccd001be --- /dev/null +++ b/Documentation/RelNotes/2.4.4.txt @@ -0,0 +1,35 @@ +Git v2.4.4 Release Notes +======================== + +Fixes since v2.4.3 +------------------ + + * l10n updates for German. + + * An earlier leakfix to bitmap testing code was incomplete. + + * "git clean pathspec..." tried to lstat(2) and complain even for + paths outside the given pathspec. + + * 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). + + * 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? + + * Make "git stash something --help" error out, so that users can + safely say "git stash drop --help". + + * Clarify that "log --raw" and "log --format=raw" are unrelated + concepts. + + * Catch a programmer mistake to feed a pointer not an array to + ARRAY_SIZE() macro, by using a couple of GCC extensions. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.5.txt b/Documentation/RelNotes/2.4.5.txt new file mode 100644 index 0000000000..568297ccb7 --- /dev/null +++ b/Documentation/RelNotes/2.4.5.txt @@ -0,0 +1,28 @@ +Git v2.4.5 Release Notes +======================== + +Fixes since v2.4.4 +------------------ + + * The setup code used to die when core.bare and core.worktree are set + inconsistently, even for commands that do not need working tree. + + * 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. + + * "color.diff.plain" was a misnomer; give it 'color.diff.context' as + a more logical synonym. + + * The configuration reader/writer uses mmap(2) interface to access + the files; when we find a directory, it barfed with "Out of memory?". + + * Recent "git prune" traverses young unreachable objects to safekeep + old objects in the reachability chain from them, which sometimes + showed unnecessary error messages that are alarming. + + * "git rebase -i" fired post-rewrite hook when it shouldn't (namely, + when it was told to stop sequencing with 'exec' insn). + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.6.txt b/Documentation/RelNotes/2.4.6.txt new file mode 100644 index 0000000000..b53f353939 --- /dev/null +++ b/Documentation/RelNotes/2.4.6.txt @@ -0,0 +1,23 @@ +Git v2.4.6 Release Notes +======================== + +Fixes since v2.4.5 +------------------ + + * "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. + + * "git fsck" used to ignore missing or invalid objects recorded in reflog. + + * The tcsh completion writes a bash scriptlet but that would have + failed for users with noclobber set. + + * 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. + + * "git format-patch --ignore-if-upstream A..B" did not like to be fed + tags as boundary commits. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.7.txt b/Documentation/RelNotes/2.4.7.txt new file mode 100644 index 0000000000..b3ac412b82 --- /dev/null +++ b/Documentation/RelNotes/2.4.7.txt @@ -0,0 +1,53 @@ +Git v2.4.7 Release Notes +======================== + +Fixes since v2.4.6 +------------------ + + * A minor regression to "git fsck" in v2.2 era was fixed; it + complained about a body-less tag object when it lacked a + separator empty line after its header to separate it with a + non-existent body. + + * 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. + + * 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. + + * Avoid possible ssize_t to int truncation. + + * "git config" failed to update the configuration file when the + underlying filesystem is incapable of renaming a file that is still + open. + + * A minor bugfix when pack bitmap is used with "rev-list --count". + + * 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. + + * Fix a small bug in our use of umask() return value. + + * "git rebase" did not exit with failure when format-patch it invoked + failed for whatever reason. + + * Disable "have we lost a race with competing repack?" check while + receiving a huge object transfer that runs index-pack. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.8.txt b/Documentation/RelNotes/2.4.8.txt new file mode 100644 index 0000000000..ad946b2673 --- /dev/null +++ b/Documentation/RelNotes/2.4.8.txt @@ -0,0 +1,21 @@ +Git v2.4.8 Release Notes +======================== + +Fixes since v2.4.7 +------------------ + + * Abandoning an already applied change in "git rebase -i" with + "--continue" left CHERRY_PICK_HEAD and confused later steps. + + * Various fixes around "git am" that applies a patch to a history + that is not there yet. + + * "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. + + * "git commit --cleanup=scissors" was not careful enough to protect + against getting fooled by a line that looked like scissors. + +Also contains typofixes, documentation updates and trivial code +clean-ups. 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..3c468519b9 --- /dev/null +++ b/Documentation/RelNotes/2.5.1.txt @@ -0,0 +1,49 @@ +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. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.6.0.txt b/Documentation/RelNotes/2.6.0.txt new file mode 100644 index 0000000000..6ba67b60c2 --- /dev/null +++ b/Documentation/RelNotes/2.6.0.txt @@ -0,0 +1,256 @@ +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 -" 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. + + +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). + + +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 38ae878 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 22d6857 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). + + * 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). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index b299b59023..a09969ba08 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -10,7 +10,7 @@ Include additional statistics at the end of blame output. -L <start>,<end>:: --L :<regex>:: +-L :<funcname>:: Annotate only the given line range. May be specified multiple times. Overlapping ranges are allowed. + diff --git a/Documentation/config.txt b/Documentation/config.txt index 2e5ceaf719..f5d15fff3e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -453,6 +453,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 @@ -622,6 +624,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 +769,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' @@ -906,7 +922,8 @@ command line with the `--color[=<when>]` option. color.diff.<slot>:: Use customized color for diff colorization. `<slot>` specifies which part of the patch to use the specified color, and is one - of `plain` (context text), `meta` (metainformation), `frag` + of `context` (context text - `plain` is a historical synonym), + `meta` (metainformation), `frag` (hunk header), 'func' (function in hunk header), `old` (removed lines), `new` (added lines), `commit` (commit headers), or `whitespace` (highlighting whitespace errors). @@ -1233,6 +1250,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 @@ -1271,21 +1307,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>. @@ -1560,6 +1609,42 @@ 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 @@ -2033,7 +2118,7 @@ pull.ff:: a case (equivalent to giving the `--no-ff` option from the command line). When set to `only`, only such fast-forward merges are allowed (equivalent to giving the `--ff-only` option from the - command line). + command line). This setting overrides `merge.ff` when pulling. pull.rebase:: When true, rebase branches on top of the fetched branch, instead @@ -2132,6 +2217,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 @@ -2168,6 +2269,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 @@ -2213,13 +2336,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 @@ -2270,18 +2390,18 @@ remote.<name>.skipFetchAll:: remote.<name>.receivepack:: The default program to execute on the remote side when pushing. See - option \--receive-pack of linkgit:git-push[1]. + option --receive-pack of linkgit:git-push[1]. remote.<name>.uploadpack:: The default program to execute on the remote side when fetching. See - option \--upload-pack of linkgit:git-fetch-pack[1]. + option --upload-pack of linkgit:git-fetch-pack[1]. remote.<name>.tagOpt:: - Setting this value to \--no-tags disables automatic tag following when - fetching from remote <name>. Setting it to \--tags will fetch every + Setting this value to --no-tags disables automatic tag following when + fetching from remote <name>. Setting it to --tags will fetch every tag from remote <name>, even if they are not reachable from remote branch heads. Passing these flags directly to linkgit:git-fetch[1] can - override this setting. See options \--tags and \--no-tags of + override this setting. See options --tags and --no-tags of linkgit:git-fetch[1]. remote.<name>.vcs:: @@ -2507,9 +2627,18 @@ 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). transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are @@ -2524,20 +2653,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 diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 843a20bac2..bcf54da82a 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -77,7 +77,7 @@ combined diff format Any diff-generating command can take the `-c` or `--cc` option to produce a 'combined diff' when showing a merge. This is the default format when showing merges with linkgit:git-diff[1] or -linkgit:git-show[1]. Note also that you can give the `-m' option to any +linkgit:git-show[1]. Note also that you can give the `-m` option to any of these commands to force generation of diffs with individual parents of a merge. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index ccd499867b..d56ca90998 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -23,7 +23,9 @@ ifndef::git-format-patch[] -u:: --patch:: Generate patch (see section on generating patches). - {git-diff? This is the default.} +ifdef::git-diff[] + This is the default. +endif::git-diff[] endif::git-format-patch[] -s:: @@ -41,8 +43,19 @@ endif::git-format-patch[] ifndef::git-format-patch[] --raw:: - Generate the raw format. - {git-diff-core? This is the default.} +ifndef::git-log[] + Generate the diff in raw format. +ifdef::git-diff-core[] + This is the default. +endif::git-diff-core[] +endif::git-log[] +ifdef::git-log[] + For each commit, show a summary of changes using the raw diff + format. See the "RAW OUTPUT FORMAT" section of + linkgit:git-diff[1]. This is different from showing the log + itself in raw format, which you can achieve with + `--format=raw`. +endif::git-log[] endif::git-format-patch[] ifndef::git-format-patch[] @@ -278,6 +291,16 @@ ifndef::git-format-patch[] 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/fmt-merge-msg-config.txt b/Documentation/fmt-merge-msg-config.txt new file mode 100644 index 0000000000..c73cfa90b7 --- /dev/null +++ b/Documentation/fmt-merge-msg-config.txt @@ -0,0 +1,10 @@ +merge.branchdesc:: + In addition to branch names, populate the log message with + the branch description text associated with them. Defaults + to false. + +merge.log:: + In addition to branch names, populate the log message with at + most the specified number of one-line descriptions from the + actual commits that are being merged. Defaults to false, and + true is a synonym for 20. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index f2eb9076d7..fe5282f130 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -93,7 +93,8 @@ This effectively runs `add --interactive`, but bypasses the initial command menu and directly jumps to the `patch` subcommand. See ``Interactive mode'' for details. --e, \--edit:: +-e:: +--edit:: Open the diff vs. the index in an editor and let the user edit it. After the editor was closed, adjust the hunk headers and apply the patch to the index. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 0d8ba48f79..dbea6e7ae9 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] @@ -90,10 +90,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:: diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 4cb52a7302..e97f2de21b 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,7 +16,6 @@ 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>...] @@ -26,64 +25,71 @@ on the subcommand: 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. 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 ------------------------------------------------ -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: +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 +Bisecting: 675 revisions left to test after this (roughly 10 steps) ------------------------------------------------ -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: +You should now compile the checked-out version and test it. If that +version works correctly, type ------------------------------------------------ -$ git bisect good # this one is good +$ git bisect good ------------------------------------------------ -The output of this command would be something similar to the following: +If that version is broken, type ------------------------------------------------ -Bisecting: 337 revisions left to test after this +$ git bisect bad ------------------------------------------------ -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. +Then `git bisect` will respond with something like + +------------------------------------------------ +Bisecting: 337 revisions left to test after this (roughly 9 steps) +------------------------------------------------ + +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 +106,10 @@ 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. + Bisect visualize ~~~~~~~~~~~~~~~~ @@ -147,17 +154,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 @@ -169,18 +176,19 @@ 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 +204,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,14 +239,14 @@ 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 @@ -247,7 +255,7 @@ as the highest sensible value to use for this purpose, because 126 and 127 are used by POSIX shells to signal specific error status (127 is for command not found, 126 is for command found but not executable---these details do not matter, as they are normal errors in the script, as far as -"bisect run" is concerned). +`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 +268,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 +315,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 +387,11 @@ 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'. +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..e6e947c808 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -76,6 +76,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 359619b552..a67138a022 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -81,7 +81,7 @@ OPTIONS `--track` or `--set-upstream`. -D:: - Delete a branch irrespective of its merged status. + Shortcut for `--delete --force`. -l:: --create-reflog:: @@ -95,13 +95,17 @@ OPTIONS --force:: Reset <branchname> to <startpoint> if <branchname> exists already. Without `-f` 'git branch' refuses to change an existing branch. + In combination with `-d` (or `--delete`), allow deleting the + branch irrespective of its merged status. In combination with + `-m` (or `--move`), allow renaming the branch even if the new + branch name already exists. -m:: --move:: Move/rename a branch and the corresponding reflog. -M:: - Move/rename a branch even if the new branch name already exists. + Shortcut for `--move --force`. --color[=<when>]:: Color branches to highlight current, local, and diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index f6a16f4300..3105fc0720 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] < <list-of-objects> 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-ref-format.txt b/Documentation/git-check-ref-format.txt index fc02959ba4..9044dfaada 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -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 d5041082e8..e269fb1108 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -3,7 +3,7 @@ git-checkout(1) NAME ---- -git-checkout - Checkout a branch or paths to the working tree +git-checkout - Switch branches or restore working tree files SYNOPSIS -------- @@ -89,6 +89,10 @@ Omitting <branch> detaches HEAD at the tip of the current branch. (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree. + +'git checkout' with <paths> or `--patch` is used to restore modified or +deleted paths to their original contents from the index or replace paths +with the contents from a named <tree-ish> (most often a commit-ish). ++ The index may contain unmerged entries because of a previous failed merge. By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. @@ -116,6 +120,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 @@ -225,6 +244,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-commit.txt b/Documentation/git-commit.txt index 617e29b38b..904dafa0f7 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -94,7 +94,7 @@ OPTIONS --reset-author:: When used with -C/-c/--amend options, or when committing after a a conflicting cherry-pick, declare that the authorship of the - resulting commit now belongs of the committer. This also renews + resulting commit now belongs to the committer. This also renews the author timestamp. --short:: @@ -180,8 +180,8 @@ OPTIONS + -- strip:: - Strip leading and trailing empty lines, trailing whitespace, and - #commentary and collapse consecutive empty lines. + Strip leading and trailing empty lines, trailing whitespace, + commentary and collapse consecutive empty lines. whitespace:: Same as `strip` except #commentary is not removed. verbatim:: @@ -282,8 +282,11 @@ configuration variable documented in linkgit:git-config[1]. --verbose:: Show unified diff between the HEAD commit and what would be committed at the bottom of the commit message - template. Note that this diff output doesn't have its - lines prefixed with '#'. + template to help the user describe the commit by reminding + 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. + If specified twice, show in addition the unified diff between what would be committed and the worktree files, i.e. the unstaged diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index bc97071e76..e3c8f276b1 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -31,10 +31,41 @@ OPTIONS --file=<path>:: - Use `<path>` to store credentials. The file will have its + Use `<path>` to lookup and store credentials. The file will have its filesystem permissions set to prevent other users on the system from reading it, but will not be encrypted or otherwise - protected. Defaults to `~/.git-credentials`. + protected. If not specified, credentials will be searched for from + `~/.git-credentials` and `$XDG_CONFIG_HOME/git/credentials`, and + credentials will be written to `~/.git-credentials` if it exists, or + `$XDG_CONFIG_HOME/git/credentials` if it exists and the former does + not. See also <<FILES>>. + +[[FILES]] +FILES +----- + +If not set explicitly with '--file', there are two files where +git-credential-store will search for credentials in order of precedence: + +~/.git-credentials:: + User-specific credentials file. + +$XDG_CONFIG_HOME/git/credentials:: + Second user-specific credentials file. If '$XDG_CONFIG_HOME' is not set + or empty, `$HOME/.config/git/credentials` will be used. Any credentials + stored in this file will not be used if `~/.git-credentials` has a + matching credential as well. It is a good idea not to create this file + if you sometimes use older versions of Git that do not support it. + +For credential lookups, the files are read in the order given above, with the +first matching credential found taking precedence over credentials found in +files further down the list. + +Credential storage will by default write to the first existing file in the +list. If none of these files exist, `~/.git-credentials` will be created and +written to. + +When erasing credentials, matching credentials will be erased from all files. EXAMPLES -------- diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index d20ca402a1..e045fc73f8 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -3,7 +3,7 @@ git-describe(1) NAME ---- -git-describe - Show the most recent tag that is reachable from a commit +git-describe - Describe a commit using the most recent tag reachable from it SYNOPSIS diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 929e496af8..ed57c684db 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -67,17 +67,17 @@ produced incorrect results if you gave these options. have been completed, or to save the marks table across incremental runs. As <file> is only opened and truncated at completion, the same path can also be safely given to - \--import-marks. + --import-marks. The file will not be written if no new object has been marked/exported. --import-marks=<file>:: Before processing any input, load the marks specified in <file>. The input file must exist, must be readable, and - must use the same format as produced by \--export-marks. + must use the same format as produced by --export-marks. + Any commits that have already been marked will not be exported again. -If the backend uses a similar \--import-marks file, this allows for +If the backend uses a similar --import-marks file, this allows for incremental bidirectional exporting of the repository by keeping the marks the same across runs. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 690fed3ea4..66910aa2fa 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -42,19 +42,19 @@ OPTIONS --quiet:: Disable all non-fatal output, making fast-import silent when it is successful. This option disables the output shown by - \--stats. + --stats. --stats:: Display some basic statistics about the objects fast-import has created, the packfiles they were stored into, and the memory used by fast-import during this run. Showing this output - is currently the default, but can be disabled with \--quiet. + is currently the default, but can be disabled with --quiet. 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. @@ -81,12 +81,12 @@ Locations of Marks Files have been completed, or to save the marks table across incremental runs. As <file> is only opened and truncated at checkpoint (or completion) the same path can also be - safely given to \--import-marks. + safely given to --import-marks. --import-marks=<file>:: Before processing any input, load the marks specified in <file>. The input file must exist, must be readable, and - must use the same format as produced by \--export-marks. + must use the same format as produced by --export-marks. Multiple options may be supplied to import more than one set of marks. If a mark is defined to different values, the last file wins. @@ -179,8 +179,8 @@ fast-forward update, fast-import will skip updating that ref and instead prints a warning message. fast-import will always attempt to update all branch refs, and does not stop on the first failure. -Branch updates can be forced with \--force, but it's recommended that -this only be used on an otherwise quiet repository. Using \--force +Branch updates can be forced with --force, but it's recommended that +this only be used on an otherwise quiet repository. Using --force is not necessary for an initial import into an empty repository. @@ -231,11 +231,11 @@ Date Formats ~~~~~~~~~~~~ The following date formats are supported. A frontend should select the format it will use for this import by passing the format name -in the \--date-format=<fmt> command-line option. +in the --date-format=<fmt> command-line option. `raw`:: This is the Git native format and is `<time> SP <offutc>`. - It is also fast-import's default format, if \--date-format was + It is also fast-import's default format, if --date-format was not specified. + The time of the event is specified by `<time>` as the number of @@ -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 @@ -437,7 +442,7 @@ the email address from the other fields in the line. Note that of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded. The time of the change is specified by `<when>` using the date format -that was selected by the \--date-format=<fmt> command-line option. +that was selected by the --date-format=<fmt> command-line option. See ``Date Formats'' above for the set of supported formats, and their syntax. @@ -600,7 +605,7 @@ be removed from the branch. See `filemodify` above for a detailed description of `<path>`. `filecopy` -^^^^^^^^^^^^ +^^^^^^^^^^ Recursively copies an existing file or subdirectory to a different location within the branch. The existing file or directory must exist. If the destination exists it will be completely replaced @@ -888,7 +893,7 @@ save out all current branch refs, tags and marks. .... Note that fast-import automatically switches packfiles when the current -packfile reaches \--max-pack-size, or 4 GiB, whichever limit is +packfile reaches --max-pack-size, or 4 GiB, whichever limit is smaller. During an automatic packfile switch fast-import does not update the branch refs, tags or marks. @@ -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 @@ -1226,7 +1253,7 @@ users of fast-import, and are offered here as suggestions. Use One Mark Per Commit ~~~~~~~~~~~~~~~~~~~~~~~ When doing a repository conversion, use a unique mark per commit -(`mark :<n>`) and supply the \--export-marks option on the command +(`mark :<n>`) and supply the --export-marks option on the command line. fast-import will dump a file which lists every mark and the Git object SHA-1 that corresponds to it. If the frontend can tie the marks back to the source repository, it is easy to verify the @@ -1291,7 +1318,7 @@ even for considerably large projects (100,000+ commits). However repacking the repository is necessary to improve data locality and access performance. It can also take hours on extremely -large projects (especially if -f and a large \--window parameter is +large projects (especially if -f and a large --window parameter is used). Since repacking is safe to run alongside readers and writers, run the repack in the background and let it finish when it finishes. There is no reason to wait to explore your new Git project! @@ -1305,7 +1332,7 @@ Repacking Historical Data ~~~~~~~~~~~~~~~~~~~~~~~~~ If you are repacking very old imported data (e.g. older than the last year), consider expending some extra CPU time and supplying -\--window=50 (or higher) when you run 'git repack'. +--window=50 (or higher) when you run 'git repack'. This will take longer, but will also produce a smaller packfile. You only need to expend the effort once, and everyone using your project will benefit from the smaller repository. @@ -1407,7 +1434,7 @@ branch, their in-memory storage size can grow to a considerable size fast-import automatically moves active branches to inactive status based on a simple least-recently-used algorithm. The LRU chain is updated on each `commit` command. The maximum number of active branches can be -increased or decreased on the command line with \--active-branches=. +increased or decreased on the command line with --active-branches=. per active tree ~~~~~~~~~~~~~~~ diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 93b5067946..8680f45f8d 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -80,7 +80,7 @@ be in a separate packet, and the list must end with a flush packet. the things up in .bash_profile). --exec=<git-upload-pack>:: - Same as \--upload-pack=<git-upload-pack>. + Same as --upload-pack=<git-upload-pack>. --depth=<n>:: Limit fetching to ancestor-chains not longer than n. diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index bb1232a52c..55a9a4b93a 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -51,17 +51,7 @@ OPTIONS CONFIGURATION ------------- - -merge.branchdesc:: - In addition to branch names, populate the log message with - the branch description text associated with them. Defaults - to false. - -merge.log:: - In addition to branch names, populate the log message with at - most the specified number of one-line descriptions from the - actual commits that are being merged. Defaults to false, and - true is a synonym for 20. +include::fmt-merge-msg-config.txt[] merge.summary:: Synonym to `merge.log`; this is deprecated and will be removed in diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 42408752d0..7f8d9a5b5f 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -97,6 +97,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. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index bb3ea9372f..0dac4e9b86 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -170,7 +170,7 @@ will want to ensure that threading is disabled for `git send-email`. -v <n>:: --reroll-count=<n>:: Mark the series as the <n>-th iteration of the topic. The - output filenames have `v<n>` pretended to them, and the + output filenames have `v<n>` prepended to them, and the subject prefix ("PATCH" by default, but configurable via the `--subject-prefix` option) has ` v<n>` appended to it. E.g. `--reroll-count=4` may produce `v4-0001-add-makefile.patch` 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-hash-object.txt b/Documentation/git-hash-object.txt index 02c1f12685..0c75f3b610 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -9,7 +9,7 @@ git-hash-object - Compute object ID and optionally creates a blob from a file SYNOPSIS -------- [verse] -'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>... +'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> DESCRIPTION @@ -51,7 +51,13 @@ OPTIONS Hash the contents as is, ignoring any input filter that would have been chosen by the attributes mechanism, including the end-of-line conversion. If the file is read from standard input then this - is always implied, unless the --path option is given. + is always implied, unless the `--path` option is given. + +--literally:: + Allow `--stdin` to hash any garbage into a loose object which might not + otherwise pass standard object parsing or git-fsck checks. Useful for + stress-testing Git itself or reproducing characteristics of corrupt or + bogus objects encountered in the wild. GIT --- diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index d422ba4b59..9268fb6b1e 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -65,8 +65,8 @@ automatically by the web server. EXAMPLES -------- -All of the following examples map 'http://$hostname/git/foo/bar.git' -to '/var/www/git/foo/bar.git'. +All of the following examples map `http://$hostname/git/foo/bar.git` +to `/var/www/git/foo/bar.git`. Apache 2.x:: Ensure mod_cgi, mod_alias, and mod_env are enabled, set @@ -255,6 +255,15 @@ The GIT_HTTP_EXPORT_ALL environmental variable may be passed to 'git-http-backend' to bypass the check for the "git-daemon-export-ok" file in each repository before allowing export of that repository. +The `GIT_HTTP_MAX_REQUEST_BUFFER` environment variable (or the +`http.maxRequestBuffer` config variable) may be set to change the +largest ref negotiation request that git will handle during a fetch; any +fetch requiring a larger buffer will not succeed. This value should not +normally need to be changed, but may be helpful if you are fetching from +a repository with an extremely large number of refs. The value can be +specified with a unit (e.g., `100M` for 100 megabytes). The default is +10 megabytes. + The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and GIT_COMMITTER_EMAIL to '$\{REMOTE_USER}@http.$\{REMOTE_ADDR\}', ensuring that any reflogs created by 'git-receive-pack' contain some diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 18bc716a0c..97b9993ee8 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -62,9 +62,9 @@ produced by `--stat`, etc. output by allowing them to allocate space in advance. -L <start>,<end>:<file>:: --L :<regex>:<file>:: +-L :<funcname>:<file>:: Trace the evolution of the line range given by "<start>,<end>" - (or the funcname regex <regex>) within the <file>. You may + (or the function name regex <funcname>) within the <file>. You may not give any pathspec limiters. This is currently limited to a walk starting from a single revision, i.e., you may only give zero or one positive revision arguments. @@ -184,6 +184,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 a single <path> is given to git log, it will act as + if the `--follow` option was also used. 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-merge.txt b/Documentation/git-merge.txt index 1f94908e3c..273a1009be 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -104,6 +104,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-p4.txt b/Documentation/git-p4.txt index a1664b9f68..82aa5d6073 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 diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index c2f76fb1ea..bbea5294ca 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -192,7 +192,7 @@ self-contained. Use `git index-pack --fix-thin` --shallow:: Optimize a pack that will be provided to a client with a shallow - repository. This option, combined with \--thin, can result in a + repository. This option, combined with --thin, can result in a smaller pack at the cost of speed. --delta-base-offset:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 712ab4baed..93c72a29ce 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 diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 863c30c4c2..135d810b7a 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -265,8 +265,8 @@ origin +master` to force a push to the `master` branch). See the --[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. + default is --verify, giving the hook a chance to prevent the + push. With --no-verify, the hook is bypassed completely. include::urls-remotes.txt[] diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 47984e84ed..ca039546a4 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -80,7 +80,7 @@ remain the checked-out branch. If the upstream branch already contains a change you have made (e.g., because you mailed a patch which was applied upstream), then that commit will be skipped. For example, running `git rebase master` on the -following history (in which A' and A introduce the same set of changes, +following history (in which `A'` and `A` introduce the same set of changes, but have different committer information): ------------ @@ -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>:: @@ -359,6 +368,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:: @@ -514,6 +527,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-rev-list.txt b/Documentation/git-rev-list.txt index 5b119220bf..7b49c85347 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -9,54 +9,55 @@ git-rev-list - Lists commit objects in reverse chronological order SYNOPSIS -------- [verse] -'git rev-list' [ \--max-count=<number> ] - [ \--skip=<number> ] - [ \--max-age=<timestamp> ] - [ \--min-age=<timestamp> ] - [ \--sparse ] - [ \--merges ] - [ \--no-merges ] - [ \--min-parents=<number> ] - [ \--no-min-parents ] - [ \--max-parents=<number> ] - [ \--no-max-parents ] - [ \--first-parent ] - [ \--remove-empty ] - [ \--full-history ] - [ \--not ] - [ \--all ] - [ \--branches[=<pattern>] ] - [ \--tags[=<pattern>] ] - [ \--remotes[=<pattern>] ] - [ \--glob=<glob-pattern> ] - [ \--ignore-missing ] - [ \--stdin ] - [ \--quiet ] - [ \--topo-order ] - [ \--parents ] - [ \--timestamp ] - [ \--left-right ] - [ \--left-only ] - [ \--right-only ] - [ \--cherry-mark ] - [ \--cherry-pick ] - [ \--encoding=<encoding> ] - [ \--(author|committer|grep)=<pattern> ] - [ \--regexp-ignore-case | -i ] - [ \--extended-regexp | -E ] - [ \--fixed-strings | -F ] - [ \--date=(local|relative|default|iso|iso-strict|rfc|short) ] - [ [ \--objects | \--objects-edge | \--objects-edge-aggressive ] - [ \--unpacked ] ] - [ \--pretty | \--header ] - [ \--bisect ] - [ \--bisect-vars ] - [ \--bisect-all ] - [ \--merge ] - [ \--reverse ] - [ \--walk-reflogs ] - [ \--no-walk ] [ \--do-walk ] - [ \--use-bitmap-index ] +'git rev-list' [ --max-count=<number> ] + [ --skip=<number> ] + [ --max-age=<timestamp> ] + [ --min-age=<timestamp> ] + [ --sparse ] + [ --merges ] + [ --no-merges ] + [ --min-parents=<number> ] + [ --no-min-parents ] + [ --max-parents=<number> ] + [ --no-max-parents ] + [ --first-parent ] + [ --remove-empty ] + [ --full-history ] + [ --not ] + [ --all ] + [ --branches[=<pattern>] ] + [ --tags[=<pattern>] ] + [ --remotes[=<pattern>] ] + [ --glob=<glob-pattern> ] + [ --ignore-missing ] + [ --stdin ] + [ --quiet ] + [ --topo-order ] + [ --parents ] + [ --timestamp ] + [ --left-right ] + [ --left-only ] + [ --right-only ] + [ --cherry-mark ] + [ --cherry-pick ] + [ --encoding=<encoding> ] + [ --(author|committer|grep)=<pattern> ] + [ --regexp-ignore-case | -i ] + [ --extended-regexp | -E ] + [ --fixed-strings | -F ] + [ --date=(local|relative|default|iso|iso-strict|rfc|short) ] + [ [ --objects | --objects-edge | --objects-edge-aggressive ] + [ --unpacked ] ] + [ --pretty | --header ] + [ --bisect ] + [ --bisect-vars ] + [ --bisect-all ] + [ --merge ] + [ --reverse ] + [ --walk-reflogs ] + [ --no-walk ] [ --do-walk ] + [ --count ] + [ --use-bitmap-index ] <commit>... [ \-- <paths>... ] DESCRIPTION diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index d6de42f74e..b6c6326cdc 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" + If you want to make sure that the output actually names an object in your object database and/or can be used as a specific type of object -you require, you can add "\^{type}" peeling operator to the parameter. +you require, you can add the `^{type}` peeling operator to the parameter. For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` names an existing object that is a commit-ish (i.e. a commit, or an annotated tag that points at a commit). To make sure that `$VAR` @@ -147,7 +147,7 @@ can be used. form as close to the original input as possible. --symbolic-full-name:: - This is similar to \--symbolic, but it omits input that + This is similar to --symbolic, but it omits input that are not refs (i.e. branch or tag names; or more explicitly disambiguating "heads/master" form, when you want to name the "master" branch when there is an @@ -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-send-email.txt b/Documentation/git-send-email.txt index 804554609d..b9134d234f 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -49,17 +49,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 +110,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 +171,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 @@ -383,7 +396,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 diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 45c7725dc3..b5d09f79ee 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -29,7 +29,7 @@ OPTIONS a directory on the default $PATH. --exec=<git-receive-pack>:: - Same as \--receive-pack=<git-receive-pack>. + Same as --receive-pack=<git-receive-pack>. --all:: Instead of explicitly specifying which refs to update, diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 4e617e6979..82a4125a2d 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -22,7 +22,7 @@ presents the merge commit in a special format as produced by For tags, it shows the tag message and the referenced objects. For trees, it shows the names (equivalent to 'git ls-tree' -with \--name-only). +with --name-only). For plain blobs, it shows the plain contents. diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 5221f950ce..335f312335 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -66,7 +66,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 6c6e989074..60328d5d08 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -49,7 +49,7 @@ EXAMPLES Given the following noisy input with '$' indicating the end of a line: --------- +--------- |A brief introduction $ | $ |$ @@ -65,7 +65,7 @@ Given the following noisy input with '$' indicating the end of a line: Use 'git stripspace' with no arguments to obtain: --------- +--------- |A brief introduction$ |$ |A new paragraph$ @@ -79,7 +79,7 @@ Use 'git stripspace' with no arguments to obtain: Use 'git stripspace --strip-comments' to obtain: --------- +--------- |A brief introduction$ |$ |A new paragraph$ diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c25916f8f..f17687e09d 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -25,22 +25,17 @@ SYNOPSIS DESCRIPTION ----------- -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. +Inspects, updates and manages submodules. -They are not to be confused with remotes, which are meant mainly -for branches of the same project; submodules are meant for -different projects you would like to make part of your source tree, -while the history of the two projects still stays completely -independent and you cannot modify the contents of the submodule -from within the main project. -If you want to merge the project histories and want to treat the -aggregated whole as a single project from then on, you may want to -add a remote for the other project and use the 'subtree' merge strategy, -instead of treating the other project as a submodule. Directories -that come from both projects can be cloned and checked out as a whole -if you choose to go that route. +A submodule allows you to keep another Git repository in a subdirectory +of your repository. The other repository has its own history, which does not +interfere with the history of the current repository. This can be used to +have external dependencies such as third party libraries for example. + +When cloning or pulling a repository containing submodules however, +these will not be checked out by default; the 'init' and 'update' +subcommands will maintain submodules checked out and at +appropriate revision in your working tree. Submodules are composed from a so-called `gitlink` tree entry in the main repository that refers to a particular commit object @@ -51,19 +46,18 @@ describes the default URL the submodule shall be cloned from. The logical name can be used for overriding this URL within your local repository configuration (see 'submodule init'). -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. -When adding a new submodule to the tree, the 'add' subcommand -is to be used. However, when pulling a tree containing submodules, -these will not be checked out by default; -the 'init' and 'update' subcommands will maintain submodules -checked out and at appropriate revision in your working tree. -You can briefly inspect the up-to-date status of your submodules -using the 'status' subcommand and get a detailed overview of the -difference between the index and checkouts using the 'summary' -subcommand. - +Submodules are not to be confused with remotes, which are other +repositories of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. COMMANDS -------- diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 39e9a181cc..11d1e2fc66 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -70,8 +70,8 @@ COMMANDS --username=<user>;; For transports that SVN handles authentication for (http, https, and plain svn), specify the username. For other - transports (e.g. svn+ssh://), you must include the username in - the URL, e.g. svn+ssh://foo@svn.bar.com/project + transports (e.g. `svn+ssh://`), you must include the username in + the URL, e.g. `svn+ssh://foo@svn.bar.com/project` --prefix=<prefix>;; This allows one to specify a prefix which is prepended to the names of remotes if trunk/branches/tags are @@ -279,9 +279,9 @@ first have already been pushed into SVN. Ask the user to confirm that a patch set should actually be sent to SVN. For each patch, one may answer "yes" (accept this patch), "no" (discard this patch), "all" (accept all patches), or "quit". - + - 'git svn dcommit' returns immediately if answer is "no" or "quit", without - committing anything to SVN. ++ +'git svn dcommit' returns immediately if answer is "no" or "quit", without +committing anything to SVN. 'branch':: Create a branch in the SVN repository. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index f5b267e1e3..84f6496bf2 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -13,8 +13,7 @@ SYNOPSIS <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] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION @@ -143,6 +142,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 @@ -158,7 +160,7 @@ This option is only applicable when listing tags without annotation lines. CONFIGURATION ------------- By default, 'git tag' in sign-with-default mode (-s) will use your -committer identity (of the form "Your Name <\your@email.address>") to +committer identity (of the form `Your Name <your@email.address>`) to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows: diff --git a/Documentation/git-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 12cb108b85..07d432988f 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] < <pack-file> +'git unpack-objects' [-n] [-q] [-r] [--strict] < <packfile> DESCRIPTION @@ -19,8 +19,8 @@ the objects contained within and writing them into the repository in "loose" (one object per file) format. Objects that already exist in the repository will *not* be unpacked -from the pack-file. Therefore, nothing will be unpacked if you use -this command on a pack-file that exists within the target repository. +from the packfile. Therefore, nothing will be unpacked if you use +this command on a packfile that exists within the target repository. See linkgit:git-repack[1] for options to generate new packs and replace existing ones. diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index aff01798cd..1a296bc29a 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -170,6 +170,20 @@ 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 extension. This could speed + up for commands that involve determining untracked files such + as `git status`. The underlying operating system and file + system must change `st_mtime` field of a directory if files + are added or deleted in that directory. + +--force-untracked-cache:: + For safety, `--untracked-cache` performs tests on the working + directory to make sure untracked cache can be used. These + tests can take a few seconds. `--force-untracked-cache` can be + used to skip the tests. + \--:: Do not interpret any more arguments as options. 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-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-pack.txt b/Documentation/git-verify-pack.txt index 526ba7be9c..61ca6d04c2 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -40,7 +40,7 @@ OUTPUT FORMAT ------------- When specifying the -v option the format used is: - SHA-1 type size size-in-pack-file offset-in-packfile + SHA-1 type size size-in-packfile offset-in-packfile for objects that are not deltified in the pack, and 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..fb68156cf8 --- /dev/null +++ b/Documentation/git-worktree.txt @@ -0,0 +1,176 @@ +git-worktree(1) +=============== + +NAME +---- +git-worktree - Manage multiple working trees + + +SYNOPSIS +-------- +[verse] +'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>] +'git worktree prune' [-n] [-v] [--expire <expire>] + +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 to another file system, or +within a file system that does not support hard links, you need to run +at least one git command inside the linked working tree +(e.g. `git status`) in order to update its administrative files in the +repository so that they do not get automatically pruned. + +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. + +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]. + +-n:: +--dry-run:: + With `prune`, do not remove anything; just report what it would + remove. + +-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. + +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. + +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 +- `list` to list linked working trees +- `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 c71e818cf4..2795340fb2 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,14 +43,28 @@ 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.4.0/git.html[documentation for release 2.4] +* link:v2.5.0/git.html[documentation for release 2.5] * release notes for + link:RelNotes/2.5.0.txt[2.5]. + +* link:v2.4.8/git.html[documentation for release 2.4.8] + +* release notes for + link:RelNotes/2.4.8.txt[2.4.8], + link:RelNotes/2.4.7.txt[2.4.7], + link:RelNotes/2.4.6.txt[2.4.6], + link:RelNotes/2.4.5.txt[2.4.5], + link:RelNotes/2.4.4.txt[2.4.4], + link:RelNotes/2.4.3.txt[2.4.3], + link:RelNotes/2.4.2.txt[2.4.2], + link:RelNotes/2.4.1.txt[2.4.1], link:RelNotes/2.4.0.txt[2.4]. -* link:v2.3.7/git.html[documentation for release 2.3.7] +* link:v2.3.8/git.html[documentation for release 2.3.8] * release notes for + link:RelNotes/2.3.8.txt[2.3.8], link:RelNotes/2.3.7.txt[2.3.7], link:RelNotes/2.3.6.txt[2.3.6], link:RelNotes/2.3.5.txt[2.3.5], @@ -767,7 +781,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 @@ -833,6 +847,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':: @@ -987,9 +1010,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. 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 8475c07932..36e9ab3e16 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -259,7 +259,7 @@ index 557db03..263414f 100644 @@ -1 +1,2 @@ Hello World +It's a new day for git ----- +------------ i.e. the diff of the change we caused by adding another line to `hello`. diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index c8b3e51c84..c579593e55 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -28,8 +28,8 @@ The 'git diff-{asterisk}' family works by first comparing two sets of files: - 'git diff-index' compares contents of a "tree" object and the - working directory (when '\--cached' flag is not used) or a - "tree" object and the index file (when '\--cached' flag is + working directory (when '--cached' flag is not used) or a + "tree" object and the index file (when '--cached' flag is used); - 'git diff-files' compares contents of the index file and the @@ -142,7 +142,7 @@ merges these filepairs and creates: When the "-C" option is used, the original contents of modified files, and deleted files (and also unmodified files, if the -"\--find-copies-harder" option is used) are considered as candidates +"--find-copies-harder" option is used) are considered as candidates of the source files in rename/copy operation. If the input were like these filepairs, that talk about a modified file fileY and a newly created file file0: diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 7ae50aa26a..6ade002176 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -99,10 +99,10 @@ linkgit:git-rev-list[1] for a complete list. detailed explanation.) -L<start>,<end>:<file>:: --L:<regex>:<file>:: +-L:<funcname>:<file>:: Trace the evolution of the line range given by "<start>,<end>" - (or the funcname regex <regex>) within the <file>. You may + (or the function name regex <funcname>) within the <file>. You may not give any pathspec limiters. This is currently limited to a walk starting from a single revision, i.e., you may only give zero or one positive revision arguments. diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 8edf72cf53..82e2d15435 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -408,14 +408,14 @@ set by Git if the remote helper has the 'option' capability. of <n> correspond to the number of -v flags passed on the command line. -'option progress' \{'true'|'false'\}:: +'option progress' {'true'|'false'}:: Enables (or disables) progress messages displayed by the transport helper during a command. 'option depth' <depth>:: Deepens the history of a shallow repository. -'option followtags' \{'true'|'false'\}:: +'option followtags' {'true'|'false'}:: If enabled the helper should automatically fetch annotated tag objects if the object the tag points at was transferred during the fetch command. If the tag is not fetched by @@ -423,7 +423,7 @@ set by Git if the remote helper has the 'option' capability. ask for the tag specifically. Some helpers may be able to use this option to avoid a second network connection. -'option dry-run' \{'true'|'false'\}: +'option dry-run' {'true'|'false'}: If true, pretend the operation completed successfully, but don't actually change any repository data. For most helpers this only applies to the 'push', if supported. @@ -434,18 +434,18 @@ set by Git if the remote helper has the 'option' capability. must not rely on this option being set before connect request occurs. -'option check-connectivity' \{'true'|'false'\}:: +'option check-connectivity' {'true'|'false'}:: Request the helper to check connectivity of a clone. -'option force' \{'true'|'false'\}:: +'option force' {'true'|'false'}:: Request the helper to perform a force update. Defaults to 'false'. -'option cloning \{'true'|'false'\}:: +'option cloning {'true'|'false'}:: Notify the helper this is a clone request (i.e. the current repository is guaranteed empty). -'option update-shallow \{'true'|'false'\}:: +'option update-shallow {'true'|'false'}:: Allow to extend .git/shallow if the new refs require it. SEE ALSO 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/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 bf383c2e8c..8c6478b2f2 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -411,6 +411,27 @@ 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>>, 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]. @@ -469,6 +490,11 @@ The most notable example is `HEAD`. <<def_push,push>> to describe the mapping between remote <<def_ref,ref>> and local ref. +[[def_remote]]remote repository:: + A <<def_repository,repository>> which is used to track the same + project but resides somewhere else. To communicate with remotes, + see <<def_fetch,fetch>> or <<def_push,push>>. + [[def_remote_tracking_branch]]remote-tracking branch:: A <<def_ref,ref>> that is used to follow changes from another <<def_repository,repository>>. It typically looks like @@ -515,6 +541,17 @@ The most notable example is `HEAD`. is created by giving the `--depth` option to linkgit:git-clone[1], and its history can be later deepened with linkgit:git-fetch[1]. +[[def_submodule]]submodule:: + A <<def_repository,repository>> that holds the history of a + separate project inside another repository (the latter of + which is called <<def_superproject, superproject>>). + +[[def_superproject]]superproject:: + A <<def_repository,repository>> that references repositories + of other projects in its working tree as <<def_submodule,submodules>>. + The superproject knows about the names of (but does not hold + copies of) commit objects of the contained submodules. + [[def_symref]]symref:: Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id itself, it is of the format 'ref: refs/some/thing' and when 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/line-range-format.txt b/Documentation/line-range-format.txt index d7f26039ca..829676ff98 100644 --- a/Documentation/line-range-format.txt +++ b/Documentation/line-range-format.txt @@ -22,8 +22,9 @@ This is only valid for <end> and will specify a number of lines before or after the line given by <start>. + -If ``:<regex>'' is given in place of <start> and <end>, it denotes the range -from the first funcname line that matches <regex>, up to the next -funcname line. ``:<regex>'' searches from the end of the previous `-L` range, -if any, otherwise from the start of file. -``^:<regex>'' searches from the start of file. +If ``:<funcname>'' is given in place of <start> and <end>, it is a +regular expression that denotes the range from the first funcname line +that matches <funcname>, up to the next funcname line. ``:<funcname>'' +searches from the end of the previous `-L` range, if any, otherwise +from the start of file. ``^:<funcname>'' searches from the start of +file. diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 8a0e52f8ee..002ca58c21 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -26,11 +26,7 @@ merge.ff:: allowed (equivalent to giving the `--ff-only` option from the command line). -merge.log:: - In addition to branch names, populate the log message with at - most the specified number of one-line descriptions from the - actual commits that are being merged. Defaults to false, and - true is a synonym for 20. +include::fmt-merge-msg-config.txt[] merge.renameLimit:: The number of files to consider when performing rename detection diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index dcf7429a47..dc865cbb27 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -79,7 +79,10 @@ stored in the commit object. Notably, the SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and 'parents' information show the true parent commits, without taking grafts or history -simplification into account. +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +`git log --raw`. To get full object names in a raw diff format, +use `--no-abbrev`. * 'format:<string>' + diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 74aa01a0ec..642af6e426 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -37,7 +37,10 @@ people using 80-column terminals. in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this - defaults to UTF-8. + defaults to UTF-8. Note that if an object claims to be encoded + in `X` and we are outputting in `X`, we will output the object + verbatim; this means that invalid sequences in the original + commit may be copied to the output. --notes[=<ref>]:: Show the notes (see linkgit:git-notes[1]) that annotate the diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 77ac439234..a9b808fab3 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -727,6 +727,11 @@ format, often found in email messages. + `--date=raw` shows the date in the internal raw Git format `%s %z` format. + +`--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. ++ `--date=default` shows timestamps in the original time zone (either committer's or author's). diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 07961185fe..d85e303364 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -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. diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 1a797812fb..8076172a08 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. 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..5f0757dcc9 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -168,6 +168,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 +218,19 @@ 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. + 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..2cfdd224a8 100644 --- a/Documentation/technical/api-remote.txt +++ b/Documentation/technical/api-remote.txt @@ -97,10 +97,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/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..7392ff636c 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -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 462e20645f..4064fc796f 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -1,11 +1,11 @@ Packfile transfer protocols =========================== -Git supports transferring data in packfiles over the ssh://, git:// and +Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing data from a client to a server and another for fetching data from a -server to a client. All three transports (ssh, git, file) use the same -protocol to transfer data. +server to a client. The three transports (ssh, git, file) use the same +protocol to transfer data. http is documented in http-protocol.txt. The processes invoked in the canonical Git implementation are 'upload-pack' on the server side and 'fetch-pack' on the client side for fetching data; @@ -465,7 +465,7 @@ contain all the objects that the server will need to complete the new references. ---- - update-request = *shallow ( command-list | push-cert ) [pack-file] + update-request = *shallow ( command-list | push-cert ) [packfile] shallow = PKT-LINE("shallow" SP obj-id LF) @@ -491,7 +491,7 @@ references. *PKT-LINE(gpg-signature-lines LF) PKT-LINE("push-cert-end" LF) - pack-file = "PACK" 28*(OCTET) + packfile = "PACK" 28*(OCTET) ---- If the receiving end does not support delete-refs, the sending end MUST @@ -502,11 +502,11 @@ MUST NOT send a push-cert command. When a push-cert command is sent, command-list MUST NOT be sent; the commands recorded in the push certificate is used instead. -The pack-file MUST NOT be sent if the only command used is 'delete'. +The packfile MUST NOT be sent if the only command used is 'delete'. -A pack-file MUST be sent if either create or update command is used, +A packfile MUST be sent if either create or update command is used, even if the server already has all the necessary objects. In this -case the client MUST send an empty pack-file. The only time this +case the client MUST send an empty packfile. The only time this is likely to happen is if the client is creating a new branch or a tag that points to an existing obj-id. 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/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 -------- |