From: Jonathan Nieder Date: Mon, 14 Oct 2013 18:07:29 +0000 (-0700) Subject: Merge branch 'po/remote-set-head-usage' X-Git-Tag: v1.8.5-rc0~63 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/c766e6f429f48e4e6e7b5609779e6cca501c31f6?hp=e49c8f33ab8e401d5d8f308f83e2a2c756377ef1 Merge branch 'po/remote-set-head-usage' * po/remote-set-head-usage: remote set-head -h: add long options to synopsis remote doc: document long forms of set-head options --- diff --git a/.gitignore b/.gitignore index 6b1fd1bfb0..66199edd4a 100644 --- a/.gitignore +++ b/.gitignore @@ -202,6 +202,7 @@ /test-string-list /test-subprocess /test-svn-fe +/test-urlmatch-normalization /test-wildmatch /common-cmds.h *.tar.gz diff --git a/.mailmap b/.mailmap index 1c1f5ec6bf..11057cbcdf 100644 --- a/.mailmap +++ b/.mailmap @@ -218,7 +218,9 @@ Tay Ray Chuan Ted Percival Theodore Ts'o Thomas Ackermann -Thomas Rast +Thomas Rast +Thomas Rast +Thomas Rast Timo Hirvonen Toby Allsopp Tom Grennan diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 559d5f9ebf..e5ca3b75d3 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -242,6 +242,14 @@ Writing Documentation: processed into HTML and manpages (e.g. git.html and git.1 in the same directory). + The documentation liberally mixes US and UK English (en_US/UK) + norms for spelling and grammar, which is somewhat unfortunate. + In an ideal world, it would have been better if it consistently + used only one and not the other, and we would have picked en_US + (if you wish to correct the English of some of the existing + documentation, please see the documentation-related advice in the + Documentation/SubmittingPatches file). + Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions. A few commented examples follow to provide reference diff --git a/Documentation/Makefile b/Documentation/Makefile index 0cfdc36b44..4f13a23893 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -103,6 +103,7 @@ MAKEINFO = makeinfo INSTALL_INFO = install-info DOCBOOK2X_TEXI = docbook2x-texi DBLATEX = dblatex +ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex ifndef PERL_PATH PERL_PATH = /usr/bin/perl endif @@ -354,7 +355,7 @@ user-manual.texi: user-manual.xml user-manual.pdf: user-manual.xml $(QUIET_DBLATEX)$(RM) $@+ $@ && \ - $(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $< && \ + $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \ mv $@+ $@ gitman.texi: $(MAN_XML) cat-texi.perl diff --git a/Documentation/RelNotes/1.7.11.2.txt b/Documentation/RelNotes/1.7.11.2.txt index a0d24d1270..f0cfd02d6f 100644 --- a/Documentation/RelNotes/1.7.11.2.txt +++ b/Documentation/RelNotes/1.7.11.2.txt @@ -31,7 +31,7 @@ Fixes since v1.7.11.1 * "git diff --no-index" did not work with pagers correctly. * "git diff COPYING HEAD:COPYING" gave a nonsense error message that - claimed that the treeish HEAD did not have COPYING in it. + claimed that the tree-ish HEAD did not have COPYING in it. * When "git log" gets "--simplify-merges/by-decoration" together with "--first-parent", the combination of these options makes the diff --git a/Documentation/RelNotes/1.8.5.txt b/Documentation/RelNotes/1.8.5.txt new file mode 100644 index 0000000000..49c037b601 --- /dev/null +++ b/Documentation/RelNotes/1.8.5.txt @@ -0,0 +1,341 @@ +Git v1.8.5 Release Notes +======================== + +Backward compatibility notes (for Git 2.0) +------------------------------------------ + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). In Git 2.0, the default will change to the "simple" +semantics that pushes: + + - only the current branch to the branch with the same name, and only + when the current branch is set to integrate with that remote + branch, if you are pushing to the same remote as you fetch from; or + + - only the current branch to the branch with the same name, if you + are pushing to a remote that is not where you usually fetch from. + +Use the user preference configuration variable "push.default" to +change this. If you are an old-timer who is used to the "matching" +semantics, you can set the variable to "matching" to keep the +traditional behaviour. If you want to live in the future early, you +can set it to "simple" today without waiting for Git 2.0. + +When "git add -u" (and "git add -A") is run inside a subdirectory and +does not specify which paths to add on the command line, it +will operate on the entire tree in Git 2.0 for consistency +with "git commit -a" and other commands. There will be no +mechanism to make plain "git add -u" behave like "git add -u .". +Current users of "git add -u" (without a pathspec) should start +training their fingers to explicitly say "git add -u ." +before Git 2.0 comes. A warning is issued when these commands are +run without a pathspec and when you have local changes outside the +current directory, because the behaviour in Git 2.0 will be different +from today's version in such a situation. + +In Git 2.0, "git add " will behave as "git add -A ", so +that "git add dir/" will notice paths you removed from the directory +and record the removal. Versions before Git 2.0, including this +release, will keep ignoring removals, but the users who rely on this +behaviour are encouraged to start using "git add --ignore-removal " +now before 2.0 is released. + + +Updates since v1.8.4 +-------------------- + +Foreign interfaces, subsystems and ports. + + * "git-svn" used with SVN 1.8.0 when talking over https:// connection + dumped core due to a bug in the serf library that SVN uses. Work + it around on our side, even though the SVN side is being fixed. + + * On MacOS X, we detected if the filesystem needs the "pre-composed + unicode strings" workaround, but did not automatically enable it. + Now we do. + + * remote-hg remote helper misbehaved when interacting with a local Hg + repository relative to the home directory, e.g. "clone hg::~/there". + + * imap-send ported to OS X uses Apple's security framework instead of + OpenSSL one. + + * Subversion 1.8.0 that was recently released breaks older subversion + clients coming over http/https in various ways. + + * "git fast-import" treats an empty path given to "ls" as the root of + the tree. + + +UI, Workflows & Features + + * Instead of typing four capital letters "HEAD", you can say "@" now, + e.g. "git log @". + + * "git check-ignore" follows the same rule as "git add" and "git + status" in that the ignore/exclude mechanism does not take effect + on paths that are already tracked. With "--no-index" option, it + can be used to diagnose which paths that should have been ignored + have been mistakenly added to the index. + + * Some irrelevant "advice" messages that are shared with "git status" + output have been removed from the commit log template. + + * "update-refs" learnt a "--stdin" option to read multiple update + requests and perform them in an all-or-none fashion. + + * Just like "make -C ", "git -C ..." tells Git + to go there before doing anything else. + + * Just like "git checkout -" knows to check out and "git merge -" + knows to merge the branch you were previously on, "git cherry-pick" + now understands "git cherry-pick -" to pick from the previous + branch. + + * "git status" now omits the prefix to make its output a comment in a + commit log editor, which is not necessary for human consumption. + Scripts that parse the output of "git status" are advised to use + "git status --porcelain" instead, as its format is stable and easier + to parse. + + * Make "foo^{tag}" to peel a tag to itself, i.e. no-op., and fail if + "foo" is not a tag. "git rev-parse --verify v1.0^{tag}" would be + a more convenient way to say "test $(git cat-file -t v1.0) = tag". + + * "git branch -v -v" (and "git status") did not distinguish among a + branch that does not build on any other branch, a branch that is in + sync with the branch it builds on, and a branch that is configured + to build on some other branch that no longer exists. + + * A packfile that stores the same object more than once is broken and + will be rejected by "git index-pack" that is run when receiving + data over the wire. + + * Earlier we started rejecting an attempt to add 0{40} object name to + the index and to tree objects, but it sometimes is necessary to + allow so to be able to use tools like filter-branch to correct such + broken tree objects. "filter-branch" can again be used to to do + so. + + * "git config" did not provide a way to set or access numbers larger + than a native "int" on the platform; it now provides 64-bit signed + integers on all platforms. + + * "git pull --rebase" always chose to do the bog-standard flattening + rebase. You can tell it to run "rebase --preserve-merges" by + setting "pull.rebase" configuration to "preserve". + + * "git push --no-thin" actually disables the "thin pack transfer" + optimization. + + * Magic pathspecs like ":(icase)makefile" that matches both + Makefile and makefile can be used in more places. + + * The "http.*" variables can now be specified per URL that the + configuration applies. For example, + + [http] + sslVerify = true + [http "https://weak.example.com/"] + sslVerify = false + + would flip http.sslVerify off only when talking to that specified + site. + + * "git mv A B" when moving a submodule A has been taught to + relocate its working tree and to adjust the paths in the + .gitmodules file. + + * "git blame" can now take more than one -L option to discover the + origin of multiple blocks of the lines. + + * The http transport clients can optionally ask to save cookies + with http.savecookies configuration variable. + + * "git push" learned a more fine grained control over a blunt + "--force" when requesting a non-fast-forward update with the + "--force-with-lease=:" option. + + * "git diff --diff-filter=" can now take + lowercase letters (e.g. "--diff-filter=d") to mean "show + everything but these classes". "git diff-files -q" is now a + deprecated synonym for "git diff-files --diff-filter=d". + + * "git fetch" (hence "git pull" as well) learned to check + "fetch.prune" and "remote.*.prune" configuration variables and + to behave as if the "--prune" command line option was given. + + * "git check-ignore -z" applied the NUL termination to both its input + (with --stdin) and its output, but "git check-attr -z" ignored the + option on the output side. Make both honor -z on the input and + output side the same way. + + * "git whatchanged" may still be used by old timers, but mention of + it in documents meant for new users will only waste readers' time + wonderig what the difference is between it and "git log". Make it + less prominent in the general part of the documentation and explain + that it is merely a "git log" with different default behaviour in + its own document. + + +Performance, Internal Implementation, etc. + + * If a build-time fallback is set to "cat" instead of "less", we + should apply the same "no subprocess or pipe" optimization as we + apply to user-supplied GIT_PAGER=cat. + + * Many commands use --dashed-option as a operation mode selector + (e.g. "git tag --delete") that the user can use at most one + (e.g. "git tag --delete --verify" is a nonsense) and you cannot + negate (e.g. "git tag --no-delete" is a nonsense). parse-options + API learned a new OPT_CMDMODE macro to make it easier to implement + such a set of options. + + * OPT_BOOLEAN() in parse-options API was misdesigned to be "counting + up" but many subcommands expect it to behave as "on/off". Update + them to use OPT_BOOL() which is a proper boolean. + + * "git gc" exits early without doing a double-work when it detects + that another instance of itself is already running. + + * Under memory pressure and/or file descriptor pressure, we used to + close pack windows that are not used and also closed filehandle to + an open but unused packfiles. These are now controlled separately + to better cope with the load. + +Also contains various documentation updates and code clean-ups. + + +Fixes since v1.8.4 +------------------ + +Unless otherwise noted, all the fixes since v1.8.4 in the maintenance +track are contained in this release (see release notes to them for +details). + + * When running "fetch -q", a long silence while the sender side + computes the set of objects to send can be mistaken by proxies as + dropped connection. The server side has been taught to send a + small empty messages to keep the connection alive. + (merge 115dedd jk/upload-pack-keepalive later to maint). + + * "git rebase" had a portability regression in v1.8.4 to trigger a + bug in some BSD shell implementations. + (merge 99855dd mm/rebase-continue-freebsd-WB later to maint). + + * "git branch --track" had a minor regression in v1.8.3.2 and later + that made it impossible to base your local work on anything but a + local branch of the upstream repository you are tracking from. + (merge b0f49ff jh/checkout-auto-tracking later to maint). + + * When the webserver responds with "405 Method Not Allowed", "git + http-backend" should tell the client what methods are allowed with + the "Allow" header. + (merge 9247be0 bc/http-backend-allow-405 later to maint). + + * When there is no sufficient overlap between old and new history + during a "git fetch" into a shallow repository, objects that the + sending side knows the receiving end has were unnecessarily sent. + (merge f21d2a7 nd/fetch-into-shallow later to maint). + + * "git cvsserver" computed the permission mode bits incorrectly for + executable files. + (merge 1b48d56 jc/cvsserver-perm-bit-fix later to maint). + + * When send-email comes up with an error message to die with upon + failure to start an SSL session, it tried to read the error string + from a wrong place. + (merge 6cb0c88 bc/send-email-ssl-die-message-fix later to maint). + + * The implementation of "add -i" has a crippling code to work around + ActiveState Perl limitation but it by mistake also triggered on Git + for Windows where MSYS perl is used. + (merge df17e77 js/add-i-mingw later to maint). + + * We made sure that we notice the user-supplied GIT_DIR is actually a + gitfile, but did not do the same when the default ".git" is a + gitfile. + (merge 487a2b7 nd/git-dir-pointing-at-gitfile later to maint). + + * When an object is not found after checking the packfiles and then + loose object directory, read_sha1_file() re-checks the packfiles to + prevent racing with a concurrent repacker; teach the same logic to + has_sha1_file(). + (merge 45e8a74 jk/has-sha1-file-retry-packed later to maint). + + * "git commit --author=$name", when $name is not in the canonical + "A. U. Thor " format, looks for a matching name + from existing history, but did not consult mailmap to grab the + preferred author name. + (merge ea16794 ap/commit-author-mailmap later to maint). + + * "git ls-files -k" needs to crawl only the part of the working tree + that may overlap the paths in the index to find killed files, but + shared code with the logic to find all the untracked files, which + made it unnecessarily inefficient. + (merge 680be04 jc/ls-files-killed-optim later to maint). + + * The commit object names in the insn sheet that was prepared at the + beginning of "rebase -i" session can become ambiguous as the + rebasing progresses and the repository gains more commits. Make + sure the internal record is kept with full 40-hex object names. + (merge 75c6976 es/rebase-i-no-abbrev later to maint). + + * "git rebase --preserve-merges" internally used the merge machinery + and as a side effect, left merge summary message in the log, but + when rebasing, there should not be a need for merge summary. + (merge a9f739c rt/rebase-p-no-merge-summary later to maint). + + * A call to xread() was used without a loop around to cope with short + read in the codepath to stream new contents to a pack. + (merge e92527c js/xread-in-full later to maint). + + * "git rebase -i" forgot that the comment character can be + configurable while reading its insn sheet. + (merge 7bca7af es/rebase-i-respect-core-commentchar later to maint). + + * The mailmap support code read past the allocated buffer when the + mailmap file ended with an incomplete line. + (merge f972a16 jk/mailmap-incomplete-line later to maint). + + * We used to send a large request to read(2)/write(2) as a single + system call, which was bad from the latency point of view when + the operation needs to be killed, and also triggered an error on + broken 64-bit systems that refuse to take more than 2GB read or + write in one go. + (merge a487916 sp/clip-read-write-to-8mb later to maint). + + * "git fetch" that auto-followed tags incorrectly reused the + connection with Git-aware transport helper (like the sample "ext::" + helper shipped with Git). + (merge 0f73f8b jc/transport-do-not-use-connect-twice-in-fetch later to maint). + + * "git log --full-diff -- " showed a huge diff for paths + outside the given for each commit, instead of showing + the change relative to the parent of the commit. "git reflog -p" + had a similar problem. + (merge 838f9a1 tr/log-full-diff-keep-true-parents later to maint). + + * Setting submodule.*.path configuration variable to true (without + giving "= value") caused Git to segfault. + (merge 4b05440 jl/some-submodule-config-are-not-boolean later to maint). + + * "git rebase -i" (there could be others, as the root cause is pretty + generic) fed a random, data dependeant string to 'echo' and + expects it to come out literally, corrupting its error message. + (merge 89b0230 mm/no-shell-escape-in-die-message later to maint). + + * Some people still use rather old versions of bash, which cannot + grok some constructs like 'printf -v varname' the prompt and + completion code started to use recently. + (merge a44aa69 bc/completion-for-bash-3.0 later to maint). + + * Code to read configuration from a blob object did not compile on + platforms with fgetc() etc. implemented as macros. + (merge 49d6cfa hv/config-from-blob later to maint-1.8.3). + + * The recent "short-cut clone connectivity check" topic broke a + shallow repository when a fetch operation tries to auto-follow tags. + (merge 6da8bdc nd/fetch-pack-shallow-fix later to maint-1.8.3). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d0a4733e45..705557689d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -65,7 +65,20 @@ feature does not trigger when it shouldn't. Also make sure that the test suite passes after your commit. Do not forget to update the documentation to describe the updated behaviour. -Oh, another thing. I am picky about whitespaces. Make sure your +Speaking of the documentation, it is currently a liberal mixture of US +and UK English norms for spelling and grammar, which is somewhat +unfortunate. A huge patch that touches the files all over the place +only to correct the inconsistency is not welcome, though. Potential +clashes with other changes that can result from such a patch are not +worth it. We prefer to gradually reconcile the inconsistencies in +favor of US English, with small and easily digestible patches, as a +side effect of doing some other real work in the vicinity (e.g. +rewriting a paragraph for clarity, while turning en_UK spelling to +en_US). Obvious typographical fixes are much more welcomed ("teh -> +"the"), preferably submitted as independent patches separate from +other documentation changes. + +Oh, another thing. We are picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped in templates/hooks--pre-commit. To help ensure this does not happen, run git diff --check on your changes before you commit. diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 4e55b1564e..0cebc4f692 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -11,12 +11,12 @@ -L ,:: -L ::: - Annotate only the given line range. and are optional. - ``-L '' or ``-L ,'' spans from to end of file. - ``-L ,'' spans from start of file to . + Annotate only the given line range. May be specified multiple times. + Overlapping ranges are allowed. ++ + and are optional. ``-L '' or ``-L ,'' spans from + to end of file. ``-L ,'' spans from start of file to . + - and can take one of these forms: - include::line-range-format.txt[] -l:: diff --git a/Documentation/config.txt b/Documentation/config.txt index ec57a15ac5..aaae06fc5a 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -170,8 +170,8 @@ advice.*:: pushNeedsForce:: Shown when linkgit:git-push[1] rejects an update that tries to overwrite a remote ref that points at an - object that is not a committish, or make the remote - ref point at an object that is not a committish. + object that is not a commit-ish, or make the remote + ref point at an object that is not a commit-ish. statusHints:: Show directions on how to proceed from the current state in the output of linkgit:git-status[1], in @@ -553,22 +553,20 @@ sequence.editor:: When not configured the default commit message editor is used instead. core.pager:: - The command that Git will use to paginate output. Can - be overridden with the `GIT_PAGER` environment - variable. Note that Git sets the `LESS` environment - variable to `FRSX` if it is unset when it runs the - pager. One can change these settings by setting the - `LESS` variable to some other value. Alternately, - these settings can be overridden on a project or - global basis by setting the `core.pager` option. - Setting `core.pager` has no effect on the `LESS` - environment variable behaviour above, so if you want - to override Git's default settings this way, you need - to be explicit. For example, to disable the S option - in a backward compatible manner, set `core.pager` - to `less -+S`. This will be passed to the shell by - Git, which will translate the final command to - `LESS=FRSX less -+S`. + Text viewer for use by Git commands (e.g., 'less'). The value + is meant to be interpreted by the shell. The order of preference + is the `$GIT_PAGER` environment variable, then `core.pager` + configuration, then `$PAGER`, and then the default chosen at + compile time (usually 'less'). ++ +When the `LESS` environment variable is unset, Git sets it to `FRSX` +(if `LESS` environment variable is set, Git does not change it at +all). If you want to selectively override Git's default setting +for `LESS`, you can set `core.pager` to e.g. `less -+S`. This will +be passed to the shell by Git, which will translate the final +command to `LESS=FRSX less -+S`. The environment tells the command +to set the `S` option to chop long lines but the command line +resets it to the default to fold long lines. core.whitespace:: A comma separated list of common whitespace problems to @@ -765,6 +763,10 @@ branch..rebase:: instead of merging the default branch from the default remote when "git pull" is run. See "pull.rebase" for doing this in a non branch-specific manner. ++ + When preserve, also pass `--preserve-merges` along to 'git rebase' + so that locally committed merge commits will not be flattened + by running 'git pull'. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] @@ -787,8 +789,8 @@ browser..path:: working repository in gitweb (see linkgit:git-instaweb[1]). clean.requireForce:: - A boolean to make git-clean do nothing unless given -f - or -n. Defaults to true. + A boolean to make git-clean do nothing unless given -f, + -i or -n. Defaults to true. color.branch:: A boolean to enable/disable color in the output of @@ -1061,6 +1063,10 @@ fetch.unpackLimit:: especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead. +fetch.prune:: + If true, fetch will automatically behave as if the `--prune` + option was given on the command line. See also `remote..prune`. + format.attach:: Enable multipart/mixed attachments as the default for 'format-patch'. The value can also be a double quoted string @@ -1445,7 +1451,11 @@ http.cookiefile:: of the file to read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie file format (see linkgit:curl[1]). NOTE that the file specified with http.cookiefile is only used as - input. No cookies will be stored in the file. + input unless http.saveCookies is set. + +http.savecookies:: + If set, store cookies received during requests to the file specified by + http.cookiefile. Has no effect if http.cookiefile is unset. http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing @@ -1525,6 +1535,51 @@ http.useragent:: of common USER_AGENT strings (but not including those like git/1.7.1). Can be overridden by the 'GIT_HTTP_USER_AGENT' environment variable. +http..*:: + Any of the http.* options above can be applied selectively to some urls. + For a config key to match a URL, each element of the config key is + compared to that of the URL, in the following order: ++ +-- +. Scheme (e.g., `https` in `https://example.com/`). This field + must match exactly between the config key and the URL. + +. Host/domain name (e.g., `example.com` in `https://example.com/`). + This field must match exactly between the config key and the URL. + +. Port number (e.g., `8080` in `http://example.com:8080/`). + This field must match exactly between the config key and the URL. + Omitted port numbers are automatically converted to the correct + default for the scheme before matching. + +. Path (e.g., `repo.git` in `https://example.com/repo.git`). The + path field of the config key must match the path field of the URL + either exactly or as a prefix of slash-delimited path elements. This means + a config key with path `foo/` matches URL path `foo/bar`. A prefix can only + match on a slash (`/`) boundary. Longer matches take precedence (so a config + key with path `foo/bar` is a better match to URL path `foo/bar` than a config + key with just path `foo/`). + +. User name (e.g., `user` in `https://user@example.com/repo.git`). If + the config key has a user name it must match the user name in the + URL exactly. If the config key does not have a user name, that + config key will match a URL with any user name (including none), + but at a lower precedence than a config key with a user name. +-- ++ +The list above is ordered by decreasing precedence; a URL that matches +a config key's path is preferred to one that matches its user name. For example, +if the URL is `https://user@example.com/foo/bar` a config key match of +`https://example.com/foo` will be preferred over a config key match of +`https://user@example.com`. ++ +All URLs are normalized before attempting any matching (the password part, +if embedded in the URL, is always ignored for matching purposes) so that +equivalent urls that are simply spelled differently will match properly. +Environment variable settings always override any matches. The urls that are +matched against are those given directly to Git commands. This means any URLs +visited as a result of a redirection do not participate in matching. + i18n.commitEncoding:: Character encoding the commit messages are stored in; Git itself does not care per se, but this information is necessary e.g. when @@ -1825,6 +1880,10 @@ pull.rebase:: of merging the default branch from the default remote when "git pull" is run. See "branch..rebase" for setting this on a per-branch basis. ++ + When preserve, also pass `--preserve-merges` along to 'git rebase' + so that locally committed merge commits will not be flattened + by running 'git pull'. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] @@ -2024,6 +2083,12 @@ remote..vcs:: Setting this to a value will cause Git to interact with the remote with the git-remote- helper. +remote..prune:: + When set to true, fetching from this remote by default will also + remove any remote-tracking branches which no longer exist on the + remote (as if the `--prune` option was give on the command line). + Overrides `fetch.prune` settings, if any. + remotes.:: The list of remotes which are fetched by "git remote update ". See linkgit:git-remote[1]. @@ -2118,6 +2183,13 @@ status.branch:: Set to true to enable --branch by default in linkgit:git-status[1]. The option --no-branch takes precedence over this variable. +status.displayCommentPrefix:: + If set to true, linkgit:git-status[1] will insert a comment + prefix before each output line (starting with + `core.commentChar`, i.e. `#` by default). This was the + behavior of linkgit:git-status[1] in Git 1.8.4 and previous. + Defaults to false. + status.showUntrackedFiles:: By default, linkgit:git-status[1] and linkgit:git-commit[1] show files which are not currently tracked by Git. Directories which @@ -2142,7 +2214,14 @@ status.submodulesummary:: If this is set to a non zero number or true (identical to -1 or an unlimited number), the submodule summary will be enabled and a summary of commits for modified submodules will be shown (see - --summary-limit option of linkgit:git-submodule[1]). + --summary-limit option of linkgit:git-submodule[1]). Please note + that the summary output command will be suppressed for all + submodules when `diff.ignoreSubmodules` is set to 'all' or only + for those submodules where `submodule..ignore=all`. To + also view the summary for ignored submodules you can either use + the --ignore-submodules=dirty command line option or the 'git + submodule summary' command, which shows a similar output but does + not honor these settings. submodule..path:: submodule..url:: @@ -2177,7 +2256,8 @@ submodule..ignore:: submodules that have untracked files in their work tree as changed. This setting overrides any setting made in .gitmodules for this submodule, both settings can be overridden on the command line by using the - "--ignore-submodules" option. + "--ignore-submodules" option. The 'git submodule' commands are not + affected by this setting. tar.umask:: This variable can be used to restrict the permission bits of @@ -2216,6 +2296,17 @@ uploadpack.allowtipsha1inwant:: of a hidden ref (by default, such a request is rejected). see also `uploadpack.hiderefs`. +uploadpack.keepalive:: + When `upload-pack` has started `pack-objects`, there may be a + quiet period while `pack-objects` prepares the pack. Normally + it would output progress information, but if `--quiet` was used + for the fetch, `pack-objects` will output nothing at all until + the pack data begins. Some clients and networks may consider + the server to be hung and give up. Setting this option instructs + `upload-pack` to send an empty keepalive packet every + `uploadpack.keepalive` seconds. Setting this option to 0 + disables keepalive packets entirely. The default is 5 seconds. + url..insteadOf:: Any URL that starts with this value will be rewritten to start, instead, with . In cases where some site serves a diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index ac77050255..223b9310df 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -73,7 +73,11 @@ diff.ignoreSubmodules:: Sets the default value of --ignore-submodules. Note that this affects only 'git diff' Porcelain, and not lower level 'diff' commands such as 'git diff-files'. 'git checkout' also honors - this setting when reporting uncommitted changes. + this setting when reporting uncommitted changes. Setting it to + 'all' disables the submodule summary normally shown by 'git commit' + and 'git status' when 'status.submodulesummary' is set unless it is + overridden by using the --ignore-submodules command line option. + The 'git submodule' commands are not affected by this setting. diff.mnemonicprefix:: If set, 'git diff' uses a prefix pair that is different from the diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index e1fba85660..2a18c1f6f2 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -304,7 +304,7 @@ and maintain access to the repository by developers. * linkgit:git-shell[1] can be used as a 'restricted login shell' for shared central repository users. -link:howto/update-hook-example.txt[update hook howto] has a good +link:howto/update-hook-example.html[update hook howto] has a good example of managing a shared central repository. diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 6cea7f1ce1..f2c85cc633 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] - [-L n,m | -L :fn] [-S ] [-M] [-C] [-C] [-C] [--since=] + [-L ] [-S ] [-M] [-C] [-C] [-C] [--since=] [--abbrev=] [ | --contents | --reverse ] [--] DESCRIPTION @@ -18,7 +18,8 @@ DESCRIPTION Annotates each line in the given file with information from the revision which last modified the line. Optionally, start annotating from the given revision. -The command can also limit the range of lines annotated. +When specified one or more times, `-L` restricts annotation to the requested +lines. The origin of lines is automatically followed across whole-file renames (currently there is no option to turn the rename-following @@ -130,7 +131,10 @@ SPECIFYING RANGES Unlike 'git blame' and 'git annotate' in older versions of git, the extent of the annotation can be limited to both line ranges and revision -ranges. When you are interested in finding the origin for +ranges. The `-L` option, which limits annotation to a range of lines, may be +specified multiple times. + +When you are interested in finding the origin for lines 40-60 for file `foo`, you can use the `-L` option like so (they mean the same thing -- both ask for 21 lines starting at line 40): diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index b7cb625b89..311b33674e 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -48,7 +48,8 @@ working tree to it; use "git checkout " to switch to the new branch. When a local branch is started off a remote-tracking branch, Git sets up the -branch so that 'git pull' will appropriately merge from +branch (specifically the `branch..remote` and `branch..merge` +configuration entries) so that 'git pull' will appropriately merge from the remote-tracking branch. This behavior may be changed via the global `branch.autosetupmerge` configuration flag. That setting can be overridden by using the `--track` and `--no-track` options, and @@ -156,7 +157,8 @@ This option is only applicable in non-verbose mode. -t:: --track:: - When creating a new branch, set up configuration to mark the + When creating a new branch, set up `branch..remote` and + `branch..merge` configuration entries to mark the start-point branch as "upstream" from the new branch. This configuration will tell git to show the relationship between the two branches in `git status` and `git branch -v`. Furthermore, diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 10fbc6a373..322f5ed315 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -54,7 +54,7 @@ OPTIONS --textconv:: Show the content as transformed by a textconv filter. In this case, - has be of the form :, or : in order + has be of the form :, or : in order to apply the filter to the content recorded in the index at . --batch:: @@ -86,10 +86,9 @@ BATCH OUTPUT ------------ If `--batch` or `--batch-check` is given, `cat-file` will read objects -from stdin, one per line, and print information about them. - -Each line is considered as a whole object name, and is parsed as if -given to linkgit:git-rev-parse[1]. +from stdin, one per line, and print information about them. By default, +the whole line is considered as an object, as if it were fed to +linkgit:git-rev-parse[1]. You can specify the information shown for each object by using a custom ``. The `` is copied literally to stdout for each @@ -110,6 +109,13 @@ newline. The available atoms are: The size, in bytes, that the object takes up on disk. See the note about on-disk sizes in the `CAVEATS` section below. +`rest`:: + If this atom is used in the output string, input lines are split + at the first whitespace boundary. All characters before that + whitespace are considered to be the object name; characters + after that first run of whitespace (i.e., the "rest" of the + line) are output in place of the `%(rest)` atom. + If no format is specified, the default format is `%(objectname) %(objecttype) %(objectsize)`. diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index a7be80d48b..00e2aa2df2 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -31,8 +31,9 @@ OPTIONS Read file names from stdin instead of from the command-line. -z:: - Only meaningful with `--stdin`; paths are separated with a - NUL character instead of a linefeed character. + The output format is modified to be machine-parseable. + If `--stdin` is also given, input paths are separated + with a NUL character instead of a linefeed character. \--:: Interpret all preceding arguments as attributes and all following @@ -48,6 +49,10 @@ OUTPUT The output is of the form: COLON SP COLON SP LF +unless `-z` is in effect, in which case NUL is used as delimiter: + NUL NUL NUL + + is the path of a file being queried, is an attribute being queried and can be either: diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index d2df487aa2..ee2e091704 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -45,6 +45,13 @@ OPTIONS not be possible to distinguish between paths which match a pattern and those which don't. +--no-index:: + Don't look in the index when undertaking the checks. This can + be used to debug why a path became tracked by e.g. `git add .` + and was not ignored by the rules as expected by the user or when + developing patterns including negation to match a path previously + added with `git add -f`. + OUTPUT ------ diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index a49be1bab4..fc02959ba4 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -54,6 +54,8 @@ Git imposes the following rules on how references are named: . They cannot contain a sequence `@{`. +. They cannot be the single character `@`. + . They cannot contain a `\`. These rules make it easy for shell script based tools to parse diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index f6c19c734d..2d0daae626 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -14,8 +14,7 @@ DESCRIPTION ----------- The changeset (or "diff") of each commit between the fork-point and is compared against each commit between the fork-point and . -The commits are compared with their 'patch id', obtained from -the 'git patch-id' program. +The diffs are compared after removing any whitespace and line numbers. Every commit that doesn't exist in the branch has its id (sha1) reported, prefixed by a symbol. The ones that have diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 2dbe486eb1..e9917b89a9 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -15,6 +15,7 @@ SYNOPSIS 'git config' [] [type] [-z|--null] --get name [value_regex] 'git config' [] [type] [-z|--null] --get-all name [value_regex] 'git config' [] [type] [-z|--null] --get-regexp name_regex [value_regex] +'git config' [] [type] [-z|--null] --get-urlmatch name URL 'git config' [] --unset name [value_regex] 'git config' [] --unset-all name [value_regex] 'git config' [] --rename-section old_name new_name @@ -95,6 +96,14 @@ OPTIONS in which section and variable names are lowercased, but subsection names are not. +--get-urlmatch name URL:: + When given a two-part name section.key, the value for + section..key whose part matches the best to the + given URL is returned (if no such key exists, the value for + section.key is used as a fallback). When given just the + section as name, do so for all the keys in the section and + list them. + --global:: For writing options: write to global `~/.gitconfig` file rather than the repository `.git/config`, write to @@ -295,6 +304,13 @@ Given a .git/config like this: gitproxy=proxy-command for kernel.org gitproxy=default-proxy ; for all the rest + ; HTTP + [http] + sslVerify + [http "https://weak.example.com"] + sslVerify = false + cookieFile = /tmp/cookie.txt + you can set the filemode to true with ------------ @@ -380,6 +396,19 @@ RESET=$(git config --get-color "" "reset") echo "${WS}your whitespace color or blue reverse${RESET}" ------------ +For URLs in `https://weak.example.com`, `http.sslVerify` is set to +false, while it is set to `true` for all others: + +------------ +% git config --bool --get-urlmatch http.sslverify https://good.example.com +true +% git config --bool --get-urlmatch http.sslverify https://weak.example.com +false +% git config --get-urlmatch http https://weak.example.com +http.cookiefile /tmp/cookie.txt +http.sslverify false +------------ + include::config.txt[] GIT diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 7da0f13a5c..b211440373 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -20,7 +20,7 @@ usernames and passwords. The git-credential command exposes this interface to scripts which may want to retrieve, store, or prompt for credentials in the same manner as Git. The design of this scriptable interface models the internal C API; see -link:technical/api-credentials.txt[the Git credential API] for more +link:technical/api-credentials.html[the Git credential API] for more background on the concepts. git-credential takes an "action" option on the command-line (one of diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 9439cd6d56..d20ca402a1 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -9,7 +9,7 @@ git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS -------- [verse] -'git describe' [--all] [--tags] [--contains] [--abbrev=] ... +'git describe' [--all] [--tags] [--contains] [--abbrev=] ... 'git describe' [--all] [--tags] [--contains] [--abbrev=] --dirty[=] DESCRIPTION @@ -26,8 +26,8 @@ see the -a and -s options to linkgit:git-tag[1]. OPTIONS ------- -...:: - Committish object names to describe. +...:: + Commit-ish object names to describe. --dirty[=]:: Describe the working tree. @@ -57,7 +57,7 @@ OPTIONS --candidates=:: Instead of considering only the 10 most recent tags as - candidates to describe the input committish consider + candidates to describe the input commit-ish consider up to candidates. Increasing above 10 will take slightly longer but may produce a more accurate result. An of 0 will cause only exact matches to be output. @@ -145,7 +145,7 @@ be sufficient to disambiguate these commits. SEARCH STRATEGY --------------- -For each committish supplied, 'git describe' will first look for +For each commit-ish supplied, 'git describe' will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match @@ -154,12 +154,12 @@ is found, its name will be output and searching will stop. If an exact match was not found, 'git describe' will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an -abbreviation of the input committish's SHA-1. If '--first-parent' was +abbreviation of the input commit-ish's SHA-1. If '--first-parent' was specified then the walk will only consider the first parent of each commit. If multiple tags were found during the walk then the tag which -has the fewest commits different from the input committish will be +has the fewest commits different from the input commit-ish will be selected and output. Here fewest commits different is defined as the number of commits which would be shown by `git log tag..input` will be the smallest number of commits possible. diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 78d6d50489..33fbd8c56f 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -28,10 +28,15 @@ two blob objects, or changes between two files on disk. words, the differences are what you _could_ tell Git to further add to the index but you still haven't. You can stage these changes by using linkgit:git-add[1]. -+ -If exactly two paths are given and at least one points outside -the current repository, 'git diff' will compare the two files / -directories. This behavior can be forced by --no-index. + +'git diff' --no-index [--options] [--] [...]:: + + This form is to compare the given two paths on the + filesystem. You can omit the `--no-index` option when + running the command in a working tree controlled by Git and + at least one of the paths points outside the working tree, + or when running the command outside a working tree + controlled by Git. 'git diff' [--options] --cached [] [--] [...]:: diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index bf1a02a80d..73f980638e 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -361,8 +361,8 @@ and control the current import process. More detailed discussion `--cat-blob-fd` or `stdout` if unspecified. `feature`:: - Require that fast-import supports the specified feature, or - abort if it does not. + Enable the specified feature. This requires that fast-import + supports the specified feature, and aborts if it does not. `option`:: Specify any of the options listed under OPTIONS that do not @@ -380,8 +380,8 @@ change to the project. ('author' (SP )? SP LT GT SP LF)? 'committer' (SP )? SP LT GT SP LF data - ('from' SP LF)? - ('merge' SP LF)? + ('from' SP LF)? + ('merge' SP LF)? (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)* LF? .... @@ -460,9 +460,9 @@ as the current commit on that branch is automatically assumed to be the first ancestor of the new commit. As `LF` is not valid in a Git refname or SHA-1 expression, no -quoting or escaping syntax is supported within ``. +quoting or escaping syntax is supported within ``. -Here `` is any of the following: +Here `` is any of the following: * The name of an existing branch already in fast-import's internal branch table. If fast-import doesn't know the name, it's treated as a SHA-1 @@ -509,7 +509,7 @@ additional ancestors (forming a 16-way merge). For this reason it is suggested that frontends do not use more than 15 `merge` commands per commit; 16, if starting a new, empty branch. -Here `` is any of the commit specification expressions +Here `` is any of the commit specification expressions also accepted by `from` (see above). `filemodify` @@ -677,8 +677,8 @@ paths for a commit are encouraged to do so. `notemodify` ^^^^^^^^^^^^ Included in a `commit` `` command to add a new note -annotating a `` or change this annotation contents. -Internally it is similar to filemodify 100644 on `` +annotating a `` or change this annotation contents. +Internally it is similar to filemodify 100644 on `` path (maybe split into subdirectories). It's not advised to use any other commands to write to the `` tree except `filedeleteall` to delete all existing notes in this tree. @@ -691,7 +691,7 @@ External data format:: commit that is to be annotated. + .... - 'N' SP SP LF + 'N' SP SP LF .... + Here `` can be either a mark reference (`:`) @@ -704,13 +704,13 @@ Inline data format:: command. + .... - 'N' SP 'inline' SP LF + 'N' SP 'inline' SP LF data .... + See below for a detailed description of the `data` command. -In both formats `` is any of the commit specification +In both formats `` is any of the commit specification expressions also accepted by `from` (see above). `mark` @@ -741,7 +741,7 @@ lightweight (non-annotated) tags see the `reset` command below. .... 'tag' SP LF - 'from' SP LF + 'from' SP LF 'tagger' (SP )? SP LT GT SP LF data .... @@ -786,11 +786,11 @@ branch from an existing commit without creating a new commit. .... 'reset' SP LF - ('from' SP LF)? + ('from' SP LF)? LF? .... -For a detailed description of `` and `` see above +For a detailed description of `` and `` see above under `commit` and `from`. The `LF` after the command is optional (it used to be required). diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 1e71754347..444b805d35 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -90,6 +90,10 @@ be in a separate packet, and the list must end with a flush packet. --no-progress:: Do not show the progress. +--check-self-contained-and-connected:: + Output "connectivity-ok" if the received pack is + self-contained and connected. + -v:: Run verbosely. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index e394276b1a..9e0ef0eaf3 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -242,6 +242,7 @@ configuration options in linkgit:git-notes[1] to use this workflow). Note that the leading character does not have to be a dot; for example, you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. +-q:: --quiet:: Do not print the names of the generated files to standard output. diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 2402ed6828..e158a3b31f 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -9,7 +9,7 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- [verse] -'git gc' [--aggressive] [--auto] [--quiet] [--prune= | --no-prune] +'git gc' [--aggressive] [--auto] [--quiet] [--prune= | --no-prune] [--force] DESCRIPTION ----------- @@ -72,6 +72,10 @@ automatic consolidation of packs. --quiet:: Suppress all progress reports. +--force:: + Force `git gc` to run even if there may be another `git gc` + instance running on this repository. + Configuration ------------- diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index ac2694d04c..34097efea7 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -62,7 +62,8 @@ produced by --stat etc. Note that only message is considered, if also a diff is shown its size is not included. --L ,:, -L :::: +-L ,::: +-L :::: Trace the evolution of the line range given by "," (or the funcname regex ) within the . You may @@ -71,8 +72,6 @@ produced by --stat etc. give zero or one positive revision arguments. You can specify this option more than once. + - and can take one of these forms: - include::line-range-format.txt[] :: diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index d7db2a3737..d2fc12ec77 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git merge-file' [-L [-L [-L ]]] [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=] - + [--[no-]diff3] DESCRIPTION @@ -66,6 +66,9 @@ OPTIONS -q:: Quiet; do not warn about conflicts. +--diff3:: + Show conflicts in "diff3" style. + --ours:: --theirs:: --union:: diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index c5f84b6495..58731c1942 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- -Reads three treeish, and output trivial merge results and +Reads three tree-ish, and output trivial merge results and conflicting stages to the standard output. This is similar to what three-way 'git read-tree -m' does, but instead of storing the results in the index, the command outputs the entries to the diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index e93fcb49fd..b1f79881ef 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- -This script is used to move or rename a file, directory or symlink. +Move or rename a file, directory or symlink. git mv [-v] [-f] [-n] [-k] git mv [-v] [-f] [-n] [-k] ... @@ -44,6 +44,14 @@ OPTIONS --verbose:: Report the names of files as they are moved. +SUBMODULES +---------- +Moving a submodule using a gitfile (which means they were cloned +with a Git version 1.7.8 or newer) will update the gitfile and +core.worktree setting to make the submodule work in the new location. +It also will attempt to update the submodule..path setting in +the linkgit:gitmodules[5] file and stage that file (unless -n is used). + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 15b00e0991..ca28fb8e2a 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git name-rev' [--tags] [--refs=] - ( --all | --stdin | ... ) + ( --all | --stdin | ... ) DESCRIPTION ----------- diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 6ef8d599d3..beea10b148 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -102,12 +102,18 @@ include::merge-options.txt[] :git-pull: 1 -r:: ---rebase:: - Rebase the current branch on top of the upstream branch after - fetching. If there is a remote-tracking branch corresponding to - the upstream branch and the upstream branch was rebased since last - fetched, the rebase uses that information to avoid rebasing - non-local changes. +--rebase[=false|true|preserve]:: + When true, rebase the current branch on top of the upstream + branch after fetching. If there is a remote-tracking branch + corresponding to the upstream branch and the upstream branch + was rebased since last fetched, the rebase uses that information + to avoid rebasing non-local changes. ++ +When preserve, also rebase the current branch on top of the upstream +branch, but pass `--preserve-merges` along to `git rebase` so that +locally created merge commits will not be flattened. ++ +When false, merge the current branch into the upstream branch. + See `pull.rebase`, `branch..rebase` and `branch.autosetuprebase` in linkgit:git-config[1] if you want to make `git pull` always use diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index f7dfe48d28..9eec740910 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git push' [--all | --mirror | --tags] [--follow-tags] [-n | --dry-run] [--receive-pack=] [--repo=] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] + [--force-with-lease[=[:]]] [--no-verify] [ [...]] DESCRIPTION @@ -120,7 +121,7 @@ already exists on the remote side. --follow-tags:: Push all the refs that would be pushed without this option, and also push annotated tags in `refs/tags` that are missing - from the remote but are pointing at committish that are + from the remote but are pointing at commit-ish that are reachable from the refs being pushed. --receive-pack=:: @@ -130,21 +131,75 @@ already exists on the remote side. repository over ssh, and you do not have the program in a directory on the default $PATH. +--[no-]force-with-lease:: +--force-with-lease=:: +--force-with-lease=::: + Usually, "git push" refuses to update a remote ref that is + not an ancestor of the local ref used to overwrite it. ++ +This option bypasses the check, but instead requires that the +current value of the ref to be the expected value. "git push" +fails otherwise. ++ +Imagine that you have to rebase what you have already published. +You will have to bypass the "must fast-forward" rule in order to +replace the history you originally published with the rebased history. +If somebody else built on top of your original history while you are +rebasing, the tip of the branch at the remote may advance with her +commit, and blindly pushing with `--force` will lose her work. ++ +This option allows you to say that you expect the history you are +updating is what you rebased and want to replace. If the remote ref +still points at the commit you specified, you can be sure that no +other people did anything to the ref (it is like taking a "lease" on +the ref without explicitly locking it, and you update the ref while +making sure that your earlier "lease" is still valid). ++ +`--force-with-lease` alone, without specifying the details, will protect +all remote refs that are going to be updated by requiring their +current value to be the same as the remote-tracking branch we have +for them, unless specified with a `--force-with-lease=:` +option that explicitly states what the expected value is. ++ +`--force-with-lease=`, without specifying the expected value, will +protect the named ref (alone), if it is going to be updated, by +requiring its current value to be the same as the remote-tracking +branch we have for it. ++ +`--force-with-lease=:` will protect the named ref (alone), +if it is going to be updated, by requiring its current value to be +the same as the specified value (which is allowed to be +different from the remote-tracking branch we have for the refname, +or we do not even have to have such a remote-tracking branch when +this form is used). ++ +Note that all forms other than `--force-with-lease=:` +that specifies the expected current value of the ref explicitly are +still experimental and their semantics may change as we gain experience +with this feature. ++ +"--no-force-with-lease" will cancel all the previous --force-with-lease on the +command line. + -f:: --force:: Usually, the command refuses to update a remote ref that is not an ancestor of the local ref used to overwrite it. - This flag disables the check. This can cause the - remote repository to lose commits; use it with care. - Note that `--force` applies to all the refs that are pushed, - hence using it with `push.default` set to `matching` or with - multiple push destinations configured with `remote.*.push` - may overwrite refs other than the current branch (including - local refs that are strictly behind their remote counterpart). - To force a push to only one branch, use a `+` in front of the - refspec to push (e.g `git push origin +master` to force a push - to the `master` branch). See the `...` section above - for details. + Also, when `--force-with-lease` option is used, the command refuses + to update a remote ref whose current value does not match + what is expected. ++ +This flag disables these checks, and can cause the remote repository +to lose commits; use it with care. ++ +Note that `--force` applies to all the refs that are pushed, hence +using it with `push.default` set to `matching` or with multiple push +destinations configured with `remote.*.push` may overwrite refs +other than the current branch (including local refs that are +strictly behind their remote counterpart). To force a push to only +one branch, use a `+` in front of the refspec to push (e.g `git push +origin +master` to force a push to the `master` branch). See the +`...` section above for details. --repo=:: This option is only relevant if no argument is diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 6b2e1c86ab..94e07fdab5 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -322,7 +322,7 @@ You may find this (or --no-ff with an interactive rebase) helpful after reverting a topic branch merge, as this option recreates the topic branch with fresh commits so it can be remerged successfully without needing to "revert the reversion" (see the -link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). --ignore-whitespace:: --whitespace=