diff options
Diffstat (limited to 'Documentation')
34 files changed, 688 insertions, 72 deletions
diff --git a/Documentation/RelNotes/1.8.3.txt b/Documentation/RelNotes/1.8.3.txt new file mode 100644 index 0000000..7799cec --- /dev/null +++ b/Documentation/RelNotes/1.8.3.txt @@ -0,0 +1,387 @@ +Git v1.8.3 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 the current branch to the branch with the same +name, only when the current branch is set to integrate with that +remote branch. There is a 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 it 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", that does not specify what paths +to add on the command line is run from inside a subdirectory, these +commands will operate on the entire tree in Git 2.0 for consistency +with "git commit -a" and other commands. Because there will be no +mechanism to make "git add -u" behave as if "git add -u .", it is +important for those who are used to "git add -u" (without pathspec) +updating the index only for paths in the current subdirectory to start +training their fingers to explicitly say "git add -u ." when they mean +it 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. + + +Updates since v1.8.2 +-------------------- + +UI, Workflows & Features + + * "git branch --vv" learned to paint the name of the branch it + integrates with in a different color (color.branch.upstream, + which defaults to blue). + + * "git count-objects" learned "--human-readable" aka "-H" option to + show various large numbers in Ki/Mi/GiB scaled as necessary. + + * "git cherry-pick $blob" and "git cherry-pick $tree" are nonsense, + and a more readable error message e.g. "can't cherry-pick a tree" + is given (we used to say "expected exactly one commit"). + + * The "--annotate" option to "git send-email" can be turned on (or + off) by default with sendemail.annotate configuration variable (you + can use --no-annotate from the command line to override it). + + * The "--cover-letter" option to "git format-patch" can be turned on + (or off) by default with format.coverLetter configuration + variable. By setting it to 'auto', you can turn it on only for a + series with two or more patches. + + * The bash completion support (in contrib/) learned that cherry-pick + takes a few more options than it already knew about. + + * "git help" learned "-g" option to show the list of guides just like + list of commands are given with "-a". + + * A triangular "pull from one place, push to another place" workflow + is supported better by new remote.pushdefault (overrides the + "origin" thing) and branch.*.pushremote (overrides the + branch.*.remote) configuration variables. + + * "git status" learned to report that you are in the middle of a + revert session, just like it does for a cherry-pick and a bisect + session. + + * The handling by "git branch --set-upstream-to" against various forms + of erroneous inputs was suboptimal and has been improved. + + * When the interactive access to git-shell is not enabled, it issues + a message meant to help the system administrator to enable it. + An explicit way to help the end users who connect to the service by + issuing custom messages to refuse such an access has been added. + + * In addition to the case where the user edits the log message with + the "e)dit" option of "am -i", replace the "Applying: this patch" + message with the final log message contents after applymsg hook + munges it. + + * "git status" suggests users to look into using --untracked=no option + when it takes too long. + + * "git status" shows a bit more information to "git status" during a + rebase/bisect session. + + * "git fetch" learned to fetch a commit at the tip of an unadvertised + ref by specifying a raw object name from the command line when the + server side supports this feature. + + * Output from "git log --graph" works better with submodule log + output now. + + * "git count-objects -v" learned to report leftover temporary + packfiles and other garbage in the object store. + + * A new read-only credential helper (in contrib/) to interact with + the .netrc/.authinfo files has been added. + + * "git send-email" can be used with the credential helper system. + + * There was no Porcelain way to say "I no longer am interested in + this submodule", once you express your interest in a submodule with + "submodule init". "submodule deinit" is the way to do so. + + * "git pull --rebase" learned to pass "-v/-q" options to underlying + "git rebase". + + * The new "--follow-tags" option tells "git push" to push relevant + annotated tags when pushing branches out. + + * "git merge" and "git pull" can optionally be told to inspect and + reject when merging a commit that does not carry a trusted GPG + signature. + + * "git mergetool" now feeds files to the "p4merge" backend in the + order that matches the p4 convention, where "theirs" is usually + shown on the left side, which is the opposite from other backend + expects. + + * "show/log" now honors gpg.program configuration just like other + parts of the code that use GnuPG. + + * "git log" that shows the difference between the parent and the + child has been optimized somewhat. + + * "git difftool" allows the user to write into the temporary files + being shown; if the user makes changes to the working tree at the + same time, one of the changes has to be lost in such a case, but it + tells the user what happened and refrains from overwriting the copy + in the working tree. + + * There was no good way to ask "I have a random string that came from + outside world. I want to turn it into a 40-hex object name while + making sure such an object exists". A new peeling suffix ^{object} + can be used for that purpose, together with "rev-parse --verify". + + +Performance, Internal Implementation, etc. + + * Updates for building under msvc. + + * The stack footprint of some codepaths that access an object from a + pack has been shrunk. + + * The logic to coalesce the same lines removed from the parents in + the output from "diff -c/--cc" has been updated, but with an O(n^2) + complexity, so this might turn out to be undesirable. + + * The code to enforce permission bits on files in $GIT_DIR/ for + shared repositories have been simplified. + + * A few codepaths knew how much data they need to put in the + hashtables they use upfront, but still started from a small table + repeatedly growing and rehashing. + + * The API to walk reflog entries from the latest to older, which was + necessary for operations such as "git checkout -", was cumbersome + to use correctly and also inefficient. + + * Codepaths that inspect log-message-to-be and decide when to add a + new Signed-off-by line in various commands have been consolidated. + + * The pkt-line API, implementation and its callers have been cleaned + up to make them more robust. + + * Cygwin port has a faster-but-lying lstat(2) emulation whose + incorrectness does not matter in practice except for a few + codepaths, and setting permission bits to directories is a codepath + that needs to use a more correct one. + + * "git checkout" had repeated pathspec matches on the same paths, + which have been consolidated. Also a bug in "git checkout dir/" + that is started from an unmerged index has been fixed. + + * A few bugfixes to "git rerere" working on corner case merge + conflicts have been applied. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v1.8.2 +------------------ + +Unless otherwise noted, all the fixes since v1.8.2 in the maintenance +track are contained in this release (see release notes to them for +details). + + * When "upload-pack" fails while generating a pack in response to + "git fetch" (or "git clone"), the receiving side mistakenly said + there was a programming error to trigger the die handler + recursively. + (merge 1ece66b jk/a-thread-only-dies-once later to maint). + + * "rev-list --stdin" and friends kept bogus pointers into input + buffer around as human readble object names. This was not a huge + problem but was exposed by a new change that uses these names in + error output. + (merge 70d26c6 tr/copy-revisions-from-stdin later to maint). + + * Smart-capable HTTP servers were not restricted via the + GIT_NAMESPACE mechanism when talking with commit-walker clients, + like they do when talking with smart HTTP clients. + (merge 6130f86 jk/http-dumb-namespaces later to maint). + + * "git merge-tree" did not omit a merge result that is identical to + "our" side in certain cases. + (merge aacecc3 jk/merge-tree-added-identically later to maint). + + * Perl scripts like "git-svn" closed (not redirecting to /dev/null) + the standard error stream, which is not a very smart thing to do. + Later open may return file descriptor #2 for unrelated purpose, and + error reporting code may write into them. + (merge a749c0b tr/perl-keep-stderr-open later to maint). + + * "git show-branch" was not prepared to show a very long run of + ancestor operators e.g. foobar^2~2^2^2^2...^2~4 correctly. + (merge aaa07e3 jk/show-branch-strbuf later to maint). + + * "git diff --diff-algorithm algo" is also understood as "git diff + --diff-algorithm=algo". + (merge 0895c6d jk/diff-algo-finishing-touches later to maint). + + * The new core.commentchar configuration was not applied to a few + places. + (merge 89c3bbd rt/commentchar-fmt-merge-msg later to maint). + + * "git bundle" did not like a bundle created using a commit without + any message as its one of the prerequistes. + (merge 5446e33 lf/bundle-with-tip-wo-message later to maint). + + * "git log -S/-G" started paying attention to textconv filter, but + there was no way to disable this. Make it honor --no-textconv + option. + (merge 61690bf sr/log-SG-no-textconv later to maint). + + * When used with "-d temporary-directory" option, "git filter-branch" + failed to come back to the original working tree to perform the + final clean-up procedure. + (merge 9727601 jk/filter-branch-come-back-to-original later to maint). + + * "git merge $(git rev-parse v1.8.2)" behaved quite differently from + "git merge v1.8.2", as if v1.8.2 were written as v1.8.2^0 and did + not pay much attention to the annotated tag payload. Make the code + notice the type of the tag object, in addition to the dwim_ref() + based classification the current code uses (i.e. the name appears + in refs/tags/) to decide when to special case merging of tags. + (merge a38d3d7 jc/merge-tag-object later to maint). + + * Fix 1.8.1.x regression that stopped matching "dir" (without + trailing slash) to a directory "dir". + (merge efa5f82 jc/directory-attrs-regression-fix later to maint-1.8.1). + + * "git apply --whitespace=fix" was not prepared to see a line getting + longer after fixing whitespaces (e.g. tab-in-indent aka Python). + (merge 329b26e jc/apply-ws-fix-tab-in-indent later to maint-1.8.1). + + * The prompt string generator (in contrib/completion/) did not notice + when we are in a middle of a "git revert" session. + (merge 3ee4452 rr/prompt-revert-head later to maint). + + * "submodule summary --summary-limit" option did not support + "--option=value" form. + (merge 862ae6c rs/submodule-summary-limit later to maint). + + * "index-pack --fix-thin" used an uninitialized value to compute + delta depths of objects it appends to the resulting pack. + (merge 57165db jk/index-pack-correct-depth-fix later to maint). + + * "index-pack --verify-stat" used a few counters outside protection + of mutex, possibly showing incorrect numbers. + (merge 8f82aad nd/index-pack-threaded-fixes later to maint). + + * The code to keep track of what directory names are known to Git on + platforms with case insensitive filesystems can get confused upon a + hash collision between these pathnames and looped forever. + + * Annotated tags outside refs/tags/ hierarchy were not advertised + correctly to the ls-remote and fetch with recent version of Git. + + * Recent optimization broke shallow clones. + (merge f59de5d jk/peel-ref later to maint). + + * "git cmd -- ':(top'" was not diagnosed as an invalid syntax, and + instead the parser kept reading beyond the end of the string. + + * "git tag -f <tag>" always said "Updated tag '<tag>'" even when + creating a new tag (i.e. not overwriting nor updating). + + * "git p4" did not behave well when the path to the root of the P4 + client was not its real path. + (merge bbd8486 pw/p4-symlinked-root later to maint). + + * "git archive" reports a failure when asked to create an archive out + of an empty tree. It would be more intuitive to give an empty + archive back in such a case. + + * When "format-patch" quoted a non-ascii strings on the header files, + it incorrectly applied rfc2047 and chopped a single character in + the middle of it. + + * An aliased command spawned from a bare repository that does not say + it is bare with "core.bare = yes" is treated as non-bare by mistake. + + * In "git reflog expire", REACHABLE bit was not cleared from the + correct objects. + + * The logic used by "git diff -M --stat" to shorten the names of + files before and after a rename did not work correctly when the + common prefix and suffix between the two filenames overlapped. + + * The "--match=<pattern>" option of "git describe", when used with + "--all" to allow refs that are not annotated tags to be used as a + base of description, did not restrict the output from the command + to those that match the given pattern. + + * Clarify in the documentation "what" gets pushed to "where" when the + command line to "git push" does not say these explicitly. + + * The "--color=<when>" argument to the commands in the diff family + was described poorly. + + * The arguments given to pre-rebase hook were not documented. + + * The v4 index format was not documented. + + * The "--match=<pattern>" argument "git describe" takes uses glob + pattern but it wasn't obvious from the documentation. + + * Some sources failed to compile on systems that lack NI_MAXHOST in + their system header (e.g. z/OS). + + * Add an example use of "--env-filter" in "filter-branch" + documentation. + + * "git bundle verify" did not say "records a complete history" for a + bundle that does not have any prerequisites. + + * In the v1.8.0 era, we changed symbols that do not have to be global + to file scope static, but a few functions in graph.c were used by + CGit from sideways bypassing the entry points of the API the + in-tree users use. + + * "git update-index -h" did not do the usual "-h(elp)" thing. + + * "git index-pack" had a buffer-overflow while preparing an + informational message when the translated version of it was too + long. + + * 'git commit -m "$msg"' used to add an extra newline even when + $msg already ended with one. + + * The SSL peer verification done by "git imap-send" did not ask for + Server Name Indication (RFC 4366), failing to connect SSL/TLS + sites that serve multiple hostnames on a single IP. + + * perl/Git.pm::cat_blob slurped everything in core only to write it + out to a file descriptor, which was not a very smart thing to do. + + * "git branch" did not bother to check nonsense command line + parameters and issue errors in many cases. + + * Verification of signed tags were not done correctly when not in C + or en/US locale. + + * Some platforms and users spell UTF-8 differently; retry with the + most official "UTF-8" when the system does not understand the + user-supplied encoding name that are the common alternative + spellings of UTF-8. + + * When export-subst is used, "zip" output recorded incorrect + size of the file. + + * "git am $maildir/" applied messages in an unexpected order; sort + filenames read from the maildir/ in a way that is more likely to + sort messages in the order the writing MUA meant to, by sorting + numeric segment in numeric order and non-numeric segment in + alphabetical order. + + * "git submodule update", when recursed into sub-submodules, did not + accumulate the prefix paths. diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl index 828ec62..87437f8 100755 --- a/Documentation/cat-texi.perl +++ b/Documentation/cat-texi.perl @@ -12,6 +12,7 @@ while (<STDIN>) { push @menu, $1; } s/\(\@pxref{\[(URLS|REMOTES)\]}\)//; + s/\@anchor\{[^{}]*\}//g; print TMP; } close TMP; diff --git a/Documentation/config.txt b/Documentation/config.txt index bc750d5..29559c8 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -727,9 +727,22 @@ branch.autosetuprebase:: This option defaults to never. branch.<name>.remote:: - When in branch <name>, it tells 'git fetch' and 'git push' which - remote to fetch from/push to. It defaults to `origin` if no remote is - configured. `origin` is also used if you are not on any branch. + When on branch <name>, it tells 'git fetch' and 'git push' + which remote to fetch from/push to. The remote to push to + may be overridden with `remote.pushdefault` (for all branches). + The remote to push to, for the current branch, may be further + overridden by `branch.<name>.pushremote`. If no remote is + configured, or if you are not on any branch, it defaults to + `origin` for fetching and `remote.pushdefault` for pushing. + +branch.<name>.pushremote:: + When on branch <name>, it overrides `branch.<name>.remote` for + pushing. It also overrides `remote.pushdefault` for pushing + from branch <name>. When you pull from one place (e.g. your + upstream) and push to another place (e.g. your own publishing + repository), you would want to set `remote.pushdefault` to + specify the remote to push to for all branches, and use this + option to override it for a specific branch. branch.<name>.merge:: Defines, together with branch.<name>.remote, the upstream branch @@ -794,7 +807,8 @@ color.branch:: color.branch.<slot>:: Use customized color for branch coloration. `<slot>` is one of `current` (the current branch), `local` (a local branch), - `remote` (a remote-tracking branch in refs/remotes/), `plain` (other + `remote` (a remote-tracking branch in refs/remotes/), + `upstream` (upstream tracking branch), `plain` (other refs). + The value for these configuration variables is a list of colors (at most @@ -1096,6 +1110,11 @@ format.signoff:: the rights to submit this work under the same open source license. Please see the 'SubmittingPatches' document for further discussion. +format.coverLetter:: + A boolean that controls whether to generate a cover-letter when + format-patch is invoked, but in addition can be set to "auto", to + generate a cover-letter only when there's more than one patch. + filter.<driver>.clean:: The command which is used to convert the content of a worktree file to a blob upon checkin. See linkgit:gitattributes[5] for @@ -1447,6 +1466,14 @@ http.sslCAPath:: with when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_CAPATH' environment variable. +http.sslTry:: + Attempt to use AUTH SSL/TLS and encrypted data transfers + when connecting via regular FTP protocol. This might be needed + if the FTP server requires it for security reasons or you wish + to connect securely whenever remote FTP server supports it. + Default is false since it might trigger certificate verification + errors on misconfigured servers. + http.maxRequests:: How many HTTP requests to launch in parallel. Can be overridden by the 'GIT_HTTP_MAX_REQUESTS' environment variable. Default is 5. @@ -1898,6 +1925,11 @@ receive.updateserverinfo:: If set to true, git-receive-pack will run git-update-server-info after receiving data from git-push and updating refs. +remote.pushdefault:: + The remote to push to by default. Overrides + `branch.<name>.remote` for all branches, and is overridden by + `branch.<name>.pushremote` for specific branches. + remote.<name>.url:: The URL of a remote repository. See linkgit:git-fetch[1] or linkgit:git-push[1]. @@ -1998,6 +2030,7 @@ sendemail.<identity>.*:: sendemail.aliasesfile:: sendemail.aliasfiletype:: +sendemail.annotate:: sendemail.bcc:: sendemail.cc:: sendemail.cccmd:: @@ -2123,7 +2156,13 @@ uploadpack.hiderefs:: are under the hierarchies listed on the value of this variable is excluded, and is hidden from `git ls-remote`, `git fetch`, etc. An attempt to fetch a hidden ref by `git - fetch` will fail. + fetch` will fail. See also `uploadpack.allowtipsha1inwant`. + +uploadpack.allowtipsha1inwant:: + When `uploadpack.hiderefs` is in effect, allow `upload-pack` + to accept a fetch request that asks for an object at the tip + of a hidden ref (by default, such a request is rejected). + see also `uploadpack.hiderefs`. url.<base>.insteadOf:: Any URL that starts with this value will be rewritten to diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index b4c2e24..250e522 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -56,7 +56,8 @@ OPTIONS Write the archive to <file> instead of stdout. --worktree-attributes:: - Look for attributes in .gitattributes in working directory too. + Look for attributes in .gitattributes files in the working tree + as well (see <<ATTRIBUTES>>). <extra>:: This can be any options that the archiver backend understands. @@ -120,6 +121,7 @@ tar.<format>.remote:: user-defined formats, but true for the "tar.gz" and "tgz" formats. +[[ATTRIBUTES]] ATTRIBUTES ---------- diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 86ef56e..cafdc96 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -10,7 +10,9 @@ SYNOPSIS -------- [verse] 'git commit-tree' <tree> [(-p <parent>)...] < changelog -'git commit-tree' [(-p <parent>)...] [(-m <message>)...] [(-F <file>)...] <tree> +'git commit-tree' [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] + [(-F <file>)...] <tree> + DESCRIPTION ----------- @@ -52,6 +54,9 @@ OPTIONS Read the commit log message from the given file. Use `-` to read from the standard input. +-S[<keyid>]:: + GPG-sign commit. + Commit Information ------------------ diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 05f8297..9b1be55 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -207,14 +207,15 @@ variable (see linkgit:git-config[1]). without changing its commit message. --amend:: - Used to amend the tip of the current branch. Prepare the tree - object you would want to replace the latest commit as usual - (this includes the usual -i/-o and explicit paths), and the - commit log editor is seeded with the commit message from the - tip of the current branch. The commit you create replaces the - current tip -- if it was a merge, it will have the parents of - the current tip as parents -- so the current top commit is - discarded. + Replace the tip of the current branch by creating a new + commit. The recorded tree is prepared as usual (including + the effect of the `-i` and `-o` options and explicit + pathspec), and the message from the original commit is used + as the starting point, instead of an empty message, when no + other message is specified from the command line via options + such as `-m`, `-F`, `-c`, etc. The new commit has the same + parents and author as the current one (the `--reset-author` + option can countermand this). + -- It is a rough equivalent for: diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 23c80ce..b300e84 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -8,7 +8,7 @@ git-count-objects - Count unpacked number of objects and their disk consumption SYNOPSIS -------- [verse] -'git count-objects' [-v] +'git count-objects' [-v] [-H | --human-readable] DESCRIPTION ----------- @@ -20,11 +20,29 @@ OPTIONS ------- -v:: --verbose:: - In addition to the number of loose objects and disk - space consumed, it reports the number of in-pack - objects, number of packs, disk space consumed by those packs, - and number of objects that can be removed by running - `git prune-packed`. + Report in more detail: ++ +count: the number of loose objects ++ +size: disk space consumed by loose objects, in KiB (unless -H is specified) ++ +in-pack: the number of in-pack objects ++ +size-pack: disk space consumed by the packs, in KiB (unless -H is specified) ++ +prune-packable: the number of loose objects that are also present in +the packs. These objects could be pruned using `git prune-packed`. ++ +garbage: the number of files in object database that are not valid +loose objects nor valid packs ++ +size-garbage: disk space consumed by garbage files, in KiB (unless -H is +specified) + +-H:: +--human-readable:: + +Print sizes in human readable format GIT --- diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 472f00f..7da0f13 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -56,7 +56,7 @@ For example, if we want a password for `https://example.com/foo.git`, we might generate the following credential description (don't forget the blank line at the end; it tells `git credential` that the application finished feeding all the -infomation it has): +information it has): protocol=https host=example.com diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 77da564..bfb106c 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -147,6 +147,13 @@ OPTIONS Giving these options is an error when used with `--inetd`; use the facility of inet daemon to achieve the same before spawning 'git daemon' if needed. ++ +Like many programs that switch user id, the daemon does not reset +environment variables such as `$HOME` when it runs git programs, +e.g. `upload-pack` and `receive-pack`. When using this option, you +may also want to set and export `HOME` to point at the home +directory of `<user>` before starting the daemon, and make sure any +Git configuration files in that directory are readable by `<user>`. --enable=<service>:: --disable=<service>:: diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index e0e12e9..8361e6e 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -72,10 +72,12 @@ with custom merge tool commands and has the same value as `$MERGED`. --symlinks:: --no-symlinks:: 'git difftool''s default behavior is create symlinks to the - working tree when run in `--dir-diff` mode. + working tree when run in `--dir-diff` mode and the right-hand + side of the comparison yields the same content as the file in + the working tree. + - Specifying `--no-symlinks` instructs 'git difftool' to create - copies instead. `--no-symlinks` is the default on Windows. +Specifying `--no-symlinks` instructs 'git difftool' to create copies +instead. `--no-symlinks` is the default on Windows. -x <command>:: --extcmd=<command>:: diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index d6487e1..feab7a3 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -66,6 +66,8 @@ produced incorrect results if you gave these options. incremental runs. As <file> is only opened and truncated at completion, the same path can also be safely given to \--import-marks. + The file will not be written if no new object has been + marked/exported. --import-marks=<file>:: Before processing any input, load the marks specified in diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 3a62f50..3911877 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -20,7 +20,7 @@ SYNOPSIS [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] - [--cover-letter] [--quiet] [--notes[=<ref>]] + [--[no-]cover-letter] [--quiet] [--notes[=<ref>]] [<common diff options>] [ <since> | <revision range> ] @@ -195,7 +195,7 @@ will want to ensure that threading is disabled for `git send-email`. `Cc:`, and custom) headers added so far from config or command line. ---cover-letter:: +--[no-]cover-letter:: In addition to the patches, generate a cover letter file containing the shortlog and the overall diffstat. You can fill in a description in the file before sending it out. @@ -260,6 +260,7 @@ attachments, and sign off patches with configuration variables. cc = <email> attach [ = mime-boundary-string ] signoff = true + coverletter = auto ------------ diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index e07b6dc..b21e9d7 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -8,31 +8,45 @@ git-help - Display help information about Git SYNOPSIS -------- [verse] -'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND] +'git help' [-a|--all] [-g|--guide] + [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE] DESCRIPTION ----------- -With no options and no COMMAND given, the synopsis of the 'git' +With no options and no COMMAND or GUIDE given, the synopsis of the 'git' command and a list of the most commonly used Git commands are printed on the standard output. -If the option '--all' or '-a' is given, then all available commands are +If the option '--all' or '-a' is given, all available commands are printed on the standard output. -If a Git subcommand is named, a manual page for that subcommand is brought -up. The 'man' program is used by default for this purpose, but this -can be overridden by other options or configuration variables. +If the option '--guide' or '-g' is given, a list of the useful +Git guides is also printed on the standard output. + +If a command, or a guide, is given, a manual page for that command or +guide is brought up. The 'man' program is used by default for this +purpose, but this can be overridden by other options or configuration +variables. Note that `git --help ...` is identical to `git help ...` because the former is internally converted into the latter. +To display the linkgit:git[1] man page, use `git help git`. + +This page can be displayed with 'git help help' or `git help --help` + OPTIONS ------- -a:: --all:: Prints all the available commands on the standard output. This - option supersedes any other option. + option overrides any given command or guide name. + +-g:: +--guides:: + Prints a list of useful guides on the standard output. This + option overrides any given command or guide name. -i:: --info:: diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 577d201..eb2883c 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -9,7 +9,7 @@ git-push - Update remote refs along with associated objects SYNOPSIS -------- [verse] -'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] +'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] [<repository> [<refspec>...]] @@ -117,6 +117,12 @@ already exists on the remote side. addition to refspecs explicitly listed on the command line. +--follow-tags:: + Push all the refs that would be pushed without this option, + and also push annotated tags in `refs/tags` that are missing + from the remote but are pointing at committish that are + reachable from the refs being pushed. + --receive-pack=<git-receive-pack>:: --exec=<git-receive-pack>:: Path to the 'git-receive-pack' program on the remote diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 58b7fac..8cfc748 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -86,7 +86,7 @@ begins with `ext::`. Examples: edit .ssh/config. "ext::socat -t3600 - ABSTRACT-CONNECT:/git-server %G/somerepo":: - Represents repository with path /somerepo accessable over + Represents repository with path /somerepo accessible over git protocol at abstract namespace address /git-server. "ext::git-server-alias foo %G/repo":: diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 10a116f..1f9ed6c 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -60,8 +60,19 @@ OPTIONS instead. --verify:: - The parameter given must be usable as a single, valid - object name. Otherwise barf and abort. + Verify that exactly one parameter is provided, and that it + can be turned into a raw 20-byte SHA-1 that can be used to + access the object database. If so, emit it to the standard + output; otherwise, error out. ++ +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. +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` +names an existing object of any type, `git rev-parse "$VAR^{object}"` +can be used. -q:: --quiet:: @@ -308,12 +319,12 @@ $ git rev-parse --verify HEAD * Print the commit object name from the revision in the $REV shell variable: + ------------ -$ git rev-parse --verify $REV +$ git rev-parse --verify $REV^{commit} ------------ + This will error out if $REV is empty or not a valid revision. -* Same as above: +* Similar to above: + ------------ $ git rev-parse --default master --verify $REV diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 92bac27..1d876c2 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -149,6 +149,10 @@ files that aren't ignored are present in the submodules work tree. Ignored files are deemed expendable and won't stop a submodule's work tree from being removed. +If you only want to remove the local checkout of a submodule from your +work tree without committing the removal, +use linkgit:git-submodule[1] `deinit` instead. + EXAMPLES -------- `git rm Documentation/\*.txt`:: diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 44a1f7c..40a9a9a 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -45,8 +45,9 @@ Composing ~~~~~~~~~ --annotate:: - Review and edit each patch you're about to send. See the - CONFIGURATION section for 'sendemail.multiedit'. + Review and edit each patch you're about to send. Default is the value + of 'sendemail.annotate'. See the CONFIGURATION section for + 'sendemail.multiedit'. --bcc=<address>:: Specify a "Bcc:" value for each email. Default is the value of @@ -164,8 +165,8 @@ Sending Furthermore, passwords need not be specified in configuration files or on the command line. If a username has been specified (with '--smtp-user' or a 'sendemail.smtpuser'), but no password has been -specified (with '--smtp-pass' or 'sendemail.smtppass'), then the -user is prompted for a password while the input is masked for privacy. +specified (with '--smtp-pass' or 'sendemail.smtppass'), then +a password is obtained using 'git-credential'. --smtp-server=<host>:: If set, specifies the outgoing SMTP server to use (e.g. diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 6a9f66d..5d709d0 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -82,6 +82,12 @@ get_author_ident_from_commit:: outputs code for use with eval to set the GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit. +create_virtual_base:: + modifies the first file so only lines in common with the + second file remain. If there is insufficient common material, + then the first file is left empty. The result is suitable + as a virtual base input for a 3-way merge. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 9b92506..c35051b 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -9,25 +9,81 @@ git-shell - Restricted login shell for Git-only SSH access SYNOPSIS -------- [verse] -'git shell' [-c <command> <argument>] +'chsh' -s $(command -v git-shell) <user> +'git clone' <user>`@localhost:/path/to/repo.git` +'ssh' <user>`@localhost` DESCRIPTION ----------- -A login shell for SSH accounts to provide restricted Git access. When -'-c' is given, the program executes <command> non-interactively; -<command> can be one of 'git receive-pack', 'git upload-pack', 'git -upload-archive', 'cvs server', or a command in COMMAND_DIR. The shell -is started in interactive mode when no arguments are given; in this -case, COMMAND_DIR must exist, and any of the executables in it can be -invoked. +This is a login shell for SSH accounts to provide restricted Git access. +It permits execution only of server-side Git commands implementing the +pull/push functionality, plus custom commands present in a subdirectory +named `git-shell-commands` in the user's home directory. -'cvs server' is a special command which executes git-cvsserver. +COMMANDS +-------- + +'git shell' accepts the following commands after the '-c' option: + +'git receive-pack <argument>':: +'git upload-pack <argument>':: +'git upload-archive <argument>':: + Call the corresponding server-side command to support + the client's 'git push', 'git fetch', or 'git archive --remote' + request. +'cvs server':: + Imitate a CVS server. See linkgit:git-cvsserver[1]. + +If a `~/git-shell-commands` directory is present, 'git shell' will +also handle other, custom commands by running +"`git-shell-commands/<command> <arguments>`" from the user's home +directory. + +INTERACTIVE USE +--------------- + +By default, the commands above can be executed only with the '-c' +option; the shell is not interactive. -COMMAND_DIR is the path "$HOME/git-shell-commands". The user must have -read and execute permissions to the directory in order to execute the -programs in it. The programs are executed with a cwd of $HOME, and -<argument> is parsed as a command-line string. +If a `~/git-shell-commands` directory is present, 'git shell' +can also be run interactively (with no arguments). If a `help` +command is present in the `git-shell-commands` directory, it is +run to provide the user with an overview of allowed actions. Then a +"git> " prompt is presented at which one can enter any of the +commands from the `git-shell-commands` directory, or `exit` to close +the connection. + +Generally this mode is used as an administrative interface to allow +users to list repositories they have access to, create, delete, or +rename repositories, or change repository descriptions and +permissions. + +If a `no-interactive-login` command exists, then it is run and the +interactive shell is aborted. + +EXAMPLE +------- + +To disable interactive logins, displaying a greeting instead: ++ +---------------- +$ chsh -s /usr/bin/git-shell +$ mkdir $HOME/git-shell-commands +$ cat >$HOME/git-shell-commands/no-interactive-login <<\EOF +#!/bin/sh +printf '%s\n' "Hi $USER! You've successfully authenticated, but I do not" +printf '%s\n' "provide interactive shell access." +exit 128 +EOF +$ chmod +x $HOME/git-shell-commands/no-interactive-login +---------------- + +SEE ALSO +-------- +ssh(1), +linkgit:git-daemon[1], +contrib/git-shell-commands/README GIT --- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index c99d795..74d5bdc 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -13,6 +13,7 @@ SYNOPSIS [--reference <repository>] [--] <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>] [--merge] [--recursive] [--] [<path>...] @@ -135,6 +136,19 @@ init:: the explicit 'init' step if you do not intend to customize any submodule locations. +deinit:: + Unregister the given submodules, i.e. remove the whole + `submodule.$name` section from .git/config together with their work + tree. Further calls to `git submodule update`, `git submodule foreach` + and `git submodule sync` will skip any unregistered submodules until + they are initialized again, so use this command if you don't want to + have a local checkout of the submodule in your work tree anymore. If + you really want to remove a submodule from the repository and commit + that use linkgit:git-rm[1] instead. ++ +If `--force` is specified, the submodule's work tree will be removed even if +it contains local modifications. + update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. @@ -214,8 +228,10 @@ OPTIONS -f:: --force:: - This option is only valid for add and update commands. + This option is only valid for add, deinit and update commands. When running add, allow adding an otherwise ignored submodule path. + When running deinit the submodule work trees will be removed even if + they contain local changes. When running update, throw away local changes in submodules when switching to a different commit; and always run a checkout operation in the submodule, even if the commit listed in the index of the diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 1b8b649..7706d41 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -245,7 +245,7 @@ first have already been pushed into SVN. patch), "all" (accept all patches), or "quit". + 'git svn dcommit' returns immediately if answer if "no" or "quit", without - commiting anything to SVN. + committing anything to SVN. 'branch':: Create a branch in the SVN repository. @@ -856,7 +856,7 @@ HANDLING OF SVN BRANCHES ------------------------ If 'git svn' is configured to fetch branches (and --follow-branches is in effect), it sometimes creates multiple Git branches for one -SVN branch, where the addtional branches have names of the form +SVN branch, where the additional branches have names of the form 'branchname@nnn' (with nnn an SVN revision number). These additional branches are created if 'git svn' cannot find a parent commit for the first commit in an SVN branch, to connect the branch to the history of diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt index ad8b823..78a0d95 100644 --- a/Documentation/git-tools.txt +++ b/Documentation/git-tools.txt @@ -109,7 +109,7 @@ Others - *git.el* (contrib/) - This is an Emacs interface for Git. The user interface is modeled on + This is an Emacs interface for Git. The user interface is modelled on pcl-cvs. It has been developed on Emacs 21 and will probably need some tweaking to work on XEmacs. diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 0c91aba..f506031 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -174,8 +174,8 @@ ref. This capability can be advertised multiple times. The first applicable refspec takes precedence. The left-hand of refspecs advertised with this capability must cover all refs reported by -the list command. If no 'refspec' capability is advertised, -there is an implied `refspec *:*`. +the list command. If a helper does not need a specific 'refspec' +capability then it should advertise `refspec *:*`. 'bidi-import':: This modifies the 'import' capability. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index eb7ba84..2478a39 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -100,9 +100,22 @@ to point at the new commit. [[def_detached_HEAD]]detached HEAD:: Normally the <<def_HEAD,HEAD>> stores the name of a - <<def_branch,branch>>. However, Git also allows you to <<def_checkout,check out>> - an arbitrary <<def_commit,commit>> that isn't necessarily the tip of any - particular branch. In this case HEAD is said to be "detached". + <<def_branch,branch>>, and commands that operate on the + history HEAD represents operate on the history leading to the + tip of the branch the HEAD points at. However, Git also + allows you to <<def_checkout,check out>> an arbitrary + <<def_commit,commit>> that isn't necessarily the tip of any + particular branch. The HEAD in such a state is called + "detached". ++ +Note that commands that operate on the history of the current branch +(e.g. `git commit` to build a new history on top of it) still work +while the HEAD is detached. They update the HEAD to point at the tip +of the updated history without affecting any branch. Commands that +update or inquire information _about_ the current branch (e.g. `git +branch --set-upstream-to` that sets what remote tracking branch the +current branch integrates with) obviously do not work, as there is no +(real) current branch to ask about in this state. [[def_dircache]]dircache:: You are *waaaaay* behind. See <<def_index,index>>. diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 34a8445..2adccf8 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -84,6 +84,11 @@ option can be used to override --squash. Pass merge strategy specific option through to the merge strategy. +--verify-signatures:: +--no-verify-signatures:: + Verify that the commits being merged have good and trusted GPG signatures + and abort the merge in case they do not. + --summary:: --no-summary:: Synonyms to --stat and --no-stat; these are deprecated and will be diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 66db802..49a9a7d 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -48,6 +48,12 @@ patience;; this when the branches to be merged have diverged wildly. See also linkgit:git-diff[1] `--patience`. +diff-algorithm=[patience|minimal|histogram|myers];; + Tells 'merge-recursive' to use a different diff algorithm, which + can help avoid mismerges that occur due to unimportant matching + lines (such as braces from distinct functions). See also + linkgit:git-diff[1] `--diff-algorithm`. + ignore-space-change;; ignore-all-space;; ignore-space-at-eol;; diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 2939655..afac703 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -131,7 +131,8 @@ The placeholders are: - '%B': raw body (unwrapped subject and body) - '%N': commit notes - '%GG': raw verification message from GPG for a signed commit -- '%G?': show either "G" for Good or "B" for Bad for a signed commit +- '%G?': show "G" for a Good signature, "B" for a Bad signature, "U" for a good, + untrusted signature and "N" for no signature - '%GS': show the name of the signer for a signed commit - '%GK': show the key used to sign a signed commit - '%gD': reflog selector, e.g., `refs/stash@{1}` diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 314e25d..8855b1a 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -55,7 +55,7 @@ when you run `git cherry-pick`. + Note that any of the 'refs/*' cases above may come either from the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. -While the ref name encoding is unspecified, UTF-8 is prefered as +While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. '<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: @@ -116,6 +116,11 @@ some output processing may assume ref names in UTF-8. object of that type is found or the object cannot be dereferenced anymore (in which case, barf). '<rev>{caret}0' is a short-hand for '<rev>{caret}\{commit\}'. ++ +'rev{caret}\{object\}' can be used to make sure 'rev' names an +object that exists, without requiring 'rev' to be a tag, and +without dereferencing 'rev'; because a tag is already an object, +it does not have to be dereferenced even once to get to an object. '<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}':: A suffix '{caret}' followed by an empty brace pair diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index a959517..a6b7d83 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -55,7 +55,7 @@ Functions initial, empty state. `argv_array_detach`:: - Detach the argv array from the `struct argv_array`, transfering + Detach the argv array from the `struct argv_array`, transferring ownership of the allocated array and strings. `argv_array_free_detached`:: diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 516fda7..c1b42a4 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -160,7 +160,7 @@ int foo_login(struct foo_connection *f) break; default: /* - * Some other error occured. We don't know if the + * Some other error occurred. We don't know if the * credential is good or bad, so report nothing to the * credential subsystem. */ diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt index dbbea95..aa1c50f 100644 --- a/Documentation/technical/api-ref-iteration.txt +++ b/Documentation/technical/api-ref-iteration.txt @@ -35,7 +35,7 @@ Iteration functions * `head_ref_submodule()`, `for_each_ref_submodule()`, `for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`, `for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()` - do the same as the functions descibed above but for a specified + do the same as the functions described above but for a specified submodule. * `for_each_rawref()` can be used to learn about broken ref and symref. diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index 2c59cb2..3350d97 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -230,6 +230,11 @@ which can be used by the programmer of the callback as she sees fit. destination. This is useful for literal data to be fed to either strbuf_expand or to the *printf family of functions. +`strbuf_humanise_bytes`:: + + Append the given byte size as a human-readable string (i.e. 12.23 KiB, + 3.50 MiB). + `strbuf_addf`:: Add a formatted string to the buffer. diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index 0e37ec9..a37f137 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -26,7 +26,9 @@ Git pack format (deltified representation) n-byte type and length (3-bit type, (n-1)*7+4-bit length) - 20-byte base object name + 20-byte base object name if OBJ_REF_DELTA or a negative relative + offset from the delta object's position in the pack if this + is an OBJ_OFS_DELTA object compressed delta data Observation: length of each object is encoded in a variable |