diff options
Diffstat (limited to 'Documentation')
62 files changed, 1481 insertions, 303 deletions
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/RelNotes/1.7.10.1.txt b/Documentation/RelNotes/1.7.10.1.txt index 806a965a1b..be68524cff 100644 --- a/Documentation/RelNotes/1.7.10.1.txt +++ b/Documentation/RelNotes/1.7.10.1.txt @@ -14,7 +14,7 @@ Fixes since v1.7.10 not exclude them and tried to apply funny patches only to fail. * "git blame" started missing quite a few changes from the origin - since we stopped using the diff minimalization by default in v1.7.2 + since we stopped using the diff minimization by default in v1.7.2 era. * When PATH contains an unreadable directory, alias expansion code diff --git a/Documentation/RelNotes/1.7.5.4.txt b/Documentation/RelNotes/1.7.5.4.txt index cf3f455ced..7796df3fe4 100644 --- a/Documentation/RelNotes/1.7.5.4.txt +++ b/Documentation/RelNotes/1.7.5.4.txt @@ -5,7 +5,7 @@ Fixes since v1.7.5.3 -------------------- * The single-key mode of "git add -p" was easily fooled into thinking - that it was told to add everthing ('a') when up-arrow was pressed by + that it was told to add everything ('a') when up-arrow was pressed by mistake. * Setting a git command that uses custom configuration via "-c var=val" diff --git a/Documentation/RelNotes/1.7.8.2.txt b/Documentation/RelNotes/1.7.8.2.txt index e74f4ef1ef..b9c66aa1b7 100644 --- a/Documentation/RelNotes/1.7.8.2.txt +++ b/Documentation/RelNotes/1.7.8.2.txt @@ -12,11 +12,11 @@ Fixes since v1.7.8.1 * The configuration file parser used for sizes (e.g. bigFileThreshold) did not correctly interpret 'g' suffix. - * The replacement implemention for snprintf used on platforms with + * The replacement implementation for snprintf used on platforms with native snprintf that is broken did not use va_copy correctly. * LF-to-CRLF streaming filter replaced all LF with CRLF, which might - be techinically correct but not friendly to people who are trying + be technically correct but not friendly to people who are trying to recover from earlier mistakes of using CRLF in the repository data in the first place. It now refrains from doing so for LF that follows a CR. diff --git a/Documentation/RelNotes/1.7.8.txt b/Documentation/RelNotes/1.7.8.txt index b4d90bba0f..249311361e 100644 --- a/Documentation/RelNotes/1.7.8.txt +++ b/Documentation/RelNotes/1.7.8.txt @@ -9,7 +9,7 @@ Updates since v1.7.7 * Updates to bash completion scripts. * The build procedure has been taught to take advantage of computed - dependency automatically when the complier supports it. + dependency automatically when the compiler supports it. * The date parser now accepts timezone designators that lack minutes part and also has a colon between "hh:mm". @@ -31,7 +31,7 @@ Updates since v1.7.7 * Variants of "git cherry-pick" and "git revert" that take multiple commits learned to "--continue" and "--abort". - * "git daemon" gives more human readble error messages to clients + * "git daemon" gives more human readable error messages to clients using ERR packets when appropriate. * Errors at the network layer is logged by "git daemon". diff --git a/Documentation/RelNotes/1.8.2.1.txt b/Documentation/RelNotes/1.8.2.1.txt index 1354ad03f5..769a6fc06c 100644 --- a/Documentation/RelNotes/1.8.2.1.txt +++ b/Documentation/RelNotes/1.8.2.1.txt @@ -49,7 +49,7 @@ Fixes since v1.8.2 common prefix and suffix between the two filenames overlapped. * "git submodule update", when recursed into sub-submodules, did not - acccumulate the prefix paths. + accumulate the prefix paths. * "git am $maildir/" applied messages in an unexpected order; sort filenames read from the maildir/ in a way that is more likely to diff --git a/Documentation/RelNotes/1.8.2.2.txt b/Documentation/RelNotes/1.8.2.2.txt index dab4831ca0..708df1ae19 100644 --- a/Documentation/RelNotes/1.8.2.2.txt +++ b/Documentation/RelNotes/1.8.2.2.txt @@ -58,4 +58,4 @@ Fixes since v1.8.2.1 conflicts have been applied. * "git bundle" did not like a bundle created using a commit without - any message as its one of the prerequistes. + any message as its one of the prerequisites. diff --git a/Documentation/RelNotes/1.8.3.3.txt b/Documentation/RelNotes/1.8.3.3.txt index 04289e793c..9ba4f4da0f 100644 --- a/Documentation/RelNotes/1.8.3.3.txt +++ b/Documentation/RelNotes/1.8.3.3.txt @@ -4,6 +4,27 @@ Git v1.8.3.3 Release Notes Fixes since v1.8.3.2 -------------------- + * "git apply" parsed patches that add new files, generated by programs + other than Git, incorrectly. This is an old breakage in v1.7.11. + + * Older cURL wanted piece of memory we call it with to be stable, but + we updated the auth material after handing it to a call. + + * "git pull" into nothing trashed "local changes" that were in the + index. + + * Many "git submodule" operations did not work on a submodule at a + path whose name is not in ASCII. + + * "cherry-pick" had a small leak in its error codepath. + + * Logic used by git-send-email to suppress cc mishandled names like + "A U. Thor" <author@example.xz>, where the human readable part + needs to be quoted (the user input may not have the double quotes + around the name, and comparison was done between quoted and + unquoted strings). It also mishandled names that need RFC2047 + quoting. + * "gitweb" forgot to clear a global variable $search_regexp upon each request, mistakenly carrying over the previous search to a new one when used as a persistent CGI. diff --git a/Documentation/RelNotes/1.8.3.4.txt b/Documentation/RelNotes/1.8.3.4.txt new file mode 100644 index 0000000000..56f106e262 --- /dev/null +++ b/Documentation/RelNotes/1.8.3.4.txt @@ -0,0 +1,20 @@ +Git v1.8.3.4 Release Notes +========================== + +This update is mostly to propagate documentation fixes and test +updates from the master front back to the maintenance track. + +Fixes since v1.8.3.3 +-------------------- + + * The bisect log listed incorrect commits when bisection ends with + only skipped ones. + + * The test coverage framework was left broken for some time. + + * The test suite for HTTP transport did not run with Apache 2.4. + + * "git diff" used to fail when core.safecrlf is set and the working + tree contents had mixed CRLF/LF line endings. Committing such a + content must be prohibited, but "git diff" should help the user to + locate and fix such problems without failing. diff --git a/Documentation/RelNotes/1.8.4.txt b/Documentation/RelNotes/1.8.4.txt index 4250e5a3a9..02f681b710 100644 --- a/Documentation/RelNotes/1.8.4.txt +++ b/Documentation/RelNotes/1.8.4.txt @@ -48,6 +48,8 @@ Updates since v1.8.3 Foreign interfaces, subsystems and ports. + * Cygwin port has been updated for more recent Cygwin 1.7. + * "git rebase -i" now honors --strategy and -X options. * Git-gui has been updated to its 0.18.0 version. @@ -76,9 +78,70 @@ Foreign interfaces, subsystems and ports. * git-remote-mw (in contrib/) hints users to check the certificate, when https:// connection failed. + * git-remote-mw (in contrib/) adds a command to allow previewing the + contents locally before pushing it out, when working with a + MediaWiki remote. + UI, Workflows & Features + * Sample "post-receive-email" hook script got an enhanced replacement + "multimail" (in contrib/). + + * Also in contrib/ is a new "contacts" script that runs "git blame" + to find out the people who may be interested in a set of changes. + + * "git clean" command learned an interactive mode. + + * The "--head" option to "git show-ref" was only to add "HEAD" to the + list of candidate refs to be filtered by the usual rules + (e.g. "--heads" that only show refs under refs/heads). The meaning + of the option has been changed to always show "HEAD" regardless of + what filtering will be applied to any other ref. + + This is a backward incompatible change and might cause breakages to + people's existing scripts. + + * "git show -s" was less discoverable than it should have been. It + now has a natural synonym "git show --no-patch". + + * "git check-mailmap" is a new command that lets you map usernames + and e-mail addresses through the mailmap mechanism, just like many + built-in commands do. + + * "git name-rev" learned to name an annotated tag object back to its + tagname; "git name-rev $(git rev-parse v1.0.0)" gives "tags/v1.0.0", + for example. + + * "git cat-file --batch-check=<format>" is added, primarily to allow + on-disk footprint of objects in packfiles (often they are a lot + smaller than their true size, when expressed as deltas) to be + reported. + + * "git rebase [-i]" used to leave just "rebase" as its reflog messages + for some operations. They have been reworded to be more informative. + + * In addition to the choice from "rebase, merge, or checkout-detach", + "submodule update" can allow a custom command to be used in to + update the working tree of submodules via the "submodule.*.update" + configuration variable. + + * "git submodule update" can optionally clone the submodule + repositories shallowly. + + * "git format-patch" learned "--from[=whom]" option, which sets the + "From: " header to the specified person (or the person who runs the + command, if "=whom" part is missing) and move the original author + information to an in-body From: header as necessary. + + * The configuration variable "merge.ff" was cleary a tri-state to + choose one from "favor fast-forward when possible", "always create + a merge even when the history could fast-forward" and "do not + create any merge, only update when the history fast-forwards", but + the command line parser did not implement the usual convention of + "last one wins, and command line overrides the configuration" + correctly. + * "gitweb" learned to optionally place extra links that point at the levels higher than the Gitweb pages themselves in the breadcrumbs, so that it can be used as part of a larger installation. @@ -127,7 +190,7 @@ UI, Workflows & Features directly uses the 40-hex string as an object name, even if a ref "refs/<some hierarchy>/<name>" exists. This disambiguation order is unlikely to change, but we should warn about the ambiguity just - like we warn when more than one refs/ hierachies share the same + like we warn when more than one refs/ hierarchies share the same name. * "git rebase" learned "--[no-]autostash" option to save local @@ -135,9 +198,6 @@ UI, Workflows & Features response was to stash them and re-run). This introduced a corner case breakage to "git am --abort" but it has been fixed. - * Instead of typing four capital letters "HEAD", you can say "@" now, - e.g. "git log @". - * "check-ignore" (new feature since 1.8.2) has been updated to work more like "check-attr" over bidi-pipes. @@ -179,6 +239,24 @@ UI, Workflows & Features Performance, Internal Implementation, etc. + * On Cygwin, we used to use our own lstat(2) emulation that is + allegedly faster than the platform one in codepaths where some of + the information it returns did not matter, but it started to bite + us in a few codepaths where the trick it uses to cheat does show + breakages. This emulation has been removed and we use the native + lstat(2) emulation supplied by Cygwin now. + + * The function attributes extensions are used to catch mistakes in + use of our own variadic functions that use NULL sentinel at the end + (i.e. like execl(3)) and format strings (i.e. like printf(3)). + + * The code to allow configuration data to be read from in-tree blob + objects is in. This may help working in a bare repository and + submodule updates. + + * Fetching between repositories with many refs employed O(n^2) + algorithm to match up the common objects, which has been corrected. + * The original way to specify remote repository using .git/branches/ used to have a nifty feature. The code to support the feature was still in a function but the caller was changed not to call it 5 @@ -189,7 +267,7 @@ Performance, Internal Implementation, etc. been susceptible to lossage of refs under right conditions, which has been tightened up. - * We read loose and packed rerferences in two steps, but after + * We read loose and packed references in two steps, but after deciding to read a loose ref but before actually opening it to read it, another process racing with us can unlink it, which would cause us to barf. The codepath has been updated to retry when such a @@ -244,6 +322,35 @@ Unless otherwise noted, all the fixes since v1.8.3 in the maintenance track are contained in this release (see release notes to them for details). + * Newer Net::SMTP::SSL module does not want the user programs to use + the default behaviour to let server certificate go without + verification, so by default enable the verification with a + mechanism to turn it off if needed. + (merge 35035bb rr/send-email-ssl-verify later to maint). + + * When "git" is spawned in such a way that any of the low 3 file + descriptors is closed, our first open() may yield file descriptor 2, + and writing error message to it would screw things up in a big way. + (merge a11c396 tr/protect-low-3-fds later to maint). + + * The mailmap mechanism unnecessarily downcased the e-mail addresses + in the output, and also ignored the human name when it is a single + character name. + (merge bd23794 jc/mailmap-case-insensitivity later to maint). + + * In two places we did not check return value (expected to be a file + descriptor) correctly. + (merge a77f106 tr/fd-gotcha-fixes later to maint). + + * Logic to auto-detect character encodings in the commit log message + did not reject overlong and invalid UTF-8 characters. + (merge 81050ac bc/commit-invalid-utf8 later to maint). + + * Pass port number as a separate argument when "send-email" initializes + Net::SMTP, instead of as a part of the hostname, i.e. host:port. + This allows GSSAPI codepath to match with the hostname given. + (merge 1a741bf bc/send-email-use-port-as-separate-param later to maint). + * "git diff" refused to even show difference when core.safecrlf is set to true (i.e. error out) and there are offending lines in the working tree files. @@ -262,12 +369,6 @@ details). the user to an unexpected place. (merge 3bed291 rr/rebase-checkout-reflog later to maint). - * "git stash save", when your local change turns a tracked file into - a directory, has to remove files in that directory in order to - revert your working tree to a pristine state. This will lose - untracked files in such a directory, and the command now requires - you to "--force" it. - * The configuration variable column.ui was poorly documented. (merge 5e62cc1 rr/column-doc later to maint). @@ -278,23 +379,18 @@ details). * "git apply" parsed patches that add new files, generated by programs other than Git, incorrectly. This is an old breakage in - v1.7.11 and will need to be merged down to the maintanance tracks. - (merge 212eb96 tr/maint-apply-non-git-patch-parsefix later to maint). + v1.7.11 and will need to be merged down to the maintenance tracks. * Older cURL wanted piece of memory we call it with to be stable, but we updated the auth material after handing it to a call. - (merge a94cf2c bc/http-keep-memory-given-to-curl later to maint). * "git pull" into nothing trashed "local changes" that were in the index, and this avoids it. - (merge b4dc085 jk/pull-into-dirty-unborn later to maint). * Many "git submodule" operations do not work on a submodule at a path whose name is not in ASCII. - (merge bed9470 fg/submodule-non-ascii-path later to maint). * "cherry-pick" had a small leak in an error codepath. - (merge 706728a fc/sequencer-plug-leak later to maint). * Logic used by git-send-email to suppress cc mishandled names like "A U. Thor" <author@example.xz>, where the human readable part @@ -302,7 +398,6 @@ details). around the name, and comparison was done between quoted and unquoted strings). It also mishandled names that need RFC2047 quoting. - (merge 1495266 mt/send-email-cc-match-fix later to maint). * Call to discard_cache/discard_index (used when we use different contents of the index in-core, in many operations like commit, @@ -313,102 +408,79 @@ details). * "gitweb" forgot to clear a global variable $search_regexp upon each request, mistakenly carrying over the previous search to a new one when used as a persistent CGI. - (merge ca7a5dc cm/gitweb-project-list-persistent-cgi-fix later to maint). * The wildmatch engine did not honor WM_CASEFOLD option correctly. - (merge b79c0c3 ar/wildmatch-foldcase later to maint). * "git log -c --follow $path" segfaulted upon hitting the commit that renamed the $path being followed. - (merge 46ec510 cb/log-follow-with-combined later to maint). * When a reflog notation is used for implicit "current branch", we did not say which branch and worse said "branch ''". - (merge 305ebea rr/die-on-missing-upstream later to maint). * "difftool --dir-diff" did not copy back changes made by the end-user in the diff tool backend to the working tree in some cases. - (merge 32eaf1d ks/difftool-dir-diff-copy-fix later to maint). * "git push $there HEAD:branch" did not resolve HEAD early enough, so it was easy to flip it around while push is still going on and push out a branch that the user did not originally intended when the command was started. - (merge 0f075b2 rr/push-head later to maint). * The bash prompt code (in contrib/) displayed the name of the branch being rebased when "rebase -i/-m/-p" modes are in use, but not the plain vanilla "rebase". - (merge 1306321 fc/show-branch-in-rebase-am later to maint). * Handling of negative exclude pattern for directories "!dir" was broken in the update to v1.8.3. - (merge c3c327d kb/status-ignored-optim-2 later to maint). * zsh prompt script that borrowed from bash prompt script did not work due to slight differences in array variable notation between these two shells. - (merge d0583da tg/maint-zsh-svn-remote-prompt later to maint). * An entry for "file://" scheme in the enumeration of URL types Git can take in the HTML documentation was made into a clickable link by mistake. - (merge 4c32e36 nd/urls-doc-no-file-hyperlink-fix later to maint). * "git push --[no-]verify" was not documented. - (merge 90d32d1 tr/push-no-verify-doc later to maint). * Stop installing the git-remote-testpy script that is only used for testing. - (merge 416fda6 fc/makefile later to maint). * "git commit --allow-empty-message -m ''" should not start an editor. - (merge 2520677 rs/commit-m-no-edit later to maint). * "git merge @{-1}~22" was rewritten to "git merge frotz@{1}~22" incorrectly when your previous branch was "frotz" (it should be rewritten to "git merge frotz~22" instead). - (merge 84cf246 jc/strbuf-branchname-fix later to maint). * "git diff -c -p" was not showing a deleted line from a hunk when another hunk immediately begins where the earlier one ends. - (merge aac3857 mk/combine-diff-context-horizon-fix later to maint). * "git log --ancestry-path A...B" did not work as expected, as it did not pay attention to the fact that the merge base between A and B was the bottom of the range being specified. - (merge a765499 kb/ancestry-path-threedots later to maint). * Mac OS X does not like to write(2) more than INT_MAX number of bytes; work it around by chopping write(2) into smaller pieces. - (merge 6c642a8 fc/macos-x-clipped-write later to maint). * Newer MacOS X encourages the programs to compile and link with their CommonCrypto, not with OpenSSL. - (merge be4c828 da/darwin later to maint). * "git clone foo/bar:baz" cannot be a request to clone from a remote over git-over-ssh specified in the scp style. This case is now detected and clones from a local repository at "foo/bar:baz". - (merge 6000334 nd/clone-local-with-colon later to maint). * When $HOME is misconfigured to point at an unreadable directory, we used to complain and die. Loosen the check. - (merge 4698c8f jn/config-ignore-inaccessible later to maint). * "git subtree" (in contrib/) had one codepath with loose error checks to lose data at the remote side. - (merge 3212d56 jk/subtree-do-not-push-if-split-fails later to maint). * "git fetch" into a shallow repository from a repository that does not know about the shallow boundary commits (e.g. a different fork from the repository the current shallow repository was cloned from) did not work correctly. - (merge 71d5f93 mh/fetch-into-shallow later to maint). * "git checkout foo" DWIMs the intended "upstream" and turns it into "git checkout -t -b foo remotes/origin/foo". This codepath has been updated to correctly take existing remote definitions into account. - (merge 229177a jh/checkout-auto-tracking later to maint). diff --git a/Documentation/RelNotes/1.8.5.txt b/Documentation/RelNotes/1.8.5.txt new file mode 100644 index 0000000000..3b43a61d85 --- /dev/null +++ b/Documentation/RelNotes/1.8.5.txt @@ -0,0 +1,130 @@ +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 <path>" will behave as "git add -A <path>", 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 <path>" +now before 2.0 is released. + + +Updates since v1.8.4 +-------------------- + +Foreign interfaces, subsystems and ports. + + * 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 + + * "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. + + * 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). + + * 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 e9f984ba01..0cebc4f692 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -9,10 +9,14 @@ --show-stats:: Include additional statistics at the end of blame output. --L <start>,<end>, -L :<regex>:: - Annotate only the given line range. <start> and <end> can take - one of these forms: - +-L <start>,<end>:: +-L :<regex>:: + Annotate only the given line range. May be specified multiple times. + Overlapping ranges are allowed. ++ +<start> and <end> are optional. ``-L <start>'' or ``-L <start>,'' spans from +<start> to end of file. ``-L ,<end>'' spans from start of file to <end>. ++ include::line-range-format.txt[] -l:: diff --git a/Documentation/config.txt b/Documentation/config.txt index 81856dd5a2..00bde9dec5 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -213,17 +213,6 @@ The default is true, except linkgit:git-clone[1] or linkgit:git-init[1] will probe and set core.fileMode false if appropriate when the repository is created. -core.ignoreCygwinFSTricks:: - This option is only used by Cygwin implementation of Git. If false, - the Cygwin stat() and lstat() functions are used. This may be useful - if your repository consists of a few separate directories joined in - one hierarchy using Cygwin mount. If true, Git uses native Win32 API - whenever it is possible and falls back to Cygwin functions only to - handle symbol links. The native mode is more than twice faster than - normal Cygwin l/stat() functions. True by default, unless core.filemode - is true, in which case ignoreCygwinFSTricks is ignored as Cygwin's - POSIX emulation is required to support core.filemode. - core.ignorecase:: If true, this option enables various workarounds to enable Git to work better on filesystems that are not case sensitive, @@ -879,16 +868,17 @@ The values of these variables may be specified as in color.branch.<slot>. color.interactive:: When set to `always`, always use colors for interactive prompts - and displays (such as those used by "git-add --interactive"). - When false (or `never`), never. When set to `true` or `auto`, use - colors only when the output is to the terminal. Defaults to false. + and displays (such as those used by "git-add --interactive" and + "git-clean --interactive"). When false (or `never`), never. + When set to `true` or `auto`, use colors only when the output is + to the terminal. Defaults to false. color.interactive.<slot>:: - Use customized color for 'git add --interactive' - output. `<slot>` may be `prompt`, `header`, `help` or `error`, for - four distinct types of normal output from interactive - commands. The values of these variables may be specified as - in color.branch.<slot>. + Use customized color for 'git add --interactive' and 'git clean + --interactive' output. `<slot>` may be `prompt`, `header`, `help` + or `error`, for four distinct types of normal output from + interactive commands. The values of these variables may be + specified as in color.branch.<slot>. color.pager:: A boolean to enable/disable colored output when the pager is in @@ -973,6 +963,10 @@ column.branch:: Specify whether to output branch listing in `git branch` in columns. See `column.ui` for details. +column.clean:: + Specify the layout when list items in `git clean -i`, which always + shows files and directories in columns. See `column.ui` for details. + column.status:: Specify whether to output untracked files in `git status` in columns. See `column.ui` for details. @@ -1067,6 +1061,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.<name>.prune`. + format.attach:: Enable multipart/mixed attachments as the default for 'format-patch'. The value can also be a double quoted string @@ -1451,7 +1449,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 @@ -1531,6 +1533,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.<url>.*:: + 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 @@ -2030,6 +2077,12 @@ remote.<name>.vcs:: Setting this to a value <vcs> will cause Git to interact with the remote with the git-remote-<vcs> helper. +remote.<name>.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.<group>:: The list of remotes which are fetched by "git remote update <group>". See linkgit:git-remote[1]. @@ -2068,6 +2121,10 @@ sendemail.smtpencryption:: sendemail.smtpssl:: Deprecated alias for 'sendemail.smtpencryption = ssl'. +sendemail.smtpsslcertpath:: + Path to ca-certificates (either a directory or a single file). + Set it to an empty string to disable certificate verification. + sendemail.<identity>.*:: Identity-specific versions of the 'sendemail.*' parameters found below, taking precedence over those when the this diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 87e92d6537..bbed2cd79c 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -26,6 +26,11 @@ ifndef::git-format-patch[] {git-diff? This is the default.} endif::git-format-patch[] +-s:: +--no-patch:: + Suppress diff output. Useful for commands like `git show` that + show the patch by default, or to cancel the effect of `--patch`. + -U<n>:: --unified=<n>:: Generate diffs with <n> lines of context instead of diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 0eed3e3f29..afeb86c6cd 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -1320,7 +1320,7 @@ So git bisect is unconditional goodness - and feel free to quote that ;-) _____________ -Acknowledgements +Acknowledgments ---------------- Many thanks to Junio Hamano for his help in reviewing this paper, for 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 <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] + [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file> 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-cat-file.txt b/Documentation/git-cat-file.txt index 30d585af5d..21cffe2bcd 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -58,12 +58,16 @@ OPTIONS to apply the filter to the content recorded in the index at <path>. --batch:: - Print the SHA-1, type, size, and contents of each object provided on - stdin. May not be combined with any other options or arguments. +--batch=<format>:: + Print object information and contents for each object provided + on stdin. May not be combined with any other options or arguments. + See the section `BATCH OUTPUT` below for details. --batch-check:: - Print the SHA-1, type, and size of each object provided on stdin. May not - be combined with any other options or arguments. +--batch-check=<format>:: + Print object information for each object provided on stdin. May + not be combined with any other options or arguments. See the + section `BATCH OUTPUT` below for details. OUTPUT ------ @@ -78,28 +82,81 @@ If '-p' is specified, the contents of <object> are pretty-printed. If <type> is specified, the raw (though uncompressed) contents of the <object> will be returned. -If '--batch' is specified, output of the following form is printed for each -object specified on stdin: +BATCH OUTPUT +------------ + +If `--batch` or `--batch-check` is given, `cat-file` will read objects +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 +`<format>`. The `<format>` is copied literally to stdout for each +object, with placeholders of the form `%(atom)` expanded, followed by a +newline. The available atoms are: + +`objectname`:: + The 40-hex object name of the object. + +`objecttype`:: + The type of of the object (the same as `cat-file -t` reports). + +`objectsize`:: + The size, in bytes, of the object (the same as `cat-file -s` + reports). + +`objectsize:disk`:: + 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)`. + +If `--batch` is specified, the object information is followed by the +object contents (consisting of `%(objectsize)` bytes), followed by a +newline. + +For example, `--batch` without a custom format would produce: ------------ <sha1> SP <type> SP <size> LF <contents> LF ------------ -If '--batch-check' is specified, output of the following form is printed for -each object specified on stdin: +Whereas `--batch-check='%(objectname) %(objecttype)'` would produce: ------------ -<sha1> SP <type> SP <size> LF +<sha1> SP <type> LF ------------ -For both '--batch' and '--batch-check', output of the following form is printed -for each object specified on stdin that does not exist in the repository: +If a name is specified on stdin that cannot be resolved to an object in +the repository, then `cat-file` will ignore any custom format and print: ------------ <object> SP missing LF ------------ + +CAVEATS +------- + +Note that the sizes of objects on disk are reported accurately, but care +should be taken in drawing conclusions about which refs or objects are +responsible for disk usage. The size of a packed non-delta object may be +much larger than the size of objects which delta against it, but the +choice of which object is the base and which is the delta is arbitrary +and is subject to change during a repack. Note also that multiple copies +of an object may be present in the object database; in this case, it is +undefined which copy's size will be reported. + + GIT --- Part of the linkgit:git[1] suite 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: <path> COLON SP <attribute> COLON SP <info> LF +unless `-z` is in effect, in which case NUL is used as delimiter: +<path> NUL <attribute> NUL <info> NUL + + <path> is the path of a file being queried, <attribute> is an attribute being queried and <info> can be either: diff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.txt new file mode 100644 index 0000000000..39028ee1a3 --- /dev/null +++ b/Documentation/git-check-mailmap.txt @@ -0,0 +1,47 @@ +git-check-mailmap(1) +==================== + +NAME +---- +git-check-mailmap - Show canonical names and email addresses of contacts + + +SYNOPSIS +-------- +[verse] +'git check-mailmap' [options] <contact>... + + +DESCRIPTION +----------- + +For each ``Name $$<user@host>$$'' or ``$$<user@host>$$'' from the command-line +or standard input (when using `--stdin`), look up the person's canonical name +and email address (see "Mapping Authors" below). If found, print them; +otherwise print the input as-is. + + +OPTIONS +------- +--stdin:: + Read contacts, one per line, from the standard input after exhausting + contacts provided on the command-line. + + +OUTPUT +------ + +For each contact, a single line is output, terminated by a newline. If the +name is provided or known to the 'mailmap', ``Name $$<user@host>$$'' is +printed; otherwise only ``$$<user@host>$$'' is printed. + + +MAPPING AUTHORS +--------------- + +include::mailmap.txt[] + + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index fc02959ba4..a49be1bab4 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -54,8 +54,6 @@ 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-clean.txt b/Documentation/git-clean.txt index bdc3ab80c7..89979228b1 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git clean' [-d] [-f] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... +'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... DESCRIPTION ----------- @@ -34,7 +34,13 @@ OPTIONS -f:: --force:: If the Git configuration variable clean.requireForce is not set - to false, 'git clean' will refuse to run unless given -f or -n. + to false, 'git clean' will refuse to run unless given -f, -n or + -i. + +-i:: +--interactive:: + Show what would be done and clean files interactively. See + ``Interactive mode'' for details. -n:: --dry-run:: @@ -63,6 +69,67 @@ OPTIONS Remove only files ignored by Git. This may be useful to rebuild everything from scratch, but keep manually created files. +Interactive mode +---------------- +When the command enters the interactive mode, it shows the +files and directories to be cleaned, and goes into its +interactive command loop. + +The command loop shows the list of subcommands available, and +gives a prompt "What now> ". In general, when the prompt ends +with a single '>', you can pick only one of the choices given +and type return, like this: + +------------ + *** Commands *** + 1: clean 2: filter by pattern 3: select by numbers + 4: ask each 5: quit 6: help + What now> 1 +------------ + +You also could say `c` or `clean` above as long as the choice is unique. + +The main command loop has 6 subcommands. + +clean:: + + Start cleaning files and directories, and then quit. + +filter by pattern:: + + This shows the files and directories to be deleted and issues an + "Input ignore patterns>>" prompt. You can input space-seperated + patterns to exclude files and directories from deletion. + E.g. "*.c *.h" will excludes files end with ".c" and ".h" from + deletion. When you are satisfied with the filtered result, press + ENTER (empty) back to the main menu. + +select by numbers:: + + This shows the files and directories to be deleted and issues an + "Select items to delete>>" prompt. When the prompt ends with double + '>>' like this, you can make more than one selection, concatenated + with whitespace or comma. Also you can say ranges. E.g. "2-5 7,9" + to choose 2,3,4,5,7,9 from the list. If the second number in a + range is omitted, all remaining items are selected. E.g. "7-" to + choose 7,8,9 from the list. You can say '*' to choose everything. + Also when you are satisfied with the filtered result, press ENTER + (empty) back to the main menu. + +ask each:: + + This will start to clean, and you must confirm one by one in order + to delete items. Please note that this action is not as efficient + as the above two actions. + +quit:: + + This lets you quit without do cleaning. + +help:: + + Show brief usage of interactive git-clean. + SEE ALSO -------- linkgit:gitignore[5] diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 85769b884e..450f158779 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -182,13 +182,11 @@ 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. A shallow repository has a - number of limitations (you cannot clone or fetch from it, nor - push into it), but is adequate if you are only interested in - the recent history of a large project with a long history. -+ -Pushing from a shallow clone should be avoided if the git version on -the receiver end is older than v1.7.10, or any other git -implementation that does not perform connectivity check. + number of limitations (you cannot clone or fetch from + it, nor push from nor into it), but is adequate if you + are only interested in the recent history of a large project + with a long history, and would want to send in fixes + as patches. --[no-]single-branch:: Clone only the history leading to the tip of a single branch, diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 99dc497b6f..e9917b89a9 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -15,6 +15,7 @@ SYNOPSIS 'git config' [<file-option>] [type] [-z|--null] --get name [value_regex] 'git config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] 'git config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [type] [-z|--null] --get-urlmatch name URL 'git config' [<file-option>] --unset name [value_regex] 'git config' [<file-option>] --unset-all name [value_regex] 'git config' [<file-option>] --rename-section old_name new_name @@ -95,30 +96,40 @@ 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.<url>.key whose <url> 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 $XDG_CONFIG_HOME/git/config file - if this file exists and the ~/.gitconfig file doesn't. + For writing options: write to global `~/.gitconfig` file + rather than the repository `.git/config`, write to + `$XDG_CONFIG_HOME/git/config` file if this file exists and the + `~/.gitconfig` file doesn't. + -For reading options: read only from global ~/.gitconfig and from -$XDG_CONFIG_HOME/git/config rather than from all available files. +For reading options: read only from global `~/.gitconfig` and from +`$XDG_CONFIG_HOME/git/config` rather than from all available files. + See also <<FILES>>. --system:: - For writing options: write to system-wide $(prefix)/etc/gitconfig - rather than the repository .git/config. + For writing options: write to system-wide + `$(prefix)/etc/gitconfig` rather than the repository + `.git/config`. + -For reading options: read only from system-wide $(prefix)/etc/gitconfig +For reading options: read only from system-wide `$(prefix)/etc/gitconfig` rather than from all available files. + See also <<FILES>>. --local:: - For writing options: write to the repository .git/config file. + For writing options: write to the repository `.git/config` file. This is the default behavior. + -For reading options: read only from the repository .git/config rather than +For reading options: read only from the repository `.git/config` rather than from all available files. + See also <<FILES>>. @@ -127,6 +138,13 @@ See also <<FILES>>. --file config-file:: Use the given config file instead of the one specified by GIT_CONFIG. +--blob blob:: + Similar to '--file' but use the given blob instead of a file. E.g. + you can use 'master:.gitmodules' to read values from the file + '.gitmodules' in the master branch. See "SPECIFYING REVISIONS" + section in linkgit:gitrevisions[7] for a more complete list of + ways to spell blob names. + --remove-section:: Remove the given section from the configuration file. @@ -211,9 +229,9 @@ $(prefix)/etc/gitconfig:: $XDG_CONFIG_HOME/git/config:: Second user-specific configuration file. If $XDG_CONFIG_HOME is not set - or empty, $HOME/.config/git/config will be used. Any single-valued + or empty, `$HOME/.config/git/config` will be used. Any single-valued variable set in this file will be overwritten by whatever is in - ~/.gitconfig. It is a good idea not to create this file if + `~/.gitconfig`. It is a good idea not to create this file if you sometimes use older versions of Git, as support for this file was added fairly recently. @@ -286,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 ------------ @@ -371,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-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 39118774af..9e0ef0eaf3 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -187,6 +187,21 @@ will want to ensure that threading is disabled for `git send-email`. The negated form `--no-cc` discards all `Cc:` headers added so far (from config or command line). +--from:: +--from=<ident>:: + Use `ident` in the `From:` header of each commit email. If the + author ident of the commit is not textually identical to the + provided `ident`, place a `From:` header in the body of the + message with the original author. If no `ident` is given, use + the committer ident. ++ +Note that this option is only useful if you are actually sending the +emails and want to identify yourself as the sender, but retain the +original author (and `git am` will correctly pick up the in-body +header). Note also that `git send-email` already handles this +transformation for you, and this option should not be used if you are +feeding the result to `git send-email`. + --add-header=<header>:: Add an arbitrary header to the email headers. This is in addition to any configured headers, and may be used multiple times. @@ -227,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=<date> | --no-prune] +'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --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 2ea79ba168..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 <start>,<end>:<file>, -L :<regex>:<file>:: +-L <start>,<end>:<file>:: +-L :<regex>:<file>:: Trace the evolution of the line range given by "<start>,<end>" (or the funcname regex <regex>) within the <file>. 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. + -<start> and <end> can take one of these forms: - include::line-range-format.txt[] <revision range>:: @@ -97,7 +96,7 @@ include::rev-list-options.txt[] include::pretty-formats.txt[] -Common diff options +COMMON DIFF OPTIONS ------------------- :git-log: 1 @@ -105,7 +104,7 @@ include::diff-options.txt[] include::diff-generate-patch.txt[] -Examples +EXAMPLES -------- `git log --no-merges`:: @@ -153,7 +152,7 @@ Examples This makes sense only when following a strict policy of merging all topic branches when staying on a single integration branch. -git log -L '/int main/',/^}/:main.c:: +`git log -L '/int main/',/^}/:main.c`:: Shows how the function `main()` in the file 'main.c' evolved over time. @@ -161,12 +160,12 @@ git log -L '/int main/',/^}/:main.c:: `git log -3`:: Limits the number of commits to show to 3. -Discussion +DISCUSSION ---------- include::i18n.txt[] -Configuration +CONFIGURATION ------------- See linkgit:git-config[1] for core variables and linkgit:git-diff[1] 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 <current-name> [-L <base-name> [-L <other-name>]]] [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>] - <current-file> <base-file> <other-file> + [--[no-]diff3] <current-file> <base-file> <other-file> 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.txt b/Documentation/git-merge.txt index 8c7f2f66d8..a74c3713c6 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -186,11 +186,11 @@ In such a case, you can "unwrap" the tag yourself before feeding it to `git merge`, or pass `--ff-only` when you do not have any work on your own. e.g. ---- +---- git fetch origin git merge v1.2.3^0 git merge --ff-only v1.2.3 ---- +---- HOW CONFLICTS ARE PRESENTED 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] <source> <destination> git mv [-v] [-f] [-n] [-k] <source> ... <destination directory> @@ -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.<name>.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-pack-refs.txt b/Documentation/git-pack-refs.txt index f131677478..154081f2de 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -33,8 +33,8 @@ Subsequent updates to branches always create new files under `$GIT_DIR/refs` directory hierarchy. A recommended practice to deal with a repository with too many -refs is to pack its refs with `--all --prune` once, and -occasionally run `git pack-refs --prune`. Tags are by +refs is to pack its refs with `--all` once, and +occasionally run `git pack-refs`. Tags are by definition stationary and are not expected to change. Branch heads will be packed with the initial `pack-refs --all`, but only the currently active branch heads will become unpacked, diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 80d01b0571..bf824108c1 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -59,7 +59,7 @@ borrows from your repository via its `.git/objects/info/alternates`: ------------ -$ git prune $(cd ../another && $(git rev-parse --all)) +$ git prune $(cd ../another && git rev-parse --all) ------------ Notes diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index f7dfe48d28..e2992f17a0 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=<git-receive-pack>] [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] + [--force-with-lease[=<refname>[:<expect>]]] [--no-verify] [<repository> [<refspec>...]] DESCRIPTION @@ -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=<refname>:: +--force-with-lease=<refname>:<expect>:: + 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=<refname>:<expect>` +option that explicitly states what the expected value is. ++ +`--force-with-lease=<refname>`, 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=<refname>:<expect>` 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 <expect> (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=<refname>:<expect>` +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 `<refspec>...` 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 +`<refspec>...` section above for details. --repo=<repository>:: This option is only relevant if no <repository> argument is diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index a404b47b7b..f445cb38fa 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git reset' [-q] [<tree-ish>] [--] <paths>... -'git reset' (--patch | -p) [<tree-sh>] [--] [<paths>...] +'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...] 'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 65ac27e0c9..045b37b82e 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -40,7 +40,7 @@ SYNOPSIS [ \--right-only ] [ \--cherry-mark ] [ \--cherry-pick ] - [ \--encoding[=<encoding>] ] + [ \--encoding=<encoding> ] [ \--(author|committer|grep)=<pattern> ] [ \--regexp-ignore-case | -i ] [ \--extended-regexp | -E ] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 993903c9f1..d068a65377 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -24,9 +24,23 @@ distinguish between them. OPTIONS ------- + +Operation Modes +~~~~~~~~~~~~~~~ + +Each of these options must appear first on the command line. + --parseopt:: Use 'git rev-parse' in option parsing mode (see PARSEOPT section below). +--sq-quote:: + Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE + section below). In contrast to the `--sq` option below, this + mode does only quoting. Nothing else is done to command input. + +Options for --parseopt +~~~~~~~~~~~~~~~~~~~~~~ + --keep-dashdash:: Only meaningful in `--parseopt` mode. Tells the option parser to echo out the first `--` met instead of skipping it. @@ -36,10 +50,8 @@ OPTIONS the first non-option argument. This can be used to parse sub-commands that take options themselves. ---sq-quote:: - Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE - section below). In contrast to the `--sq` option below, this - mode does only quoting. Nothing else is done to command input. +Options for Filtering +~~~~~~~~~~~~~~~~~~~~~ --revs-only:: Do not output flags and parameters not meant for @@ -55,6 +67,9 @@ OPTIONS --no-flags:: Do not output flag parameters. +Options for Output +~~~~~~~~~~~~~~~~~~ + --default <arg>:: If there is no parameter given by the user, use `<arg>` instead. @@ -83,7 +98,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" + If you want to make sure that the output actually names an object in your object database and/or can be used as a specific type of object -you require, you can add "^{type}" peeling operator to the parmeter. +you require, you can add "^{type}" peeling operator to the parameter. For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` names an existing object that is a commit-ish (i.e. a commit, or an annotated tag that points at a commit). To make sure that `$VAR` @@ -110,6 +125,17 @@ can be used. strip '{caret}' prefix from the object names that already have one. +--abbrev-ref[=(strict|loose)]:: + A non-ambiguous short name of the objects name. + The option core.warnAmbiguousRefs is used to select the strict + abbreviation mode. + +--short:: +--short=number:: + Instead of outputting the full SHA-1 values of object names try to + abbreviate them to a shorter unique name. When no length is specified + 7 is used. The minimum length is 4. + --symbolic:: Usually the object names are output in SHA-1 form (with possible '{caret}' prefix); this option makes them output in a @@ -123,16 +149,8 @@ can be used. unfortunately named tag "master"), and show them as full refnames (e.g. "refs/heads/master"). ---abbrev-ref[=(strict|loose)]:: - A non-ambiguous short name of the objects name. - The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. - ---disambiguate=<prefix>:: - Show every object whose name begins with the given prefix. - The <prefix> must be at least 4 hexadecimal digits long to - avoid listing each and every object in the repository by - mistake. +Options for Objects +~~~~~~~~~~~~~~~~~~~ --all:: Show all refs found in `refs/`. @@ -155,18 +173,20 @@ shown. If the pattern does not contain a globbing character (`?`, character (`?`, `*`, or `[`), it is turned into a prefix match by appending `/*`. ---show-toplevel:: - Show the absolute path of the top-level directory. +--disambiguate=<prefix>:: + Show every object whose name begins with the given prefix. + The <prefix> must be at least 4 hexadecimal digits long to + avoid listing each and every object in the repository by + mistake. ---show-prefix:: - When the command is invoked from a subdirectory, show the - path of the current directory relative to the top-level - directory. +Options for Files +~~~~~~~~~~~~~~~~~ ---show-cdup:: - When the command is invoked from a subdirectory, show the - path of the top-level directory relative to the current - directory (typically a sequence of "../", or an empty string). +--local-env-vars:: + List the GIT_* environment variables that are local to the + repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). + Only the names of the variables are listed, not their value, + even if they are set. --git-dir:: Show `$GIT_DIR` if defined. Otherwise show the path to @@ -188,17 +208,27 @@ print a message to stderr and exit with nonzero status. --is-bare-repository:: When the repository is bare print "true", otherwise "false". ---local-env-vars:: - List the GIT_* environment variables that are local to the - repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). - Only the names of the variables are listed, not their value, - even if they are set. +--resolve-git-dir <path>:: + Check if <path> is a valid repository or a gitfile that + points at a valid repository, and print the location of the + repository. If <path> is a gitfile then the resolved path + to the real repository is printed. ---short:: ---short=number:: - Instead of outputting the full SHA-1 values of object names try to - abbreviate them to a shorter unique name. When no length is specified - 7 is used. The minimum length is 4. +--show-cdup:: + When the command is invoked from a subdirectory, show the + path of the top-level directory relative to the current + directory (typically a sequence of "../", or an empty string). + +--show-prefix:: + When the command is invoked from a subdirectory, show the + path of the current directory relative to the top-level + directory. + +--show-toplevel:: + Show the absolute path of the top-level directory. + +Other Options +~~~~~~~~~~~~~ --since=datestring:: --after=datestring:: @@ -213,12 +243,6 @@ print a message to stderr and exit with nonzero status. <args>...:: Flags and parameters to be parsed. ---resolve-git-dir <path>:: - Check if <path> is a valid repository or a gitfile that - points at a valid repository, and print the location of the - repository. If <path> is a gitfile then the resolved path - to the real repository is printed. - include::revisions.txt[] diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 1d876c2619..9d731b453d 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -134,14 +134,16 @@ use the following command: git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached ---------------- -Submodules -~~~~~~~~~~ +SUBMODULES +---------- Only submodules using a gitfile (which means they were cloned with a Git version 1.7.8 or newer) will be removed from the work tree, as their repository lives inside the .git directory of the superproject. If a submodule (or one of those nested inside it) still uses a .git directory, `git rm` will fail - no matter if forced -or not - to protect the submodule's history. +or not - to protect the submodule's history. If it exists the +submodule.<name> section in the linkgit:gitmodules[5] file will also +be removed and that file will be staged (unless --cached or -n are used). A submodule is considered up-to-date when the HEAD is the same as recorded in the index, no tracked files are modified and no untracked diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 40a9a9abc1..f0e57a597b 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -198,6 +198,12 @@ must be used for each option. --smtp-ssl:: Legacy alias for '--smtp-encryption ssl'. +--smtp-ssl-cert-path:: + Path to ca-certificates (either a directory or a single file). + Set it to an empty string to disable certificate verification. + Defaults to the value set to the 'sendemail.smtpsslcertpath' + configuration variable, if set, or `/etc/ssl/certs` otherwise. + --smtp-user=<user>:: Username for SMTP-AUTH. Default is the value of 'sendemail.smtpuser'; if a username is not specified (with '--smtp-user' or 'sendemail.smtpuser'), diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index de4d352da2..b0a309b117 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -21,6 +21,8 @@ commit IDs. Results can be filtered using a pattern and tags can be dereferenced into object IDs. Additionally, it can be used to test whether a particular ref exists. +By default, shows the tags, heads, and remote refs. + The --exclude-existing form is a filter that does the inverse, it shows the refs from stdin that don't exist in the local repository. @@ -32,14 +34,14 @@ OPTIONS --head:: - Show the HEAD reference. + Show the HEAD reference, even if it would normally be filtered out. --tags:: --heads:: - Limit to only "refs/heads" and "refs/tags", respectively. These - options are not mutually exclusive; when given both, references stored - in "refs/heads" and "refs/tags" are displayed. + Limit to "refs/heads" and "refs/tags", respectively. These options + are not mutually exclusive; when given both, references stored in + "refs/heads" and "refs/tags" are displayed. -d:: --dereference:: diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index ae4edcccfb..4e617e6979 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -45,6 +45,15 @@ include::pretty-options.txt[] include::pretty-formats.txt[] +COMMON DIFF OPTIONS +------------------- + +:git-log: 1 +include::diff-options.txt[] + +include::diff-generate-patch.txt[] + + EXAMPLES -------- diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 7c8b648fbe..db7e803038 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -14,8 +14,7 @@ SYNOPSIS 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] 'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] - [-u|--include-untracked] [-a|--all] [-f|--force] - [<message>]] + [-u|--include-untracked] [-a|--all] [<message>]] 'git stash' clear 'git stash' create [<message>] 'git stash' store [-m|--message <message>] [-q|--quiet] <commit> @@ -45,7 +44,7 @@ is also possible). OPTIONS ------- -save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-f|--force] [<message>]:: +save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: Save your local modifications to a new 'stash', and run `git reset --hard` to revert them. The <message> part is optional and gives @@ -72,13 +71,6 @@ linkgit:git-add[1] to learn how to operate the `--patch` mode. + The `--patch` option implies `--keep-index`. You can use `--no-keep-index` to override this. -+ -In some cases, saving a stash could mean irretrievably removing some -data - if a directory with untracked files replaces a tracked file of -the same name, the new untracked files are not saved (except in case -of `--include-untracked`) but the original tracked file shall be restored. -By default, `stash save` will abort in such a case; `--force` will allow -it to remove the untracked files. list [<options>]:: diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index bfff09062d..bfef8a0c62 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -10,12 +10,12 @@ SYNOPSIS -------- [verse] 'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>] - [--reference <repository>] [--] <repository> [<path>] + [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] [--] <path>... 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] - [-f|--force] [--rebase] [--reference <repository>] + [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>] [--merge] [--recursive] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] @@ -159,7 +159,9 @@ update:: This will make the submodules HEAD be detached unless `--rebase` or `--merge` is specified or the key `submodule.$name.update` is set to `rebase`, `merge` or `none`. `none` can be overridden by specifying - `--checkout`. + `--checkout`. Setting the key `submodule.$name.update` to `!command` + will cause `command` to be run. `command` can be any arbitrary shell + command that takes a single argument, namely the sha1 to update to. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the @@ -328,6 +330,12 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. only in the submodules of the current repo, but also in any nested submodules inside those submodules (and so on). +--depth:: + This option is valid for add and update commands. Create a 'shallow' + clone with a history truncated to the specified number of revisions. + See linkgit:git-clone[1] + + <path>...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index aad452f169..4dd3bcb511 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -256,7 +256,7 @@ first have already been pushed into SVN. For each patch, one may answer "yes" (accept this patch), "no" (discard this patch), "all" (accept all patches), or "quit". + - 'git svn dcommit' returns immediately if answer if "no" or "quit", without + 'git svn dcommit' returns immediately if answer is "no" or "quit", without committing anything to SVN. 'branch':: diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 22894cbee6..c418c44d40 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -42,6 +42,17 @@ committer identity for the current user is used to find the GnuPG key for signing. The configuration variable `gpg.program` is used to specify custom GnuPG binary. +Tag objects (created with `-a`, `s`, or `-u`) are called "annotated" +tags; they contain a creation date, the tagger name and e-mail, a +tagging message, and an optional GnuPG signature. Whereas a +"lightweight" tag is simply a name for an object (usually a commit +object). + +Annotated tags are meant for release while lightweight tags are meant +for private or temporary object labels. For this reason, some git +commands for naming objects (like `git describe`) will ignore +lightweight tags by default. + OPTIONS ------- diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index c600b61e2b..8b63ceb00e 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -13,43 +13,17 @@ SYNOPSIS DESCRIPTION ----------- -Shows commit logs and diff output each commit introduces. The -command internally invokes 'git rev-list' piped to -'git diff-tree', and takes command line options for both of -these commands. -This manual page describes only the most frequently used options. +Shows commit logs and diff output each commit introduces. +New users are encouraged to use linkgit:git-log[1] instead. The +`whatchanged` command is essentially the same as linkgit:git-log[1] +but defaults to show the raw format diff output and to skip merges. -OPTIONS -------- --p:: - Show textual diffs, instead of the Git internal diff - output format that is useful only to tell the changed - paths and their nature of changes. +The command is kept primarily for historical reasons; fingers of +many people who learned Git long before `git log` was invented by +reading Linux kernel mailing list are trained to type it. --<n>:: - Limit output to <n> commits. - -<since>..<until>:: - Limit output to between the two named commits (bottom - exclusive, top inclusive). - --r:: - Show Git internal diff output, but for the whole tree, - not just the top level. - --m:: - By default, differences for merge commits are not shown. - With this flag, show differences to that commit from all - of its parents. -+ -However, it is not very useful in general, although it -*is* useful on a file-by-file basis. - -include::pretty-options.txt[] - -include::pretty-formats.txt[] Examples -------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 2c1f6f5f53..c4f0ed5957 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,16 @@ unreleased) version of Git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.8.3.2/git.html[documentation for release 1.8.3.2] +* link:v1.8.4/git.html[documentation for release 1.8.4] * release notes for + link:RelNotes/1.8.4.txt[1.8.4]. + +* link:v1.8.3.4/git.html[documentation for release 1.8.3.4] + +* release notes for + link:RelNotes/1.8.3.4.txt[1.8.3.4], + link:RelNotes/1.8.3.3.txt[1.8.3.3], link:RelNotes/1.8.3.2.txt[1.8.3.2], link:RelNotes/1.8.3.1.txt[1.8.3.1], link:RelNotes/1.8.3.txt[1.8.3]. @@ -831,7 +838,7 @@ for further details. 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', - 'git check-attr', 'git check-ignore', and 'git whatchanged' will + 'git check-attr' and 'git check-ignore' will force a flush of the output stream after each record have been flushed. If this variable is set to "0", the output of these commands will be done diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f538a870c7..058a352980 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -534,42 +534,9 @@ all, but just show the actual commit message. In fact, together with the 'git rev-list' program (which generates a list of revisions), 'git diff-tree' ends up being a veritable fount of -changes. A trivial (but very useful) script called 'git whatchanged' is -included with Git which does exactly this, and shows a log of recent -activities. - -To see the whole history of our pitiful little git-tutorial project, you -can do - ----------------- -$ git log ----------------- - -which shows just the log messages, or if we want to see the log together -with the associated patches use the more complex (and much more -powerful) - ----------------- -$ git whatchanged -p ----------------- - -and you will see exactly what has changed in the repository over its -short history. - -[NOTE] -When using the above two commands, the initial commit will be shown. -If this is a problem because it is huge, you can hide it by setting -the log.showroot configuration variable to false. Having this, you -can still show it for each command just adding the `--root` option, -which is a flag for 'git diff-tree' accepted by both commands. - -With that, you should now be having some inkling of what Git does, and -can explore on your own. - -[NOTE] -Most likely, you are not directly using the core -Git Plumbing commands, but using Porcelain such as 'git add', `git-rm' -and `git-commit'. +changes. You can emulate `git log`, `git log -p`, etc. with a trivial +script that pipes the output of `git rev-list` to `git diff-tree --stdin`, +which was exactly how early versions of `git log` were implemented. Tagging a version diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 0827f69139..bc069c23df 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -143,6 +143,10 @@ Supported commands: 'list', 'fetch'. + Supported commands: 'list', 'import'. +'check-connectivity':: + Can guarantee that when a clone is requested, the received + pack is self contained and is connected. + If a helper advertises 'connect', Git will use it if possible and fall back to another capability if the helper requests so when connecting (see the 'connect' command under COMMANDS). @@ -270,6 +274,9 @@ Optionally may output a 'lock <file>' line indicating a file under GIT_DIR/objects/pack which is keeping a pack until refs can be suitably updated. + +If option 'check-connectivity' is requested, the helper must output +'connectivity-ok' if the clone is self-contained and connected. ++ Supported if the helper has the "fetch" capability. 'push' +<src>:<dst>:: @@ -416,6 +423,9 @@ set by Git if the remote helper has the 'option' capability. must not rely on this option being set before connect request occurs. +'option check-connectivity' \{'true'|'false'\}:: + Request the helper to check connectivity of a clone. + SEE ALSO -------- linkgit:git-remote[1] diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index 40969f1098..cca14b8cc3 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -504,7 +504,7 @@ repositories, you can configure Apache like this: The above configuration expects your public repositories to live under '/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`, -both as cloneable Git URL and as browseable gitweb interface. If you then +both as clonable Git URL and as browseable gitweb interface. If you then start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` then you can even use the `git://` URL with exactly the same path. diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt index 2abc3a0a0e..d7de5a3e9e 100644 --- a/Documentation/howto/new-command.txt +++ b/Documentation/howto/new-command.txt @@ -94,7 +94,7 @@ your language, document it in the INSTALL file. 6. There is a file command-list.txt in the distribution main directory that categorizes commands by type, so they can be listed in appropriate subsections in the documentation's summary command list. Add an entry -for yours. To understand the categories, look at git-cmmands.txt +for yours. To understand the categories, look at git-commands.txt in the main directory. 7. Give the maintainer one paragraph to include in the RelNotes file diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt index 84dd839db4..0d5419e1a9 100644 --- a/Documentation/howto/revert-branch-rebase.txt +++ b/Documentation/howto/revert-branch-rebase.txt @@ -12,7 +12,7 @@ How to revert an existing commit ================================ One of the changes I pulled into the 'master' branch turns out to -break building Git with GCC 2.95. While they were well intentioned +break building Git with GCC 2.95. While they were well-intentioned portability fixes, keeping things working with gcc-2.95 was also important. Here is what I did to revert the change in the 'master' branch and to adjust the 'pu' branch, using core Git tools and diff --git a/Documentation/line-range-format.txt b/Documentation/line-range-format.txt index 3e7ce72daa..d7f26039ca 100644 --- a/Documentation/line-range-format.txt +++ b/Documentation/line-range-format.txt @@ -1,3 +1,5 @@ +<start> and <end> can take one of these forms: + - number + If <start> or <end> is a number, it specifies an @@ -7,7 +9,10 @@ absolute line number (lines count from 1). - /regex/ + This form will use the first line matching the given -POSIX regex. If <end> is a regex, it will search +POSIX regex. If <start> is a regex, it will search from the end of +the previous `-L` range, if any, otherwise from the start of file. +If <start> is ``^/regex/'', it will search from the start of file. +If <end> is a regex, it will search starting at the line given by <start>. + @@ -15,11 +20,10 @@ starting at the line given by <start>. + This is only valid for <end> and will specify a number of lines before or after the line given by <start>. -+ -- :regex + -If the option's argument is of the form :regex, it denotes the range +If ``:<regex>'' is given in place of <start> and <end>, it denotes the range from the first funcname line that matches <regex>, up to the next -funcname line. -+ +funcname line. ``:<regex>'' searches from the end of the previous `-L` range, +if any, otherwise from the start of file. +``^:<regex>'' searches from the start of file. diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 5e499421a4..eea0e306a8 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -28,7 +28,7 @@ people using 80-column terminals. This is a shorthand for "--pretty=oneline --abbrev-commit" used together. ---encoding[=<encoding>]:: +--encoding=<encoding>:: The commit objects record the encoding used for the log message in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index e157ec3fe7..5bdfb42852 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -119,7 +119,7 @@ if it is part of the log message. --no-min-parents:: --no-max-parents:: - Show only commits which have at least (or at most) that many + Show only commits which have at least (or at most) that many parent commits. In particular, `--max-parents=1` is the same as `--no-merges`, `--min-parents=2` is the same as `--merges`. `--max-parents=0` gives all root commits and `--min-parents=3` all octopus merges. @@ -369,7 +369,7 @@ each merge. The commits are: * `E` changes `quux` to "xyzzy", and its merge `P` combines the strings to "quux xyzzy". `P` is TREESAME to `O`, but not to `E`. -* `X` is an indpendent root commit that added a new file `side`, and `Y` +* `X` is an independent root commit that added a new file `side`, and `Y` modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and `Q` is TREESAME to `P`, but not to `Y`. @@ -849,7 +849,4 @@ options may be given. See linkgit:git-diff-files[1] for more options. -t:: Show the tree objects in the diff output. This implies '-r'. - --s:: - Suppress diff output. endif::git-rev-list[] diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 09896a37b1..d477b3f6bc 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -58,9 +58,6 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. -'@':: - '@' alone is a shortcut for 'HEAD'. - '<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: A ref followed by the suffix '@' with a date specification enclosed in a brace diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt index b7d0d9a8a7..55b878ade8 100644 --- a/Documentation/technical/api-revision-walking.txt +++ b/Documentation/technical/api-revision-walking.txt @@ -59,7 +59,7 @@ function. `reset_revision_walk`:: Reset the flags used by the revision walking api. You can use - this to do multiple sequencial revision walks. + this to do multiple sequential revision walks. Data structures --------------- diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt new file mode 100644 index 0000000000..a1173ee266 --- /dev/null +++ b/Documentation/technical/http-protocol.txt @@ -0,0 +1,503 @@ +HTTP transfer protocols +======================= + +Git supports two HTTP based transfer protocols. A "dumb" protocol +which requires only a standard HTTP server on the server end of the +connection, and a "smart" protocol which requires a Git aware CGI +(or server module). This document describes both protocols. + +As a design feature smart clients can automatically upgrade "dumb" +protocol URLs to smart URLs. This permits all users to have the +same published URL, and the peers automatically select the most +efficient transport available to them. + + +URL Format +---------- + +URLs for Git repositories accessed by HTTP use the standard HTTP +URL syntax documented by RFC 1738, so they are of the form: + + http://<host>:<port>/<path>?<searchpart> + +Within this documentation the placeholder $GIT_URL will stand for +the http:// repository URL entered by the end-user. + +Servers SHOULD handle all requests to locations matching $GIT_URL, as +both the "smart" and "dumb" HTTP protocols used by Git operate +by appending additional path components onto the end of the user +supplied $GIT_URL string. + +An example of a dumb client requesting for a loose object: + + $GIT_URL: http://example.com:8080/git/repo.git + URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355 + +An example of a smart request to a catch-all gateway: + + $GIT_URL: http://example.com/daemon.cgi?svc=git&q= + URL request: http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack + +An example of a request to a submodule: + + $GIT_URL: http://example.com/git/repo.git/path/submodule.git + URL request: http://example.com/git/repo.git/path/submodule.git/info/refs + +Clients MUST strip a trailing '/', if present, from the user supplied +$GIT_URL string to prevent empty path tokens ('//') from appearing +in any URL sent to a server. Compatible clients MUST expand +'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'. + + +Authentication +-------------- + +Standard HTTP authentication is used if authentication is required +to access a repository, and MAY be configured and enforced by the +HTTP server software. + +Because Git repositories are accessed by standard path components +server administrators MAY use directory based permissions within +their HTTP server to control repository access. + +Clients SHOULD support Basic authentication as described by RFC 2616. +Servers SHOULD support Basic authentication by relying upon the +HTTP server placed in front of the Git server software. + +Servers SHOULD NOT require HTTP cookies for the purposes of +authentication or access control. + +Clients and servers MAY support other common forms of HTTP based +authentication, such as Digest authentication. + + +SSL +--- + +Clients and servers SHOULD support SSL, particularly to protect +passwords when relying on Basic HTTP authentication. + + +Session State +------------- + +The Git over HTTP protocol (much like HTTP itself) is stateless +from the perspective of the HTTP server side. All state MUST be +retained and managed by the client process. This permits simple +round-robin load-balancing on the server side, without needing to +worry about state management. + +Clients MUST NOT require state management on the server side in +order to function correctly. + +Servers MUST NOT require HTTP cookies in order to function correctly. +Clients MAY store and forward HTTP cookies during request processing +as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any +cookies sent by a client. + + +General Request Processing +-------------------------- + +Except where noted, all standard HTTP behavior SHOULD be assumed +by both client and server. This includes (but is not necessarily +limited to): + +If there is no repository at $GIT_URL, or the resource pointed to by a +location matching $GIT_URL does not exist, the server MUST NOT respond +with '200 OK' response. A server SHOULD respond with +'404 Not Found', '410 Gone', or any other suitable HTTP status code +which does not imply the resource exists as requested. + +If there is a repository at $GIT_URL, but access is not currently +permitted, the server MUST respond with the '403 Forbidden' HTTP +status code. + +Servers SHOULD support both HTTP 1.0 and HTTP 1.1. +Servers SHOULD support chunked encoding for both request and response +bodies. + +Clients SHOULD support both HTTP 1.0 and HTTP 1.1. +Clients SHOULD support chunked encoding for both request and response +bodies. + +Servers MAY return ETag and/or Last-Modified headers. + +Clients MAY revalidate cached entities by including If-Modified-Since +and/or If-None-Match request headers. + +Servers MAY return '304 Not Modified' if the relevant headers appear +in the request and the entity has not changed. Clients MUST treat +'304 Not Modified' identical to '200 OK' by reusing the cached entity. + +Clients MAY reuse a cached entity without revalidation if the +Cache-Control and/or Expires header permits caching. Clients and +servers MUST follow RFC 2616 for cache controls. + + +Discovering References +---------------------- + +All HTTP clients MUST begin either a fetch or a push exchange by +discovering the references available on the remote repository. + +Dumb Clients +~~~~~~~~~~~~ + +HTTP clients that only support the "dumb" protocol MUST discover +references by making a request for the special info/refs file of +the repository. + +Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs, +without any search/query parameters. + + C: GET $GIT_URL/info/refs HTTP/1.0 + + S: 200 OK + S: + S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint + S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master + S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0 + S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{} + +The Content-Type of the returned info/refs entity SHOULD be +"text/plain; charset=utf-8", but MAY be any content type. +Clients MUST NOT attempt to validate the returned Content-Type. +Dumb servers MUST NOT return a return type starting with +"application/x-git-". + +Cache-Control headers MAY be returned to disable caching of the +returned entity. + +When examining the response clients SHOULD only examine the HTTP +status code. Valid responses are '200 OK', or '304 Not Modified'. + +The returned content is a UNIX formatted text file describing +each ref and its known value. The file SHOULD be sorted by name +according to the C locale ordering. The file SHOULD NOT include +the default ref named 'HEAD'. + + info_refs = *( ref_record ) + ref_record = any_ref / peeled_ref + + any_ref = obj-id HTAB refname LF + peeled_ref = obj-id HTAB refname LF + obj-id HTAB refname "^{}" LF + +Smart Clients +~~~~~~~~~~~~~ + +HTTP clients that support the "smart" protocol (or both the +"smart" and "dumb" protocols) MUST discover references by making +a parameterized request for the info/refs file of the repository. + +The request MUST contain exactly one query parameter, +'service=$servicename', where $servicename MUST be the service +name the client wishes to contact to complete the operation. +The request MUST NOT contain additional query parameters. + + C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 + + dumb server reply: + S: 200 OK + S: + S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint + S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master + S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0 + S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{} + + smart server reply: + S: 200 OK + S: Content-Type: application/x-git-upload-pack-advertisement + S: Cache-Control: no-cache + S: + S: 001e# service=git-upload-pack\n + S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n + S: 0042d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n + S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n + S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n + +Dumb Server Response +^^^^^^^^^^^^^^^^^^^^ +Dumb servers MUST respond with the dumb server reply format. + +See the prior section under dumb clients for a more detailed +description of the dumb server response. + +Smart Server Response +^^^^^^^^^^^^^^^^^^^^^ +If the server does not recognize the requested service name, or the +requested service name has been disabled by the server administrator, +the server MUST respond with the '403 Forbidden' HTTP status code. + +Otherwise, smart servers MUST respond with the smart server reply +format for the requested service name. + +Cache-Control headers SHOULD be used to disable caching of the +returned entity. + +The Content-Type MUST be 'application/x-$servicename-advertisement'. +Clients SHOULD fall back to the dumb protocol if another content +type is returned. When falling back to the dumb protocol clients +SHOULD NOT make an additional request to $GIT_URL/info/refs, but +instead SHOULD use the response already in hand. Clients MUST NOT +continue if they do not support the dumb protocol. + +Clients MUST validate the status code is either '200 OK' or +'304 Not Modified'. + +Clients MUST validate the first five bytes of the response entity +matches the regex "^[0-9a-f]{4}#". If this test fails, clients +MUST NOT continue. + +Clients MUST parse the entire response as a sequence of pkt-line +records. + +Clients MUST verify the first pkt-line is "# service=$servicename". +Servers MUST set $servicename to be the request parameter value. +Servers SHOULD include an LF at the end of this line. +Clients MUST ignore an LF at the end of the line. + +Servers MUST terminate the response with the magic "0000" end +pkt-line marker. + +The returned response is a pkt-line stream describing each ref and +its known value. The stream SHOULD be sorted by name according to +the C locale ordering. The stream SHOULD include the default ref +named 'HEAD' as the first ref. The stream MUST include capability +declarations behind a NUL on the first ref. + + smart_reply = PKT-LINE("# service=$servicename" LF) + ref_list + "0000" + ref_list = empty_list / non_empty_list + + empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF) + + non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF) + *ref_record + + cap-list = capability *(SP capability) + capability = 1*(LC_ALPHA / DIGIT / "-" / "_") + LC_ALPHA = %x61-7A + + ref_record = any_ref / peeled_ref + any_ref = PKT-LINE(obj-id SP name LF) + peeled_ref = PKT-LINE(obj-id SP name LF) + PKT-LINE(obj-id SP name "^{}" LF + +Smart Service git-upload-pack +------------------------------ +This service reads from the repository pointed to by $GIT_URL. + +Clients MUST first perform ref discovery with +'$GIT_URL/info/refs?service=git-upload-pack'. + + C: POST $GIT_URL/git-upload-pack HTTP/1.0 + C: Content-Type: application/x-git-upload-pack-request + C: + C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n + C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n + C: 0000 + + S: 200 OK + S: Content-Type: application/x-git-upload-pack-result + S: Cache-Control: no-cache + S: + S: ....ACK %s, continue + S: ....NAK + +Clients MUST NOT reuse or revalidate a cached reponse. +Servers MUST include sufficient Cache-Control headers +to prevent caching of the response. + +Servers SHOULD support all capabilities defined here. + +Clients MUST send at least one 'want' command in the request body. +Clients MUST NOT reference an id in a 'want' command which did not +appear in the response obtained through ref discovery unless the +server advertises capability "allow-tip-sha1-in-want". + + compute_request = want_list + have_list + request_end + request_end = "0000" / "done" + + want_list = PKT-LINE(want NUL cap_list LF) + *(want_pkt) + want_pkt = PKT-LINE(want LF) + want = "want" SP id + cap_list = *(SP capability) SP + + have_list = *PKT-LINE("have" SP id LF) + +TODO: Document this further. +TODO: Don't use uppercase for variable names below. + +The Negotiation Algorithm +~~~~~~~~~~~~~~~~~~~~~~~~~ +The computation to select the minimal pack proceeds as follows +(c = client, s = server): + + init step: + (c) Use ref discovery to obtain the advertised refs. + (c) Place any object seen into set ADVERTISED. + + (c) Build an empty set, COMMON, to hold the objects that are later + determined to be on both ends. + (c) Build a set, WANT, of the objects from ADVERTISED the client + wants to fetch, based on what it saw during ref discovery. + + (c) Start a queue, C_PENDING, ordered by commit time (popping newest + first). Add all client refs. When a commit is popped from + the queue its parents SHOULD be automatically inserted back. + Commits MUST only enter the queue once. + + one compute step: + (c) Send one $GIT_URL/git-upload-pack request: + + C: 0032want <WANT #1>............................... + C: 0032want <WANT #2>............................... + .... + C: 0032have <COMMON #1>............................. + C: 0032have <COMMON #2>............................. + .... + C: 0032have <HAVE #1>............................... + C: 0032have <HAVE #2>............................... + .... + C: 0000 + + The stream is organized into "commands", with each command + appearing by itself in a pkt-line. Within a command line + the text leading up to the first space is the command name, + and the remainder of the line to the first LF is the value. + Command lines are terminated with an LF as the last byte of + the pkt-line value. + + Commands MUST appear in the following order, if they appear + at all in the request stream: + + * want + * have + + The stream is terminated by a pkt-line flush ("0000"). + + A single "want" or "have" command MUST have one hex formatted + SHA-1 as its value. Multiple SHA-1s MUST be sent by sending + multiple commands. + + The HAVE list is created by popping the first 32 commits + from C_PENDING. Less can be supplied if C_PENDING empties. + + If the client has sent 256 HAVE commits and has not yet + received one of those back from S_COMMON, or the client has + emptied C_PENDING it SHOULD include a "done" command to let + the server know it won't proceed: + + C: 0009done + + (s) Parse the git-upload-pack request: + + Verify all objects in WANT are directly reachable from refs. + + The server MAY walk backwards through history or through + the reflog to permit slightly stale requests. + + If no WANT objects are received, send an error: + +TODO: Define error if no want lines are requested. + + If any WANT object is not reachable, send an error: + +TODO: Define error if an invalid want is requested. + + Create an empty list, S_COMMON. + + If 'have' was sent: + + Loop through the objects in the order supplied by the client. + For each object, if the server has the object reachable from + a ref, add it to S_COMMON. If a commit is added to S_COMMON, + do not add any ancestors, even if they also appear in HAVE. + + (s) Send the git-upload-pack response: + + If the server has found a closed set of objects to pack or the + request ends with "done", it replies with the pack. + +TODO: Document the pack based response + S: PACK... + + The returned stream is the side-band-64k protocol supported + by the git-upload-pack service, and the pack is embedded into + stream 1. Progress messages from the server side MAY appear + in stream 2. + + Here a "closed set of objects" is defined to have at least + one path from every WANT to at least one COMMON object. + + If the server needs more information, it replies with a + status continue response: + +TODO: Document the non-pack response + + (c) Parse the upload-pack response: + +TODO: Document parsing response + + Do another compute step. + + +Smart Service git-receive-pack +------------------------------ +This service reads from the repository pointed to by $GIT_URL. + +Clients MUST first perform ref discovery with +'$GIT_URL/info/refs?service=git-receive-pack'. + + C: POST $GIT_URL/git-receive-pack HTTP/1.0 + C: Content-Type: application/x-git-receive-pack-request + C: + C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status + C: 0000 + C: PACK.... + + S: 200 OK + S: Content-Type: application/x-git-receive-pack-result + S: Cache-Control: no-cache + S: + S: .... + +Clients MUST NOT reuse or revalidate a cached reponse. +Servers MUST include sufficient Cache-Control headers +to prevent caching of the response. + +Servers SHOULD support all capabilities defined here. + +Clients MUST send at least one command in the request body. +Within the command portion of the request body clients SHOULD send +the id obtained through ref discovery as old_id. + + update_request = command_list + "PACK" <binary data> + + command_list = PKT-LINE(command NUL cap_list LF) + *(command_pkt) + command_pkt = PKT-LINE(command LF) + cap_list = *(SP capability) SP + + command = create / delete / update + create = zero-id SP new_id SP name + delete = old_id SP zero-id SP name + update = old_id SP new_id SP name + +TODO: Document this further. + + +References +---------- + +link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] +link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] +link:technical/pack-protocol.txt +link:technical/protocol-capabilities.txt diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 0810251f5a..f352a9b22e 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -175,7 +175,7 @@ Git index format A conflict is represented in the index as a set of higher stage entries. When a conflict is resolved (e.g. with "git add path"), these higher - stage entries will be removed and a stage-0 entry with proper resoluton + stage entries will be removed and a stage-0 entry with proper resolution is added. When these higher stage entries are removed, they are saved in the diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index b15517fa06..fd8ffa5df3 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -18,11 +18,12 @@ was sent. Server MUST NOT ignore capabilities that client requested and server advertised. As a consequence of these rules, server MUST NOT advertise capabilities it does not understand. -The 'report-status' and 'delete-refs' capabilities are sent and +The 'report-status', 'delete-refs', and 'quiet' capabilities are sent and recognized by the receive-pack (push to server) process. -The 'ofs-delta' capability is sent and recognized by both upload-pack -and receive-pack protocols. +The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized +by both upload-pack and receive-pack protocols. The 'agent' capability +may optionally be sent in both protocols. All other capabilities are only recognized by the upload-pack (fetch from server) process. @@ -123,6 +124,20 @@ Server can send, and client understand PACKv2 with delta referring to its base by position in pack rather than by an obj-id. That is, they can send/read OBJ_OFS_DELTA (aka type 6) in a packfile. +agent +----- + +The server may optionally send a capability of the form `agent=X` to +notify the client that the server is running version `X`. The client may +optionally return its own agent string by responding with an `agent=Y` +capability (but it MUST NOT do so if the server did not mention the +agent capability). The `X` and `Y` strings may contain any printable +ASCII characters except space (i.e., the byte range 32 < x < 127), and +are typically of the form "package/version" (e.g., "git/1.8.3.1"). The +agent strings are purely informative for statistics and debugging +purposes, and MUST NOT be used to programatically assume the presence +or absence of particular features. + shallow ------- @@ -168,7 +183,7 @@ of whether or not there are tags available. report-status ------------- -The upload-pack process can receive a 'report-status' capability, +The receive-pack process can receive a 'report-status' capability, which tells it that the client wants a report of what happened after a packfile upload and reference update. If the pushing client requests this capability, after unpacking and updating references the server @@ -185,3 +200,20 @@ it is capable of accepting a zero-id value as the target value of a reference update. It is not sent back by the client, it simply informs the client that it can be sent zero-id values to delete references. + +quiet +----- + +If the receive-pack server advertises the 'quiet' capability, it is +capable of silencing human-readable progress output which otherwise may +be shown when processing the received pack. A send-pack client should +respond with the 'quiet' capability to suppress server-side progress +reporting if the local progress reporting is also being suppressed +(e.g., via `push -q`, or if stderr does not go to a tty). + +allow-tip-sha1-in-want +---------------------- + +If the upload-pack server advertises this capability, fetch-pack may +send "want" lines with SHA-1s that exist at the server but are not +advertised by upload-pack. diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index f716d6d97f..242a044db9 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -46,7 +46,7 @@ because in-core timestamps can have finer granularity than on-disk timestamps, resulting in meaningless changes when an inode is evicted from the inode cache. See commit 8ce13b0 of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git -([PATCH] Sync in core time granuality with filesystems, +([PATCH] Sync in core time granularity with filesystems, 2005-01-04). Racy Git diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index e364007d7c..fe723e4722 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -4675,5 +4675,5 @@ Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. More on recovery from repository corruption. See: - http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2 - http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 + http://marc.info/?l=git&m=117263864820799&w=2 + http://marc.info/?l=git&m=117147855503798&w=2 |