diff options
Diffstat (limited to 'Documentation')
74 files changed, 1360 insertions, 406 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b1bfff6..7e4d571 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -237,6 +237,9 @@ For Python scripts: Writing Documentation: + Most (if not all) of the documentation pages are written in AsciiDoc + and processed into HTML output and manpages. + 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.8.1.6.txt b/Documentation/RelNotes/1.8.1.6.txt new file mode 100644 index 0000000..c15cf2e --- /dev/null +++ b/Documentation/RelNotes/1.8.1.6.txt @@ -0,0 +1,39 @@ +Git 1.8.1.6 Release Notes +========================= + +Fixes since v1.8.1.5 +-------------------- + + * An earlier change to the attribute system introduced at v1.8.1.2 by + mistake stopped a pattern "dir" (without trailing slash) from + matching a directory "dir" (it only wanted to allow pattern "dir/" + to also match). + + * 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. + + * When the "--prefix" option is used to "checkout-index", the code + did not pick the correct output filter based on the attribute + setting. + + * Annotated tags outside refs/tags/ hierarchy were not advertised + correctly to the ls-remote and fetch with recent version of Git. + + * 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. + + * "git update-index -h" did not do the usual "-h(elp)" thing. + + * 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. + + * 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. + + * "git bundle verify" did not say "records a complete history" for a + bundle that does not have any prerequisites. + +Also contains various documentation fixes. diff --git a/Documentation/RelNotes/1.8.2.1.txt b/Documentation/RelNotes/1.8.2.1.txt new file mode 100644 index 0000000..1354ad0 --- /dev/null +++ b/Documentation/RelNotes/1.8.2.1.txt @@ -0,0 +1,115 @@ +Git v1.8.2.1 Release Notes +========================== + +Fixes since v1.8.2 +------------------ + + * An earlier change to the attribute system introduced at v1.8.1.2 by + mistake stopped a pattern "dir" (without trailing slash) from + matching a directory "dir" (it only wanted to allow pattern "dir/" + to also match). + + * Verification of signed tags were not done correctly when not in C + or en/US locale. + + * 'git commit -m "$msg"' used to add an extra newline even when + $msg already ended with one. + + * 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. + + * 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. + + * 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. + + * "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. + + * "git tag -f <tag>" always said "Updated tag '<tag>'" even when + creating a new tag (i.e. not overwriting nor updating). + + * "git cmd -- ':(top'" was not diagnosed as an invalid syntax, and + instead the parser kept reading beyond the end of the string. + + * Annotated tags outside refs/tags/ hierarchy were not advertised + correctly to the ls-remote and fetch with recent version of Git. + + * 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. + + * 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. + + * "git submodule update", when recursed into sub-submodules, did not + acccumulate 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 + sort messages in the order the writing MUA meant to, by sorting + numeric segment in numeric order and non-numeric segment in + alphabetical order. + + * When export-subst is used, "zip" output recorded incorrect + size of the file. + + * 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. + + * "git branch" did not bother to check nonsense command line + parameters and issue errors in many cases. + + * "git update-index -h" did not do the usual "-h(elp)" thing. + + * 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. + + * 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. + + * "git index-pack" had a buffer-overflow while preparing an + informational message when the translated version of it was too + long. + + * Clarify in the documentation "what" gets pushed to "where" when the + command line to "git push" does not say these explicitly. + + * In "git reflog expire", REACHABLE bit was not cleared from the + correct objects. + + * 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 merge-tree" had a typo in the logic to detect d/f conflicts, + which caused it to segfault in some cases. diff --git a/Documentation/RelNotes/1.8.2.txt b/Documentation/RelNotes/1.8.2.txt index 78c6577..fc606ae 100644 --- a/Documentation/RelNotes/1.8.2.txt +++ b/Documentation/RelNotes/1.8.2.txt @@ -1,19 +1,8 @@ Git v1.8.2 Release Notes ======================== -Backward compatibility notes ----------------------------- - -In the next major release Git 2.0 (not *this* one), we will change the -behavior of the "git push" command. - -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). We will use 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. +Backward compatibility notes (this release) +------------------------------------------- "git push $there tag v1.2.3" used to allow replacing a tag v1.2.3 that already exists in the repository $there, if the rewritten tag @@ -22,22 +11,41 @@ that the old tag v1.2.3 points at. This was found to be error prone and starting with this release, any attempt to update an existing ref under refs/tags/ hierarchy will fail, without "--force". -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, the +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, the scope of the operation has always been limited to the subdirectory. Many users found this counter-intuitive, given that "git commit -a" and other commands operate on the entire tree regardless of where you -are. In this release, these commands give warning in such a case and -encourage the user to say "git add -u/-A ." instead when restricting -the scope to the current directory. - -At Git 2.0 (not *this* one), we plan to change these commands without -pathspec to operate on the entire tree. Forming a habit to type "." -when you mean to limit the command to the current working directory -will protect you against the planned future change, and that is the -whole point of the new message (there will be no configuration -variable to squelch this warning---it goes against the "habit forming" -objective). +are. In this release, these commands give a warning message that +suggests the users to use "git add -u/-A ." when they want to limit +the scope to the current directory; doing so will squelch the message, +while training their fingers. + + +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. Updates since v1.8.1 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 bbba728..c67038b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -178,6 +178,10 @@ advice.*:: the template shown when writing commit messages in linkgit:git-commit[1], and in the help message shown by linkgit:git-checkout[1] when switching branch. + statusUoption:: + Advise to consider using the `-u` option to linkgit:git-status[1] + when the command takes more than 2 seconds to enumerate untracked + files. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to merge to avoid overwriting local changes. @@ -408,7 +412,7 @@ repository's usual working tree). core.logAllRefUpdates:: Enable the reflog. Updates to a ref <ref> is logged to the file "$GIT_DIR/logs/<ref>", by appending the new and old - SHA1, the date/time and the reason of the update, but + SHA-1, the date/time and the reason of the update, but only when the file exists. If this configuration variable is set to true, missing "$GIT_DIR/logs/<ref>" file is automatically created for branch heads (i.e. under @@ -443,7 +447,7 @@ core.sharedRepository:: core.warnAmbiguousRefs:: If true, Git will warn you if the ref name you passed it is ambiguous - and might match multiple refs in the .git/refs/ tree. True by default. + and might match multiple refs in the repository. True by default. core.compression:: An integer -1..9, indicating a default compression level. @@ -551,7 +555,7 @@ core.commentchar:: (default '#'). sequence.editor:: - Text editor used by `git rebase -i` for editing the rebase insn file. + Text editor used by `git rebase -i` for editing the rebase instruction file. The value is meant to be interpreted by the shell when it is used. It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable. When not configured the default commit message editor is used instead. @@ -723,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 @@ -790,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 @@ -1092,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 @@ -1443,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. @@ -1894,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]. @@ -1994,6 +2030,7 @@ sendemail.<identity>.*:: sendemail.aliasesfile:: sendemail.aliasfiletype:: +sendemail.annotate:: sendemail.bcc:: sendemail.cc:: sendemail.cccmd:: @@ -2119,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/diff-options.txt b/Documentation/diff-options.txt index 869d965..104579d 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -195,8 +195,8 @@ any of those replacements occurred. --color[=<when>]:: Show colored diff. - The value must be `always` (the default for `<when>`), `never`, or `auto`. - The default value is `never`. + `--color` (i.e. without '=<when>') is the same as `--color=always`. + '<when>' can be one of `always`, `never`, or `auto`. ifdef::git-diff[] It can be changed by the `color.ui` and `color.diff` configuration settings. 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-cat-file.txt b/Documentation/git-cat-file.txt index 2fb95bb..30d585a 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -20,7 +20,7 @@ object type, or '-s' is used to find the object size, or '--textconv' is used (which implies type "blob"). In the second form, a list of objects (separated by linefeeds) is provided on -stdin, and the SHA1, type, and size of each object is printed on stdout. +stdin, and the SHA-1, type, and size of each object is printed on stdout. OPTIONS ------- @@ -58,11 +58,11 @@ OPTIONS to apply the filter to the content recorded in the index at <path>. --batch:: - Print the SHA1, type, size, and contents of each object provided on + 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-check:: - Print the SHA1, type, and size of each object provided on stdin. May not + Print the SHA-1, type, and size of each object provided on stdin. May not be combined with any other options or arguments. OUTPUT diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 8edcdca..23a9413 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -180,6 +180,12 @@ branch by running "git rm -rf ." from the top level of the working tree. Afterwards you will be ready to prepare your new files, repopulating the working tree, by copying them from elsewhere, extracting a tarball, etc. +--ignore-skip-worktree-bits:: + In sparse checkout mode, `git checkout -- <paths>` would + update only entries matched by <paths> and sparse patterns + in $GIT_DIR/info/sparse-checkout. This option ignores + the sparse patterns and adds back any files in <paths>. + -m:: --merge:: When switching branches, 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 0eb79cc..9b1be55 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -137,6 +137,8 @@ OPTIONS -m <msg>:: --message=<msg>:: Use the given <msg> as the commit message. + If multiple `-m` options are given, their values are + concatenated as separate paragraphs. -t <file>:: --template=<file>:: @@ -172,16 +174,25 @@ OPTIONS linkgit:git-commit-tree[1]. --cleanup=<mode>:: - This option sets how the commit message is cleaned up. - The '<mode>' can be one of 'verbatim', 'whitespace', 'strip', - and 'default'. The 'default' mode will strip leading and - trailing empty lines and #commentary from the commit message - only if the message is to be edited. Otherwise only whitespace - removed. The 'verbatim' mode does not change message at all, - 'whitespace' removes just leading/trailing whitespace lines - and 'strip' removes both whitespace and commentary. The default - can be changed by the 'commit.cleanup' configuration variable - (see linkgit:git-config[1]). + This option determines how the supplied commit message should be + cleaned up before committing. The '<mode>' can be `strip`, + `whitespace`, `verbatim`, or `default`. ++ +-- +strip:: + Strip leading and trailing empty lines, trailing whitespace, and + #commentary and collapse consecutive empty lines. +whitespace:: + Same as `strip` except #commentary is not removed. +verbatim:: + Do not change the message at all. +default:: + Same as `strip` if the message is to be edited. + Otherwise `whitespace`. +-- ++ +The default can be changed by the 'commit.cleanup' configuration +variable (see linkgit:git-config[1]). -e:: --edit:: @@ -196,14 +207,15 @@ OPTIONS 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-describe.txt b/Documentation/git-describe.txt index 32da244..28e5ec0 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -81,8 +81,9 @@ OPTIONS that points at object deadbee....). --match <pattern>:: - Only consider tags matching the given pattern (can be used to avoid - leaking private tags made from the repository). + Only consider tags matching the given `glob(7)` pattern, + excluding the "refs/tags/" prefix. This can be used to avoid + leaking private tags from the repository. --always:: Show uniquely abbreviated commit object as fallback. @@ -148,7 +149,7 @@ is found, its name will be output and searching will stop. If an exact match was not found, 'git describe' will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an -abbreviation of the input committish's SHA1. +abbreviation of the input committish's SHA-1. If multiple tags were found during the walk then the tag which has the fewest commits different from the input committish will be 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-filter-branch.txt b/Documentation/git-filter-branch.txt index dfd12c9..e4c8e82 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -64,8 +64,11 @@ argument is always evaluated in the shell context using the 'eval' command Prior to that, the $GIT_COMMIT environment variable will be set to contain the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, -and GIT_COMMITTER_DATE are set according to the current commit. The values -of these variables after the filters have run, are used for the new commit. +and GIT_COMMITTER_DATE are taken from the current commit and exported to +the environment, in order to affect the author and committer identities of +the replacement commit created by linkgit:git-commit-tree[1] after the +filters have run. + If any evaluation of <command> returns a non-zero exit status, the whole operation will be aborted. @@ -329,6 +332,26 @@ git filter-branch --msg-filter ' ' HEAD~10..HEAD -------------------------------------------------------- +The `--env-filter` option can be used to modify committer and/or author +identity. For example, if you found out that your commits have the wrong +identity due to a misconfigured user.email, you can make a correction, +before publishing the project, like this: + +-------------------------------------------------------- +git filter-branch --env-filter ' + if test "$GIT_AUTHOR_EMAIL" = "root@localhost" + then + GIT_AUTHOR_EMAIL=john@example.com + export GIT_AUTHOR_EMAIL + fi + if test "$GIT_COMMITTER_EMAIL" = "root@localhost" + then + GIT_COMMITTER_EMAIL=john@example.com + export GIT_COMMITTER_EMAIL + fi +' -- --all +-------------------------------------------------------- + To restrict rewriting to only part of the history, specify a revision range in addition to the new branch name. The new branch name will point to the top-most revision that a 'git rev-list' of this range 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-fsck.txt b/Documentation/git-fsck.txt index eff9188..e5878bd 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -23,7 +23,7 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the -index file, all SHA1 references in `refs` namespace, and all reflogs +index file, all SHA-1 references in `refs` namespace, and all reflogs (unless --no-reflogs is given) as heads. --unreachable:: @@ -89,7 +89,7 @@ index file, all SHA1 references in `refs` namespace, and all reflogs DISCUSSION ---------- -git-fsck tests SHA1 and general object sanity, and it does full tracking +git-fsck tests SHA-1 and general object sanity, and it does full tracking of the resulting reachability and everything else. It prints out any corruption it finds (missing or bad objects), and if you use the '--unreachable' flag it will also print out objects that exist but that 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-http-backend.txt b/Documentation/git-http-backend.txt index 7b1e85c..e3bcdb5 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -80,7 +80,30 @@ ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ ---------------------------------------------------------------- + To enable anonymous read access but authenticated write access, -require authorization with a LocationMatch directive: +require authorization for both the initial ref advertisement (which we +detect as a push via the service parameter in the query string), and the +receive-pack invocation itself: ++ +---------------------------------------------------------------- +RewriteCond %{QUERY_STRING} service=git-receive-pack [OR] +RewriteCond %{REQUEST_URI} /git-receive-pack$ +RewriteRule ^/git/ - [E=AUTHREQUIRED:yes] + +<LocationMatch "^/git/"> + Order Deny,Allow + Deny from env=AUTHREQUIRED + + AuthType Basic + AuthName "Git Access" + Require group committers + Satisfy Any + ... +</LocationMatch> +---------------------------------------------------------------- ++ +If you do not have `mod_rewrite` available to match against the query +string, it is sufficient to just protect `git-receive-pack` itself, +like: + ---------------------------------------------------------------- <LocationMatch "^/git/.*/git-receive-pack$"> @@ -91,6 +114,15 @@ require authorization with a LocationMatch directive: </LocationMatch> ---------------------------------------------------------------- + +In this mode, the server will not request authentication until the +client actually starts the object negotiation phase of the push, rather +than during the initial contact. For this reason, you must also enable +the `http.receivepack` config option in any repositories that should +accept a push. The default behavior, if `http.receivepack` is not set, +is to reject any pushes by unauthenticated users; the initial request +will therefore report `403 Forbidden` to the client, without even giving +an opportunity for authentication. ++ To require authentication for both reads and writes, use a Location directive around the repository, or one of its parent directories: + @@ -158,6 +190,54 @@ ScriptAliasMatch \ ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ ---------------------------------------------------------------- +Lighttpd:: + Ensure that `mod_cgi`, `mod_alias, `mod_auth`, `mod_setenv` are + loaded, then set `GIT_PROJECT_ROOT` appropriately and redirect + all requests to the CGI: ++ +---------------------------------------------------------------- +alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" ) +$HTTP["url"] =~ "^/git" { + cgi.assign = ("" => "") + setenv.add-environment = ( + "GIT_PROJECT_ROOT" => "/var/www/git", + "GIT_HTTP_EXPORT_ALL" => "" + ) +} +---------------------------------------------------------------- ++ +To enable anonymous read access but authenticated write access: ++ +---------------------------------------------------------------- +$HTTP["querystring"] =~ "service=git-receive-pack" { + include "git-auth.conf" +} +$HTTP["url"] =~ "^/git/.*/git-receive-pack$" { + include "git-auth.conf" +} +---------------------------------------------------------------- ++ +where `git-auth.conf` looks something like: ++ +---------------------------------------------------------------- +auth.require = ( + "/" => ( + "method" => "basic", + "realm" => "Git Access", + "require" => "valid-user" + ) +) +# ...and set up auth.backend here +---------------------------------------------------------------- ++ +To require authentication for both reads and writes: ++ +---------------------------------------------------------------- +$HTTP["url"] =~ "^/git/private" { + include "git-auth.conf" +} +---------------------------------------------------------------- + ENVIRONMENT ----------- diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 36adc5f..bde8eec 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -89,7 +89,7 @@ Note ---- Once the index has been created, the list of object names is sorted -and the SHA1 hash of that list is printed to stdout. If --stdin was +and the SHA-1 hash of that list is printed to stdout. If --stdin was also used then this is prefixed by either "pack\t", or "keep\t" if a new .keep file was successfully created. This is useful to remove a .keep file used as a lock to prevent the race with 'git repack' diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 0bdebff..c0856a6 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -164,7 +164,7 @@ which case it outputs: 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine detailed information on unmerged paths. -For an unmerged path, instead of recording a single mode/SHA1 pair, +For an unmerged path, instead of recording a single mode/SHA-1 pair, the index records up to three such pairs; one from tree O in stage 1, A in stage 2, and B in stage 3. This information can be used by the user (or the porcelain) to see what should eventually be recorded at the diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 0c80cec..02676fb 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- This looks up the <file>(s) in the index and, if there are any merge -entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty +entries, passes the SHA-1 hash for those files as arguments 1, 2, 3 (empty argument if no file), and <file> as argument 4. File modes for the three files are passed as arguments 5, 6 and 7. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index c852a26..42391f2 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -170,6 +170,30 @@ happens: If you tried a merge which resulted in complex conflicts and want to start over, you can recover with `git merge --abort`. +MERGING TAG +----------- + +When merging an annotated (and possibly signed) tag, Git always +creates a merge commit even if a fast-forward merge is possible, and +the commit message template is prepared with the tag message. +Additionally, if the tag is signed, the signature check is reported +as a comment in the message template. See also linkgit:git-tag[1]. + +When you want to just integrate with the work leading to the commit +that happens to be tagged, e.g. synchronizing with an upstream +release point, you may not want to make an unnecessary merge commit. + +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-pack-objects.txt b/Documentation/git-pack-objects.txt index 69c9313..d94edcd 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -50,7 +50,7 @@ base-name:: Write into a pair of files (.pack and .idx), using <base-name> to determine the name of the created file. When this option is used, the two files are written in - <base-name>-<SHA1>.{pack,idx} files. <SHA1> is a hash + <base-name>-<SHA-1>.{pack,idx} files. <SHA-1> is a hash of the sorted object names to make the resulting filename based on the pack content, and written to the standard output of the command. diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 90268f0..312c3b1 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -12,7 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -A "patch ID" is nothing but a SHA1 of the diff associated with a patch, with +A "patch ID" is nothing but a SHA-1 of the diff associated with a patch, with whitespace and line numbers ignored. As such, it's "reasonably stable", but at the same time also reasonably unique, i.e., two patches that have the same "patch ID" are almost guaranteed to be the same thing. diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index c975743..24ab07a 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -218,7 +218,7 @@ $ git merge origin/next ------------------------------------------------ -If you tried a pull which resulted in a complex conflicts and +If you tried a pull which resulted in complex conflicts and would want to start over, you can recover with 'git reset'. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 1398025..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>...]] @@ -23,6 +23,17 @@ You can make interesting things happen to a repository every time you push into it, by setting up 'hooks' there. See documentation for linkgit:git-receive-pack[1]. +When the command line does not specify where to push with the +`<repository>` argument, `branch.*.remote` configuration for the +current branch is consulted to determine where to push. If the +configuration is missing, it defaults to 'origin'. + +When the command line does not specify what to push with `<refspec>...` +arguments or `--all`, `--mirror`, `--tags` options, the command finds +the default `<refspec>` by consulting `remote.*.push` configuration, +and if it is not found, honors `push.default` configuration to decide +what to push (See gitlink:git-config[1] for the meaning of `push.default`). + OPTIONS[[OPTIONS]] ------------------ @@ -33,13 +44,10 @@ OPTIONS[[OPTIONS]] of a remote (see the section <<REMOTES,REMOTES>> below). <refspec>...:: + Specify what destination ref to update with what source object. The format of a <refspec> parameter is an optional plus - `+`, followed by the source ref <src>, followed + `+`, followed by the source object <src>, followed by a colon `:`, followed by the destination ref <dst>. - It is used to specify with what <src> object the <dst> ref - in the remote repository is to be updated. If not specified, - the behavior of the command is controlled by the `push.default` - configuration variable. + The <src> is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as `master~4` or @@ -66,10 +74,7 @@ the remote repository. The special refspec `:` (or `+:` to allow non-fast-forward updates) directs Git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name -already exists on the remote side. This is the default operation mode -if no explicit refspec is found (that is neither on the command line -nor in any Push line of the corresponding remotes file---see below) and -no `push.default` configuration variable is set. +already exists on the remote side. --all:: Instead of naming each ref to push, specifies that all @@ -112,6 +117,12 @@ no `push.default` configuration variable is set. 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-replace.txt b/Documentation/git-replace.txt index 0142cd1..e0b4057 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -16,8 +16,8 @@ DESCRIPTION ----------- Adds a 'replace' reference in `refs/replace/` namespace. -The name of the 'replace' reference is the SHA1 of the object that is -replaced. The content of the 'replace' reference is the SHA1 of the +The name of the 'replace' reference is the SHA-1 of the object that is +replaced. The content of the 'replace' reference is the SHA-1 of the replacement object. Unless `-f` is given, the 'replace' reference must not yet exist. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 10a116f..947d62f 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:: @@ -84,7 +95,7 @@ OPTIONS one. --symbolic:: - Usually the object names are output in SHA1 form (with + Usually the object names are output in SHA-1 form (with possible '{caret}' prefix); this option makes them output in a form as close to the original input as possible. @@ -169,7 +180,7 @@ print a message to stderr and exit with nonzero status. --short:: --short=number:: - Instead of outputting the full SHA1 values of object names try to + 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. @@ -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-show-branch.txt b/Documentation/git-show-branch.txt index a8e77b5..a515648 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -31,7 +31,7 @@ no <rev> nor <glob> is given on the command line. OPTIONS ------- <rev>:: - Arbitrary extended SHA1 expression (see linkgit:gitrevisions[7]) + Arbitrary extended SHA-1 expression (see linkgit:gitrevisions[7]) that typically names a branch head or a tag. <glob>:: @@ -142,7 +142,7 @@ displayed, indented N places. If a commit is on the I-th branch, the I-th indentation character shows a `+` sign; otherwise it shows a space. Merge commits are denoted by a `-` sign. Each commit shows a short name that -can be used as an extended SHA1 to name that commit. +can be used as an extended SHA-1 to name that commit. The following example shows three branches, "master", "fixes" and "mhf": diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index 9cbbed9..fbdc8ad 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -19,7 +19,7 @@ Reads given idx file for packed Git archive created with The information it outputs is subset of what you can get from 'git verify-pack -v'; this command only shows the packfile -offset and SHA1 of each object. +offset and SHA-1 of each object. GIT --- diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 5dbcd47..de4d352 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -50,8 +50,8 @@ OPTIONS -s:: --hash[=<n>]:: - Only show the SHA1 hash, not the reference name. When combined with - --dereference the dereferenced tag will still be shown after the SHA1. + Only show the SHA-1 hash, not the reference name. When combined with + --dereference the dereferenced tag will still be shown after the SHA-1. --verify:: diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 0412c40..9046df9 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -46,15 +46,21 @@ OPTIONS Show untracked files. + The mode parameter is optional (defaults to 'all'), and is used to -specify the handling of untracked files; when -u is not used, the -default is 'normal', i.e. show untracked files and directories. +specify the handling of untracked files. + The possible options are: + - - 'no' - Show no untracked files - - 'normal' - Shows untracked files and directories + - 'no' - Show no untracked files. + - 'normal' - Shows untracked files and directories. - 'all' - Also shows individual files in untracked directories. + +When `-u` option is not used, untracked files and directories are +shown (i.e. the same as specifying `normal`), to help you avoid +forgetting to add newly created files. Because it takes extra work +to find untracked files in the filesystem, this mode may take some +time in a large working tree. You can use `no` to have `git status` +return more quickly without showing untracked files. ++ The default can be changed using the status.showUntrackedFiles configuration variable documented in linkgit:git-config[1]. 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-tag.txt b/Documentation/git-tag.txt index e3032c4..22894cb 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -33,7 +33,7 @@ in the tag message. If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. -Otherwise just a tag reference for the SHA1 object name of the commit object is +Otherwise just a tag reference for the SHA-1 object name of the commit object is created (i.e. a lightweight tag). A GnuPG signed tag object will be created when `-s` or `-u @@ -126,6 +126,12 @@ This option is only applicable when listing tags without annotation lines. linkgit:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a tag name. +<commit>:: +<object>:: + The object that the new tag will refer to, usually a commit. + Defaults to HEAD. + + CONFIGURATION ------------- By default, 'git tag' in sign-with-default mode (-s) will use your 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/git-update-index.txt b/Documentation/git-update-index.txt index 77a912d..670e9fb 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -145,7 +145,15 @@ you will need to handle the situation manually. --index-version <n>:: Write the resulting index out in the named on-disk format version. - The current default version is 2. + Supported versions are 2, 3 and 4. The current default version is 2 + or 3, depending on whether extra features are used, such as + `git add -N`. ++ +Version 4 performs a simple pathname compression that reduces index +size by 30%-50% on large repositories, which results in faster load +time. Version 4 is relatively young (first released in in 1.8.0 in +October 2012). Other Git implementations such as JGit and libgit2 +may not support it yet. -z:: Only meaningful with `--stdin` or `--index-info`; paths are @@ -239,7 +247,7 @@ $ git update-index --index-info ------------ The first line of the input feeds 0 as the mode to remove the -path; the SHA1 does not matter as long as it is well formatted. +path; the SHA-1 does not matter as long as it is well formatted. Then the second and third line feeds stage 1 and stage 2 entries for that path. After the above, we would end up with this: diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 0eb9ffb..526ba7b 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -40,11 +40,11 @@ OUTPUT FORMAT ------------- When specifying the -v option the format used is: - SHA1 type size size-in-pack-file offset-in-packfile + SHA-1 type size size-in-pack-file offset-in-packfile for objects that are not deltified in the pack, and - SHA1 type size size-in-packfile offset-in-packfile depth base-SHA1 + SHA-1 type size size-in-packfile offset-in-packfile depth base-SHA-1 for objects that are deltified. diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index e996135..f88ba96 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -21,7 +21,7 @@ OPTIONS Print the contents of the tag object before validating it. <tag>...:: - SHA1 identifiers of Git tag objects. + SHA-1 identifiers of Git tag objects. GIT --- diff --git a/Documentation/git.txt b/Documentation/git.txt index 9d29ed5..807a13c 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.1.5/git.html[documentation for release 1.8.1.5] +* link:v1.8.2.1/git.html[documentation for release 1.8.2.1] * release notes for + link:RelNotes/1.8.2.1.txt[1.8.2.1]. + link:RelNotes/1.8.2.txt[1.8.2]. + +* link:v1.8.1.6/git.html[documentation for release 1.8.1.6] + +* release notes for + link:RelNotes/1.8.1.6.txt[1.8.1.6], link:RelNotes/1.8.1.5.txt[1.8.1.5], link:RelNotes/1.8.1.4.txt[1.8.1.4], link:RelNotes/1.8.1.3.txt[1.8.1.3], @@ -734,7 +741,7 @@ where: <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the contents of <old|new>, - <old|new>-hex:: are the 40-hexdigit SHA1 hashes, + <old|new>-hex:: are the 40-hexdigit SHA-1 hashes, <old|new>-mode:: are the octal representation of the file modes. + The file parameters can point at the user's working file @@ -769,9 +776,12 @@ other If this environment variable is set then 'git fetch' and 'git push' will use this command instead of 'ssh' when they need to connect to a remote system. - The '$GIT_SSH' command will be given exactly two arguments: - the 'username@host' (or just 'host') from the URL and the - shell command to execute on that remote system. + The '$GIT_SSH' command will be given exactly two or + four arguments: the 'username@host' (or just 'host') + from the URL and the shell command to execute on that + remote system, optionally preceded by '-p' (literally) and + the 'port' from the URL when it specifies something other + than the default SSH port. + To pass options to the program that you want to list in GIT_SSH you will need to wrap the program and options into a shell script, @@ -854,7 +864,7 @@ The commit, equivalent to what other systems call a "changeset" or represents an immediately preceding step. Commits with more than one parent represent merges of independent lines of development. -All objects are named by the SHA1 hash of their contents, normally +All objects are named by the SHA-1 hash of their contents, normally written as a string of 40 hex digits. Such names are globally unique. The entire history leading up to a commit can be vouched for by signing just that commit. A fourth object type, the tag, is provided for this @@ -864,9 +874,9 @@ When first created, objects are stored in individual files, but for efficiency may later be compressed together into "pack files". Named pointers called refs mark interesting points in history. A ref -may contain the SHA1 name of an object or the name of another ref. Refs -with names beginning `ref/head/` contain the SHA1 name of the most -recent commit (or "head") of a branch under development. SHA1 names of +may contain the SHA-1 name of an object or the name of another ref. Refs +with names beginning `ref/head/` contain the SHA-1 name of the most +recent commit (or "head") of a branch under development. SHA-1 names of tags of interest are stored under `ref/tags/`. A special ref named `HEAD` contains the name of the currently checked-out branch. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index dc9e617..9ac5088 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -107,13 +107,14 @@ couple of magic command line options: --------------------------------------------- $ git describe -h usage: git describe [options] <committish>* + or: git describe [options] --dirty --contains find the tag that comes after the commit --debug debug search strategy on stderr - --all use any ref in .git/refs - --tags use any tag in .git/refs/tags - --abbrev [<n>] use <n> digits to display SHA-1s - --candidates <n> consider <n> most recent tags (default: 10) + --all use any ref + --tags use any tag, even unannotated + --long always use long format + --abbrev[=<n>] use <n> digits to display SHA-1s --------------------------------------------- --help-all:: diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 59c1c17..f538a87 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -106,9 +106,9 @@ branch. A number of the Git tools will assume that `.git/HEAD` is valid, though. [NOTE] -An 'object' is identified by its 160-bit SHA1 hash, aka 'object name', +An 'object' is identified by its 160-bit SHA-1 hash, aka 'object name', and a reference to an object is always the 40-byte hex -representation of that SHA1 name. The files in the `refs` +representation of that SHA-1 name. The files in the `refs` subdirectory are expected to contain these hex references (usually with a final `\n` at the end), and you should thus expect to see a number of 41-byte files containing these @@ -763,7 +763,7 @@ already discussed, the `HEAD` branch is nothing but a symlink to one of these object pointers. You can at any time create a new branch by just picking an arbitrary -point in the project history, and just writing the SHA1 name of that +point in the project history, and just writing the SHA-1 name of that object into a file under `.git/refs/heads/`. You can use any filename you want (and indeed, subdirectories), but the convention is that the "normal" branch is called `master`. That's just a convention, though, @@ -1233,7 +1233,7 @@ file (the first tree goes to stage 1, the second to stage 2, etc.). After reading three trees into three stages, the paths that are the same in all three stages are 'collapsed' into stage 0. Also paths that are the same in two of three stages are -collapsed into stage 0, taking the SHA1 from either stage 2 or +collapsed into stage 0, taking the SHA-1 from either stage 2 or stage 3, whichever is different from stage 1 (i.e. only one side changed from the common ancestor). diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 4ed71c7..568d757 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -108,7 +108,7 @@ it changes it to: For the purpose of breaking a filepair, diffcore-break examines the extent of changes between the contents of the files before and after modification (i.e. the contents that have "bcd1234..." -and "0123456..." as their SHA1 content ID, in the above +and "0123456..." as their SHA-1 content ID, in the above example). The amount of deletion of original contents and insertion of new material are added together, and if it exceeds the "break score", the filepair is broken into two. The break diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index eab9b35..d48bf4d 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -99,7 +99,7 @@ given); `template` (if a `-t` option was given or the configuration option `commit.template` is set); `merge` (if the commit is a merge or a `.git/MERGE_MSG` file exists); `squash` (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by -a commit SHA1 (if a `-c`, `-C` or `--amend` option was given). +a commit SHA-1 (if a `-c`, `-C` or `--amend` option was given). If the exit status is non-zero, 'git commit' will abort. @@ -140,9 +140,11 @@ the outcome of 'git commit'. pre-rebase ~~~~~~~~~~ -This hook is called by 'git rebase' and can be used to prevent a branch -from getting rebased. - +This hook is called by 'git rebase' and can be used to prevent a +branch from getting rebased. The hook may be called with one or +two parameters. The first parameter is the upstream from which +the series was forked. The second parameter is the branch being +rebased, and is not set when rebasing the current branch. post-checkout ~~~~~~~~~~~~~ @@ -194,11 +196,11 @@ hook would receive a line like the following: refs/heads/master 67890 refs/heads/foreign 12345 -although the full, 40-character SHA1s would be supplied. If the foreign ref -does not yet exist the `<remote SHA1>` will be 40 `0`. If a ref is to be +although the full, 40-character SHA-1s would be supplied. If the foreign ref +does not yet exist the `<remote SHA-1>` will be 40 `0`. If a ref is to be deleted, the `<local ref>` will be supplied as `(delete)` and the `<local -SHA1>` will be 40 `0`. If the local commit was specified by something other -than a name which could be expanded (such as `HEAD~`, or a SHA1) it will be +SHA-1>` will be 40 `0`. If the local commit was specified by something other +than a name which could be expanded (such as `HEAD~`, or a SHA-1) it will be supplied as it was originally given. If this hook exits with a non-zero status, 'git push' will abort without 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/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index f0eef76..d6f3393 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -106,7 +106,7 @@ refs/remotes/`name`:: from a remote repository. refs/replace/`<obj-sha1>`:: - records the SHA1 of the object that replaces `<obj-sha1>`. + records the SHA-1 of the object that replaces `<obj-sha1>`. This is similar to info/grafts and is internally used and maintained by linkgit:git-replace[1]. Such refs can be exchanged between repositories while grafts are not. @@ -184,6 +184,10 @@ info/exclude:: 'git clean' look at it but the core Git commands do not look at it. See also: linkgit:gitignore[5]. +info/sparse-checkout:: + This file stores sparse checkout patterns. + See also: linkgit:git-read-tree[1]. + remotes:: Stores shorthands for URL and default refnames for use when interacting with remote repositories via 'git fetch', diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index 94c906e..3109ea8 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -46,9 +46,9 @@ What are the 7 digits of hex that Git responded to the commit with? We saw in part one of the tutorial that commits have names like this. It turns out that every object in the Git history is stored under -a 40-digit hex name. That name is the SHA1 hash of the object's +a 40-digit hex name. That name is the SHA-1 hash of the object's contents; among other things, this ensures that Git will never store -the same data twice (since identical data is given an identical SHA1 +the same data twice (since identical data is given an identical SHA-1 name), and that the contents of a Git object will never change (since that would change the object's name as well). The 7 char hex strings here are simply the abbreviation of such 40 character long strings. @@ -56,7 +56,7 @@ Abbreviations can be used everywhere where the 40 character strings can be used, so long as they are unambiguous. It is expected that the content of the commit object you created while -following the example above generates a different SHA1 hash than +following the example above generates a different SHA-1 hash than the one shown above because the commit object records the time when it was created and the name of the person performing the commit. @@ -80,14 +80,14 @@ A tree can refer to one or more "blob" objects, each corresponding to a file. In addition, a tree can also refer to other tree objects, thus creating a directory hierarchy. You can examine the contents of any tree using ls-tree (remember that a long enough initial portion -of the SHA1 will also work): +of the SHA-1 will also work): ------------------------------------------------ $ git ls-tree 92b8b694 100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt ------------------------------------------------ -Thus we see that this tree has one file in it. The SHA1 hash is a +Thus we see that this tree has one file in it. The SHA-1 hash is a reference to that file's data: ------------------------------------------------ @@ -106,7 +106,7 @@ Note that this is the old file data; so the object that Git named in its response to the initial tree was a tree with a snapshot of the directory state that was recorded by the first commit. -All of these objects are stored under their SHA1 names inside the Git +All of these objects are stored under their SHA-1 names inside the Git directory: ------------------------------------------------ @@ -142,7 +142,7 @@ ref: refs/heads/master As you can see, this tells us which branch we're currently on, and it tells us this by naming a file under the .git directory, which itself -contains a SHA1 name referring to a commit object, which we can +contains a SHA-1 name referring to a commit object, which we can examine with cat-file: ------------------------------------------------ @@ -208,7 +208,7 @@ project's history: Note, by the way, that lots of commands take a tree as an argument. But as we can see above, a tree can be referred to in many different -ways--by the SHA1 name for that tree, by the name of a commit that +ways--by the SHA-1 name for that tree, by the name of a commit that refers to the tree, by the name of a branch whose head refers to that tree, etc.--and most such commands can accept any of these names. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index eb7ba84..ce3e4fa 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -100,12 +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_dircache]]dircache:: - You are *waaaaay* behind. See <<def_index,index>>. + <<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_directory]]directory:: The list you get with "ls" :-) @@ -115,11 +125,6 @@ to point at the new commit. it contains modifications which have not been <<def_commit,committed>> to the current <<def_branch,branch>>. -[[def_ent]]ent:: - Favorite synonym to "<<def_tree-ish,tree-ish>>" by some total geeks. See - http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth - explanation. Avoid this term, not to confuse people. - [[def_evil_merge]]evil merge:: An evil merge is a <<def_merge,merge>> that introduces changes that do not appear in any <<def_parent,parent>>. @@ -161,7 +166,7 @@ to point at the new commit. created. Configured via the `.git/info/grafts` file. [[def_hash]]hash:: - In Git's context, synonym to <<def_object_name,object name>>. + In Git's context, synonym for <<def_object_name,object name>>. [[def_head]]head:: A <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a @@ -233,7 +238,7 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_object]]object:: The unit of storage in Git. It is uniquely identified by the - <<def_SHA1,SHA1>> of its contents. Consequently, an + <<def_SHA1,SHA-1>> of its contents. Consequently, an object can not be changed. [[def_object_database]]object database:: @@ -245,10 +250,9 @@ This commit is referred to as a "merge commit", or sometimes just a Synonym for <<def_object_name,object name>>. [[def_object_name]]object name:: - The unique identifier of an <<def_object,object>>. The <<def_hash,hash>> - of the object's contents using the Secure Hash Algorithm - 1 and usually represented by the 40 character hexadecimal encoding of - the <<def_hash,hash>> of the object. + The unique identifier of an <<def_object,object>>. The + object name is usually represented by a 40 character + hexadecimal string. Also colloquially called <<def_SHA1,SHA-1>>. [[def_object_type]]object type:: One of the identifiers "<<def_commit_object,commit>>", @@ -257,8 +261,7 @@ This commit is referred to as a "merge commit", or sometimes just a <<def_object,object>>. [[def_octopus]]octopus:: - To <<def_merge,merge>> more than two <<def_branch,branches>>. Also denotes an - intelligent predator. + To <<def_merge,merge>> more than two <<def_branch,branches>>. [[def_origin]]origin:: The default upstream <<def_repository,repository>>. Most projects have @@ -278,7 +281,7 @@ This commit is referred to as a "merge commit", or sometimes just a pack. [[def_pathspec]]pathspec:: - Pattern used to specify paths. + Pattern used to limit paths in Git commands. + Pathspecs are used on the command line of "git ls-files", "git ls-tree", "git add", "git grep", "git diff", "git checkout", @@ -287,6 +290,8 @@ limit the scope of operations to some subset of the tree or worktree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The pathspec syntax is as follows: ++ +-- * any path matches itself * the pathspec up to the last slash represents a @@ -296,11 +301,12 @@ pathspec syntax is as follows: of the pathname. Paths relative to the directory prefix will be matched against that pattern using fnmatch(3); in particular, '*' and '?' _can_ match directory separators. + +-- + For example, Documentation/*.jpg will match all .jpg files in the Documentation subtree, including Documentation/chapter_1/figure_1.jpg. - + A pathspec that begins with a colon `:` has special meaning. In the short form, the leading colon `:` is followed by zero or more "magic @@ -316,18 +322,10 @@ and a close parentheses `)`, and the remainder is the pattern to match against the path. + The "magic signature" consists of an ASCII symbol that is not -alphanumeric. -+ --- -top `/`;; - The magic word `top` (mnemonic: `/`) makes the pattern match - from the root of the working tree, even when you are running - the command from inside a subdirectory. --- -+ -Currently only the slash `/` is recognized as the "magic signature", -but it is envisioned that we will support more types of magic in later -versions of Git. +alphanumeric. Currently only the slash `/` is recognized as a +"magic signature": it makes the pattern match from the root of +the working tree, even when you are running the command from +inside a subdirectory. + A pathspec with only a colon means "there is no pathspec". This form should not be combined with other pathspec. @@ -385,7 +383,7 @@ should not be combined with other pathspec. to the result. [[def_ref]]ref:: - A 40-byte hex representation of a <<def_SHA1,SHA1>> or a name that + A 40-byte hex representation of a <<def_SHA1,SHA-1>> or a name that denotes a particular <<def_object,object>>. They may be stored in a file under `$GIT_DIR/refs/` directory, or in the `$GIT_DIR/packed-refs` file. @@ -399,15 +397,7 @@ should not be combined with other pathspec. [[def_refspec]]refspec:: A "refspec" is used by <<def_fetch,fetch>> and <<def_push,push>> to describe the mapping between remote - <<def_ref,ref>> and local ref. They are combined with a colon in - the format <src>:<dst>, preceded by an optional plus sign, +. - For example: `git fetch $URL - refs/heads/master:refs/heads/origin` means "grab the master - <<def_branch,branch>> <<def_head,head>> from the $URL and store - it as my origin branch head". And `git push - $URL refs/heads/master:refs/heads/to-upstream` means "publish my - master branch head as to-upstream branch at $URL". See also - linkgit:git-push[1]. + <<def_ref,ref>> and local ref. [[def_remote_tracking_branch]]remote-tracking branch:: A regular Git <<def_branch,branch>> that is used to follow changes from @@ -441,8 +431,9 @@ should not be combined with other pathspec. [[def_SCM]]SCM:: Source code management (tool). -[[def_SHA1]]SHA1:: - Synonym for <<def_object_name,object name>>. +[[def_SHA1]]SHA-1:: + "Secure Hash Algorithm 1"; a cryptographic hash function. + In the context of Git used as a synonym for <<def_object_name,object name>>. [[def_shallow_repository]]shallow repository:: A shallow <<def_repository,repository>> has an incomplete @@ -456,7 +447,7 @@ should not be combined with other pathspec. its history can be later deepened with linkgit:git-fetch[1]. [[def_symref]]symref:: - Symbolic reference: instead of containing the <<def_SHA1,SHA1>> + Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id itself, it is of the format 'ref: refs/some/thing' and when referenced, it recursively dereferences to this reference. '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic diff --git a/Documentation/howto/recover-corrupted-blob-object.txt b/Documentation/howto/recover-corrupted-blob-object.txt index 6d362ce..1b3b188 100644 --- a/Documentation/howto/recover-corrupted-blob-object.txt +++ b/Documentation/howto/recover-corrupted-blob-object.txt @@ -15,7 +15,7 @@ On Fri, 9 Nov 2007, Yossi Leybovich wrote: > Any one know how can I track this object and understand which file is it ----------------------------------------------------------- -So exactly *because* the SHA1 hash is cryptographically secure, the hash +So exactly *because* the SHA-1 hash is cryptographically secure, the hash itself doesn't actually tell you anything, in order to fix a corrupt object you basically have to find the "original source" for it. @@ -44,7 +44,7 @@ So: ----------------------------------------------------------- This is the right thing to do, although it's usually best to save it under -it's full SHA1 name (you just dropped the "4b" from the result ;). +it's full SHA-1 name (you just dropped the "4b" from the result ;). Let's see what that tells us: @@ -89,7 +89,7 @@ working tree, in which case fixing this problem is really simple, just do git hash-object -w my-magic-file -again, and if it outputs the missing SHA1 (4b945..) you're now all done! +again, and if it outputs the missing SHA-1 (4b945..) you're now all done! But that's the really lucky case, so let's assume that it was some older version that was broken. How do you tell which version it was? diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 0bcbe0a..2adccf8 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -30,7 +30,8 @@ set to `no` at the beginning of them. --no-ff:: Create a merge commit even when the merge resolves as a - fast-forward. + fast-forward. This is the default behaviour when merging an + annotated (and possibly signed) tag. --ff-only:: Refuse to merge and exit with a non-zero status unless the @@ -83,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 105f18a..f5b50dc 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -75,7 +75,7 @@ This is designed to be as compact as possible. * 'raw' + The 'raw' format shows the entire commit exactly as -stored in the commit object. Notably, the SHA1s are +stored in the commit object. Notably, the SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and 'parents' information show the true parent commits, without taking grafts nor history @@ -131,8 +131,10 @@ 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}` - '%gd': shortened reflog selector, e.g., `stash@{1}` - '%gn': reflog identity name diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 678d175..a8ff691 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -2,13 +2,13 @@ SPECIFYING REVISIONS -------------------- A revision parameter '<rev>' typically, but not necessarily, names a -commit object. It uses what is called an 'extended SHA1' +commit object. It uses what is called an 'extended SHA-1' syntax. Here are various ways to spell object names. The ones listed near the end of this list name trees and blobs contained in a commit. '<sha1>', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e':: - The full SHA1 object name (40-byte hexadecimal string), or + The full SHA-1 object name (40-byte hexadecimal string), or a leading substring that is unique within the repository. E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the same commit object if there is no other object in @@ -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\}':: @@ -88,10 +88,10 @@ some output processing may assume ref names in UTF-8. The construct '@\{-<n>\}' means the <n>th branch checked out before the current one. -'<refname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: - The suffix '@\{upstream\}' to a ref (short form '<refname>@\{u\}') refers to - the branch the ref is set to build on top of. A missing ref defaults - to the current branch. +'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: + The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}') + refers to the branch that the branch specified by branchname is set to build on + top of. A missing branchname defaults to the current one. '<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of @@ -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-sha1-array.txt b/Documentation/technical/api-sha1-array.txt index 45d1c51..3e75497 100644 --- a/Documentation/technical/api-sha1-array.txt +++ b/Documentation/technical/api-sha1-array.txt @@ -1,7 +1,7 @@ sha1-array API ============== -The sha1-array API provides storage and manipulation of sets of SHA1 +The sha1-array API provides storage and manipulation of sets of SHA-1 identifiers. The emphasis is on storage and processing efficiency, making them suitable for large lists. Note that the ordering of items is not preserved over some operations. @@ -11,7 +11,7 @@ Data Structures `struct sha1_array`:: - A single array of SHA1 hashes. This should be initialized by + A single array of SHA-1 hashes. This should be initialized by assignment from `SHA1_ARRAY_INIT`. The `sha1` member contains the actual data. The `nr` member contains the number of items in the set. The `alloc` and `sorted` members are used internally, 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/index-format.txt b/Documentation/technical/index-format.txt index 27c716b..0810251 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -12,7 +12,7 @@ Git index format The signature is { 'D', 'I', 'R', 'C' } (stands for "dircache") 4-byte version number: - The current supported versions are 2 and 3. + The current supported versions are 2, 3 and 4. 32-bit number of index entries. @@ -93,8 +93,8 @@ Git index format 12-bit name length if the length is less than 0xFFF; otherwise 0xFFF is stored in this field. - (Version 3) A 16-bit field, only applicable if the "extended flag" - above is 1, split into (high to low bits). + (Version 3 or later) A 16-bit field, only applicable if the + "extended flag" above is 1, split into (high to low bits). 1-bit reserved for future diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index 0e37ec9..8e5bf60 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -26,13 +26,15 @@ 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 length format and is not constrained to 32-bit or anything. - - The trailer records 20-byte SHA1 checksum of all of the above. + - The trailer records 20-byte SHA-1 checksum of all of the above. == Original (version 1) pack-*.idx files have the following format: @@ -53,10 +55,10 @@ Git pack format - The file is concluded with a trailer: - A copy of the 20-byte SHA1 checksum at the end of + A copy of the 20-byte SHA-1 checksum at the end of corresponding packfile. - 20-byte SHA1-checksum of all of the above. + 20-byte SHA-1-checksum of all of the above. Pack Idx file: @@ -104,7 +106,7 @@ Pack file entry: <+ If it is not DELTA, then deflated bytes (the size above is the size before compression). If it is REF_DELTA, then - 20-byte base object name SHA1 (the size above is the + 20-byte base object name SHA-1 (the size above is the size of the delta data that follows). delta data, deflated. If it is OFS_DELTA, then @@ -133,7 +135,7 @@ Pack file entry: <+ - A 256-entry fan-out table just like v1. - - A table of sorted 20-byte SHA1 object names. These are + - A table of sorted 20-byte SHA-1 object names. These are packed together without offset values to reduce the cache footprint of the binary search for a specific object name. @@ -154,7 +156,7 @@ Pack file entry: <+ - The same trailer as a v1 pack file: - A copy of the 20-byte SHA1 checksum at the end of + A copy of the 20-byte SHA-1 checksum at the end of corresponding packfile. - 20-byte SHA1-checksum of all of the above. + 20-byte SHA-1-checksum of all of the above. diff --git a/Documentation/technical/pack-heuristics.txt b/Documentation/technical/pack-heuristics.txt index dbdf7ba..8b7ae1c 100644 --- a/Documentation/technical/pack-heuristics.txt +++ b/Documentation/technical/pack-heuristics.txt @@ -89,7 +89,7 @@ Ah, grasshopper! And thus the enlightenment begins anew. <linus> The "magic" is actually in theory totally arbitrary. ANY order will give you a working pack, but no, it's not - ordered by SHA1. + ordered by SHA-1. Before talking about the ordering for the sliding delta window, let's talk about the recency order. That's more diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt index ea2f69f..5183b15 100644 --- a/Documentation/technical/shallow.txt +++ b/Documentation/technical/shallow.txt @@ -8,7 +8,7 @@ repo, and therefore grafts are introduced pretending that these commits have no parents. ********************************************************* -The basic idea is to write the SHA1s of shallow commits into +The basic idea is to write the SHA-1s of shallow commits into $GIT_DIR/shallow, and handle its contents like the contents of $GIT_DIR/info/grafts (with the difference that shallow cannot contain parent information). @@ -18,7 +18,7 @@ even the config, since the user should not touch that file at all (even throughout development of the shallow clone, it was never manually edited!). -Each line contains exactly one SHA1. When read, a commit_graft +Each line contains exactly one SHA-1. When read, a commit_graft will be constructed, which has nr_parent < 0 to make it easier to discern from user provided grafts. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 5f36f81..e831cc2 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -19,7 +19,7 @@ Further chapters cover more specialized topics. Comprehensive reference documentation is available through the man pages, or linkgit:git-help[1] command. For example, for the command -"git clone <repo>", you can either use: +`git clone <repo>`, you can either use: ------------------------------------------------ $ man git-clone @@ -66,11 +66,11 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git The initial clone may be time-consuming for a large project, but you will only need to clone once. -The clone command creates a new directory named after the project ("git" -or "linux-2.6" in the examples above). After you cd into this +The clone command creates a new directory named after the project (`git` +or `linux-2.6` in the examples above). After you cd into this directory, you will see that it contains a copy of the project files, called the <<def_working_tree,working tree>>, together with a special -top-level directory named ".git", which contains all the information +top-level directory named `.git`, which contains all the information about the history of the project. [[how-to-check-out]] @@ -188,7 +188,7 @@ As you can see, a commit shows who made the latest change, what they did, and why. Every commit has a 40-hexdigit id, sometimes called the "object name" or the -"SHA-1 id", shown on the first line of the "git show" output. You can usually +"SHA-1 id", shown on the first line of the `git show` output. You can usually refer to a commit by a shorter name, such as a tag or a branch name, but this longer name can also be useful. Most importantly, it is a globally unique name for this commit: so if you tell somebody else the object name (for @@ -268,35 +268,35 @@ Manipulating branches Creating, deleting, and modifying branches is quick and easy; here's a summary of the commands: -git branch:: +`git branch`:: list all branches -git branch <branch>:: - create a new branch named <branch>, referencing the same +`git branch <branch>`:: + create a new branch named `<branch>`, referencing the same point in history as the current branch -git branch <branch> <start-point>:: - create a new branch named <branch>, referencing - <start-point>, which may be specified any way you like, +`git branch <branch> <start-point>`:: + create a new branch named `<branch>`, referencing + `<start-point>`, which may be specified any way you like, including using a branch name or a tag name -git branch -d <branch>:: - delete the branch <branch>; if the branch you are deleting +`git branch -d <branch>`:: + delete the branch `<branch>`; if the branch you are deleting points to a commit which is not reachable from the current branch, this command will fail with a warning. -git branch -D <branch>:: +`git branch -D <branch>`:: even if the branch points to a commit not reachable from the current branch, you may know that that commit is still reachable from some other branch or tag. In that case it is safe to use this command to force Git to delete the branch. -git checkout <branch>:: - make the current branch <branch>, updating the working - directory to reflect the version referenced by <branch> -git checkout -b <new> <start-point>:: - create a new branch <new> referencing <start-point>, and +`git checkout <branch>`:: + make the current branch `<branch>`, updating the working + directory to reflect the version referenced by `<branch>` +`git checkout -b <new> <start-point>`:: + create a new branch `<new>` referencing `<start-point>`, and check it out. The special symbol "HEAD" can always be used to refer to the current -branch. In fact, Git uses a file named "HEAD" in the .git directory to -remember which branch is current: +branch. In fact, Git uses a file named `HEAD` in the `.git` directory +to remember which branch is current: ------------------------------------------------ $ cat .git/HEAD @@ -346,7 +346,7 @@ of the HEAD in the repository that you cloned from. That repository may also have had other branches, though, and your local repository keeps branches which track each of those remote branches, called remote-tracking branches, which you -can view using the "-r" option to linkgit:git-branch[1]: +can view using the `-r` option to linkgit:git-branch[1]: ------------------------------------------------ $ git branch -r @@ -364,7 +364,7 @@ In this example, "origin" is called a remote repository, or "remote" for short. The branches of this repository are called "remote branches" from our point of view. The remote-tracking branches listed above were created based on the remote branches at clone time and will -be updated by "git fetch" (hence "git pull") and "git push". See +be updated by `git fetch` (hence `git pull`) and `git push`. See <<Updating-a-repository-With-git-fetch>> for details. You might want to build on one of these remote-tracking branches @@ -374,7 +374,7 @@ on a branch of your own, just as you would for a tag: $ git checkout -b my-todo-copy origin/todo ------------------------------------------------ -You can also check out "origin/todo" directly to examine it or +You can also check out `origin/todo` directly to examine it or write a one-off patch. See <<detached-head,detached head>>. Note that the name "origin" is just the name that Git uses by default @@ -386,17 +386,17 @@ Naming branches, tags, and other references Branches, remote-tracking branches, and tags are all references to commits. All references are named with a slash-separated path name -starting with "refs"; the names we've been using so far are actually +starting with `refs`; the names we've been using so far are actually shorthand: - - The branch "test" is short for "refs/heads/test". - - The tag "v2.6.18" is short for "refs/tags/v2.6.18". - - "origin/master" is short for "refs/remotes/origin/master". + - The branch `test` is short for `refs/heads/test`. + - The tag `v2.6.18` is short for `refs/tags/v2.6.18`. + - `origin/master` is short for `refs/remotes/origin/master`. The full name is occasionally useful if, for example, there ever exists a tag and a branch with the same name. -(Newly created refs are actually stored in the .git/refs directory, +(Newly created refs are actually stored in the `.git/refs` directory, under the path given by their name. However, for efficiency reasons they may also be packed together in a single file; see linkgit:git-pack-refs[1]). @@ -418,7 +418,7 @@ Eventually the developer cloned from will do additional work in her repository, creating new commits and advancing the branches to point at the new commits. -The command "git fetch", with no arguments, will update all of the +The command `git fetch`, with no arguments, will update all of the remote-tracking branches to the latest version found in her repository. It will not touch any of your own branches--not even the "master" branch that was created for you on clone. @@ -438,7 +438,7 @@ $ git fetch linux-nfs ------------------------------------------------- New remote-tracking branches will be stored under the shorthand name -that you gave "git remote add", in this case linux-nfs: +that you gave `git remote add`, in this case `linux-nfs`: ------------------------------------------------- $ git branch -r @@ -446,10 +446,10 @@ linux-nfs/master origin/master ------------------------------------------------- -If you run "git fetch <remote>" later, the remote-tracking branches for the -named <remote> will be updated. +If you run `git fetch <remote>` later, the remote-tracking branches +for the named `<remote>` will be updated. -If you examine the file .git/config, you will see that Git has added +If you examine the file `.git/config`, you will see that Git has added a new stanza: ------------------------------------------------- @@ -462,7 +462,7 @@ $ cat .git/config ------------------------------------------------- This is what causes Git to track the remote's branches; you may modify -or delete these configuration options by editing .git/config with a +or delete these configuration options by editing `.git/config` with a text editor. (See the "CONFIGURATION FILE" section of linkgit:git-config[1] for details.) @@ -499,7 +499,7 @@ Bisecting: 3537 revisions left to test after this [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] ------------------------------------------------- -If you run "git branch" at this point, you'll see that Git has +If you run `git branch` at this point, you'll see that Git has temporarily moved you in "(no branch)". HEAD is now detached from any branch and points directly to a commit (with commit id 65934...) that is reachable from "master" but not from v2.6.18. Compile and test it, @@ -545,11 +545,11 @@ id, and check it out with: $ git reset --hard fb47ddb2db... ------------------------------------------------- -then test, run "bisect good" or "bisect bad" as appropriate, and +then test, run `bisect good` or `bisect bad` as appropriate, and continue. -Instead of "git bisect visualize" and then "git reset --hard -fb47ddb2db...", you might just want to tell Git that you want to skip +Instead of `git bisect visualize` and then `git reset --hard +fb47ddb2db...`, you might just want to tell Git that you want to skip the current commit: ------------------------------------------------- @@ -561,8 +561,8 @@ bad one between some first skipped commits and a later bad commit. There are also ways to automate the bisecting process if you have a test script that can tell a good from a bad commit. See -linkgit:git-bisect[1] for more information about this and other "git -bisect" features. +linkgit:git-bisect[1] for more information about this and other `git +bisect` features. [[naming-commits]] Naming commits @@ -591,7 +591,7 @@ $ git show HEAD~4 # the great-great-grandparent ------------------------------------------------- Recall that merge commits may have more than one parent; by default, -^ and ~ follow the first parent listed in the commit, but you can +`^` and `~` follow the first parent listed in the commit, but you can also choose: ------------------------------------------------- @@ -640,7 +640,7 @@ running $ git tag stable-1 1b2e1d63ff ------------------------------------------------- -You can use stable-1 to refer to the commit 1b2e1d63ff. +You can use `stable-1` to refer to the commit 1b2e1d63ff. This creates a "lightweight" tag. If you would also like to include a comment with the tag, and possibly sign it cryptographically, then you @@ -669,7 +669,7 @@ $ git log -S'foo()' # commits which add or remove any file data ------------------------------------------------- And of course you can combine all of these; the following finds -commits since v2.5 which touch the Makefile or any file under fs: +commits since v2.5 which touch the `Makefile` or any file under `fs`: ------------------------------------------------- $ git log v2.5.. Makefile fs/ @@ -681,7 +681,7 @@ You can also ask git log to show patches: $ git log -p ------------------------------------------------- -See the "--pretty" option in the linkgit:git-log[1] man page for more +See the `--pretty` option in the linkgit:git-log[1] man page for more display options. Note that git log starts with the most recent commit and works @@ -742,8 +742,8 @@ Examples Counting the number of commits on a branch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Suppose you want to know how many commits you've made on "mybranch" -since it diverged from "origin": +Suppose you want to know how many commits you've made on `mybranch` +since it diverged from `origin`: ------------------------------------------------- $ git log --pretty=oneline origin..mybranch | wc -l @@ -780,7 +780,7 @@ $ git rev-list master e05db0fd4f31dde7005f075a84f96b360d05984b ------------------------------------------------- -Or you could recall that the ... operator selects all commits +Or you could recall that the `...` operator selects all commits contained reachable from either one reference or the other but not both; so @@ -880,7 +880,7 @@ Showing commits unique to a given branch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Suppose you would like to see all the commits reachable from the branch -head named "master" but not from any other head in your repository. +head named `master` but not from any other head in your repository. We can list all the heads in this repository with linkgit:git-show-ref[1]: @@ -894,7 +894,7 @@ a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes ------------------------------------------------- -We can get just the branch-head names, and remove "master", with +We can get just the branch-head names, and remove `master`, with the help of the standard utilities cut and grep: ------------------------------------------------- @@ -939,7 +939,7 @@ is preceded by `project/`. The output file format is inferred from the output file extension if possible, see linkgit:git-archive[1] for details. -Versions of Git older than 1.7.7 don't know about the 'tar.gz' format, +Versions of Git older than 1.7.7 don't know about the `tar.gz` format, you'll need to use gzip explicitly: ------------------------------------------------- @@ -1062,7 +1062,7 @@ at step 3, Git maintains a snapshot of the tree's contents in a special staging area called "the index." At the beginning, the content of the index will be identical to -that of the HEAD. The command "git diff --cached", which shows +that of the HEAD. The command `git diff --cached`, which shows the difference between the HEAD and the index, should therefore produce no output at that point. @@ -1101,7 +1101,7 @@ $ git diff shows the difference between the working tree and the index file. -Note that "git add" always adds just the current contents of a file +Note that `git add` always adds just the current contents of a file to the index; further changes to the same file will be ignored unless you run `git add` on the file again. @@ -1172,8 +1172,9 @@ annoying to have these untracked files lying around; e.g. they make `git add .` practically useless, and they keep showing up in the output of `git status`. -You can tell Git to ignore certain files by creating a file called .gitignore -in the top level of your working directory, with contents such as: +You can tell Git to ignore certain files by creating a file called +`.gitignore` in the top level of your working directory, with contents +such as: ------------------------------------------------- # Lines starting with '#' are considered comments. @@ -1197,10 +1198,10 @@ for other users who clone your repository. If you wish the exclude patterns to affect only certain repositories (instead of every repository for a given project), you may instead put -them in a file in your repository named .git/info/exclude, or in any file -specified by the `core.excludesfile` configuration variable. Some Git -commands can also take exclude patterns directly on the command line. -See linkgit:gitignore[5] for the details. +them in a file in your repository named `.git/info/exclude`, or in any +file specified by the `core.excludesfile` configuration variable. +Some Git commands can also take exclude patterns directly on the +command line. See linkgit:gitignore[5] for the details. [[how-to-merge]] How to merge @@ -1213,10 +1214,10 @@ linkgit:git-merge[1]: $ git merge branchname ------------------------------------------------- -merges the development in the branch "branchname" into the current +merges the development in the branch `branchname` into the current branch. -A merge is made by combining the changes made in "branchname" and the +A merge is made by combining the changes made in `branchname` and the changes made up to the latest commit in your current branch since their histories forked. The work tree is overwritten by the result of the merge when this combining is done cleanly, or overwritten by a @@ -1338,7 +1339,7 @@ that part is not conflicting and is not shown. Same for stage 3). The diff above shows the differences between the working-tree version of file.txt and the stage 2 and stage 3 versions. So instead of preceding -each line by a single "+" or "-", it now uses two columns: the first +each line by a single `+` or `-`, it now uses two columns: the first column is used for differences between the first parent and the working directory copy, and the second for differences between the second parent and the working directory copy. (See the "COMBINED DIFF FORMAT" section @@ -1613,7 +1614,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f You will see informational messages on dangling objects. They are objects that still exist in the repository but are no longer referenced by any of -your branches, and can (and will) be removed after a while with "gc". +your branches, and can (and will) be removed after a while with `gc`. You can run `git fsck --no-dangling` to suppress these messages, and still view real errors. @@ -1625,9 +1626,9 @@ Recovering lost changes Reflogs ^^^^^^^ -Say you modify a branch with +linkgit:git-reset[1] \--hard+, and then -realize that the branch was the only reference you had to that point in -history. +Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>, +and then realize that the branch was the only reference you had to +that point in history. Fortunately, Git also keeps a log, called a "reflog", of all the previous values of each branch. So in this case you can still find the @@ -1638,8 +1639,8 @@ $ git log master@{1} ------------------------------------------------- This lists the commits reachable from the previous version of the -"master" branch head. This syntax can be used with any Git command -that accepts a commit, not just with git log. Some other examples: +`master` branch head. This syntax can be used with any Git command +that accepts a commit, not just with `git log`. Some other examples: ------------------------------------------------- $ git show master@{2} # See where the branch pointed 2, @@ -1743,8 +1744,8 @@ one step: $ git pull origin master ------------------------------------------------- -In fact, if you have "master" checked out, then this branch has been -configured by "git clone" to get changes from the HEAD branch of the +In fact, if you have `master` checked out, then this branch has been +configured by `git clone` to get changes from the HEAD branch of the origin repository. So often you can accomplish the above with just a simple @@ -1759,11 +1760,11 @@ the current branch. More generally, a branch that is created from a remote-tracking branch will pull by default from that branch. See the descriptions of the -branch.<name>.remote and branch.<name>.merge options in +`branch.<name>.remote` and `branch.<name>.merge` options in linkgit:git-config[1], and the discussion of the `--track` option in linkgit:git-checkout[1], to learn how to control these defaults. -In addition to saving you keystrokes, "git pull" also helps you by +In addition to saving you keystrokes, `git pull` also helps you by producing a default commit message documenting the branch and repository that you pulled from. @@ -1771,7 +1772,7 @@ repository that you pulled from. <<fast-forwards,fast-forward>>; instead, your branch will just be updated to point to the latest commit from the upstream branch.) -The `git pull` command can also be given "." as the "remote" repository, +The `git pull` command can also be given `.` as the "remote" repository, in which case it just merges in a branch from the current repository; so the commands @@ -1796,7 +1797,7 @@ $ git format-patch origin ------------------------------------------------- will produce a numbered series of files in the current directory, one -for each patch in the current branch but not in origin/HEAD. +for each patch in the current branch but not in `origin/HEAD`. `git format-patch` can include an initial "cover letter". You can insert commentary on individual patches after the three dash line which @@ -1818,7 +1819,7 @@ Importing patches to a project Git also provides a tool called linkgit:git-am[1] (am stands for "apply mailbox"), for importing such an emailed series of patches. Just save all of the patch-containing messages, in order, into a -single mailbox file, say "patches.mbox", then run +single mailbox file, say `patches.mbox`, then run ------------------------------------------------- $ git am -3 patches.mbox @@ -1826,7 +1827,7 @@ $ git am -3 patches.mbox Git will apply each patch in order; if any conflicts are found, it will stop, and you can fix the conflicts as described in -"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells +"<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells Git to perform a merge; if you would prefer it just to abort and leave your tree and index untouched, you may omit that option.) @@ -1902,7 +1903,7 @@ We explain how to do this in the following sections. Setting up a public repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Assume your personal repository is in the directory ~/proj. We +Assume your personal repository is in the directory `~/proj`. We first create a new clone of the repository and tell `git daemon` that it is meant to be public: @@ -1912,10 +1913,10 @@ $ touch proj.git/git-daemon-export-ok ------------------------------------------------- The resulting directory proj.git contains a "bare" git repository--it is -just the contents of the ".git" directory, without any files checked out +just the contents of the `.git` directory, without any files checked out around it. -Next, copy proj.git to the server where you plan to host the +Next, copy `proj.git` to the server where you plan to host the public repository. You can use scp, rsync, or whatever is most convenient. @@ -1926,8 +1927,8 @@ Exporting a Git repository via the Git protocol This is the preferred method. If someone else administers the server, they should tell you what -directory to put the repository in, and what git:// URL it will appear -at. You can then skip to the section +directory to put the repository in, and what `git://` URL it will +appear at. You can then skip to the section "<<pushing-changes-to-a-public-repository,Pushing changes to a public repository>>", below. @@ -1962,7 +1963,7 @@ $ mv hooks/post-update.sample hooks/post-update (For an explanation of the last two lines, see linkgit:git-update-server-info[1] and linkgit:githooks[5].) -Advertise the URL of proj.git. Anybody else should then be able to +Advertise the URL of `proj.git`. Anybody else should then be able to clone or pull from that URL, for example with a command line like: ------------------------------------------------- @@ -1985,8 +1986,8 @@ access, which you will need to update the public repository with the latest changes created in your private repository. The simplest way to do this is using linkgit:git-push[1] and ssh; to -update the remote branch named "master" with the latest state of your -branch named "master", run +update the remote branch named `master` with the latest state of your +branch named `master`, run ------------------------------------------------- $ git push ssh://yourserver.com/~you/proj.git master:master @@ -2002,7 +2003,7 @@ As with `git fetch`, `git push` will complain if this does not result in a <<fast-forwards,fast-forward>>; see the following section for details on handling this case. -Note that the target of a "push" is normally a +Note that the target of a `push` is normally a <<def_bare_repository,bare>> repository. You can also push to a repository that has a checked-out working tree, but a push to update the currently checked-out branch is denied by default to prevent confusion. @@ -2030,9 +2031,9 @@ which lets you do the same push with just $ git push public-repo master ------------------------------------------------- -See the explanations of the remote.<name>.url, branch.<name>.remote, -and remote.<name>.push options in linkgit:git-config[1] for -details. +See the explanations of the `remote.<name>.url`, +`branch.<name>.remote`, and `remote.<name>.push` options in +linkgit:git-config[1] for details. [[forcing-push]] What to do when a push fails @@ -2167,7 +2168,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see Now create the branches in which you are going to work; these start out at the current tip of origin/master branch, and should be set up (using -the --track option to linkgit:git-branch[1]) to merge changes in from +the `--track` option to linkgit:git-branch[1]) to merge changes in from Linus by default. ------------------------------------------------- @@ -2186,7 +2187,7 @@ Important note! If you have any local changes in these branches, then this merge will create a commit object in the history (with no local changes Git will simply do a "fast-forward" merge). Many people dislike the "noise" that this creates in the Linux history, so you should avoid -doing this capriciously in the "release" branch, as these noisy commits +doing this capriciously in the `release` branch, as these noisy commits will become part of the permanent history when you ask Linus to pull from the release branch. @@ -2228,7 +2229,7 @@ patches), and create a new branch from a recent stable tag of Linus's branch. Picking a stable base for your branch will: 1) help you: by avoiding inclusion of unrelated and perhaps lightly tested changes -2) help future bug hunters that use "git bisect" to find problems +2) help future bug hunters that use `git bisect` to find problems ------------------------------------------------- $ git checkout -b speed-up-spinlocks v2.6.35 @@ -2253,9 +2254,9 @@ It is unlikely that you would have any conflicts here ... but you might if you spent a while on this step and had also pulled new versions from upstream. Some time later when enough time has passed and testing done, you can pull the -same branch into the "release" tree ready to go upstream. This is where you +same branch into the `release` tree ready to go upstream. This is where you see the value of keeping each patch (or patch series) in its own branch. It -means that the patches can be moved into the "release" tree in any order. +means that the patches can be moved into the `release` tree in any order. ------------------------------------------------- $ git checkout release && git pull . speed-up-spinlocks @@ -2288,7 +2289,7 @@ If it has been merged, then there will be no output.) Once a patch completes the great cycle (moving from test to release, then pulled by Linus, and finally coming back into your local -"origin/master" branch), the branch for this change is no longer needed. +`origin/master` branch), the branch for this change is no longer needed. You detect this when the output from: ------------------------------------------------- @@ -2303,8 +2304,8 @@ $ git branch -d branchname Some changes are so trivial that it is not necessary to create a separate branch and then merge into each of the test and release branches. For -these changes, just apply directly to the "release" branch, and then -merge that into the "test" branch. +these changes, just apply directly to the `release` branch, and then +merge that into the `test` branch. After pushing your work to `mytree`, you can use linkgit:git-request-pull[1] to prepare a "please pull" request message @@ -2337,7 +2338,7 @@ origin) fi ;; *) - echo "Usage: $0 origin|test|release" 1>&2 + echo "usage: $0 origin|test|release" 1>&2 exit 1 ;; esac @@ -2351,7 +2352,7 @@ pname=$0 usage() { - echo "Usage: $pname branch test|release" 1>&2 + echo "usage: $pname branch test|release" 1>&2 exit 1 } @@ -2475,8 +2476,8 @@ you are rewriting history. Keeping a patch series up to date using git rebase -------------------------------------------------- -Suppose that you create a branch "mywork" on a remote-tracking branch -"origin", and create some commits on top of it: +Suppose that you create a branch `mywork` on a remote-tracking branch +`origin`, and create some commits on top of it: ------------------------------------------------- $ git checkout -b mywork origin @@ -2488,7 +2489,7 @@ $ git commit ------------------------------------------------- You have performed no merges into mywork, so it is just a simple linear -sequence of patches on top of "origin": +sequence of patches on top of `origin`: ................................................ o--o--O <-- origin @@ -2497,7 +2498,7 @@ sequence of patches on top of "origin": ................................................ Some more interesting work has been done in the upstream project, and -"origin" has advanced: +`origin` has advanced: ................................................ o--o--O--o--o--o <-- origin @@ -2505,7 +2506,7 @@ Some more interesting work has been done in the upstream project, and a--b--c <-- mywork ................................................ -At this point, you could use "pull" to merge your changes back in; +At this point, you could use `pull` to merge your changes back in; the result would create a new merge commit, like this: ................................................ @@ -2524,7 +2525,7 @@ $ git rebase origin ------------------------------------------------- This will remove each of your commits from mywork, temporarily saving -them as patches (in a directory named ".git/rebase-apply"), update mywork to +them as patches (in a directory named `.git/rebase-apply`), update mywork to point at the latest version of origin, then apply each of the saved patches to the new mywork. The result will look like: @@ -2795,10 +2796,10 @@ arbitrary name: $ git fetch origin todo:my-todo-work ------------------------------------------------- -The first argument, "origin", just tells Git to fetch from the +The first argument, `origin`, just tells Git to fetch from the repository you originally cloned from. The second argument tells Git -to fetch the branch named "todo" from the remote repository, and to -store it locally under the name refs/heads/my-todo-work. +to fetch the branch named `todo` from the remote repository, and to +store it locally under the name `refs/heads/my-todo-work`. You can also fetch branches from other repositories; so @@ -2806,8 +2807,8 @@ You can also fetch branches from other repositories; so $ git fetch git://example.com/proj.git master:example-master ------------------------------------------------- -will create a new branch named "example-master" and store in it the -branch named "master" from the repository at the given URL. If you +will create a new branch named `example-master` and store in it the +branch named `master` from the repository at the given URL. If you already have a branch named example-master, it will attempt to <<fast-forwards,fast-forward>> to the commit given by example.com's master branch. In more detail: @@ -2816,7 +2817,7 @@ master branch. In more detail: git fetch and fast-forwards --------------------------- -In the previous example, when updating an existing branch, "git fetch" +In the previous example, when updating an existing branch, `git fetch` checks to make sure that the most recent commit on the remote branch is a descendant of the most recent commit on your copy of the branch before updating your copy of the branch to point at the new @@ -2842,11 +2843,11 @@ resulting in a situation like: o--o--o <-- new head of the branch ................................................ -In this case, "git fetch" will fail, and print out a warning. +In this case, `git fetch` will fail, and print out a warning. In that case, you can still force Git to update to the new head, as described in the following section. However, note that in the -situation above this may mean losing the commits labeled "a" and "b", +situation above this may mean losing the commits labeled `a` and `b`, unless you've already created a reference of your own pointing to them. @@ -2861,7 +2862,7 @@ descendant of the old head, you may force the update with: $ git fetch git://example.com/proj.git +master:refs/remotes/example/master ------------------------------------------------- -Note the addition of the "+" sign. Alternatively, you can use the "-f" +Note the addition of the `+` sign. Alternatively, you can use the `-f` flag to force updates of all the fetched branches, as in: ------------------------------------------------- @@ -2875,7 +2876,7 @@ may be lost, as we saw in the previous section. Configuring remote-tracking branches ------------------------------------ -We saw above that "origin" is just a shortcut to refer to the +We saw above that `origin` is just a shortcut to refer to the repository that you originally cloned from. This information is stored in Git configuration variables, which you can see using linkgit:git-config[1]: @@ -2984,7 +2985,7 @@ Commit Object ~~~~~~~~~~~~~ The "commit" object links a physical state of a tree with a description -of how we got there and why. Use the --pretty=raw option to +of how we got there and why. Use the `--pretty=raw` option to linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite commit: @@ -3026,7 +3027,7 @@ of the tree referred to by this commit with the trees associated with its parents. In particular, Git does not attempt to record file renames explicitly, though it can identify cases where the existence of the same file data at changing paths suggests a rename. (See, for example, the --M option to linkgit:git-diff[1]). +`-M` option to linkgit:git-diff[1]). A commit is usually created by linkgit:git-commit[1], which creates a commit whose parent is normally the current HEAD, and whose tree is @@ -3077,7 +3078,7 @@ Blob Object ~~~~~~~~~~~ You can use linkgit:git-show[1] to examine the contents of a blob; take, -for example, the blob in the entry for "COPYING" from the tree above: +for example, the blob in the entry for `COPYING` from the tree above: ------------------------------------------------ $ git show 6ff87c4664 @@ -3160,14 +3161,14 @@ nLE/L9aUXdWeTFPron96DLA= See the linkgit:git-tag[1] command to learn how to create and verify tag objects. (Note that linkgit:git-tag[1] can also be used to create "lightweight tags", which are not tag objects at all, but just simple -references whose names begin with "refs/tags/"). +references whose names begin with `refs/tags/`). [[pack-files]] How Git stores objects efficiently: pack files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Newly created objects are initially created in a file named after the -object's SHA-1 hash (stored in .git/objects). +object's SHA-1 hash (stored in `.git/objects`). Unfortunately this system becomes inefficient once a project has a lot of objects. Try this on an old project: @@ -3208,9 +3209,9 @@ $ git prune to remove any of the "loose" objects that are now contained in the pack. This will also remove any unreferenced objects (which may be -created when, for example, you use "git reset" to remove a commit). +created when, for example, you use `git reset` to remove a commit). You can verify that the loose objects are gone by looking at the -.git/objects directory or by running +`.git/objects` directory or by running ------------------------------------------------ $ git count-objects @@ -3237,7 +3238,7 @@ branch still exists, as does everything it pointed to. The branch pointer itself just doesn't, since you replaced it with another one. There are also other situations that cause dangling objects. For -example, a "dangling blob" may arise because you did a "git add" of a +example, a "dangling blob" may arise because you did a `git add` of a file, but then, before you actually committed it and made it part of the bigger picture, you changed something else in that file and committed that *updated* thing--the old state that you added originally ends up @@ -3280,14 +3281,14 @@ $ git show <dangling-blob/tree-sha-goes-here> ------------------------------------------------ to show what the contents of the blob were (or, for a tree, basically -what the "ls" for that directory was), and that may give you some idea +what the `ls` for that directory was), and that may give you some idea of what the operation was that left that dangling object. Usually, dangling blobs and trees aren't very interesting. They're almost always the result of either being a half-way mergebase (the blob will often even have the conflict markers from a merge in it, if you have had conflicting merges that you fixed up by hand), or simply -because you interrupted a "git fetch" with ^C or something like that, +because you interrupted a `git fetch` with ^C or something like that, leaving _some_ of the new objects in the object database, but just dangling and useless. @@ -3298,16 +3299,16 @@ state, you can just prune all unreachable objects: $ git prune ------------------------------------------------ -and they'll be gone. But you should only run "git prune" on a quiescent +and they'll be gone. But you should only run `git prune` on a quiescent repository--it's kind of like doing a filesystem fsck recovery: you don't want to do that while the filesystem is mounted. -(The same is true of "git fsck" itself, btw, but since +(The same is true of `git fsck` itself, btw, but since `git fsck` never actually *changes* the repository, it just reports on what it found, `git fsck` itself is never 'dangerous' to run. Running it while somebody is actually changing the repository can cause confusing and scary messages, but it won't actually do anything bad. In -contrast, running "git prune" while somebody is actively changing the +contrast, running `git prune` while somebody is actively changing the repository is a *BAD* idea). [[recovering-from-repository-corruption]] @@ -3345,7 +3346,7 @@ missing blob 4b9458b3786228369c63936db65827de3cc06200 Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 points to it. If you could find just one copy of that missing blob object, possibly in some other repository, you could move it into -.git/objects/4b/9458b3... and be done. Suppose you can't. You can +`.git/objects/4b/9458b3...` and be done. Suppose you can't. You can still examine the tree that pointed to it with linkgit:git-ls-tree[1], which might output something like: @@ -3360,10 +3361,10 @@ $ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 ------------------------------------------------ So now you know that the missing blob was the data for a file named -"myfile". And chances are you can also identify the directory--let's -say it's in "somedirectory". If you're lucky the missing copy might be +`myfile`. And chances are you can also identify the directory--let's +say it's in `somedirectory`. If you're lucky the missing copy might be the same as the copy you have checked out in your working tree at -"somedirectory/myfile"; you can test whether that's right with +`somedirectory/myfile`; you can test whether that's right with linkgit:git-hash-object[1]: ------------------------------------------------ @@ -3418,7 +3419,7 @@ $ git hash-object -w <recreated-file> and your repository is good again! -(Btw, you could have ignored the fsck, and started with doing a +(Btw, you could have ignored the `fsck`, and started with doing a ------------------------------------------------ $ git log --raw --all @@ -3432,7 +3433,7 @@ just missing one particular blob version. The index ----------- -The index is a binary file (generally kept in .git/index) containing a +The index is a binary file (generally kept in `.git/index`) containing a sorted list of path names, each with permissions and the SHA-1 of a blob object; linkgit:git-ls-files[1] can show you the contents of the index: @@ -3572,7 +3573,7 @@ $ ls -a The `git submodule add <repo> <path>` command does a couple of things: -- It clones the submodule from <repo> to the given <path> under the +- It clones the submodule from `<repo>` to the given `<path>` under the current directory and by default checks out the master branch. - It adds the submodule's clone path to the linkgit:gitmodules[5] file and adds this file to the index, ready to be committed. @@ -3700,11 +3701,11 @@ Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path In older Git versions it could be easily forgotten to commit new or modified files in a submodule, which silently leads to similar problems as not pushing -the submodule changes. Starting with Git 1.7.0 both "git status" and "git diff" +the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff` in the superproject show submodules as modified when they contain new or -modified files to protect against accidentally committing such a state. "git -diff" will also add a "-dirty" to the work tree side when generating patch -output or used with the --submodule option: +modified files to protect against accidentally committing such a state. `git +diff` will also add a `-dirty` to the work tree side when generating patch +output or used with the `--submodule` option: ------------------------------------------------- $ git diff @@ -3880,7 +3881,7 @@ or, if you want to check out all of the index, use `-a`. NOTE! `git checkout-index` normally refuses to overwrite old files, so if you have an old version of the tree already checked out, you will -need to use the "-f" flag ('before' the "-a" flag or the filename) to +need to use the `-f` flag ('before' the `-a` flag or the filename) to 'force' the checkout. @@ -3891,7 +3892,7 @@ from one representation to the other: Tying it all together ~~~~~~~~~~~~~~~~~~~~~ -To commit a tree you have instantiated with "git write-tree", you'd +To commit a tree you have instantiated with `git write-tree`, you'd create a "commit" object that refers to that tree and the history behind it--most notably the "parent" commits that preceded it in history. @@ -4152,8 +4153,9 @@ As a result, the general consistency of an object can always be tested independently of the contents or the type of the object: all objects can be validated by verifying that (a) their hashes match the content of the file and (b) the object successfully inflates to a stream of bytes that -forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal -size> {plus} <byte\0> {plus} <binary object data>. +forms a sequence of +`<ascii type without space> + <space> + <ascii decimal size> + +<byte\0> + <binary object data>`. The structured objects can further have their structure and connectivity to other objects verified. This is generally done with @@ -4632,10 +4634,10 @@ Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading everything in between. -Scan Documentation/ for other stuff left out; in particular: +Scan `Documentation/` for other stuff left out; in particular: - howto's -- some of technical/? +- some of `technical/`? - hooks - list of commands in linkgit:git[1] |