diff options
Diffstat (limited to 'Documentation')
35 files changed, 1094 insertions, 79 deletions
diff --git a/Documentation/RelNotes/2.7.0.txt b/Documentation/RelNotes/2.7.0.txt new file mode 100644 index 0000000000..563dadc57e --- /dev/null +++ b/Documentation/RelNotes/2.7.0.txt @@ -0,0 +1,414 @@ +Git 2.7 Release Notes +===================== + +Updates since v2.6 +------------------ + +UI, Workflows & Features + + * The appearance of "gitk", particularly on high DPI monitors, have + been improved. "gitk" also comes with an undated translation for + Swedish and Japanese. + + * "git remote" learned "get-url" subcommand to show the URL for a + given remote name used for fetching and pushing. + + * There was no way to defeat a configured rebase.autostash variable + from the command line, as "git rebase --no-autostash" was missing. + + * "git log --date=local" used to only show the normal (default) + format in the local timezone. The command learned to take 'local' + as an instruction to use the local timezone with other formats, + + * The refs used during a "git bisect" session is now per-worktree so + that independent bisect sessions can be done in different worktrees + created with "git worktree add". + + * Users who are too busy to type three extra keystrokes to ask for + "git stash show -p" can now set stash.showPatch configuration + variable to true to always see the actual patch, not just the list + of paths affected with feel for the extent of damage via diffstat. + + * "quiltimport" allows to specify the series file by honoring the + $QUILT_SERIES environment and also --series command line option. + + * The use of 'good/bad' in "git bisect" made it confusing to use when + hunting for a state change that is not a regression (e.g. bugfix). + The command learned 'old/new' and then allows the end user to + say e.g. "bisect start --term-old=fast --term-new=slow" to find a + performance regression. + + * "git interpret-trailers" can now run outside of a Git repository. + + * "git p4" learned to reencode the pathname it uses to communicate + with the p4 depot with a new option. + + * Give progress meter to "git filter-branch". + + * Allow a later "!/abc/def" to override an earlier "/abc" that + appears in the same .gitignore file to make it easier to express + "everything in /abc directory is ignored, except for ...". + + * Teach "git p4" to send large blobs outside the repository by + talking to Git LFS. + + * Prepare for Git on-disk repository representation to undergo + backward incompatible changes by introducing a new repository + format version "1", with an extension mechanism. + + * "git worktree" learned a "list" subcommand. + + * "git clone --dissociate" learned that it can be used even when + "--reference" was not used at the same time. + + * "git blame" learnt to take "--first-parent" and "--reverse" at the + same time when it makes sense. + + * "git checkout" did not follow the usual "--[no-]progress" + convention and implemented only "--quiet" that is essentially + a superset of "--no-progress". Extend the command to support the + usual "--[no-]progress". + + * The semantics of transfer.hideRefs configuration variable have been + extended to work better with the ref "namespace" feature that lets + you throw unrelated bunches of repositories in a single physical + repository and virtually serve them as separate ones. + + * send-email config variables whose values are pathnames now go + through the ~username/ expansion. + + * bash completion learnt to TAB-complete recipient addresses given + to send-email. + + * The credential-cache daemon can be told to ignore SIGHUP to work + around issue when running Git from inside emacs. + + * "git push" learned new configuration for doing "--recurse-submodules" + on each push. + + * "format-patch" has learned a new option to zero-out the commit + object name on the mbox "From " line. + + +Performance, Internal Implementation, Development Support etc. + + * The infrastructure to rewrite "git submodule" in C is being built + incrementally. Let's polish these early parts well enough and make + them graduate to 'next' and 'master', so that the more involved + follow-up can start cooking on a solid ground. + + * Some features from "git tag -l" and "git branch -l" have been made + available to "git for-each-ref" so that eventually the unified + implementation can be shared across all three. The version merged + to the 'master' branch earlier had a performance regression in "tag + --contains", which has since been corrected. + + * Because "test_when_finished" in our test framework queues the + clean-up tasks to be done in a shell variable, it should not be + used inside a subshell. Add a mechanism to allow 'bash' to catch + such uses, and fix the ones that were found. + + * The debugging infrastructure for pkt-line based communication has + been improved to mark the side-band communication specifically. + + * Update "git branch" that list existing branches, using the + ref-filter API that is shared with "git tag" and "git + for-each-ref". + + * The test for various line-ending conversions has been enhanced. + + * A few test scripts around "git p4" have been improved for + portability. + + * Many allocations that is manually counted (correctly) that are + followed by strcpy/sprintf have been replaced with a less error + prone constructs such as xstrfmt. + + * The internal stripspace() function has been moved to where it + logically belongs to, i.e. strbuf API, and the command line parser + of "git stripspace" has been updated to use the parse_options API. + + * "git am" used to spawn "git mailinfo" via run_command() API once + per each patch, but learned to make a direct call to mailinfo() + instead. + + * The implementation of "git mailinfo" was refactored so that a + mailinfo() function can be directly called from inside a process. + + * With a "debug" helper, debugging of a single "git" invocation in + our test scripts has become a lot easier. + + * The "configure" script did not test for -lpthread correctly, which + upset some linkers. + + * Cross completed task off of subtree project's todo list. + + * Test cleanups for the subtree project. + + * Clean up style in an ancient test t9300. + + * Work around some test flakiness with p4d. + + * Fsck did not correctly detect a NUL-truncated header in a tag. + + * Use a safer behavior when we hit errors verifying remote certificates. + + * Speed up filter-branch for cases where we only care about rewriting + commits, not tree data. + + * The parse-options API has been updated to make "-h" command line + option work more consistently in all commands. + + * "git svn rebase/mkdirs" got optimized by keeping track of empty + directories better. + + * Fix some racy client/server tests by treating SIGPIPE the same as a + normal non-zero exit. + + * The necessary infrastructure to build topics using the free Travis + CI has been added. Developers forking from this topic (and enabling + Travis) can do their own builds, and we can turn on auto-builds for + git/git (including build-status for pull requests that people + open). + + * The write(2) emulation for Windows learned to set errno to EPIPE + when necessary. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.6 +---------------- + +Unless otherwise noted, all the fixes since v2.6 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * Very small number of options take a parameter that is optional + (which is not a great UI element as they can only appear at the end + of the command line). Add notice to documentation of each and + every one of them. + + * "git blame --first-parent v1.0..v2.0" was not rejected but did not + limit the blame to commits on the first parent chain. + + * "git subtree" (in contrib/) now can take whitespaces in the + pathnames, not only in the in-tree pathname but the name of the + directory that the repository is in. + + * The ssh transport, just like any other transport over the network, + did not clear GIT_* environment variables, but it is possible to + use SendEnv and AcceptEnv to leak them to the remote invocation of + Git, which is not a good idea at all. Explicitly clear them just + like we do for the local transport. + + * Correct "git p4 --detect-labels" so that it does not fail to create + a tag that points at a commit that is also being imported. + + * The Makefile always runs the library archiver with hardcoded "crs" + options, which was inconvenient for exotic platforms on which + people want to use programs with totally different set of command + line options. + + * Customization to change the behaviour with "make -w" and "make -s" + in our Makefile was broken when they were used together. + + * Allocation related functions and stdio are unsafe things to call + inside a signal handler, and indeed killing the pager can cause + glibc to deadlock waiting on allocation mutex as our signal handler + tries to free() some data structures in wait_for_pager(). Reduce + these unsafe calls. + + * The way how --ref/--notes to specify the notes tree reference are + DWIMmed was not clearly documented. + + * "git gc" used to barf when a symbolic ref has gone dangling + (e.g. the branch that used to be your upstream's default when you + cloned from it is now gone, and you did "fetch --prune"). + + * "git clone --dissociate" runs a big "git repack" process at the + end, and it helps to close file descriptors that are open on the + packs and their idx files before doing so on filesystems that + cannot remove a file that is still open. + + * Description of the "log.follow" configuration variable in "git log" + documentation is now also copied to "git config" documentation. + + * "git rebase -i" had a minor regression recently, which stopped + considering a line that begins with an indented '#' in its insn + sheet not a comment. Further, the code was still too picky on + Windows where CRLF left by the editor is turned into a trailing CR + on the line read via the "read" built-in command of bash. Both of + these issues are now fixed. + + * After "git checkout --detach", "git status" reported a fairly + useless "HEAD detached at HEAD", instead of saying at which exact + commit. + + * When "git send-email" wanted to talk over Net::SMTP::SSL, + Net::Cmd::datasend() did not like to be fed too many bytes at the + same time and failed to send messages. Send the payload one line + at a time to work around the problem. + + * When "git am" was rewritten as a built-in, it stopped paying + attention to user.signingkey, which was fixed. + + * It was not possible to use a repository-lookalike created by "git + worktree add" as a local source of "git clone". + + * On a case insensitive filesystems, setting GIT_WORK_TREE variable + using a random cases that does not agree with what the filesystem + thinks confused Git that it wasn't inside the working tree. + + * Performance-measurement tests did not work without an installed Git. + + * A test script for the HTTP service had a timing dependent bug, + which was fixed. + + * There were some classes of errors that "git fsck" diagnosed to its + standard error that did not cause it to exit with non-zero status. + + * Work around "git p4" failing when the P4 depot records the contents + in UTF-16 without UTF-16 BOM. + + * When "git gc --auto" is backgrounded, its diagnosis message is + lost. Save it to a file in $GIT_DIR and show it next time the "gc + --auto" is run. + + * The submodule code has been taught to work better with separate + work trees created via "git worktree add". + + * "git gc" is safe to run anytime only because it has the built-in + grace period to protect young objects. In order to run with no + grace period, the user must make sure that the repository is + quiescent. + + * A recent "filter-branch --msg-filter" broke skipping of the commit + object header, which is fixed. + + * The normalize_ceiling_entry() function does not muck with the end + of the path it accepts, and the real world callers do rely on that, + but a test insisted that the function drops a trailing slash. + + * A test for interaction between untracked cache and sparse checkout + added in Git 2.5 days were flaky. + + * A couple of commands still showed "[options]" in their usage string + to note where options should come on their command line, but we + spell that "[<options>]" in most places these days. + + * The synopsis text and the usage string of subcommands that read + list of things from the standard input are often shown as if they + only take input from a file on a filesystem, which was misleading. + + * "git am -3" had a small regression where it is aborted in its error + handling codepath when underlying merge-recursive failed in certain + ways, as it assumed that the internal call to merge-recursive will + never die, which is not the case (yet). + + * The linkage order of libraries was wrong in places around libcurl. + + * The name-hash subsystem that is used to cope with case insensitive + filesystems keeps track of directories and their on-filesystem + cases for all the paths in the index by holding a pointer to a + randomly chosen cache entry that is inside the directory (for its + ce->ce_name component). This pointer was not updated even when the + cache entry was removed from the index, leading to use after free. + This was fixed by recording the path for each directory instead of + borrowing cache entries and restructuring the API somewhat. + + * "git merge-file" tried to signal how many conflicts it found, which + obviously would not work well when there are too many of them. + + * The error message from "git blame --contents --reverse" incorrectly + talked about "--contents --children". + + * "git imap-send" did not compile well with older version of cURL library. + + * Merging a branch that removes a path and another that changes the + mode bits on the same path should have conflicted at the path, but + it didn't and silently favoured the removal. + + * "git --literal-pathspecs add -u/-A" without any command line + argument misbehaved ever since Git 2.0. + + * "git daemon" uses "run_command()" without "finish_command()", so it + needs to release resources itself, which it forgot to do. + + * "git status --branch --short" accessed beyond the constant string + "HEAD", which has been corrected. + + * We peek objects from submodule's object store by linking it to the + list of alternate object databases, but the code to do so forgot to + correctly initialize the list. + + * The code to prepare the working tree side of temporary directory + for the "dir-diff" feature forgot that symbolic links need not be + copied (or symlinked) to the temporary area, as the code already + special cases and overwrites them. Besides, it was wrong to try + computing the object name of the target of symbolic link, which may + not even exist or may be a directory. + + * A Range: request can be responded with a full response and when + asked properly libcurl knows how to strip the result down to the + requested range. However, we were hand-crafting a range request + and it did not kick in. + + * Having a leftover .idx file without corresponding .pack file in + the repository hurts performance; "git gc" learned to prune them. + + * Apple's common crypto implementation of SHA1_Update() does not take + more than 4GB at a time, and we now have a compile-time workaround + for it. + + * Produce correct "dirty" marker for shell prompts, even when we + are on an orphan or an unborn branch. + + * A build without NO_IPv6 used to use gethostbyname() when guessing + user's hostname, instead of getaddrinfo() that is used in other + codepaths in such a build. + + * The exit code of git-fsck did not reflect some types of errors + found in packed objects, which has been corrected. + + * The helper used to iterate over loose object directories to prune + stale objects did not closedir() immediately when it is done with a + directory--a callback such as the one used for "git prune" may want + to do rmdir(), but it would fail on open directory on platforms + such as WinXP. + + * "git p4" used to import Perforce CLs that touch only paths outside + the client spec as empty commits. It has been corrected to ignore + them instead, with a new configuration git-p4.keepEmptyCommits as a + backward compatibility knob. + + * The completion script (in contrib/) used to list "git column" + (which is not an end-user facing command) as one of the choices + (merge 160fcdb sg/completion-no-column later to maint). + + * The error reporting from "git send-email", when SMTP TLS fails, has + been improved. + (merge 9d60524 jk/send-email-ssl-errors later to maint). + + * When getpwuid() on the system returned NULL (e.g. the user is not + in the /etc/passwd file or other uid-to-name mappings), the + codepath to find who the user is to record it in the reflog barfed + and died. Loosen the check in this codepath, which already accepts + questionable ident string (e.g. host part of the e-mail address is + obviously bogus), and in general when we operate fmt_ident() function + in non-strict mode. + (merge 92bcbb9 jk/ident-loosen-getpwuid later to maint). + + * "git symbolic-ref" forgot to report a failure with its exit status. + (merge f91b273 jk/symbolic-ref-maint later to maint). + + * History traversal with "git log --source" that starts with an + annotated tag failed to report the tag as "source", due to an + old regression in the command line parser back in v2.2 days. + (merge 728350b jk/pending-keep-tag-name later to maint). + + * "git p4" when interacting with multiple depots at the same time + used to incorrectly drop changes. + + * Code clean-up, minor fixes etc. diff --git a/Documentation/RelNotes/2.7.1.txt b/Documentation/RelNotes/2.7.1.txt new file mode 100644 index 0000000000..6553d69e33 --- /dev/null +++ b/Documentation/RelNotes/2.7.1.txt @@ -0,0 +1,87 @@ +Git v2.7.1 Release Notes +======================== + +Fixes since v2.7 +---------------- + + * An earlier change in 2.5.x-era broke users' hooks and aliases by + exporting GIT_WORK_TREE to point at the root of the working tree, + interfering when they tried to use a different working tree without + setting GIT_WORK_TREE environment themselves. + + * The "exclude_list" structure has the usual "alloc, nr" pair of + fields to be used by ALLOC_GROW(), but clear_exclude_list() forgot + to reset 'alloc' to 0 when it cleared 'nr' to discard the managed + array. + + * "git send-email" was confused by escaped quotes stored in the alias + files saved by "mutt", which has been corrected. + + * A few unportable C construct have been spotted by clang compiler + and have been fixed. + + * The documentation has been updated to hint the connection between + the '--signoff' option and DCO. + + * "git reflog" incorrectly assumed that all objects that used to be + at the tip of a ref must be commits, which caused it to segfault. + + * The ignore mechanism saw a few regressions around untracked file + listing and sparse checkout selection areas in 2.7.0; the change + that is responsible for the regression has been reverted. + + * Some codepaths used fopen(3) when opening a fixed path in $GIT_DIR + (e.g. COMMIT_EDITMSG) that is meant to be left after the command is + done. This however did not work well if the repository is set to + be shared with core.sharedRepository and the umask of the previous + user is tighter. They have been made to work better by calling + unlink(2) and retrying after fopen(3) fails with EPERM. + + * Asking gitweb for a nonexistent commit left a warning in the server + log. + + * "git rebase", unlike all other callers of "gc --auto", did not + ignore the exit code from "gc --auto". + + * Many codepaths that run "gc --auto" before exiting kept packfiles + mapped and left the file descriptors to them open, which was not + friendly to systems that cannot remove files that are open. They + now close the packs before doing so. + + * A recent optimization to filter-branch in v2.7.0 introduced a + regression when --prune-empty filter is used, which has been + corrected. + + * The description for SANITY prerequisite the test suite uses has + been clarified both in the comment and in the implementation. + + * "git tag" started listing a tag "foo" as "tags/foo" when a branch + named "foo" exists in the same repository; remove this unnecessary + disambiguation, which is a regression introduced in v2.7.0. + + * The way "git svn" uses auth parameter was broken by Subversion + 1.9.0 and later. + + * The "split" subcommand of "git subtree" (in contrib/) incorrectly + skipped merges when it shouldn't, which was corrected. + + * A few options of "git diff" did not work well when the command was + run from a subdirectory. + + * dirname() emulation has been added, as Msys2 lacks it. + + * The underlying machinery used by "ls-files -o" and other commands + have been taught not to create empty submodule ref cache for a + directory that is not a submodule. This removes a ton of wasted + CPU cycles. + + * Drop a few old "todo" items by deciding that the change one of them + suggests is not such a good idea, and doing the change the other + one suggested to do. + + * Documentation for "git fetch --depth" has been updated for clarity. + + * The command line completion learned a handful of additional options + and command specific syntax. + +Also includes a handful of documentation and test updates. diff --git a/Documentation/RelNotes/2.7.2.txt b/Documentation/RelNotes/2.7.2.txt new file mode 100644 index 0000000000..4feef76704 --- /dev/null +++ b/Documentation/RelNotes/2.7.2.txt @@ -0,0 +1,41 @@ +Git v2.7.2 Release Notes +======================== + +Fixes since v2.7.1 +------------------ + + * The low-level merge machinery has been taught to use CRLF line + termination when inserting conflict markers to merged contents that + are themselves CRLF line-terminated. + + * "git worktree" had a broken code that attempted to auto-fix + possible inconsistency that results from end-users moving a + worktree to different places without telling Git (the original + repository needs to maintain backpointers to its worktrees, but + "mv" run by end-users who are not familiar with that fact will + obviously not adjust them), which actually made things worse + when triggered. + + * "git push --force-with-lease" has been taught to report if the push + needed to force (or fast-forwarded). + + * The emulated "yes" command used in our test scripts has been + tweaked not to spend too much time generating unnecessary output + that is not used, to help those who test on Windows where it would + not stop until it fills the pipe buffer due to lack of SIGPIPE. + + * The vimdiff backend for "git mergetool" has been tweaked to arrange + and number buffers in the order that would match the expectation of + majority of people who read left to right, then top down and assign + buffers 1 2 3 4 "mentally" to local base remote merge windows based + on that order. + + * The documentation for "git clean" has been corrected; it mentioned + that .git/modules/* are removed by giving two "-f", which has never + been the case. + + * Paths that have been told the index about with "add -N" are not + quite yet in the index, but a few commands behaved as if they + already are in a harmful way. + +Also includes tiny documentation and test updates. diff --git a/Documentation/RelNotes/2.7.3.txt b/Documentation/RelNotes/2.7.3.txt new file mode 100644 index 0000000000..6adf038915 --- /dev/null +++ b/Documentation/RelNotes/2.7.3.txt @@ -0,0 +1,62 @@ +Git v2.7.3 Release Notes +======================== + +Fixes since v2.7.2 +------------------ + + * Traditionally, the tests that try commands that work on the + contents in the working tree were named with "worktree" in their + filenames, but with the recent addition of "git worktree" + subcommand, whose tests are also named similarly, it has become + harder to tell them apart. The traditional tests have been renamed + to use "work-tree" instead in an attempt to differentiate them. + + * Many codepaths forget to check return value from git_config_set(); + the function is made to die() to make sure we do not proceed when + setting a configuration variable failed. + + * Handling of errors while writing into our internal asynchronous + process has been made more robust, which reduces flakiness in our + tests. + + * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a + rev, i.e. the object named by the the pathname with wildcard + characters in a tree object. + + * "git rev-parse --git-common-dir" used in the worktree feature + misbehaved when run from a subdirectory. + + * The "v(iew)" subcommand of the interactive "git am -i" command was + broken in 2.6.0 timeframe when the command was rewritten in C. + + * "git merge-tree" used to mishandle "both sides added" conflict with + its own "create a fake ancestor file that has the common parts of + what both sides have added and do a 3-way merge" logic; this has + been updated to use the usual "3-way merge with an empty blob as + the fake common ancestor file" approach used in the rest of the + system. + + * The memory ownership rule of fill_textconv() API, which was a bit + tricky, has been documented a bit better. + + * The documentation did not clearly state that the 'simple' mode is + now the default for "git push" when push.default configuration is + not set. + + * Recent versions of GNU grep are pickier when their input contains + arbitrary binary data, which some of our tests uses. Rewrite the + tests to sidestep the problem. + + * A helper function "git submodule" uses since v2.7.0 to list the + modules that match the pathspec argument given to its subcommands + (e.g. "submodule add <repo> <path>") has been fixed. + + * "git config section.var value" to set a value in per-repository + configuration file failed when it was run outside any repository, + but didn't say the reason correctly. + + * The code to read the pack data using the offsets stored in the pack + idx file has been made more carefully check the validity of the + data in the idx. + +Also includes documentation and test updates. diff --git a/Documentation/RelNotes/2.7.4.txt b/Documentation/RelNotes/2.7.4.txt new file mode 100644 index 0000000000..883ae896fe --- /dev/null +++ b/Documentation/RelNotes/2.7.4.txt @@ -0,0 +1,11 @@ +Git v2.7.4 Release Notes +======================== + +Fixes since v2.7.3 +------------------ + + * Bugfix patches were backported from the 'master' front to plug heap + corruption holes, to catch integer overflow in the computation of + pathname lengths, and to get rid of the name_path API. Both of + these would have resulted in writing over an under-allocated buffer + when formulating pathnames while tree traversal. diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index a09969ba08..760eab7428 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -63,11 +63,10 @@ include::line-range-format.txt[] `-` to make the command read from the standard input). --date <format>:: - The value is one of the following alternatives: - {relative,local,default,iso,rfc,short}. If --date is not + Specifies the format used to output dates. If --date is not provided, the value of the blame.date config variable is used. If the blame.date config variable is also not set, the - iso format is used. For more information, See the discussion + iso format is used. For supported values, see the discussion of the --date option at linkgit:git-log[1]. -M|<num>|:: diff --git a/Documentation/config.txt b/Documentation/config.txt index fec0dea5d0..f61788668e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1122,6 +1122,9 @@ credential.<url>.*:: example.com. See linkgit:gitcredentials[7] for details on how URLs are matched. +credentialCache.ignoreSIGHUP:: + Tell git-credential-cache--daemon to ignore SIGHUP, instead of quitting. + include::diff-config.txt[] difftool.<tool>.path:: @@ -1829,9 +1832,7 @@ log.abbrevCommit:: log.date:: Set the default date-time mode for the 'log' command. Setting a value for log.date is similar to using 'git log''s - `--date` option. Possible values are `relative`, `local`, - `default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1] - for details. + `--date` option. See linkgit:git-log[1] for details. log.decorate:: Print out the ref names of any commits that are shown by the log @@ -2228,6 +2229,20 @@ push.gpgSign:: override a value from a lower-priority config file. An explicit command-line flag always overrides this config option. +push.recurseSubmodules:: + Make sure all submodule commits used by the revisions to be pushed + are available on a remote-tracking branch. If the value is 'check' + then Git will verify that all submodule commits that changed in the + revisions to be pushed are available on at least one remote of the + submodule. If any commits are missing, the push will be aborted and + exit with non-zero status. If the value is 'on-demand' then all + submodules that changed in the revisions to be pushed will be + pushed. If on-demand was not able to push all necessary revisions + it will also be aborted and exit with non-zero status. If the value + is 'no' then default behavior of ignoring submodules when pushing + is retained. You may override this configuration at time of push by + specifying '--recurse-submodules=check|on-demand|no'. + rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. @@ -2593,6 +2608,16 @@ status.submoduleSummary:: submodule summary' command, which shows a similar output but does not honor these settings. +stash.showPatch:: + If this is set to true, the `git stash show` command without an + option will show the stash in patch form. Defaults to false. + See description of 'show' command in linkgit:git-stash[1]. + +stash.showStat:: + If this is set to true, the `git stash show` command without an + option will show diffstat of the stash. Defaults to true. + See description of 'show' command in linkgit:git-stash[1]. + submodule.<name>.path:: submodule.<name>.url:: The path within this project and URL for a submodule. These @@ -2665,6 +2690,15 @@ You may also include a `!` in front of the ref name to negate the entry, explicitly exposing it, even if an earlier entry marked it as hidden. If you have multiple hideRefs values, later entries override earlier ones (and entries in more-specific config files override less-specific ones). ++ +If a namespace is in use, the namespace prefix is stripped from each +reference before it is matched against `transfer.hiderefs` patterns. +For example, if `refs/heads/master` is specified in `transfer.hideRefs` and +the current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master` +is omitted from the advertisements but `refs/heads/master` and +`refs/namespaces/bar/refs/heads/master` are still advertised as so-called +"have" lines. In order to match refs before stripping, add a `^` in front of +the ref name. If you combine `!` and `^`, `!` must be specified first. transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 45583d8454..78cd2653cd 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -8,10 +8,11 @@ option old data in `.git/FETCH_HEAD` will be overwritten. --depth=<depth>:: - Deepen or shorten the history of a 'shallow' repository created by - `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) - to the specified number of commits from the tip of each remote - branch history. Tags for the deepened commits are not fetched. + Limit fetching to the specified number of commits from the tip of + each remote branch history. If fetching to a 'shallow' repository + created by `git clone` with `--depth=<depth>` option (see + linkgit:git-clone[1]), deepen or shorten the history to the specified + number of commits. Tags for the deepened commits are not fetched. --unshallow:: If the source repository is complete, convert a shallow diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index fe5282f130..6a96a669c2 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -24,7 +24,7 @@ remove paths that do not exist in the working tree anymore. The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus -after making any changes to the working directory, and before running +after making any changes to the working tree, and before running the commit command, you must use the `add` command to add any new or modified files to the index. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 452c1feb23..13cdd7f3b6 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -35,6 +35,7 @@ OPTIONS --signoff:: Add a `Signed-off-by:` line to the commit message, using the committer identity of yourself. + See the signoff option in linkgit:git-commit[1] for more information. -k:: --keep:: diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 1b7a97b1db..7e79aaedeb 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -16,9 +16,11 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: - git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] - git bisect bad [<rev>] - git bisect good [<rev>...] + git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>] + [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] + git bisect (bad|new) [<rev>] + git bisect (good|old) [<rev>...] + git bisect terms [--term-good | --term-bad] git bisect skip [(<rev>|<range>)...] git bisect reset [<commit>] git bisect visualize @@ -36,6 +38,13 @@ whether the selected commit is "good" or "bad". It continues narrowing down the range until it finds the exact commit that introduced the change. +In fact, `git bisect` can be used to find the commit that changed +*any* property of your project; e.g., the commit that fixed a bug, or +the commit that caused a benchmark's performance to improve. To +support this more general usage, the terms "old" and "new" can be used +in place of "good" and "bad", or you can choose your own terms. See +section "Alternate terms" below for more information. + Basic bisect commands: start, bad, good ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -111,6 +120,79 @@ bad revision, while `git bisect reset HEAD` will leave you on the current bisection commit and avoid switching commits at all. +Alternate terms +~~~~~~~~~~~~~~~ + +Sometimes you are not looking for the commit that introduced a +breakage, but rather for a commit that caused a change between some +other "old" state and "new" state. For example, you might be looking +for the commit that introduced a particular fix. Or you might be +looking for the first commit in which the source-code filenames were +finally all converted to your company's naming standard. Or whatever. + +In such cases it can be very confusing to use the terms "good" and +"bad" to refer to "the state before the change" and "the state after +the change". So instead, you can use the terms "old" and "new", +respectively, in place of "good" and "bad". (But note that you cannot +mix "good" and "bad" with "old" and "new" in a single session.) + +In this more general usage, you provide `git bisect` with a "new" +commit has some property and an "old" commit that doesn't have that +property. Each time `git bisect` checks out a commit, you test if that +commit has the property. If it does, mark the commit as "new"; +otherwise, mark it as "old". When the bisection is done, `git bisect` +will report which commit introduced the property. + +To use "old" and "new" instead of "good" and bad, you must run `git +bisect start` without commits as argument and then run the following +commands to add the commits: + +------------------------------------------------ +git bisect old [<rev>] +------------------------------------------------ + +to indicate that a commit was before the sought change, or + +------------------------------------------------ +git bisect new [<rev>...] +------------------------------------------------ + +to indicate that it was after. + +To get a reminder of the currently used terms, use + +------------------------------------------------ +git bisect terms +------------------------------------------------ + +You can get just the old (respectively new) term with `git bisect term +--term-old` or `git bisect term --term-good`. + +If you would like to use your own terms instead of "bad"/"good" or +"new"/"old", you can choose any names you like (except existing bisect +subcommands like `reset`, `start`, ...) by starting the +bisection using + +------------------------------------------------ +git bisect start --term-old <term-old> --term-new <term-new> +------------------------------------------------ + +For example, if you are looking for a commit that introduced a +performance regression, you might use + +------------------------------------------------ +git bisect start --term-old fast --term-new slow +------------------------------------------------ + +Or if you are looking for the commit that fixed a bug, you might use + +------------------------------------------------ +git bisect start --term-new fixed --term-old broken +------------------------------------------------ + +Then, use `git bisect <term-old>` and `git bisect <term-new>` instead +of `git bisect good` and `git bisect bad` to mark commits. + Bisect visualize ~~~~~~~~~~~~~~~~ @@ -387,6 +469,21 @@ In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit has at least one parent whose reachable graph is fully traversable in the sense required by 'git pack objects'. +* Look for a fix instead of a regression in the code ++ +------------ +$ git bisect start +$ git bisect new HEAD # current commit is marked as new +$ git bisect old HEAD~10 # the tenth commit from now is marked as old +------------ ++ +or: +------------ +$ git bisect start --term-old broken --term-new fixed +$ git bisect fixed +$ git bisect broken HEAD~10 +------------ + Getting help ~~~~~~~~~~~~ diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index bbbade4f51..4a7037f1c8 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -11,7 +11,8 @@ SYNOPSIS 'git branch' [--color[=<when>] | --no-color] [-r | -a] [--list] [-v [--abbrev=<length> | --no-abbrev]] [--column[=<options>] | --no-column] - [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] + [(--merged | --no-merged | --contains) [<commit>]] [--sort=<key>] + [--points-at <object>] [<pattern>...] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 'git branch' --unset-upstream [<branchname>] @@ -231,6 +232,19 @@ start-point is either a local or remote-tracking branch. The new name for an existing branch. The same restrictions as for <branchname> apply. +--sort=<key>:: + Sort based on the key given. Prefix `-` to sort in descending + order of the value. You may use the --sort=<key> option + multiple times, in which case the last key becomes the primary + key. The keys supported are the same as those in `git + for-each-ref`. Sort order defaults to sorting based on the + full refname (including `refs/...` prefix). This lists + detached HEAD (if present) first, then local branches and + finally remote-tracking branches. + + +--points-at <object>:: + Only list branches of the given object. Examples -------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index e269fb1108..5e5273e073 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -107,6 +107,12 @@ OPTIONS --quiet:: Quiet, suppress feedback messages. +--[no-]progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless `--quiet` + is specified. This flag enables progress reporting even if not + attached to a terminal, regardless of `--quiet`. + -f:: --force:: When switching branches, proceed even if the index or the diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 77da29a474..6154e57238 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -100,6 +100,7 @@ effect to your index in a row. -s:: --signoff:: Add Signed-off-by line at the end of the commit message. + See the signoff option in linkgit:git-commit[1] for more information. -S[<keyid>]:: --gpg-sign[=<keyid>]:: diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 641681f61a..51a7e26a8e 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -37,9 +37,7 @@ OPTIONS to false, 'git clean' will refuse to delete files or directories unless given -f, -n or -i. Git will refuse to delete directories with .git sub directory or file unless a second -f - is given. This affects also git submodules where the storage area - of the removed submodule under .git/modules/ is not removed until - -f is given twice. + is given. -i:: --interactive:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index f1f2a3f7ea..789b668f77 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -104,8 +104,13 @@ objects from the source repository into a pack in the cloned repository. --dissociate:: Borrow the objects from reference repositories specified with the `--reference` options only to reduce network - transfer and stop borrowing from them after a clone is made - by making necessary local copies of borrowed objects. + transfer, and stop borrowing from them after a clone is made + by making necessary local copies of borrowed objects. This + option can also be used when cloning locally from a + repository that already borrows objects from another + repository--the new repository will borrow objects from the + same repository, and this option can be used to stop the + borrowing. --quiet:: -q:: @@ -185,15 +190,14 @@ objects from the source repository into a pack in the cloned repository. --depth <depth>:: Create a 'shallow' clone with a history truncated to the - specified number of revisions. + specified number of commits. Implies `--single-branch` unless + `--no-single-branch` is given to fetch the histories near the + tips of all branches. --[no-]single-branch:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary - branch remote's `HEAD` points at. When creating a shallow - clone with the `--depth` option, this is the default, unless - `--no-single-branch` is given to fetch the histories near the - tips of all branches. + branch remote's `HEAD` points at. Further fetches into the resulting repository will only update the remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 7f34a5b331..9ec6b3cc17 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -154,7 +154,11 @@ OPTIONS -s:: --signoff:: Add Signed-off-by line by the committer at the end of the commit - log message. + log message. The meaning of a signoff depends on the project, + but it typically certifies that committer has + the rights to submit this work under the same license and + agrees to a Developer Certificate of Origin + (see http://developercertificate.org/ for more information). -n:: --no-verify:: diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 7f8d9a5b5f..2e3e96f663 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -10,6 +10,8 @@ SYNOPSIS [verse] 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] [<pattern>...] + [--points-at <object>] [(--merged | --no-merged) [<object>]] + [--contains [<object>]] DESCRIPTION ----------- @@ -62,6 +64,20 @@ OPTIONS the specified host language. This is meant to produce a scriptlet that can directly be `eval`ed. +--points-at <object>:: + Only list refs which points at the given object. + +--merged [<object>]:: + Only list refs whose tips are reachable from the + specified commit (HEAD if not specified). + +--no-merged [<object>]:: + Only list refs whose tips are not reachable from the + specified commit (HEAD if not specified). + +--contains [<object>]:: + Only list tags which contain the specified commit (HEAD if not + specified). FIELD NAMES ----------- @@ -76,7 +92,11 @@ refname:: The name of the ref (the part after $GIT_DIR/). For a non-ambiguous short name of the ref append `:short`. The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. + abbreviation mode. If `strip=<N>` is appended, strips `<N>` + slash-separated path components from the front of the refname + (e.g., `%(refname:strip=2)` turns `refs/tags/foo` into `foo`. + `<N>` must be a positive integer. If a displayed ref has fewer + components than `<N>`, the command aborts with an error. objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). @@ -111,10 +131,26 @@ color:: Change output color. Followed by `:<colorname>`, where names are described in `color.branch.*`. +align:: + Left-, middle-, or right-align the content between + %(align:...) and %(end). The "align:" is followed by `<width>` + and `<position>` in any order separated by a comma, where the + `<position>` is either left, right or middle, default being + left and `<width>` is the total length of the content with + alignment. If the contents length is more than the width then + no alignment is performed. If used with '--quote' everything + in between %(align:...) and %(end) is quoted, but if nested + then only the topmost level performs quoting. + In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can be used to specify the value in the header field. +For commit and tag objects, the special `creatordate` and `creator` +fields will correspond to the appropriate date or name-email-date tuple +from the `committer` or `tagger` fields depending on the object type. +These are intended for working on a mix of annotated and lightweight tags. + Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. @@ -123,20 +159,23 @@ The complete message in a commit and tag object is `contents`. Its first line is `contents:subject`, where subject is the concatenation of all lines of the commit message up to the first blank line. The next line is 'contents:body', where body is all of the lines after the first -blank line. Finally, the optional GPG signature is `contents:signature`. +blank line. The optional GPG signature is `contents:signature`. The +first `N` lines of the message is obtained using `contents:lines=N`. -For sorting purposes, fields with numeric values sort in numeric -order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). +For sorting purposes, fields with numeric values sort in numeric order +(`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`). All other fields are used to sort in their byte-value order. +There is also an option to sort by versions, this can be done by using +the fieldname `version:refname` or its alias `v:refname`. + In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error. It returns an empty string instead. As a special case for the date-type fields, you may specify a format for -the date by adding one of `:default`, `:relative`, `:short`, `:local`, -`:iso8601`, `:rfc2822` or `:raw` to the end of the fieldname; e.g. -`%(taggerdate:relative)`. +the date by adding `:` followed by date format name (see the +values the `--date` option to linkgit::git-rev-list[1] takes). EXAMPLES diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 4035649117..b149e09065 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -109,6 +109,7 @@ include::diff-options.txt[] --signoff:: Add `Signed-off-by:` line to the commit message, using the committer identity of yourself. + See the signoff option in linkgit:git-commit[1] for more information. --stdout:: Print all commits to the standard output in mbox format, @@ -256,6 +257,10 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. using this option cannot be applied properly, but they are still useful for code review. +--zero-commit:: + Output an all-zero hash in each patch's From header instead + of the hash of the commit. + --root:: Treat the revision argument as a <revision range>, even if it is just a single commit (that would normally be treated as a diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index b3e768ee81..738cfde10c 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -510,6 +510,45 @@ git-p4.useClientSpec:: option '--use-client-spec'. See the "CLIENT SPEC" section above. This variable is a boolean, not the name of a p4 client. +git-p4.pathEncoding:: + Perforce keeps the encoding of a path as given by the originating OS. + Git expects paths encoded as UTF-8. Use this config to tell git-p4 + what encoding Perforce had used for the paths. This encoding is used + to transcode the paths to UTF-8. As an example, Perforce on Windows + often uses “cp1252” to encode path names. + +git-p4.largeFileSystem:: + Specify the system that is used for large (binary) files. Please note + that large file systems do not support the 'git p4 submit' command. + Only Git LFS [1] is implemented right now. Download + and install the Git LFS command line extension to use this option + and configure it like this: ++ +------------- +git config git-p4.largeFileSystem GitLFS +------------- ++ + [1] https://git-lfs.github.com/ + +git-p4.largeFileExtensions:: + All files matching a file extension in the list will be processed + by the large file system. Do not prefix the extensions with '.'. + +git-p4.largeFileThreshold:: + All files with an uncompressed size exceeding the threshold will be + processed by the large file system. By default the threshold is + defined in bytes. Add the suffix k, m, or g to change the unit. + +git-p4.largeFileCompressedThreshold:: + All files with a compressed size exceeding the threshold will be + processed by the large file system. This option might slow down + your clone/sync process. By default the threshold is defined in + bytes. Add the suffix k, m, or g to change the unit. + +git-p4.largeFilePush:: + Boolean variable which defines if large files are automatically + pushed to a server. + git-p4.keepEmptyCommits:: A changelist that contains only excluded files will be imported as an empty commit if this boolean option is set to true. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 85a4d7d6d5..af521f8990 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -37,6 +37,13 @@ the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide what to push (See linkgit:git-config[1] for the meaning of `push.default`). +When neither the command-line nor the configuration specify what to +push, the default behavior is used, which corresponds to the `simple` +value for `push.default`: the current branch is pushed to the +corresponding upstream branch, but as a safety measure, the push is +aborted if the upstream branch does not have the same name as the +local one. + OPTIONS[[OPTIONS]] ------------------ @@ -257,16 +264,20 @@ origin +master` to force a push to the `master` branch). See the is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---recurse-submodules=check|on-demand:: - Make sure all submodule commits used by the revisions to be - pushed are available on a remote-tracking branch. If 'check' is - used Git will verify that all submodule commits that changed in - the revisions to be pushed are available on at least one remote - of the submodule. If any commits are missing the push will be - aborted and exit with non-zero status. If 'on-demand' is used - all submodules that changed in the revisions to be pushed will - be pushed. If on-demand was not able to push all necessary - revisions it will also be aborted and exit with non-zero status. +--no-recurse-submodules:: +--recurse-submodules=check|on-demand|no:: + May be used to make sure all submodule commits used by the + revisions to be pushed are available on a remote-tracking branch. + If 'check' is used Git will verify that all submodule commits that + changed in the revisions to be pushed are available on at least one + remote of the submodule. If any commits are missing the push will + be aborted and exit with non-zero status. If 'on-demand' is used + all submodules that changed in the revisions to be pushed will be + pushed. If on-demand was not able to push all necessary revisions + it will also be aborted and exit with non-zero status. A value of + 'no' or using '--no-recurse-submodules' can be used to override the + push.recurseSubmodules configuration variable when no submodule + recursion is required. --[no-]verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index d64388cb8e..ff633b0db7 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git quiltimport' [--dry-run | -n] [--author <author>] [--patches <dir>] + [--series <file>] DESCRIPTION @@ -42,13 +43,19 @@ OPTIONS information can be found in the patch description. --patches <dir>:: - The directory to find the quilt patches and the - quilt series file. + The directory to find the quilt patches. + The default for the patch directory is patches or the value of the $QUILT_PATCHES environment variable. +--series <file>:: + The quilt series file. ++ +The default for the series file is <patches>/series +or the value of the $QUILT_SERIES environment +variable. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 8bd22aff87..1d7eceaa93 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -15,6 +15,7 @@ SYNOPSIS 'git remote remove' <name> 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>) 'git remote set-branches' [--add] <name> <branch>... +'git remote get-url' [--push] [--all] <name> 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> 'git remote set-url --delete' [--push] <name> <url> @@ -131,6 +132,15 @@ The named branches will be interpreted as if specified with the With `--add`, instead of replacing the list of currently tracked branches, adds to that list. +'get-url':: + +Retrieves the URLs for a remote. Configurations for `insteadOf` and +`pushInsteadOf` are expanded here. By default, only the first URL is listed. ++ +With '--push', push URLs are queried rather than fetch URLs. ++ +With '--all', all URLs for the remote will be listed. + 'set-url':: Changes URLs for the remote. Sets first URL for remote <name> that matches diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 7b49c85347..ef22f1775b 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -45,7 +45,7 @@ SYNOPSIS [ --regexp-ignore-case | -i ] [ --extended-regexp | -E ] [ --fixed-strings | -F ] - [ --date=(local|relative|default|iso|iso-strict|rfc|short) ] + [ --date=<format>] [ [ --objects | --objects-edge | --objects-edge-aggressive ] [ --unpacked ] ] [ --pretty | --header ] diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index b15139ffdc..573616a04a 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -89,6 +89,7 @@ effect to your index in a row. -s:: --signoff:: Add Signed-off-by line at the end of the commit message. + See the signoff option in linkgit:git-commit[1] for more information. --strategy=<strategy>:: Use the given merge strategy. Should only be used once. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index b9134d234f..771a7b5b09 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git send-email' [options] <file|directory|rev-list options>... +'git send-email' --dump-aliases DESCRIPTION @@ -387,6 +388,16 @@ default to '--validate'. Send emails even if safety checks would prevent it. +Information +~~~~~~~~~~~ + +--dump-aliases:: + Instead of the normal operation, dump the shorthand alias names from + the configured alias file(s), one per line in alphabetical order. Note, + this only includes the alias name and not its expanded email addresses. + See 'sendemail.aliasesfile' for more information about aliases. + + CONFIGURATION ------------- diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 375213fe46..92df596e5f 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -95,6 +95,8 @@ show [<stash>]:: shows the latest one. By default, the command shows the diffstat, but it will accept any format known to 'git diff' (e.g., `git stash show -p stash@{1}` to view the second most recent stash in patch form). + You can use stash.showStat and/or stash.showPatch config variables + to change the default behavior. pop [--index] [-q|--quiet] [<stash>]:: diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 08b4dfbf1b..abab4814ec 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -13,7 +13,8 @@ SYNOPSIS <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>] - [--column[=<options>] | --no-column] [--create-reflog] [<pattern>...] + [--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>] + [--format=<format>] [--[no-]merged [<commit>]] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION @@ -94,14 +95,16 @@ OPTIONS using fnmatch(3)). Multiple patterns may be given; if any of them matches, the tag is shown. ---sort=<type>:: - Sort in a specific order. Supported type is "refname" - (lexicographic order), "version:refname" or "v:refname" (tag +--sort=<key>:: + Sort based on the key given. Prefix `-` to sort in + descending order of the value. You may use the --sort=<key> option + multiple times, in which case the last key becomes the primary + key. Also supports "version:refname" or "v:refname" (tag names are treated as versions). The "version:refname" sort order can also be affected by the - "versionsort.prereleaseSuffix" configuration variable. Prepend - "-" to reverse sort order. When this option is not given, the - sort order defaults to the value configured for the 'tag.sort' + "versionsort.prereleaseSuffix" configuration variable. + The keys supported are the same as those in `git for-each-ref`. + Sort order defaults to the value configured for the 'tag.sort' variable if it exists, or lexicographic order otherwise. See linkgit:git-config[1]. @@ -156,6 +159,16 @@ This option is only applicable when listing tags without annotation lines. The object that the new tag will refer to, usually a commit. Defaults to HEAD. +<format>:: + A string that interpolates `%(fieldname)` from the object + pointed at by a ref being shown. The format is the same as + that of linkgit:git-for-each-ref[1]. When unspecified, + defaults to `%(refname:strip=2)`. + +--[no-]merged [<commit>]:: + Only list tags whose tips are reachable, or not reachable + if '--no-merged' is used, from the specified commit ('HEAD' + if not specified). CONFIGURATION ------------- diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index fb68156cf8..62c76c1c89 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>] 'git worktree prune' [-n] [-v] [--expire <expire>] +'git worktree list' [--porcelain] DESCRIPTION ----------- @@ -31,11 +32,9 @@ The working tree's administrative files in the repository (see `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 you move a linked working tree, you need to manually update the +administrative files so that they do not get pruned automatically. See +section "DETAILS" for more information. If a linked working tree is stored on a portable device or network share which is not always mounted, you can prevent its administrative files from @@ -59,6 +58,13 @@ prune:: Prune working tree information in $GIT_DIR/worktrees. +list:: + +List details of each worktree. The main worktree is listed first, followed by +each of the linked worktrees. The output details include if the worktree is +bare, the revision currently checked out, and the branch currently checked out +(or 'detached HEAD' if none). + OPTIONS ------- @@ -86,6 +92,11 @@ OPTIONS With `prune`, do not remove anything; just report what it would remove. +--porcelain:: + With `list`, output in an easy-to-parse format for scripts. + This format will remain stable across Git versions and regardless of user + configuration. See below for details. + -v:: --verbose:: With `prune`, report all removals. @@ -124,6 +135,13 @@ thumb is do not make any assumption about whether a path belongs to $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. +If you move a linked working tree, you need to update the 'gitdir' file +in the entry's directory. For example, if a linked working tree is moved +to `/newpath/test-next` and its `.git` file points to +`/path/main/.git/worktrees/test-next`, then update +`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` +instead. + To prevent a $GIT_DIR/worktrees entry from being pruned (which can be useful in some situations, such as when the entry's working tree is stored on a portable device), add a file named @@ -134,6 +152,41 @@ to `/path/main/.git/worktrees/test-next` then a file named `test-next` entry from being pruned. See linkgit:gitrepository-layout[5] for details. +LIST OUTPUT FORMAT +------------------ +The worktree list command has two output formats. The default format shows the +details on a single line with columns. For example: + +------------ +S git worktree list +/path/to/bare-source (bare) +/path/to/linked-worktree abcd1234 [master] +/path/to/other-linked-worktree 1234abc (detached HEAD) +------------ + +Porcelain Format +~~~~~~~~~~~~~~~~ +The porcelain format has a line per attribute. Attributes are listed with a +label and value separated by a single space. Boolean attributes (like 'bare' +and 'detached') are listed as a label only, and are only present if and only +if the value is true. An empty line indicates the end of a worktree. For +example: + +------------ +S git worktree list --porcelain +worktree /path/to/bare-source +bare + +worktree /path/to/linked-worktree +HEAD abcd1234abcd1234abcd1234abcd1234abcd1234 +branch refs/heads/master + +worktree /path/to/other-linked-worktree +HEAD 1234abc1234abc1234abc1234abc1234abc1234a +detached + +------------ + EXAMPLES -------- You are in the middle of a refactoring session and your boss comes in and @@ -167,7 +220,6 @@ 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) diff --git a/Documentation/git.txt b/Documentation/git.txt index 64ac7b255f..4b324c8f5e 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,6 +43,14 @@ 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.7.3/git.html[documentation for release 2.7.3] + +* release notes for + link:RelNotes/2.7.3.txt[2.7.3], + link:RelNotes/2.7.2.txt[2.7.2], + link:RelNotes/2.7.1.txt[2.7.1], + link:RelNotes/2.7.0.txt[2.7]. + * link:v2.6.7/git.html[documentation for release 2.6.7] * release notes for diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 7ba0ac965d..a2f59b194c 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -397,7 +397,7 @@ preceding SP is also omitted. Currently, no commands pass any 'extra-info'. The hook always runs after the automatic note copying (see -"notes.rewrite.<command>" in linkgit:git-config.txt[1]) has happened, and +"notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and thus has access to these notes. The following command-specific comments apply: diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 8c6478b2f2..cafc284359 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -413,8 +413,9 @@ exclude;; [[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. + global. This is presently only <<def_HEAD,HEAD>> and any refs + that start with `refs/bisect/`, but might later include other + unusual refs. [[def_pseudoref]]pseudoref:: Pseudorefs are a class of files under `$GIT_DIR` which behave @@ -530,6 +531,11 @@ The most notable example is `HEAD`. "Secure Hash Algorithm 1"; a cryptographic hash function. In the context of Git used as a synonym for <<def_object_name,object name>>. +[[def_shallow_clone]]shallow clone:: + Mostly a synonym to <<def_shallow_repository,shallow repository>> + but the phrase makes it more explicit that it was created by + running `git clone --depth=...` command. + [[def_shallow_repository]]shallow repository:: A shallow <<def_repository,repository>> has an incomplete history some of whose <<def_commit,commits>> have <<def_parent,parents>> cauterized away (in other diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index f1c52208f0..4f009d4424 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -701,15 +701,19 @@ include::pretty-options.txt[] --relative-date:: Synonym for `--date=relative`. ---date=(relative|local|default|iso|iso-strict|rfc|short|raw):: +--date=<format>:: Only takes effect for dates shown in human-readable format, such as when using `--pretty`. `log.date` config variable sets a default - value for the log command's `--date` option. + value for the log command's `--date` option. By default, dates + are shown in the original time zone (either committer's or + author's). If `-local` is appended to the format (e.g., + `iso-local`), the user's local time zone is used instead. + `--date=relative` shows dates relative to the current time, -e.g. ``2 hours ago''. +e.g. ``2 hours ago''. The `-local` option cannot be used with +`--raw` or `--relative`. + -`--date=local` shows timestamps in user's local time zone. +`--date=local` is an alias for `--date=default-local`. + `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. The differences to the strict ISO 8601 format are: @@ -732,10 +736,15 @@ format, often found in email messages. `--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. +format placeholders. When using `-local`, the correct syntax is +`--date=format-local:...`. + -`--date=default` shows timestamps in the original time zone -(either committer's or author's). +`--date=default` is the default format, and is similar to +`--date=rfc2822`, with a few exceptions: + + - there is no comma after the day-of-week + + - the time zone is omitted when the local time zone is used ifdef::git-rev-list[] --header:: diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 8076172a08..cfc063018c 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -56,3 +56,10 @@ Functions `argv_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. + +`argv_array_detach`:: + Disconnect the `argv` member from the `argv_array` struct and + return it. The caller is responsible for freeing the memory used + by the array, and by the strings it references. After detaching, + the `argv_array` is in a reinitialized state and can be pushed + into again. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 1c790ac74a..ec6bacfcdf 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -2125,8 +2125,37 @@ Allowing web browsing of a repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The gitweb cgi script provides users an easy way to browse your -project's files and history without having to install Git; see the file -gitweb/INSTALL in the Git source tree for instructions on setting it up. +project's revisions, file contents and logs without having to install +Git. Features like RSS/Atom feeds and blame/annotation details may +optionally be enabled. + +The linkgit:git-instaweb[1] command provides a simple way to start +browsing the repository using gitweb. The default server when using +instaweb is lighttpd. + +See the file gitweb/INSTALL in the Git source tree and +linkgit:gitweb[1] for instructions on details setting up a permament +installation with a CGI or Perl capable server. + +[[how-to-get-a-git-repository-with-minimal-history]] +How to get a Git repository with minimal history +------------------------------------------------ + +A <<def_shallow_clone,shallow clone>>, with its truncated +history, is useful when one is interested only in recent history +of a project and getting full history from the upstream is +expensive. + +A <<def_shallow_clone,shallow clone>> is created by specifying +the linkgit:git-clone[1] `--depth` switch. The depth can later be +changed with the linkgit:git-fetch[1] `--depth` switch, or full +history restored with `--unshallow`. + +Merging inside a <<def_shallow_clone,shallow clone>> will work as long +as a merge base is in the recent history. +Otherwise, it will be like merging unrelated histories and may +have to result in huge conflicts. This limitation may make such +a repository unsuitable to be used in merge based workflows. [[sharing-development-examples]] Examples @@ -4636,23 +4665,15 @@ Scan email archives for other stuff left out Scan man pages to see if any assume more background than this manual provides. -Simplify beginning by suggesting disconnected head instead of -temporary branch creation? - Add more good examples. Entire sections of just cookbook examples might be a good idea; maybe make an "advanced examples" section a standard end-of-chapter section? Include cross-references to the glossary, where appropriate. -Document shallow clones? See draft 1.5.0 release notes for some -documentation. - Add a section on working with other version control systems, including CVS, Subversion, and just imports of series of release tarballs. -More details on gitweb? - Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. |