diff options
Diffstat (limited to 'Documentation')
99 files changed, 1808 insertions, 510 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b1bfff630f..559d5f9ebf 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -237,6 +237,11 @@ For Python scripts: Writing Documentation: + Most (if not all) of the documentation pages are written in the + AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and + processed into HTML and manpages (e.g. git.html and git.1 in the + same directory). + 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 0000000000..c15cf2e805 --- /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 0000000000..1354ad03f5 --- /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.2.txt b/Documentation/RelNotes/1.8.2.2.txt new file mode 100644 index 0000000000..dab4831ca0 --- /dev/null +++ b/Documentation/RelNotes/1.8.2.2.txt @@ -0,0 +1,61 @@ +Git v1.8.2.2 Release Notes +========================== + +Fixes since v1.8.2.1 +-------------------- + + * Zsh completion forgot that '%' character used to signal untracked + files needs to be escaped with another '%'. + + * A commit object whose author or committer ident are malformed + crashed some code that trusted that a name, an email and an + timestamp can always be found in it. + + * The new core.commentchar configuration was not applied to a few + places. + + * "git pull --rebase" did not pass "-v/-q" options to underlying + "git rebase". + + * When receive-pack detects error in the pack header it received in + order to decide which of unpack-objects or index-pack to run, it + returned without closing the error stream, which led to a hang + sideband thread. + + * "git diff --diff-algorithm=algo" was understood by the command line + parser, but "git diff --diff-algorithm algo" was not. + + * "git log -S/-G" started paying attention to textconv filter, but + there was no way to disable this. Make it honor --no-textconv + option. + + * "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. + + * "git cherry-pick" and "git revert" can take more than one commit + on the command line these days, but it was not mentioned on the usage + text. + + * 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. + + * "git apply --whitespace=fix" was not prepared to see a line getting + longer after fixing whitespaces (e.g. tab-in-indent aka Python). + + * "git diff/log --cc" did not work well with options that ignore + whitespace changes. + + * Documentation on setting up a http server that requires + authentication only on the push but not fetch has been clarified. + + * A few bugfixes to "git rerere" working on corner case merge + conflicts have been applied. + + * "git bundle" did not like a bundle created using a commit without + any message as its one of the prerequistes. diff --git a/Documentation/RelNotes/1.8.2.3.txt b/Documentation/RelNotes/1.8.2.3.txt new file mode 100644 index 0000000000..613948251a --- /dev/null +++ b/Documentation/RelNotes/1.8.2.3.txt @@ -0,0 +1,19 @@ +Git v1.8.2.3 Release Notes +========================== + +Fixes since v1.8.2.2 +-------------------- + + * "rev-list --stdin" and friends kept bogus pointers into the input + buffer around as human readable object names. This was not a + huge problem but was exposed by a new change that uses these + names in error output. + + * When "git difftool" drove "kdiff3", it mistakenly passed --auto + option that was meant while resolving merge conflicts. + + * "git remote add" command did not diagnose extra command line + arguments as an error and silently ignored them. + +Also contains a handful of trivial code clean-ups, documentation +updates, updates to the test suite, etc. diff --git a/Documentation/RelNotes/1.8.3.txt b/Documentation/RelNotes/1.8.3.txt new file mode 100644 index 0000000000..ead568e7f1 --- /dev/null +++ b/Documentation/RelNotes/1.8.3.txt @@ -0,0 +1,436 @@ +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 only the current branch to the branch with the same +name, and only when the current branch is set to integrate with that +remote branch. Use the user preference configuration variable +"push.default" to change this. If you are an old-timer who is used +to the "matching" semantics, you can set the variable to "matching" +to keep the traditional behaviour. If you want to live in the future +early, you can set it to "simple" today without waiting for Git 2.0. + +When "git add -u" (and "git add -A") is run inside a subdirectory and +does not specify which paths to add on the command line, it +will operate on the entire tree in Git 2.0 for consistency +with "git commit -a" and other commands. There will be no +mechanism to make plain "git add -u" behave like "git add -u .". +Current users of "git add -u" (without a pathspec) should start +training their fingers to explicitly say "git add -u ." +before Git 2.0 comes. A warning is issued when these commands are +run without a pathspec and when you have local changes outside the +current directory, because the behaviour in Git 2.0 will be different +from today's version in such a situation. + +In Git 2.0, "git add <path>" will behave as "git add -A <path>", so +that "git add dir/" will notice paths you removed from the directory +and record the removal. Versions before Git 2.0, including this +release, will keep ignoring removals, but the users who rely on this +behaviour are encouraged to start using "git add --ignore-removal <path>" +now before 2.0 is released. + + +Updates since v1.8.2 +-------------------- + +Foreign interface + + * remote-hg and remote-bzr helpers (in contrib/ since v1.8.2) have + been updated; especially, the latter has been done in an + accelerated schedule (read: we may not have merged to this release + if we were following the usual "cook sufficiently in next before + unleashing it to the world" workflow) in order to help Emacs folks, + whose primary SCM seems to be stagnating. + + +UI, Workflows & Features + + * A handful of updates applied to gitk, including an addition of + "revert" action, showing dates in tags in a nicer way, making + colors configurable, and support for -G'pickaxe' search. + + * The prompt string generator (in contrib/completion/) learned to + show how many changes there are in total and how many have been + replayed during a "git rebase" session. + + * "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). + + * In a sparsely populated working tree, "git checkout <pathspec>" no + longer unmarks paths that match the given pathspec that were + originally ignored with "--sparse" (use --ignore-skip-worktree-bits + option to resurrect these paths out of the index if you really want + to). + + * "git log --format" specifier learned %C(auto) token that tells Git + to use color when interpolating %d (decoration), %h (short commit + object name), etc. for terminal output. + + * "git bisect" leaves the final outcome as a comment in its bisect + log file. + + * "git clone --reference" can now refer to a gitfile "textual symlink" + that points at the real location of the repository. + + * "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 has been added to issue custom messages to refuse an + access over the network to help the end users who connect to the + service expecting an interactive shell. + + * 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 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 what other backends + expect. + + * "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, it now refrains from overwriting the copy in the working + tree and leaves the temporary file so that changes can be merged + manually. + + * 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. + + * A handful of issues in the code that traverses the working tree to find + untracked and/or ignored files have been fixed, and the general + codepath involved in "status -u" and "clean" have been cleaned up + and optimized. + + * 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 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 has been simplified. + + * A few codepaths know how much data they need to put in the + hashtables they use when they start, but still began with small tables + and repeatedly grew and rehashed them. + + * 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. + + * The 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 on 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). + + * Recent versions of File::Temp (used by "git svn") started blowing + up when its tempfile sub is called as a class method; updated the + callsite to call it as a plain vanilla function to fix it. + (merge eafc2dd hb/git-pm-tempfile later to maint). + + * Various subcommands of "git remote" simply ignored extraneous + command line arguments instead of diagnosing them as errors. + + * When receive-pack detects an error in the pack header it received in + order to decide which of unpack-objects or index-pack to run, it + returned without closing the error stream, which led to a hung + sideband thread. + + * Zsh completion forgot that the '%' character used to signal untracked + files needs to be escaped with another '%'. + + * A commit object whose author or committer ident are malformed + crashed some code that trusted that a name, an email and a + timestamp can always be found in it. + + * When "upload-pack" fails while generating a pack in response to + "git fetch" (or "git clone"), the receiving side had + a programming error that triggered the die handler + recursively. + + * "rev-list --stdin" and friends kept bogus pointers into the input + buffer around as human readable object names. This was not a huge + problem but was exposed by a new change that uses these names in + error output. + + * Smart-capable HTTP servers were not restricted via the + GIT_NAMESPACE mechanism when talking with commit-walking clients, + like they are 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 + the "our" side in certain cases. + (merge aacecc3 jk/merge-tree-added-identically later to maint). + + * Perl scripts like "git-svn" closed (instead of redirecting to /dev/null) + the standard error stream, which is not a very smart thing to do. + A later open may return file descriptor #2 for an unrelated purpose, and + error reporting code may write into it. + + * "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. + + * "git diff --diff-algorithm algo" is also understood as "git diff + --diff-algorithm=algo". + + * The new core.commentchar configuration was not applied in a few + places. + + * "git bundle" erroneously bailed out when parsing a valid bundle + containing a prerequisite commit without a commit message. + + * "git log -S/-G" started paying attention to textconv filter, but + there was no way to disable this. Make it honor the --no-textconv + option. + + * When used with the "-d temporary-directory" option, "git filter-branch" + failed to come back to the original working tree to perform the + final clean-up procedure. + + * "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 tag merging. + + * Fix a 1.8.1.x regression that stopped matching "dir" (without a + trailing slash) to a directory "dir". + + * "git apply --whitespace=fix" was not prepared to see a line getting + longer after fixing whitespaces (e.g. tab-in-indent aka Python). + + * The prompt string generator (in contrib/completion/) did not notice + when we are in a middle of a "git revert" session. + + * "submodule summary --summary-limit" option did not support the + "--option=value" form. + + * "index-pack --fix-thin" used an uninitialized value to compute + the delta depths of objects it appends to the resulting pack. + + * "index-pack --verify-stat" used a few counters outside the protection + of a mutex, possibly showing incorrect numbers. + + * The code to keep track of what directory names are known to Git on + platforms with case insensitive filesystems could get confused upon a + hash collision between these pathnames and would loop forever. + + * Annotated tags outside the refs/tags/ hierarchy were not advertised + correctly to ls-remote and fetch with recent versions of Git. + + * Recent optimizations broke shallow clones. + + * "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. neither 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" reported a failure when asked to create an archive out + of an empty tree. It is more intuitive to give an empty + archive back in such a case. + + * When "format-patch" quoted a non-ascii string in header files, + it incorrectly applied rfc2047 and chopped a single character in + the middle of the string. + + * An aliased command spawned from a bare repository that does not say + it is bare with "core.bare = yes" was treated as non-bare by mistake. + + * In "git reflog expire", the 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 a + base of description, did not restrict the output from the command + to those refs 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 the 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 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 to 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. It now issues errors in many cases. + + * Verification of signed tags was 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 is a common alternative + spelling of UTF-8. + + * When export-subst is used, "zip" output recorded an 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 the messages in the order the writing MUA meant to, by sorting + numeric segments in numeric order and non-numeric segments in + alphabetical order. + + * "git submodule update", when recursed into sub-submodules, did not + accumulate the prefix paths. diff --git a/Documentation/RelNotes/1.8.4.txt b/Documentation/RelNotes/1.8.4.txt new file mode 100644 index 0000000000..4d86a78fdf --- /dev/null +++ b/Documentation/RelNotes/1.8.4.txt @@ -0,0 +1,68 @@ +Git v1.8.4 Release Notes +======================== + +Updates since v1.8.3 +-------------------- + +Foreign interface + + * Remote transport helper has been updated to report errors and + maintain ref hierarchy used to keep track of its own state better. + + +UI, Workflows & Features + + * "check-ignore" (new feature since 1.8.2) has been updated to work + more like "check-attr" over bidi-pipes. + + * We used the approxidate() parser for "--expire=<timestamp>" options + of various commands, but it is better to treat --expire=all and + --expire=now a bit more specially than using the current timestamp. + "git gc" and "git reflog" have been updated with a new parsing + function for expiry dates. + + +Performance, Internal Implementation, etc. + + * Object lookup logic, when the object hashtable starts to become + crowded, has been optimized. + + * When TEST_OUTPUT_DIRECTORY setting is used, it was handled somewhat + inconsistently between the test framework and t/Makefile, and logic + to summarize the results looked at a wrong place. + + * Many warnings from sparse source checker in compat/ area has been + squelched. + + * The code to reading and updating packed-refs file has been updated, + correcting corner case bugs. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v1.8.3 +------------------ + +Unless otherwise noted, all the fixes since v1.8.3 in the maintenance +track are contained in this release (see release notes to them for +details). + + * When $HOME is misconfigured to point at an unreadable directory, we + used to complain and die. Loosen the check. + (merge 4698c8f jn/config-ignore-inaccessible later to maint). + + * "git subtree" (in contrib/) had one codepath with loose error + checks to lose data at the remote side. + (merge 3212d56 jk/subtree-do-not-push-if-split-fails later to maint). + + * "git fetch" into a shallow repository from a repository that does + not know about the shallow boundary commits (e.g. a different fork + from the repository the current shallow repository was cloned from) + did not work correctly. + (merge 71d5f93 mh/fetch-into-shallow later to maint). + + * "git checkout foo" DWIMs the intended "upstream" and turns it into + "git checkout -t -b foo remotes/origin/foo". This codepath has been + updated to correctly take existing remote definitions into account. + (merge 229177a jh/checkout-auto-tracking later to maint). diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl index 828ec62554..87437f8a95 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 bbba728d09..6e53fc5074 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 @@ -1086,11 +1104,16 @@ format.thread:: value disables threading. format.signoff:: - A boolean value which lets you enable the `-s/--signoff` option of - format-patch by default. *Note:* Adding the Signed-off-by: line to a - patch should be a conscious act and means that you certify you have - the rights to submit this work under the same open source license. - Please see the 'SubmittingPatches' document for further discussion. + A boolean value which lets you enable the `-s/--signoff` option of + format-patch by default. *Note:* Adding the Signed-off-by: line to a + patch should be a conscious act and means that you certify you have + 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 @@ -1202,7 +1225,7 @@ gitcvs.dbname:: gitcvs.dbdriver:: Used Perl DBI driver. You can specify any available driver - for this here, but it might not work. git-cvsserver is tested + for this here, but it might not work. git-cvsserver is tested with 'DBD::SQLite', reported to work with 'DBD::Pg', and reported *not* to work with 'DBD::mysql'. Experimental feature. May not contain double colons (`:`). Default: 'SQLite'. @@ -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 869d965a3b..b8a9b86375 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. @@ -480,7 +480,7 @@ endif::git-format-patch[] --ignore-submodules[=<when>]:: Ignore changes to submodules in the diff generation. <when> can be - either "none", "untracked", "dirty" or "all", which is the default + either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index b0944e57d5..48754cbc67 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -9,9 +9,9 @@ SYNOPSIS -------- [verse] 'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] - [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N] - [--refresh] [--ignore-errors] [--ignore-missing] [--] - [<pathspec>...] + [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] + [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] + [--] [<pathspec>...] DESCRIPTION ----------- @@ -111,6 +111,7 @@ of Git, hence the form without <pathspec> should not be used. -A:: --all:: +--no-ignore-removal:: Update the index not only where the working tree has a file matching <pathspec> but also where the index already has an entry. This adds, modifies, and removes index entries to @@ -121,6 +122,19 @@ If no <pathspec> is given, the current version of Git defaults to and its subdirectories. This default will change in a future version of Git, hence the form without <pathspec> should not be used. +--no-all:: +--ignore-removal:: + Update the index by adding new files that are unknown to the + index and files modified in the working tree, but ignore + files that have been removed from the working tree. This + option is a no-op when no <pathspec> is used. ++ +This option is primarily to help the current users of Git, whose +"git add <pathspec>..." ignores removed files. In future versions +of Git, "git add <pathspec>..." will be a synonym to "git add -A +<pathspec>..." and "git add --ignore-removal <pathspec>..." will behave like +today's "git add <pathspec>...", ignoring removed files. + -N:: --intent-to-add:: Record only the fact that the path will be added later. An entry diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 19d57a80f5..5bbe7b6d10 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,12 +9,12 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git am' [--signoff] [--keep] [--keep-cr | --no-keep-cr] [--utf8 | --no-utf8] +'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] - [--scissors | --no-scissors] + [--[no-]scissors] [(<mbox> | <Maildir>)...] 'git am' (--continue | --skip | --abort) @@ -43,8 +43,7 @@ OPTIONS --keep-non-patch:: Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). ---keep-cr:: ---no-keep-cr:: +--[no-]keep-cr:: With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) with the same option, to prevent it from stripping CR at the end of lines. `am.keepcr` configuration variable can be used to specify the diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index b4c2e24849..b97aaab4ed 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] - [-o | --output=<file>] [--worktree-attributes] + [-o <file> | --output=<file>] [--worktree-attributes] [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> [<path>...] @@ -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 2fb95bbd19..30d585af5d 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-check-attr.txt b/Documentation/git-check-attr.txt index 5abdbaa51c..a7be80d48b 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -56,6 +56,11 @@ being queried and <info> can be either: 'set';; when the attribute is defined as true. <value>;; when a value has been assigned to the attribute. +Buffering happens as documented under the `GIT_FLUSH` option in +linkgit:git[1]. The caller is responsible for avoiding deadlocks +caused by overfilling an input buffer or reading from an empty output +buffer. + EXAMPLES -------- diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 854e4d0c42..8e1f7ab7ea 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -39,6 +39,12 @@ OPTIONS below). If `--stdin` is also given, input paths are separated with a NUL character instead of a linefeed character. +-n, --non-matching:: + Show given paths which don't match any pattern. This only + makes sense when `--verbose` is enabled, otherwise it would + not be possible to distinguish between paths which match a + pattern and those which don't. + OUTPUT ------ @@ -65,6 +71,20 @@ are also used instead of colons and hard tabs: <source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL> +If `-n` or `--non-matching` are specified, non-matching pathnames will +also be output, in which case all fields in each output record except +for <pathname> will be empty. This can be useful when running +non-interactively, so that files can be incrementally streamed to +STDIN of a long-running check-ignore process, and for each of these +files, STDOUT will indicate whether that file matched a pattern or +not. (Without this option, it would be impossible to tell whether the +absence of output for a given file meant that it didn't match any +pattern, or that the output hadn't been generated yet.) + +Buffering happens as documented under the `GIT_FLUSH` option in +linkgit:git[1]. The caller is responsible for avoiding deadlocks +caused by overfilling an input buffer or reading from an empty output +buffer. EXIT STATUS ----------- diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index ec1739a896..a49be1bab4 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -83,8 +83,7 @@ typed the branch name. OPTIONS ------- ---allow-onelevel:: ---no-allow-onelevel:: +--[no-]allow-onelevel:: Controls whether one-level refnames are accepted (i.e., refnames that do not contain multiple `/`-separated components). The default is `--no-allow-onelevel`. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 8edcdcae9d..ca118ac6bf 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -131,9 +131,9 @@ entries; instead, unmerged entries are ignored. "--track" in linkgit:git-branch[1] for details. + If no '-b' option is given, the name of the new branch will be -derived from the remote-tracking branch. If "remotes/" or "refs/remotes/" -is prefixed it is stripped away, and then the part up to the -next slash (which would be the nickname of the remote) is removed. +derived from the remote-tracking branch, by looking at the local part of +the refspec configured for the corresponding remote, and then stripping +the initial part up to the "*". This would tell us to use "hack" as the local branch when branching off of "origin/hack" (or "remotes/origin/hack", or even "refs/remotes/origin/hack"). If the given name has no slash, or the above @@ -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-clone.txt b/Documentation/git-clone.txt index 5c16e317f6..a0727d7759 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -14,7 +14,7 @@ SYNOPSIS [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--separate-git-dir <git dir>] [--depth <depth>] [--[no-]single-branch] - [--recursive|--recurse-submodules] [--] <repository> + [--recursive | --recurse-submodules] [--] <repository> [<directory>] DESCRIPTION @@ -188,7 +188,7 @@ objects from the source repository into a pack in the cloned repository. with a long history, and would want to send in fixes as patches. ---single-branch:: +--[no-]single-branch:: Clone only the history leading to the tip of a single branch, either specified by the `--branch` option or the primary branch remote's `HEAD` points at. When creating a shallow diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 86ef56e7c8..cafdc9642d 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 0eb79ccdba..1a7616c73a 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -12,7 +12,7 @@ SYNOPSIS [--dry-run] [(-c | -C | --fixup | --squash) <commit>] [-F <file> | -m <msg>] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] - [--date=<date>] [--cleanup=<mode>] [--status | --no-status] + [--date=<date>] [--cleanup=<mode>] [--[no-]status] [-i | -o] [-S[<keyid>]] [--] [<file>...] DESCRIPTION @@ -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,22 +174,31 @@ 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:: The message taken from file with `-F`, command line with - `-m`, and from file with `-C` are usually used as the - commit log message unmodified. This option lets you + `-m`, and from commit object with `-C` are usually used as + the commit log message unmodified. This option lets you further edit the message taken from these sources. --no-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-config.txt b/Documentation/git-config.txt index 9ae2508f3f..d88a6fcb29 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -186,8 +186,7 @@ See also <<FILES>>. Opens an editor to modify the specified config file; either '--system', '--global', or repository (default). ---includes:: ---no-includes:: +--[no-]includes:: Respect `include.*` directives in config files when looking up values. Defaults to on. diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 23c80cea64..b300e846f1 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 472f00f607..7da0f13a5c 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 77da564134..223f731523 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -16,8 +16,10 @@ SYNOPSIS [--reuseaddr] [--detach] [--pid-file=<file>] [--enable=<service>] [--disable=<service>] [--allow-override=<service>] [--forbid-override=<service>] - [--access-hook=<path>] - [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]] + [--access-hook=<path>] [--[no-]informative-errors] + [--inetd | + [--listen=<host_or_ipaddr>] [--port=<n>] + [--user=<user> [--group=<group>]]] [<directory>...] DESCRIPTION @@ -147,6 +149,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>:: @@ -162,8 +171,7 @@ the facility of inet daemon to achieve the same before spawning repository configuration. By default, all the services are overridable. ---informative-errors:: ---no-informative-errors:: +--[no-]informative-errors:: When informative errors are turned on, git-daemon will report more verbose errors to the client, differentiating conditions like "no such repository" from "repository not exported". This diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 32da244fd5..28e5ec0e2c 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-diff-index.txt b/Documentation/git-diff-index.txt index c0b7c581ad..a86cf62e68 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -3,7 +3,7 @@ git-diff-index(1) NAME ---- -git-diff-index - Compares content and mode of blobs between the index and repository +git-diff-index - Compare a tree to the working tree or index SYNOPSIS @@ -13,11 +13,11 @@ SYNOPSIS DESCRIPTION ----------- -Compares the content and mode of the blobs found via a tree -object with the content of the current index and, optionally -ignoring the stat state of the file on disk. When paths are -specified, compares only those named paths. Otherwise all -entries in the index are compared. +Compares the content and mode of the blobs found in a tree object +with the corresponding tracked files in the working tree, or with the +corresponding paths in the index. When <path> arguments are present, +compares only paths matching those patterns. Otherwise all tracked +files are compared. OPTIONS ------- diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index e0e12e9470..11887e63a0 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -69,13 +69,14 @@ with custom merge tool commands and has the same value as `$MERGED`. --tool-help:: Print a list of diff tools that may be used with `--tool`. ---symlinks:: ---no-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 d6487e1ce0..efb03806f5 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -27,15 +27,17 @@ OPTIONS Insert 'progress' statements every <n> objects, to be shown by 'git fast-import' during import. ---signed-tags=(verbatim|warn|strip|abort):: +--signed-tags=(verbatim|warn|warn-strip|strip|abort):: Specify how to handle signed tags. Since any transformation after the export can change the tag names (which can also happen when excluding revisions) the signatures will not match. + When asking to 'abort' (which is the default), this program will die -when encountering a signed tag. With 'strip', the tags will be made -unsigned, with 'verbatim', they will be silently exported -and with 'warn', they will be exported, but you will see a warning. +when encountering a signed tag. With 'strip', the tags will silently +be made unsigned, with 'warn-strip' they will be made unsigned but a +warning will be displayed, with 'verbatim', they will be silently +exported and with 'warn', they will be exported, but you will see a +warning. --tag-of-filtered-object=(abort|drop|rewrite):: Specify how to handle tags whose tagged object is filtered out. @@ -66,6 +68,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 @@ -102,11 +106,11 @@ marks the same across runs. different from the commit's first parent). [<git-rev-list-args>...]:: - A list of arguments, acceptable to 'git rev-parse' and - 'git rev-list', that specifies the specific objects and references - to export. For example, `master~10..master` causes the - current master reference to be exported along with all objects - added since its 10th ancestor commit. + A list of arguments, acceptable to 'git rev-parse' and + 'git rev-list', that specifies the specific objects and references + to export. For example, `master~10..master` causes the + current master reference to be exported along with all objects + added since its 10th ancestor commit. EXAMPLES -------- diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index b81e90d8e7..1e71754347 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -10,9 +10,9 @@ SYNOPSIS -------- [verse] 'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] - [--upload-pack=<git-upload-pack>] - [--depth=<n>] [--no-progress] - [-v] [<host>:]<directory> [<refs>...] + [--upload-pack=<git-upload-pack>] + [--depth=<n>] [--no-progress] + [-v] [<host>:]<directory> [<refs>...] DESCRIPTION ----------- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index dfd12c94e4..e4c8e82660 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-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 3a0f55ec8e..bb1232a52c 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -35,8 +35,7 @@ OPTIONS Do not list one-line descriptions from the actual commits being merged. ---summary:: ---no-summary:: +--[no-]summary:: Synonyms to --log and --no-log; these are deprecated and will be removed in the future. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 3a62f50eda..39118774af 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 eff91889d7..25c431d3c5 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -23,15 +23,14 @@ 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:: Print out objects that exist but that aren't reachable from any of the reference nodes. ---dangling:: ---no-dangling:: +--[no-]dangling:: Print objects that exist but that are never 'directly' used (default). `--no-dangling` can be used to omit this information from the output. @@ -78,8 +77,7 @@ index file, all SHA1 references in `refs` namespace, and all reflogs a blob, the contents are written into the file, rather than its object name. ---progress:: ---no-progress:: +--[no-]progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless --no-progress or --verbose is specified. --progress forces @@ -89,7 +87,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-gc.txt b/Documentation/git-gc.txt index b370b025b8..2402ed6828 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -62,8 +62,9 @@ automatic consolidation of packs. --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, - overridable by the config variable `gc.pruneExpire`). This - option is on by default. + overridable by the config variable `gc.pruneExpire`). + --prune=all prunes loose objects regardless of their age. + --prune is on by default. --no-prune:: Do not prune any loose objects. diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 50d46e1a7b..8497aa4494 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -25,7 +25,7 @@ SYNOPSIS [-W | --function-context] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] - [ [--exclude-standard] [--cached | --no-index | --untracked] | <tree>...] + [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...] [--] [<pathspec>...] DESCRIPTION diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index e07b6dc19a..b21e9d79be 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 7b1e85cd15..e3bcdb50e3 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 36adc5fc14..bde8eec30d 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-log.txt b/Documentation/git-log.txt index 69db5783ce..a976534ab8 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -9,7 +9,7 @@ git-log - Show commit logs SYNOPSIS -------- [verse] -'git log' [<options>] [<since>..<until>] [[\--] <path>...] +'git log' [<options>] [<revision range>] [[\--] <path>...] DESCRIPTION ----------- @@ -24,13 +24,6 @@ each commit introduces are shown. OPTIONS ------- -<since>..<until>:: - Show only commits between the named two commits. When - either <since> or <until> is omitted, it defaults to - `HEAD`, i.e. the tip of the current branch. - For a more complete list of ways to spell <since> - and <until>, see linkgit:gitrevisions[7]. - --follow:: Continue listing the history of a file beyond renames (works only for a single file). @@ -69,14 +62,23 @@ produced by --stat etc. Note that only message is considered, if also a diff is shown its size is not included. +<revision range>:: + Show only commits in the specified revision range. When no + <revision range> is specified, it defaults to `HEAD` (i.e. the + whole history leading to the current commit). `origin..HEAD` + specifies all the commits reachable from the current commit + (i.e. `HEAD`), but not from `origin`. For a complete list of + ways to spell <revision range>, see the "Specifying Ranges" + section of linkgit:gitrevisions[7]. + [\--] <path>...:: Show only commits that are enough to explain how the files that match the specified paths came to be. See "History Simplification" below for details and other simplification modes. + -To prevent confusion with options and branch names, paths may need to -be prefixed with "\-- " to separate them from options or refnames. +Paths may need to be prefixed with "\-- " to separate them from +options or the revision range, when confusion arises. include::rev-list-options.txt[] diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 0bdebff6f7..c0856a6e0a 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-mailinfo.txt b/Documentation/git-mailinfo.txt index 97e7a8e9e7..164a3c6ede 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -9,7 +9,7 @@ git-mailinfo - Extracts patch and authorship from a single e-mail message SYNOPSIS -------- [verse] -'git mailinfo' [-k|-b] [-u | --encoding=<encoding> | -n] [--scissors] <msg> <patch> +'git mailinfo' [-k|-b] [-u | --encoding=<encoding> | -n] [--[no-]scissors] <msg> <patch> DESCRIPTION diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 0c80cec0e8..02676fb391 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 c852a2677a..67ca99cd92 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -76,8 +76,7 @@ The 'git fmt-merge-msg' command can be used to give a good default for automated 'git merge' invocations. ---rerere-autoupdate:: ---no-rerere-autoupdate:: +--[no-]rerere-autoupdate:: Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. @@ -170,6 +169,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-mergetool.txt b/Documentation/git-mergetool.txt index 6b563c500f..07137f252b 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -8,7 +8,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts SYNOPSIS -------- [verse] -'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...] +'git mergetool' [--tool=<tool>] [-y | --[no-]prompt] [<file>...] DESCRIPTION ----------- diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 69c9313cf5..d94edcd4b4 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 90268f02e7..312c3b1fe5 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 c975743230..24ab07a3f8 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 13980257ee..d51481394c 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 @@ -151,8 +162,7 @@ useful if you write an alias or script around 'git push'. linkgit:git-pull[1] and other commands. For more information, see 'branch.<name>.merge' in linkgit:git-config[1]. ---thin:: ---no-thin:: +--[no-]thin:: These options are passed to linkgit:git-send-pack[1]. A thin transfer significantly reduces the amount of sent data when the sender and receiver share many of the same objects in common. The default is diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index fb8697ea4c..70791b9fd8 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -67,14 +67,19 @@ them. --expire=<time>:: Entries older than this time are pruned. Without the option it is taken from configuration `gc.reflogExpire`, - which in turn defaults to 90 days. + which in turn defaults to 90 days. --expire=all prunes + entries regardless of their age; --expire=never turns off + pruning of reachable entries (but see --expire-unreachable). --expire-unreachable=<time>:: Entries older than this time and not reachable from the current tip of the branch are pruned. Without the option it is taken from configuration `gc.reflogExpireUnreachable`, which in turn defaults to - 30 days. + 30 days. --expire-unreachable=all prunes unreachable + entries regardless of their age; --expire-unreachable=never + turns off early pruning of unreachable entries (but see + --expire). --all:: Instead of listing <refs> explicitly, prune all refs. diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 58b7facb09..8cfc748ae2 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-remote.txt b/Documentation/git-remote.txt index e8c396b5f9..581bb4c413 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror=<fetch|push>] <name> <url> +'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=<fetch|push>] <name> <url> 'git remote rename' <old> <new> 'git remote remove' <name> 'git remote set-head' <name> (-a | -d | <branch>) @@ -18,8 +18,8 @@ SYNOPSIS 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> 'git remote set-url --delete' [--push] <name> <url> -'git remote' [-v | --verbose] 'show' [-n] <name> -'git remote prune' [-n | --dry-run] <name> +'git remote' [-v | --verbose] 'show' [-n] <name>... +'git remote prune' [-n | --dry-run] <name>... 'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...] DESCRIPTION diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 0142cd18ae..e0b4057976 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 10a116faf8..947d62fd25 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-revert.txt b/Documentation/git-revert.txt index 70152e8b1e..f79c9d8583 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -8,7 +8,7 @@ git-revert - Revert some existing commits SYNOPSIS -------- [verse] -'git revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit>... +'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] <commit>... 'git revert' --continue 'git revert' --quit 'git revert' --abort diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 92bac27e05..1d876c2619 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 44a1f7c4e8..40a9a9abc1 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 6a9f66d1d9..5d709d02c3 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 9b9250600f..c35051ba58 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-shortlog.txt b/Documentation/git-shortlog.txt index c308e91537..31af7f2736 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,8 +8,8 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- [verse] -git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] -'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] <commit>... +git log --pretty=short | 'git shortlog' [<options>] +'git shortlog' [<options>] [<revision range>] [[\--] <path>...] DESCRIPTION ----------- @@ -26,10 +26,6 @@ reference to the current repository. OPTIONS ------- --h:: ---help:: - Print a short usage message and exit. - -n:: --numbered:: Sort output according to the number of commits per author instead @@ -60,6 +56,21 @@ OPTIONS If width is `0` (zero) then indent the lines of the output without wrapping them. +<revision range>:: + Show only commits in the specified revision range. When no + <revision range> is specified, it defaults to `HEAD` (i.e. the + whole history leading to the current commit). `origin..HEAD` + specifies all the commits reachable from the current commit + (i.e. `HEAD`), but not from `origin`. For a complete list of + ways to spell <revision range>, see the "Specifying Ranges" + section of linkgit:gitrevisions[7]. + +[\--] <path>...:: + Consider only commits that are enough to explain how the files + that match the specified paths came to be. ++ +Paths may need to be prefixed with "\-- " to separate them from +options or the revision range, when confusion arises. MAPPING AUTHORS --------------- diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index a8e77b5350..a515648ab0 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 9cbbed944c..fbdc8adae5 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 5dbcd47fec..de4d352da2 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 0412c4017d..9046df98a0 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 c99d795618..e5767134b1 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>...] @@ -76,6 +77,8 @@ argument <path> is the relative location for the cloned submodule to exist in the superproject. If <path> is not given, the "humanish" part of the source repository is used ("repo" for "/path/to/repo.git" and "foo" for "host.xz:foo/.git"). +The <path> is also used as the submodule's logical name in its +configuration entries unless `--name` is used to specify a logical name. + <repository> is the URL of the new submodule's origin repository. This may be either an absolute URL, or (if it begins with ./ @@ -123,8 +126,10 @@ linkgit:git-status[1] and linkgit:git-diff[1] will provide that information too (and can also report changes to a submodule's work tree). init:: - Initialize the submodules, i.e. register each submodule name - and url found in .gitmodules into .git/config. + Initialize the submodules recorded in the index (which were + added and committed elsewhere) by copying submodule + names and urls from .gitmodules to .git/config. + Optional <path> arguments limit which submodules will be initialized. It will also copy the value of `submodule.$name.update` into .git/config. The key used in .git/config is `submodule.$name.url`. @@ -135,6 +140,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 +232,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 1b8b6498cd..aad452f169 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -85,6 +85,10 @@ COMMANDS When passed to 'init' or 'clone' this regular expression will be preserved as a config key. See 'fetch' for a description of '--ignore-paths'. +--include-paths=<regex>;; + When passed to 'init' or 'clone' this regular expression will + be preserved as a config key. See 'fetch' for a description + of '--include-paths'. --no-minimize-url;; When tracking multiple directories (using --stdlayout, --branches, or --tags options), git svn will attempt to connect @@ -146,6 +150,14 @@ Skip "branches" and "tags" of first level directories;; ------------------------------------------------------------------------ -- +--include-paths=<regex>;; + This allows one to specify a Perl regular expression that will + cause the inclusion of only matching paths from checkout from SVN. + The '--include-paths' option should match for every 'fetch' + (including automatic fetches due to 'clone', 'dcommit', + 'rebase', etc) on a given repository. '--ignore-paths' takes + precedence over '--include-paths'. + --log-window-size=<n>;; Fetch <n> log entries per request when scanning Subversion history. The default is 100. For very large Subversion repositories, larger @@ -245,7 +257,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. @@ -259,13 +271,15 @@ first have already been pushed into SVN. Create a tag by using the tags_subdir instead of the branches_subdir specified during git svn init. --d;; ---destination;; +-d<path>;; +--destination=<path>;; + If more than one --branches (or --tags) option was given to the 'init' or 'clone' command, you must provide the location of the branch (or - tag) you wish to create in the SVN repository. The value of this - option must match one of the paths specified by a --branches (or - --tags) option. You can see these paths with the commands + tag) you wish to create in the SVN repository. <path> specifies which + path to use to create the branch or tag and should match the pattern + on the left-hand side of one of the configured branches or tags + refspecs. You can see these refspecs with the commands + git config --get-all svn-remote.<name>.branches git config --get-all svn-remote.<name>.tags @@ -286,6 +300,11 @@ where <name> is the name of the SVN repository as specified by the -R option to git config --get-all svn-remote.<name>.commiturl + +--parents;; + Create parent folders. This parameter is equivalent to the parameter + --parents on svn cp commands and is useful for non-standard repository + layouts. + 'tag':: Create a tag in the SVN repository. This is a shorthand for 'branch -t'. @@ -856,7 +875,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 @@ -1020,6 +1039,25 @@ comma-separated list of names within braces. For example: tags = tags/{1.0,2.0}/src:refs/remotes/tags/* ------------------------------------------------------------------------ +Multiple fetch, branches, and tags keys are supported: + +------------------------------------------------------------------------ +[svn-remote "messy-repo"] + url = http://server.org/svn + fetch = trunk/project-a:refs/remotes/project-a/trunk + fetch = branches/demos/june-project-a-demo:refs/remotes/project-a/demos/june-demo + branches = branches/server/*:refs/remotes/project-a/branches/* + branches = branches/demos/2011/*:refs/remotes/project-a/2011-demos/* + tags = tags/server/*:refs/remotes/project-a/tags/* +------------------------------------------------------------------------ + +Creating a branch in such a configuration requires disambiguating which +location to use using the -d or --destination flag: + +------------------------------------------------------------------------ +$ git svn branch -d branches/server release-2-3-0 +------------------------------------------------------------------------ + Note that git-svn keeps track of the highest revision in which a branch or tag has appeared. If the subset of branches or tags is changed after fetching, then .git/svn/.metadata must be manually edited to remove (or diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index e3032c46c6..22894cbee6 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 ad8b823f77..78a0d955ec 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 77a912d4ea..e0a87029cd 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -14,8 +14,8 @@ SYNOPSIS [--refresh] [-q] [--unmerged] [--ignore-missing] [(--cacheinfo <mode> <object> <file>)...] [--chmod=(+|-)x] - [--assume-unchanged | --no-assume-unchanged] - [--skip-worktree | --no-skip-worktree] + [--[no-]assume-unchanged] + [--[no-]skip-worktree] [--ignore-submodules] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] @@ -77,8 +77,7 @@ OPTIONS --chmod=(+|-)x:: Set the execute permissions on the updated files. ---assume-unchanged:: ---no-assume-unchanged:: +--[no-]assume-unchanged:: When these flags are specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "assume unchanged" bit for the @@ -102,8 +101,7 @@ you will need to handle the situation manually. Like '--refresh', but checks stat information unconditionally, without regard to the "assume unchanged" setting. ---skip-worktree:: ---no-skip-worktree:: +--[no-]skip-worktree:: When one of these flags is specified, the object name recorded for the paths are not updated. Instead, these options set and unset the "skip-worktree" bit for the paths. See @@ -145,7 +143,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 +245,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 0eb9ffbdd2..526ba7be9c 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 e996135be9..f88ba96f02 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 7efaa591b8..68f1ee60cf 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,14 +43,23 @@ 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.2/git.html[documentation for release 1.8.2] +* link:v1.8.3/git.html[documentation for release 1.8.3] * release notes for + link:RelNotes/1.8.3.txt[1.8.3]. + +* link:v1.8.2.3/git.html[documentation for release 1.8.2.3] + +* release notes for + link:RelNotes/1.8.2.3.txt[1.8.2.3], + link:RelNotes/1.8.2.2.txt[1.8.2.2], + link:RelNotes/1.8.2.1.txt[1.8.2.1], link:RelNotes/1.8.2.txt[1.8.2]. -* link:v1.8.1.5/git.html[documentation for release 1.8.1.5] +* 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], @@ -739,7 +748,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 @@ -774,9 +783,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, @@ -804,8 +816,9 @@ for further details. 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', - and 'git whatchanged' will force a flush of the output stream - after each commit-oriented record have been flushed. If this + 'git check-attr', 'git check-ignore', and 'git whatchanged' will + force a flush of the output stream after each record have been + flushed. If this variable is set to "0", the output of these commands will be done using completely buffered I/O. If this environment variable is not set, Git will choose buffered or record-oriented flushing @@ -859,7 +872,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 @@ -869,9 +882,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 dc9e617a10..9ac5088acd 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 59c1c17cca..f538a870c7 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 4ed71c76cb..568d75783a 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 eab9b356cd..d48bf4d6fa 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 0c91aba861..0827f69139 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -159,11 +159,11 @@ Miscellaneous capabilities carried out. 'refspec' <refspec>:: - This modifies the 'import' capability, allowing the produced - fast-import stream to modify refs in a private namespace - instead of writing to refs/heads or refs/remotes directly. + For remote helpers that implement 'import' or 'export', this capability + allows the refs to be constrained to a private namespace, instead of + writing to refs/heads or refs/remotes directly. It is recommended that all importers providing the 'import' - capability use this. + capability use this. It's mandatory for 'export'. + A helper advertising the capability `refspec refs/heads/*:refs/svn/origin/branches/*` @@ -202,6 +202,10 @@ there is an implied `refspec *:*`. marks specified in <file> before processing any input. For details, read up on '--import-marks=<file>' in linkgit:git-fast-export[1]. +'signed-tags':: + This modifies the 'export' capability, instructing Git to pass + '--signed-tags=verbatim' to linkgit:git-fast-export[1]. In the + absence of this capability, Git will use '--signed-tags=warn-strip'. diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index f0eef765b9..d6f3393c5f 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 94c906eda8..3109ea8aad 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/gitweb.conf.txt b/Documentation/gitweb.conf.txt index eb636317be..ea0526ecc4 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -857,6 +857,13 @@ adding the following lines to your gitweb configuration file: $known_snapshot_formats{'zip'}{'disabled'} = 1; $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; +BUGS +---- +Debugging would be easier if the fallback configuration file +(`/etc/gitweb.conf`) and environment variable to override its location +('GITWEB_CONFIG_SYSTEM') had names reflecting their "fallback" role. +The current names are kept to avoid breaking working setups. + ENVIRONMENT ----------- The location of per-instance and system-wide configuration files can be diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index eb7ba84f1f..db2a74df93 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,23 +397,16 @@ 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 - another <<def_repository,repository>>. A remote-tracking - branch should not contain direct modifications or have local commits - made to it. A remote-tracking branch can usually be - identified as the right-hand-side <<def_ref,ref>> in a Pull: - <<def_refspec,refspec>>. + A <<def_ref,ref>> that is used to follow changes from another + <<def_repository,repository>>. It typically looks like + 'refs/remotes/foo/bar' (indicating that it tracks a branch named + 'bar' in a remote named 'foo'), and matches the right-hand-side of + a configured fetch <<def_refspec,refspec>>. A remote-tracking + branch should not contain direct modifications or have local + commits made to it. [[def_repository]]repository:: A collection of <<def_ref,refs>> together with an @@ -430,9 +421,7 @@ should not be combined with other pathspec. <<def_merge,merge>> left behind. [[def_revision]]revision:: - A particular state of files and directories which was stored in the - <<def_object_database,object database>>. It is referenced by a - <<def_commit_object,commit object>>. + Synonym for <<def_commit,commit>> (the noun). [[def_rewind]]rewind:: To throw away part of the development, i.e. to assign the @@ -441,8 +430,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 +446,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 6d362ceb10..1b3b188d3c 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 0bcbe0ac3c..afba8d4f3b 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -8,12 +8,13 @@ failed and do not autocommit, to give the user a chance to inspect and further tweak the merge result before committing. --edit:: +-e:: --no-edit:: Invoke an editor before committing successful mechanical merge to further edit the auto-generated merge message, so that the user can explain and justify the merge. The `--no-edit` option can be used to accept the auto-generated message (this is generally - discouraged). The `--edit` option is still useful if you are + discouraged). The `--edit` (or `-e`) option is still useful if you are giving a draft message with the `-m` option from the command line and want to edit it in the editor. + @@ -30,7 +31,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 +85,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 66db80296f..49a9a7d53f 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 105f18a6f9..1d174fd0b6 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 @@ -106,18 +106,22 @@ The placeholders are: - '%P': parent hashes - '%p': abbreviated parent hashes - '%an': author name -- '%aN': author name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%aN': author name (respecting .mailmap, see linkgit:git-shortlog[1] + or linkgit:git-blame[1]) - '%ae': author email -- '%aE': author email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%aE': author email (respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%ad': author date (format respects --date= option) - '%aD': author date, RFC2822 style - '%ar': author date, relative - '%at': author date, UNIX timestamp - '%ai': author date, ISO 8601 format - '%cn': committer name -- '%cN': committer name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%cN': committer name (respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%ce': committer email -- '%cE': committer email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%cE': committer email (respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%cd': committer date - '%cD': committer date, RFC2822 style - '%cr': committer date, relative @@ -131,14 +135,18 @@ 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 -- '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%gN': reflog identity name (respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%ge': reflog identity email -- '%gE': reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%gE': reflog identity email (respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%gs': reflog subject - '%Cred': switch color to red - '%Cgreen': switch color to green @@ -148,13 +156,28 @@ The placeholders are: adding `auto,` at the beginning will emit color only when colors are enabled for log output (by `color.diff`, `color.ui`, or `--color`, and respecting the `auto` settings of the former if we are going to a - terminal) + terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring + on the next placeholders until the color is switched again. - '%m': left, right or boundary mark - '%n': newline - '%%': a raw '%' - '%x00': print a byte from a hex code - '%w([<w>[,<i1>[,<i2>]]])': switch line wrapping, like the -w option of linkgit:git-shortlog[1]. +- '%<(<N>[,trunc|ltrunc|mtrunc])': make the next placeholder take at + least N columns, padding spaces on the right if necessary. + Optionally truncate at the beginning (ltrunc), the middle (mtrunc) + or the end (trunc) if the output is longer than N columns. + Note that truncating only works correctly with N >= 2. +- '%<|(<N>)': make the next placeholder take at least until Nth + columns, padding spaces on the right if necessary +- '%>(<N>)', '%>|(<N>)': similar to '%<(<N>)', '%<|(<N>)' + respectively, but padding spaces on the left +- '%>>(<N>)', '%>>|(<N>)': similar to '%>(<N>)', '%>|(<N>)' + respectively, except that if the next placeholder takes more spaces + than given and there are spaces on its left, use those spaces +- '%><(<N>)', '%><|(<N>)': similar to '% <(<N>)', '%<|(<N>)' + respectively, but padding both sides (i.e. the text is centered) NOTE: Some placeholders may depend on other options given to the revision traversal engine. For example, the `%g*` reflog options will diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 678d1756a5..d477b3f6bc 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 @@ -239,11 +244,13 @@ To summarize: '<rev1>..<rev2>':: Include commits that are reachable from <rev2> but exclude - those that are reachable from <rev1>. + those that are reachable from <rev1>. When either <rev1> or + <rev2> is omitted, it defaults to 'HEAD'. '<rev1>\...<rev2>':: Include commits that are reachable from either <rev1> or - <rev2> but exclude those that are reachable from both. + <rev2> but exclude those that are reachable from both. When + either <rev1> or <rev2> is omitted, it defaults to 'HEAD'. '<rev>{caret}@', e.g. 'HEAD{caret}@':: A suffix '{caret}' followed by an at sign is the same as listing diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index a959517b23..a6b7d83a8e 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 516fda7412..c1b42a40d3 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-directory-listing.txt b/Documentation/technical/api-directory-listing.txt index 1f349b28ae..7f8e78d916 100644 --- a/Documentation/technical/api-directory-listing.txt +++ b/Documentation/technical/api-directory-listing.txt @@ -22,12 +22,23 @@ The notable options are: `flags`:: - A bit-field of options: + A bit-field of options (the `*IGNORED*` flags are mutually exclusive): `DIR_SHOW_IGNORED`::: - The traversal is for finding just ignored files, not unignored - files. + Return just ignored files in `entries[]`, not untracked files. + +`DIR_SHOW_IGNORED_TOO`::: + + Similar to `DIR_SHOW_IGNORED`, but return ignored files in `ignored[]` + in addition to untracked files in `entries[]`. + +`DIR_COLLECT_IGNORED`::: + + Special mode for git-add. Return ignored files in `ignored[]` and + untracked files in `entries[]`. Only returns ignored files that match + pathspec exactly (no wildcards). Does not recurse into ignored + directories. `DIR_SHOW_OTHER_DIRECTORIES`::: @@ -57,6 +68,14 @@ The result of the enumeration is left in these fields: Internal use; keeps track of allocation of `entries[]` array. +`ignored[]`:: + + An array of `struct dir_entry`, used for ignored paths with the + `DIR_SHOW_IGNORED_TOO` and `DIR_COLLECT_IGNORED` flags. + +`ignored_nr`:: + + The number of members in `ignored[]` array. Calling sequence ---------------- diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 32ddc1cf13..1317db4d6c 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -41,6 +41,8 @@ The parse-options API allows: * Boolean long options can be 'negated' (or 'unset') by prepending `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely, options that begin with `no-` can be 'negated' by removing it. + Other long options can be unset (e.g., set string to NULL, set + integer to 0) by prepending `no-`. * Options and non-option arguments can clearly be separated using the `--` option, e.g. `-a -b --option -- --this-is-a-file` indicates that @@ -174,6 +176,10 @@ There are some macros to easily define options: Introduce an option with date argument, see `approxidate()`. The timestamp is put into `int_var`. +`OPT_EXPIRY_DATE(short, long, &int_var, description)`:: + Introduce an option with expiry date argument, see `parse_expiry_date()`. + The timestamp is put into `int_var`. + `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: Introduce an option with argument. The argument will be fed into the function given by `func_ptr` diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt index dbbea95db7..aa1c50f181 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 45d1c517cd..3e75497a37 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 2c59cb2259..3350d97dda 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 27c716b15f..0810251f5a 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 0e37ec9de5..8e5bf60be3 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 dbdf7ba9c8..8b7ae1c140 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/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index f1a51edf47..b898e97988 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -228,8 +228,7 @@ obtained through ref discovery. The client MUST write all obj-ids which it only has shallow copies of (meaning that it does not have the parents of a commit) as 'shallow' lines so that the server is aware of the limitations of -the client's history. Clients MUST NOT mention an obj-id which -it does not know exists on the server. +the client's history. The client now sends the maximum commit history depth it wants for this transaction, which is the number of commits it wants from the diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt index ea2f69faf5..5183b15422 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 5f36f8115f..e831cc2020 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] |