diff options
Diffstat (limited to 'Documentation')
71 files changed, 1355 insertions, 387 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 7a8037f586..06b0c57b95 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -84,7 +84,7 @@ endif # ifdef ASCIIDOC8 -ASCIIDOC_EXTRA += -a asciidoc7compatible +ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal endif ifdef DOCBOOK_XSL_172 ASCIIDOC_EXTRA += -a git-asciidoc-no-roff diff --git a/Documentation/RelNotes-1.6.3.1.txt b/Documentation/RelNotes-1.6.3.1.txt new file mode 100644 index 0000000000..2400b72ef7 --- /dev/null +++ b/Documentation/RelNotes-1.6.3.1.txt @@ -0,0 +1,10 @@ +GIT v1.6.3.1 Release Notes +========================== + +Fixes since v1.6.3 +------------------ + +* "git checkout -b new-branch" with a staged change in the index + incorrectly primed the in-index cache-tree, resulting a wrong tree + object to be written out of the index. This is a grave regression + since the last 1.6.2.X maintenance release. diff --git a/Documentation/RelNotes-1.6.3.2.txt b/Documentation/RelNotes-1.6.3.2.txt new file mode 100644 index 0000000000..b2f3f0293c --- /dev/null +++ b/Documentation/RelNotes-1.6.3.2.txt @@ -0,0 +1,61 @@ +GIT v1.6.3.2 Release Notes +========================== + +Fixes since v1.6.3.1 +-------------------- + + * A few codepaths picked up the first few bytes from an sha1[] by + casting the (char *) pointer to (int *); GCC 4.4 did not like this, + and aborted compilation. + + * Some unlink(2) failures went undiagnosed. + + * The "recursive" merge strategy misbehaved when faced rename/delete + conflicts while coming up with an intermediate merge base. + + * The low-level merge algorithm did not handle a degenerate case of + merging a file with itself using itself as the common ancestor + gracefully. It should produce the file itself, but instead + produced an empty result. + + * GIT_TRACE mechanism segfaulted when tracing a shell-quoted aliases. + + * OpenBSD also uses st_ctimspec in "struct stat", instead of "st_ctim". + + * With NO_CROSS_DIRECTORY_HARDLINKS, "make install" can be told not to + create hardlinks between $(gitexecdir)/git-$builtin_commands and + $(bindir)/git. + + * command completion code in bash did not reliably detect that we are + in a bare repository. + + * "git add ." in an empty directory complained that pathspec "." did not + match anything, which may be technically correct, but not useful. We + silently make it a no-op now. + + * "git add -p" (and "patch" action in "git add -i") was broken when + the first hunk that adds a line at the top was split into two and + both halves are marked to be used. + + * "git blame path" misbehaved at the commit where path became file + from a directory with some files in it. + + * "git for-each-ref" had a segfaulting bug when dealing with a tag object + created by an ancient git. + + * "git format-patch -k" still added patch numbers if format.numbered + configuration was set. + + * "git grep --color ''" did not terminate. The command also had + subtle bugs with its -w option. + + * http-push had a small use-after-free bug. + + * "git push" was converting OFS_DELTA pack representation into less + efficient REF_DELTA representation unconditionally upon transfer, + making the transferred data unnecessarily larger. + + * "git remote show origin" segfaulted when origin was still empty. + +Many other general usability updates around help text, diagnostic messages +and documentation are included as well. diff --git a/Documentation/RelNotes-1.6.3.3.txt b/Documentation/RelNotes-1.6.3.3.txt new file mode 100644 index 0000000000..1c28398bb6 --- /dev/null +++ b/Documentation/RelNotes-1.6.3.3.txt @@ -0,0 +1,38 @@ +GIT v1.6.3.3 Release Notes +========================== + +Fixes since v1.6.3.2 +-------------------- + + * "git archive" running on Cygwin can get stuck in an infinite loop. + + * "git daemon" did not correctly parse the initial line that carries + virtual host request information. + + * "git diff --textconv" leaked memory badly when the textconv filter + errored out. + + * The built-in regular expressions to pick function names to put on + hunk header lines for java and objc were very inefficiently written. + + * in certain error situations git-fetch (and git-clone) on Windows didn't + detect connection abort and ended up waiting indefinitely. + + * import-tars script (in contrib) did not import symbolic links correctly. + + * http.c used CURLOPT_SSLKEY even on libcURL version 7.9.2, even though + it was only available starting 7.9.3. + + * low-level filelevel merge driver used return value from strdup() + without checking if we ran out of memory. + + * "git rebase -i" left stray closing parenthesis in its reflog message. + + * "git remote show" did not show all the URLs associated with the named + remote, even though "git remote -v" did. Made them consistent by + making the former show all URLs. + + * "whitespace" attribute that is set was meant to detect all errors known + to git, but it told git to ignore trailing carriage-returns. + +Includes other documentation fixes. diff --git a/Documentation/RelNotes-1.6.3.4.txt b/Documentation/RelNotes-1.6.3.4.txt new file mode 100644 index 0000000000..cad461bc76 --- /dev/null +++ b/Documentation/RelNotes-1.6.3.4.txt @@ -0,0 +1,36 @@ +GIT v1.6.3.4 Release Notes +========================== + +Fixes since v1.6.3.3 +-------------------- + + * "git add --no-ignore-errors" did not override configured + add.ignore-errors configuration. + + * "git apply --whitespace=fix" did not fix trailing whitespace on an + incomplete line. + + * "git branch" opened too many commit objects unnecessarily. + + * "git checkout -f $commit" with a path that is a file (or a symlink) in + the work tree to a commit that has a directory at the path issued an + unnecessary error message. + + * "git diff -c/--cc" was very inefficient in coalescing the removed lines + shared between parents. + + * "git diff -c/--cc" showed removed lines at the beginning of a file + incorrectly. + + * "git remote show nickname" did not honor configured + remote.nickname.uploadpack when inspecting the branches at the remote. + + * "git request-pull" when talking to the terminal for a preview + showed some of the output in the pager. + + * "git request-pull start nickname [end]" did not honor configured + remote.nickname.uploadpack when it ran git-ls-remote against the remote + repository to learn the current tip of branches. + +Includes other documentation updates and minor fixes. + diff --git a/Documentation/RelNotes-1.6.4.1.txt b/Documentation/RelNotes-1.6.4.1.txt new file mode 100644 index 0000000000..e439e45b96 --- /dev/null +++ b/Documentation/RelNotes-1.6.4.1.txt @@ -0,0 +1,46 @@ +GIT v1.6.4.1 Release Notes +========================== + +Fixes since v1.6.4 +------------------ + + * An unquoted value in the configuration file, when it contains more than + one whitespaces in a row, got them replaced with a single space. + + * "git am" used to accept a single piece of e-mail per file (not a mbox) + as its input, but multiple input format support in v1.6.4 broke it. + Apparently many people have been depending on this feature. + + * The short help text for "git filter-branch" command was a single long + line, wrapped by terminals, and was hard to read. + + * The "recursive" strategy of "git merge" segfaulted when a merge has + more than one merge-bases, and merging of these merge-bases involves + a rename/rename or a rename/add conflict. + + * "git pull --rebase" did not use the right fork point when the + repository has already fetched from the upstream that rewinds the + branch it is based on in an earlier fetch. + + * Explain the concept of fast-forward more fully in "git push" + documentation, and hint to refer to it from an error message when the + command refuses an update to protect the user. + + * The default value for pack.deltacachesize, used by "git repack", is now + 256M, instead of unbounded. Otherwise a repack of a moderately sized + repository would needlessly eat into swap. + + * Document how "git repack" (hence "git gc") interacts with a repository + that borrows its objects from other repositories (e.g. ones created by + "git clone -s"). + + * "git show" on an annotated tag lacked a delimiting blank line between + the tag itself and the contents of the object it tags. + + * "git verify-pack -v" erroneously reported number of objects with too + deep delta depths as "chain length 0" objects. + + * Long names of authors and committers outside US-ASCII were sometimes + incorrectly shown in "gitweb". + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.4.2.txt b/Documentation/RelNotes-1.6.4.2.txt new file mode 100644 index 0000000000..c11ec0115c --- /dev/null +++ b/Documentation/RelNotes-1.6.4.2.txt @@ -0,0 +1,32 @@ +GIT v1.6.4.2 Release Notes +========================== + +Fixes since v1.6.4.1 +-------------------- + +* --date=relative output between 1 and 5 years ago rounded the number of + years when saying X years Y months ago, instead of rounding it down. + +* "git add -p" did not handle changes in executable bits correctly + (a regression around 1.6.3). + +* "git apply" did not honor GNU diff's convention to mark the creation/deletion + event with UNIX epoch timestamp on missing side. + +* "git checkout" incorrectly removed files in a directory pointed by a + symbolic link during a branch switch that replaces a directory with + a symbolic link. + +* "git clean -d -f" happily descended into a subdirectory that is managed by a + separate git repository. It now requires two -f options for safety. + +* "git fetch/push" over http transports had two rather grave bugs. + +* "git format-patch --cover-letter" did not prepare the cover letter file + for use with non-ASCII strings when there are the series contributors with + non-ASCII names. + +* "git pull origin branch" and "git fetch origin && git merge origin/branch" + left different merge messages in the resulting commit. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.4.3.txt b/Documentation/RelNotes-1.6.4.3.txt new file mode 100644 index 0000000000..4f29babdeb --- /dev/null +++ b/Documentation/RelNotes-1.6.4.3.txt @@ -0,0 +1,29 @@ +GIT v1.6.4.3 Release Notes +========================== + +Fixes since v1.6.4.2 +-------------------- + +* "git clone" from an empty repository gave unnecessary error message, + even though it did everything else correctly. + +* "git cvsserver" invoked git commands via "git-foo" style, which has long + been deprecated. + +* "git fetch" and "git clone" had an extra sanity check to verify the + presense of the corresponding *.pack file before downloading *.idx + file by issuing a HEAD request. Github server however sometimes + gave 500 (Internal server error) response to HEAD even if a GET + request for *.pack file to the same URL would have succeeded, and broke + clone over HTTP from some of their repositories. As a workaround, this + verification has been removed (as it is not absolutely necessary). + +* "git grep" did not like relative pathname to refer outside the current + directory when run from a subdirectory. + +* an error message from "git push" was formatted in a very ugly way. + +* "git svn" did not quote the subversion user name correctly when + running its author-prog helper program. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.4.4.txt b/Documentation/RelNotes-1.6.4.4.txt new file mode 100644 index 0000000000..0ead45fc72 --- /dev/null +++ b/Documentation/RelNotes-1.6.4.4.txt @@ -0,0 +1,26 @@ +GIT v1.6.4.4 Release Notes +========================== + +Fixes since v1.6.4.4 +-------------------- + +* The workaround for Github server that sometimes gave 500 (Internal server + error) response to HEAD requests in 1.6.4.3 introduced a regression that + caused re-fetching projects over http to segfault in certain cases due + to uninitialized pointer being freed. + +* "git pull" on an unborn branch used to consider anything in the work + tree and the index discardable. + +* "git diff -b/w" did not work well on the incomplete line at the end of + the file, due to an incorrect hashing of lines in the low-level xdiff + routines. + +* "git checkout-index --prefix=$somewhere" used to work when $somewhere is + a symbolic link to a directory elsewhere, but v1.6.4.2 broke it. + +* "git unpack-objects --strict", invoked when receive.fsckobjects + configuration is set in the receiving repository of "git push", did not + properly check the objects, especially the submodule links, it received. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.4.txt b/Documentation/RelNotes-1.6.4.txt new file mode 100644 index 0000000000..7a904419f7 --- /dev/null +++ b/Documentation/RelNotes-1.6.4.txt @@ -0,0 +1,147 @@ +GIT v1.6.4 Release Notes +======================== + +With the next major release, "git push" into a branch that is +currently checked out will be refused by default. You can choose +what should happen upon such a push by setting the configuration +variable receive.denyCurrentBranch in the receiving repository. + +To ease the transition plan, the receiving repository of such a +push running this release will issue a big warning when the +configuration variable is missing. Please refer to: + + http://git.or.cz/gitwiki/GitFaq#non-bare + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + +for more details on the reason why this change is needed and the +transition plan. + +For a similar reason, "git push $there :$killed" to delete the branch +$killed in a remote repository $there, if $killed branch is the current +branch pointed at by its HEAD, gets a large warning. You can choose what +should happen upon such a push by setting the configuration variable +receive.denyDeleteCurrent in the receiving repository. + + +Updates since v1.6.3 +-------------------- + +(subsystems) + + * gitweb Perl style clean-up. + + * git-svn updates, including a new --authors-prog option to map author + names by invoking an external program, 'git svn reset' to unwind + 'git svn fetch', support for more than one branches, documenting + of the useful --minimize-url feature, new "git svn gc" command, etc. + +(portability) + + * We feed iconv with "UTF-8" instead of "utf8"; the former is + understood more widely. Similarly updated test scripts to use + encoding names more widely understood (e.g. use "ISO8859-1" instead + of "ISO-8859-1"). + + * Various portability fixes/workarounds for different vintages of + SunOS, IRIX, and Windows. + + * Git-over-ssh transport on Windows supports PuTTY plink and TortoisePlink. + +(performance) + + * Many repeated use of lstat() are optimized out in "checkout" codepath. + + * git-status (and underlying git-diff-index --cached) are optimized + to take advantage of cache-tree information in the index. + +(usability, bells and whistles) + + * "git add --edit" lets users edit the whole patch text to fine-tune what + is added to the index. + + * "git am" accepts StGIT series file as its input. + + * "git bisect skip" skips to a more randomly chosen place in the hope + to avoid testing a commit that is too close to a commit that is + already known to be untestable. + + * "git cvsexportcommit" learned -k option to stop CVS keywords expansion + + * "git fast-export" learned to handle history simplification more + gracefully. + + * "git fast-export" learned an option --tag-of-filtered-object to handle + dangling tags resulting from history simplification more usefully. + + * "git grep" learned -p option to show the location of the match using the + same context hunk marker "git diff" uses. + + * https transport can optionally be told that the used client + certificate is password protected, in which case it asks the + password only once. + + * "git imap-send" is IPv6 aware. + + * "git log --graph" draws graphs more compactly by using horizontal lines + when able. + + * "git log --decorate" shows shorter refnames by stripping well-known + refs/* prefix. + + * "git push $name" honors remote.$name.pushurl if present before + using remote.$name.url. In other words, the URL used for fetching + and pushing can be different. + + * "git send-email" understands quoted aliases in .mailrc files (might + have to be backported to 1.6.3.X). + + * "git send-email" can fetch the sender address from the configuration + variable "sendmail.from" (and "sendmail.<identity>.from"). + + * "git show-branch" can color its output. + + * "add" and "update" subcommands to "git submodule" learned --reference + option to use local clone with references. + + * "git submodule update" learned --rebase option to update checked + out submodules by rebasing the local changes. + + * "gitweb" can optionally use gravatar to adorn author/committer names. + +(developers) + + * A major part of the "git bisect" wrapper has moved to C. + + * Formatting with the new version of AsciiDoc 8.4.1 is now supported. + +Fixes since v1.6.3 +------------------ + +All of the fixes in v1.6.3.X maintenance series are included in this +release, unless otherwise noted. + +Here are fixes that this release has, but have not been backported to +v1.6.3.X series. + + * "git diff-tree -r -t" used to omit new or removed directories from + the output. df533f3 (diff-tree -r -t: include added/removed + directories in the output, 2009-06-13) may need to be cherry-picked + to backport this fix. + + * The way Git.pm sets up a Repository object was not friendly to callers + that chdir around. It now internally records the repository location + as an absolute path when autodetected. + + * Removing a section with "git config --remove-section", when its + section header has a variable definition on the same line, lost + that variable definition. + + * "git rebase -p --onto" used to always leave side branches of a merge + intact, even when both branches are subject to rewriting. + + * "git repack" used to faithfully follow grafts and considered true + parents recorded in the commit object unreachable from the commit. + After such a repacking, you cannot remove grafts without corrupting + the repository. + + * "git send-email" did not detect erroneous loops in alias expansion. diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index dc76e7f073..87a90f2c3f 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -17,6 +17,7 @@ caret=^ startsb=[ endsb=] tilde=~ +backtick=` ifdef::backend-docbook[] [linkgit-inlinemacro] diff --git a/Documentation/config.txt b/Documentation/config.txt index 5dcad94f84..2632c5149e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -49,7 +49,8 @@ There is also a case insensitive alternative `[section.subsection]` syntax. In this syntax, subsection names follow the same restrictions as for section names. -All the other lines are recognized as setting variables, in the form +All the other lines (and the remainder of the line after the section +header) are recognized as setting variables, in the form 'name = value'. If there is no equal sign on the line, the entire line is taken as 'name' and the variable is recognized as boolean "true". The variable names are case-insensitive and only alphanumeric @@ -438,6 +439,11 @@ On some file system/operating system combinations, this is unreliable. Set this config setting to 'rename' there; However, This will remove the check that makes sure that existing object files will not get overwritten. +add.ignore-errors:: + Tells 'git-add' to continue adding files when some files cannot be + added due to indexing errors. Equivalent to the '--ignore-errors' + option of linkgit:git-add[1]. + alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation @@ -451,7 +457,9 @@ If the alias expansion is prefixed with an exclamation point, it will be treated as a shell command. For example, defining "alias.new = !gitk --all --not ORIG_HEAD", the invocation "git new" is equivalent to running the shell command -"gitk --all --not ORIG_HEAD". +"gitk --all --not ORIG_HEAD". Note that shell commands will be +executed from the top-level directory of a repository, which may +not necessarily be the current directory. apply.whitespace:: Tells 'git-apply' how to handle whitespaces, in the same way @@ -597,13 +605,19 @@ color.interactive.<slot>:: Use customized color for 'git-add --interactive' output. `<slot>` may be `prompt`, `header`, `help` or `error`, for four distinct types of normal output from interactive - programs. The values of these variables may be specified as + commands. The values of these variables may be specified as in color.branch.<slot>. color.pager:: A boolean to enable/disable colored output when the pager is in use (default is true). +color.showbranch:: + A boolean to enable/disable color in the output of + linkgit:git-show-branch[1]. May be set to `always`, + `false` (or `never`) or `auto` (or `true`), in which case colors are used + only when the output is to a terminal. Defaults to false. + color.status:: A boolean to enable/disable color in the output of linkgit:git-status[1]. May be set to `always`, @@ -1032,6 +1046,12 @@ http.sslKey:: over HTTPS. Can be overridden by the 'GIT_SSL_KEY' environment variable. +http.sslCertPasswordProtected:: + Enable git's password prompt for the SSL certificate. Otherwise + OpenSSL will prompt the user, possibly many times, if the + certificate or private key is encrypted. Can be overridden by the + 'GIT_SSL_CERT_PASSWORD_PROTECTED' environment variable. + http.sslCAInfo:: File containing the certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the @@ -1093,7 +1113,7 @@ instaweb.port:: linkgit:git-instaweb[1]. interactive.singlekey:: - In interactive programs, allow the user to provide one-letter + In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). Currently this is used only by the `\--patch` mode of linkgit:git-add[1]. Note that this setting is silently @@ -1198,12 +1218,20 @@ pack.compression:: pack.deltaCacheSize:: The maximum memory in bytes used for caching deltas in - linkgit:git-pack-objects[1]. - A value of 0 means no limit. Defaults to 0. + linkgit:git-pack-objects[1] before writing them out to a pack. + This cache is used to speed up the writing object phase by not + having to recompute the final delta result once the best match + for all objects is found. Repacking large repositories on machines + which are tight with memory might be badly impacted by this though, + especially if this cache pushes the system into swapping. + A value of 0 means no limit. The smallest size of 1 byte may be + used to virtually disable this cache. Defaults to 256 MiB. pack.deltaCacheLimit:: The maximum size of a delta, that is cached in - linkgit:git-pack-objects[1]. Defaults to 1000. + linkgit:git-pack-objects[1]. This cache is used to speed up the + writing object phase by not having to recompute the final delta + result once the best match for all objects is found. Defaults to 1000. pack.threads:: Specifies the number of threads to spawn when searching for best @@ -1308,6 +1336,9 @@ remote.<name>.url:: The URL of a remote repository. See linkgit:git-fetch[1] or linkgit:git-push[1]. +remote.<name>.pushurl:: + The push URL of a remote repository. See linkgit:git-push[1]. + remote.<name>.proxy:: For remotes that require curl (http, https and ftp), the URL to the proxy to use for that remote. Set to the empty string to @@ -1365,6 +1396,50 @@ rerere.enabled:: default enabled if you create `rr-cache` directory under `$GIT_DIR`, but can be disabled by setting this option to false. +sendemail.identity:: + A configuration identity. When given, causes values in the + 'sendemail.<identity>' subsection to take precedence over + values in the 'sendemail' section. The default identity is + the value of 'sendemail.identity'. + +sendemail.smtpencryption:: + See linkgit:git-send-email[1] for description. Note that this + setting is not subject to the 'identity' mechanism. + +sendemail.smtpssl:: + Deprecated alias for 'sendemail.smtpencryption = ssl'. + +sendemail.<identity>.*:: + Identity-specific versions of the 'sendemail.*' parameters + found below, taking precedence over those when the this + identity is selected, through command-line or + 'sendemail.identity'. + +sendemail.aliasesfile:: +sendemail.aliasfiletype:: +sendemail.bcc:: +sendemail.cc:: +sendemail.cccmd:: +sendemail.chainreplyto:: +sendemail.confirm:: +sendemail.envelopesender:: +sendemail.from:: +sendemail.multiedit:: +sendemail.signedoffbycc:: +sendemail.smtppass:: +sendemail.suppresscc:: +sendemail.suppressfrom:: +sendemail.to:: +sendemail.smtpserver:: +sendemail.smtpserverport:: +sendemail.smtpuser:: +sendemail.thread:: +sendemail.validate:: + See linkgit:git-send-email[1] for description. + +sendemail.signedoffcc:: + Deprecated alias for 'sendemail.signedoffbycc'. + showbranch.default:: The default set of branches for linkgit:git-show-branch[1]. See linkgit:git-show-branch[1]. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 1eeb1c7683..b71712473e 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -1,4 +1,7 @@ -The output format from "git-diff-index", "git-diff-tree", +Raw output format +----------------- + +The raw output format from "git-diff-index", "git-diff-tree", "git-diff-files" and "git diff --raw" are very similar. These commands all compare two sets of things; what is @@ -16,6 +19,9 @@ git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]:: git-diff-files [<pattern>...]:: compares the index and the files on the filesystem. +The "git-diff-tree" command begins its ouput by printing the hash of +what is being compared. After that, all the commands print one output +line per changed file. An output line is formatted this way: diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index d313795fdb..5eb2b0ee07 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -1,11 +1,13 @@ +ifndef::git-pull[] -q:: --quiet:: Pass --quiet to git-fetch-pack and silence any other internally - used programs. + used git commands. -v:: --verbose:: Be verbose. +endif::git-pull[] -a:: --append:: diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index d938b42289..e67b7e875e 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -9,8 +9,8 @@ SYNOPSIS -------- [verse] 'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] - [--all | [--update | -u]] [--intent-to-add | -N] - [--refresh] [--ignore-errors] [--] <filepattern>... + [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N] + [--refresh] [--ignore-errors] [--] [<filepattern>...] DESCRIPTION ----------- @@ -76,6 +76,15 @@ OPTIONS bypassed and the 'patch' subcommand is invoked using each of the specified filepatterns before exiting. +-e, \--edit:: + Open the diff vs. the index in an editor and let the user + edit it. After the editor was closed, adjust the hunk headers + and apply the patch to the index. ++ +*NOTE*: Obviously, if you change anything else than the first character +on lines beginning with a space or a minus, the patch will no longer +apply. + -u:: --update:: Update only files that git already knows about, staging modified diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 6d92cbee64..32e689b2bf 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -13,7 +13,7 @@ SYNOPSIS [--3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] - [--reject] + [--reject] [-q | --quiet] [<mbox> | <Maildir>...] 'git am' (--skip | --resolved | --abort) @@ -39,6 +39,10 @@ OPTIONS --keep:: Pass `-k` flag to 'git-mailinfo' (see linkgit:git-mailinfo[1]). +-q:: +--quiet:: + Be quiet. Only print error messages. + -u:: --utf8:: Pass `-u` flag to 'git-mailinfo' (see linkgit:git-mailinfo[1]). diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 9e5baa2777..735374d7df 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -3,7 +3,7 @@ git-apply(1) NAME ---- -git-apply - Apply a patch on a git index file and a working tree +git-apply - Apply a patch on a git index file and/or a working tree SYNOPSIS diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index bc132c87e1..92444ddf10 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -9,7 +9,7 @@ git-archive - Create an archive of files from a named tree SYNOPSIS -------- [verse] -'git archive' --format=<fmt> [--list] [--prefix=<prefix>/] [<extra>] +'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] [--output=<file>] [--worktree-attributes] [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> [path...] diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index ffc02c737c..63e7a42cb3 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -164,9 +164,8 @@ to do it for you by issuing the command: $ git bisect skip # Current version cannot be tested ------------ -But computing the commit to test may be slower afterwards and git may -eventually not be able to tell the first bad commit among a bad commit -and one or more skipped commits. +But git may eventually be unable to tell the first bad commit among +a bad commit and one or more skipped commits. You can even skip a range of commits, instead of just one commit, using the "'<commit1>'..'<commit2>'" notation. For example: diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index cbd4275871..ae201deb7a 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -111,6 +111,7 @@ OPTIONS --no-abbrev:: Display the full sha1s in the output listing rather than abbreviating them. +-t:: --track:: When creating a new branch, set up configuration to mark the start-point branch as "upstream" from the new branch. This diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index b191276d7a..58c8d65772 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -9,8 +9,8 @@ git-cat-file - Provide content or type and size information for repository objec SYNOPSIS -------- [verse] -'git cat-file' [-t | -s | -e | -p | <type>] <object> -'git cat-file' [--batch | --batch-check] < <list-of-objects> +'git cat-file' (-t | -s | -e | -p | <type>) <object> +'git cat-file' (--batch | --batch-check) < <list-of-objects> DESCRIPTION ----------- diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index c1ce26884e..e9b3b40af4 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git check-ref-format' <refname> -'git check-ref-format' [--branch] <branchname-shorthand> +'git check-ref-format' --branch <branchname-shorthand> DESCRIPTION ----------- @@ -25,6 +25,10 @@ imposes the following rules on how references are named: grouping, but no slash-separated component can begin with a dot `.`. +. They must contain at least one `/`. This enforces the presence of a + category like `heads/`, `tags/` etc. but the actual names are not + restricted. + . They cannot have two consecutive dots `..` anywhere. . They cannot have ASCII control characters (i.e. bytes whose @@ -38,6 +42,8 @@ imposes the following rules on how references are named: . They cannot contain a sequence `@{`. +- They cannot contain a `\\`. + These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoids ambiguities in certain @@ -57,8 +63,11 @@ reference name expressions (see linkgit:git-rev-parse[1]): . at-open-brace `@{` is used as a notation to access a reflog entry. -With the `--branch` option, it expands a branch name shorthand and -prints the name of the branch the shorthand refers to. +With the `--branch` option, it expands the ``previous branch syntax'' +`@{-n}`. For example, `@{-1}` is a way to refer the last branch you +were on. This option should be used by porcelains to accept this +syntax anywhere a branch name is expected, so they can act as if you +typed the branch name. EXAMPLE ------- diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index be894af39f..ae8938b2de 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -27,6 +27,9 @@ OPTIONS ------- -d:: Remove untracked directories in addition to untracked files. + If an untracked directory is managed by a different git + repository, it is not removed by default. Use -f option twice + if you really want to remove such a directory. -f:: If the git configuration specifies clean.requireForce as true, diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 4072f40d7a..1709a2dbd0 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -72,11 +72,19 @@ These objects may be removed by normal git operations (such as 'git-commit') which automatically call `git gc --auto`. (See linkgit:git-gc[1].) If these objects are removed and were referenced by the cloned repository, then the cloned repository will become corrupt. - - ++ +Note that running `git repack` without the `-l` option in a repository +cloned with `-s` will copy objects from the source repository into a pack +in the cloned repository, removing the disk space savings of `clone -s`. +It is safe, however, to run `git gc`, which uses the `-l` option by +default. ++ +If you want to break the dependency of a repository cloned with `-s` on +its source repository, you can simply run `git repack -a` to copy all +objects from the source repository into a pack in the cloned repository. --reference <repository>:: - If the reference repository is on the local machine + If the reference repository is on the local machine, automatically setup .git/objects/info/alternates to obtain objects from the reference repository. Using an already existing repository as an alternate will @@ -149,7 +157,7 @@ then the cloned repository will become corrupt. part of the source repository is used if no directory is explicitly given ("repo" for "/path/to/repo.git" and "foo" for "host.xz:foo/.git"). Cloning into an existing directory - is not allowed. + is only allowed if the directory is empty. :git-clone: 1 include::urls.txt[] diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 7131ee3c66..f68b198205 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -69,7 +69,8 @@ OPTIONS --add:: Adds a new line to the option without altering any existing - values. This is the same as providing '^$' as the value_regex. + values. This is the same as providing '^$' as the value_regex + in `--replace-all`. --get:: Get the value for a given key (optionally filtered by a regex @@ -155,7 +156,7 @@ See also <<FILES>>. When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color name default:: +--get-color name [default]:: Find the color configured for `name` (e.g. `color.diff.new`) and output it as the ANSI color escape sequence to the standard diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 2da8588f4f..abaaf273bb 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -63,6 +63,10 @@ OPTIONS -u:: Update affected files from CVS repository before attempting export. +-k:: + Reverse CVS keyword expansion (e.g. $Revision: 1.2.3.4$ + becomes $Revision$) in working CVS checkout before applying patch. + -w:: Specify the location of the CVS checkout to use for the export. This option does not require GIT_DIR to be set before execution if the diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index c526141564..4ef03578eb 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -43,8 +43,7 @@ omit diff output for unmerged entries and just show "Unmerged". -q:: Remain silent even on nonexistent files -Output format -------------- + include::diff-format.txt[] diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 26920d4f63..8b9ed29299 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -34,8 +34,6 @@ include::diff-options.txt[] 'git-diff-index' say that all non-checked-out files are up to date. -Output format -------------- include::diff-format.txt[] Operating Modes diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 23b7abd3c6..f2cef1260b 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -159,8 +159,7 @@ HEAD commits it finds, which is even more interesting. in case you care). -Output format -------------- + include::diff-format.txt[] diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index a2f192fb75..0ac711230e 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -84,8 +84,7 @@ include::diff-options.txt[] the diff to the named paths (you can give directory names and get diff for all files under them). -Output format -------------- + include::diff-format.txt[] EXAMPLES diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 15b247bab4..96a6c51a4b 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -31,7 +31,7 @@ OPTIONS Use the diff tool specified by <tool>. Valid merge tools are: kdiff3, kompare, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, - ecmerge, diffuse and opendiff + ecmerge, diffuse, opendiff and araxis. + If a diff tool is not specified, 'git-difftool' will use the configuration variable `diff.tool`. If the diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 0c9eb567cb..af2328d401 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -36,6 +36,17 @@ 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. +--tag-of-filtered-object=(abort|drop|rewrite):: + Specify how to handle tags whose tagged objectis filtered out. + Since revisions and files to export can be limited by path, + tagged objects may be filtered completely. ++ +When asking to 'abort' (which is the default), this program will die +when encountering such a tag. With 'drop' it will omit such tags from +the output. With 'rewrite', if the tagged object is a commit, it will +rewrite the tag to tag an ancestor commit (via parent rewriting; see +linkgit:git-rev-list[1]) + -M:: -C:: Perform move and/or copy detection, as described in the @@ -71,6 +82,12 @@ marks the same across runs. allow that. So fake a tagger to be able to fast-import the output. +[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. EXAMPLES -------- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index ab527b5b31..32ea8564a5 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -305,6 +305,16 @@ 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 will print. +If you need to add 'Acked-by' lines to, say, the last 10 commits (none +of which is a merge), use this command: + +-------------------------------------------------------- +git filter-branch --msg-filter ' + cat && + echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>" +' HEAD~10..HEAD +-------------------------------------------------------- + *NOTE* the changes introduced by the commits, and which are not reverted by subsequent commits, will still be in the rewritten branch. If you want to throw out _changes_ together with the commits, you should use the diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 6f1fc80119..687e667598 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout] - [--thread[=<style>]] + [--no-thread | --thread[=<style>]] [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] [-n | --numbered | -N | --no-numbered] @@ -124,17 +124,25 @@ include::diff-options.txt[] second part, with "Content-Disposition: inline". --thread[=<style>]:: - Add In-Reply-To and References headers to make the second and - subsequent mails appear as replies to the first. Also generates - the Message-Id header to reference. +--no-thread:: + Controls addition of In-Reply-To and References headers to + make the second and subsequent mails appear as replies to the + first. Also controls generation of the Message-Id header to + reference. + The optional <style> argument can be either `shallow` or `deep`. 'shallow' threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the `\--in-reply-to`, and the first patch mail, in this order. 'deep' -threading makes every mail a reply to the previous one. If not -specified, defaults to the 'format.thread' configuration, or `shallow` -if that is not set. +threading makes every mail a reply to the previous one. ++ +The default is --no-thread, unless the 'format.thread' configuration +is set. If --thread is specified without a style, it defaults to the +style specified by 'format.thread' if any, or else `shallow`. ++ +Beware that the default for 'git send-email' is to thread emails +itself. If you want 'git format-patch' to take care of hreading, you +will want to ensure that threading is disabled for 'git send-email'. --in-reply-to=Message-Id:: Make the first mail (or all the mails with --no-thread) appear as a diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index b292e9843a..dcac8c8e29 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -61,7 +61,7 @@ automatic consolidation of packs. --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, - overrideable by the config variable `gc.pruneExpire`). This + overridable by the config variable `gc.pruneExpire`). This option is on by default. --no-prune:: diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index fccb82deb4..b753c9d76f 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -122,6 +122,14 @@ OPTIONS -<num>:: A shortcut for specifying -C<num>. +-p:: +--show-function:: + Show the preceding line that contains the function name of + the match, unless the matching line is a function name itself. + The name is determined in the same way as 'git diff' works out + patch hunk headers (see 'Defining a custom hunk-header' in + linkgit:gitattributes[5]). + -f <file>:: Read patterns from <file>, one per line. diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 34cf4e5811..3d79de11ec 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -37,8 +37,12 @@ include::diff-options.txt[] and <until>, see "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. ---decorate:: - Print out the ref names of any commits that are shown. +--decorate[=short|full]:: + Print out the ref names of any commits that are shown. If 'short' is + specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and + 'refs/remotes/' will not be printed. If 'full' is specified, the + full ref name (including prefix) will be printed. The default option + is 'short'. --source:: Print out the ref name given on the command line by which each diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index f68e5c5c1a..c3fdccb4c2 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -82,8 +82,10 @@ Output Format ------------- <mode> SP <type> SP <object> TAB <file> -When the `-z` option is not used, TAB, LF, and backslash characters +Unless the `-z` option is used, TAB, LF, and backslash characters in pathnames are represented as `\t`, `\n`, and `\\`, respectively. +This output format is compatible with what '--index-info --stdin' of +'git update-index' expects. When the `-l` option is used, format changes to diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index c04ae739ed..af68d694a0 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... - [-m <msg>] <remote> <remote>... + [-m <msg>] <remote>... 'git merge' <msg> HEAD <remote>... DESCRIPTION diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index ff9700d17a..68ed6c0956 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -27,7 +27,7 @@ OPTIONS Use the merge resolution program specified by <tool>. Valid merge tools are: kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, - diffuse, tortoisemerge and opendiff + diffuse, tortoisemerge, opendiff and araxis. + If a merge resolution program is not specified, 'git-mergetool' will use the configuration variable `merge.tool`. If the diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index af19f06ed7..81e3326772 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -8,12 +8,13 @@ git-mktree - Build a tree-object from ls-tree formatted text SYNOPSIS -------- -'git mktree' [-z] +'git mktree' [-z] [--missing] [--batch] DESCRIPTION ----------- -Reads standard input in non-recursive `ls-tree` output format, -and creates a tree object. The object name of the tree object +Reads standard input in non-recursive `ls-tree` output format, and creates +a tree object. The order of the tree entries is normalised by mktree so +pre-sorting the input is not required. The object name of the tree object built is written to the standard output. OPTIONS @@ -21,6 +22,18 @@ OPTIONS -z:: Read the NUL-terminated `ls-tree -z` output instead. +--missing:: + Allow missing objects. The default behaviour (without this option) + is to verify that each tree entry's sha1 identifies an existing + object. This option has no effect on the treatment of gitlink entries + (aka "submodules") which are always allowed to be missing. + +--batch:: + Allow building of more than one tree object before exiting. Each + tree is separated by as single blank line. The final new-line is + optional. Note - if the '-z' option is used, lines are terminated + with NUL. + Author ------ Written by Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 7d4c1a7556..2e4992970e 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -11,7 +11,8 @@ SYNOPSIS [verse] 'git pack-objects' [-q] [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=N] [--depth=N] [--all-progress] - [--revs [--unpacked | --all]*] [--stdout | base-name] < object-list + [--revs [--unpacked | --all]*] [--stdout | base-name] + [--keep-true-parents] < object-list DESCRIPTION @@ -197,6 +198,10 @@ base-name:: to force the version for the generated pack index, and to force 64-bit index entries on objects located above the given offset. +--keep-true-parents:: + With this option, parents that are hidden by grafts are packed + nevertheless. + Author ------ diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt index cd43069874..39d9daa7e0 100644 --- a/Documentation/git-parse-remote.txt +++ b/Documentation/git-parse-remote.txt @@ -17,26 +17,6 @@ routines to parse files under $GIT_DIR/remotes/ and $GIT_DIR/branches/ and configuration variables that are related to fetching, pulling and pushing. -The primary entry points are: - -get_remote_refs_for_fetch:: - Given the list of user-supplied `<repo> <refspec>...`, - return the list of refs to fetch after canonicalizing - them into `$GIT_DIR` relative paths - (e.g. `refs/heads/foo`). When `<refspec>...` is empty - the returned list of refs consists of the defaults - for the given `<repo>`, if specified in - `$GIT_DIR/remotes/`, `$GIT_DIR/branches/`, or `remote.*.fetch` - configuration. - -get_remote_refs_for_push:: - Given the list of user-supplied `<repo> <refspec>...`, - return the list of refs to push in a form suitable to be - fed to the 'git-send-pack' command. When `<refspec>...` - is empty the returned list of refs consists of the - defaults for the given `<repo>`, if specified in - `$GIT_DIR/remotes/`. - Author ------ Written by Junio C Hamano. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index fd53c49fb8..58d2bd5d4a 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -85,6 +85,11 @@ nor in any Push line of the corresponding remotes file---see below). --dry-run:: Do everything except actually send the updates. +--porcelain:: + Produce machine-readable output. The output status line for each ref + will be tab-separated and sent to stdout instead of stderr. The full + symbolic names of the refs will be given. + --tags:: All refs under `$GIT_DIR/refs/tags` are pushed, in addition to refspecs explicitly listed on the command @@ -148,6 +153,12 @@ representing the status of a single ref. Each line is of the form: <flag> <summary> <from> -> <to> (<reason>) ------------------------------- +If --porcelain is used, then each line of the output is of the form: + +------------------------------- + <flag> \t <from>:<to> \t <summary> (<reason>) +------------------------------- + flag:: A single character indicating the status of the ref. This is blank for a successfully pushed ref, `!` for a ref that was @@ -184,6 +195,92 @@ reason:: refs, no explanation is needed. For a failed ref, the reason for failure is described. +Note about fast-forwards +------------------------ + +When an update changes a branch (or more in general, a ref) that used to +point at commit A to point at another commit B, it is called a +fast-forward update if and only if B is a descendant of A. + +In a fast-forward update from A to B, the set of commits that the original +commit A built on top of is a subset of the commits the new commit B +builds on top of. Hence, it does not lose any history. + +In contrast, a non-fast-forward update will lose history. For example, +suppose you and somebody else started at the same commit X, and you built +a history leading to commit B while the other person built a history +leading to commit A. The history looks like this: + +---------------- + + B + / + ---X---A + +---------------- + +Further suppose that the other person already pushed changes leading to A +back to the original repository you two obtained the original commit X. + +The push done by the other person updated the branch that used to point at +commit X to point at commit A. It is a fast-forward. + +But if you try to push, you will attempt to update the branch (that +now points at A) with commit B. This does _not_ fast-forward. If you did +so, the changes introduced by commit A will be lost, because everybody +will now start building on top of B. + +The command by default does not allow an update that is not a fast-forward +to prevent such loss of history. + +If you do not want to lose your work (history from X to B) nor the work by +the other person (history from X to A), you would need to first fetch the +history from the repository, create a history that contains changes done +by both parties, and push the result back. + +You can perform "git pull", resolve potential conflicts, and "git push" +the result. A "git pull" will create a merge commit C between commits A +and B. + +---------------- + + B---C + / / + ---X---A + +---------------- + +Updating A with the resulting merge commit will fast-forward and your +push will be accepted. + +Alternatively, you can rebase your change between X and B on top of A, +with "git pull --rebase", and push the result back. The rebase will +create a new commit D that builds the change between X and B on top of +A. + +---------------- + + B D + / / + ---X---A + +---------------- + +Again, updating A with this commit will fast-forward and your push will be +accepted. + +There is another common situation where you may encounter non-fast-forward +rejection when you try to push, and it is possible even when you are +pushing into a repository nobody else pushes into. After you push commit +A yourself (in the first picture in this section), replace it with "git +commit --amend" to produce commit B, and you try to push it out, because +forgot that you have pushed A out already. In such a case, and only if +you are certain that nobody in the meantime fetched your earlier commit A +(and started building on top of it), you can run "git push --force" to +overwrite it. In other words, "git push --force" is a method reserved for +a case where you do mean to lose history. + + Examples -------- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 3d5a066c31..db1b71d248 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -231,12 +231,15 @@ OPTIONS -s <strategy>:: --strategy=<strategy>:: - Use the given merge strategy; can be supplied more than - once to specify them in the order they should be tried. + Use the given merge strategy. If there is no `-s` option, a built-in list of strategies is used instead ('git-merge-recursive' when merging a single head, 'git-merge-octopus' otherwise). This implies --merge. +-q:: +--quiet:: + Be quiet. Implies --no-stat. + -v:: --verbose:: Be verbose. Implies --stat. diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 9e2b4eaa38..82a3d29673 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -114,14 +114,14 @@ These stale branches have already been removed from the remote repository referenced by <name>, but are still locally available in "remotes/<name>". + -With `--dry-run` option, report what branches will be pruned, but do no +With `--dry-run` option, report what branches will be pruned, but do not actually prune them. 'update':: Fetch updates for a named set of remotes in the repository as defined by remotes.<group>. If a named group is not specified on the command line, -the configuration parameter remotes.default will get used; if +the configuration parameter remotes.default will be used; if remotes.default is not defined, all remotes which do not have the configuration parameter remote.<name>.skipDefaultUpdate set to true will be updated. (See linkgit:git-config[1]). diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index aaa8852629..c9257a10c9 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -31,11 +31,14 @@ OPTIONS Instead of incrementally packing the unpacked objects, pack everything referenced into a single pack. Especially useful when packing a repository that is used - for private development and there is no need to worry - about people fetching via dumb protocols from it. Use + for private development. Use with '-d'. This will clean up the objects that `git prune` leaves behind, but `git fsck --full` shows as dangling. ++ +Note that users fetching over dumb protocols will have to fetch the +whole new pack in order to get any contained object, no matter how many +other objects in that pack they already have locally. -A:: Same as `-a`, unless '-d' is used. Then any unreachable diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 64715c17da..7dd515b8cc 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -12,18 +12,18 @@ SYNOPSIS DESCRIPTION ----------- -In a workflow that employs relatively long lived topic branches, -the developer sometimes needs to resolve the same conflict over +In a workflow employing relatively long lived topic branches, +the developer sometimes needs to resolve the same conflicts over and over again until the topic branches are done (either merged to the "release" branch, or sent out and accepted upstream). -This command helps this process by recording conflicted -automerge results and corresponding hand-resolve results on the -initial manual merge, and later by noticing the same automerge -results and applying the previously recorded hand resolution. +This command assists the developer in this process by recording +conflicted automerge results and corresponding hand resolve results +on the initial manual merge, and applying previously recorded +hand resolutions to their corresponding automerge results. [NOTE] -You need to set the configuration variable rerere.enabled to +You need to set the configuration variable rerere.enabled in order to enable this command. @@ -54,18 +54,18 @@ for resolutions. 'gc':: -This command is used to prune records of conflicted merge that -occurred long time ago. By default, conflicts older than 15 -days that you have not recorded their resolution, and conflicts -older than 60 days, are pruned. These are controlled with +This prunes records of conflicted merges that +occurred a long time ago. By default, unresolved conflicts older +than 15 days and resolved conflicts older than 60 +days are pruned. These defaults are controlled via the `gc.rerereunresolved` and `gc.rerereresolved` configuration -variables. +variables respectively. DISCUSSION ---------- -When your topic branch modifies overlapping area that your +When your topic branch modifies an overlapping area that your master branch (or upstream) touched since your topic branch forked from it, you may want to test it with the latest master, even before your topic branch is ready to be pushed upstream: @@ -140,9 +140,9 @@ top of the tip before the test merge: This would leave only one merge commit when your topic branch is finally ready and merged into the master branch. This merge would require you to resolve the conflict, introduced by the -commits marked with `*`. However, often this conflict is the +commits marked with `*`. However, this conflict is often the same conflict you resolved when you created the test merge you -blew away. 'git-rerere' command helps you to resolve this final +blew away. 'git-rerere' helps you resolve this final conflicted merge using the information from your earlier hand resolve. @@ -150,33 +150,32 @@ Running the 'git-rerere' command immediately after a conflicted automerge records the conflicted working tree files, with the usual conflict markers `<<<<<<<`, `=======`, and `>>>>>>>` in them. Later, after you are done resolving the conflicts, -running 'git-rerere' again records the resolved state of these +running 'git-rerere' again will record the resolved state of these files. Suppose you did this when you created the test merge of master into the topic branch. -Next time, running 'git-rerere' after seeing a conflicted -automerge, if the conflict is the same as the earlier one -recorded, it is noticed and a three-way merge between the +Next time, after seeing the same conflicted automerge, +running 'git-rerere' will perform a three-way merge between the earlier conflicted automerge, the earlier manual resolution, and -the current conflicted automerge is performed by the command. +the current conflicted automerge. If this three-way merge resolves cleanly, the result is written -out to your working tree file, so you would not have to manually +out to your working tree file, so you do not have to manually resolve it. Note that 'git-rerere' leaves the index file alone, so you still need to do the final sanity checks with `git diff` (or `git diff -c`) and 'git-add' when you are satisfied. As a convenience measure, 'git-merge' automatically invokes -'git-rerere' when it exits with a failed automerge, which -records it if it is a new conflict, or reuses the earlier hand +'git-rerere' upon exiting with a failed automerge and 'git-rerere' +records the hand resolve when it is a new conflict, or reuses the earlier hand resolve when it is not. 'git-commit' also invokes 'git-rerere' -when recording a merge result. What this means is that you do -not have to do anything special yourself (Note: you still have -to set the config variable rerere.enabled to enable this command). +when committing a merge result. What this means is that you do +not have to do anything special yourself (besides enabling +the rerere.enabled config variable). -In our example, when you did the test merge, the manual +In our example, when you do the test merge, the manual resolution is recorded, and it will be reused when you do the -actual merge later with updated master and topic branch, as long -as the earlier resolution is still applicable. +actual merge later with the updated master and topic branch, as long +as the recorded resolution is still applicable. The information 'git-rerere' records is also used when running 'git-rebase'. After blowing away the test merge and continuing @@ -194,11 +193,11 @@ development on the topic branch: o---o---o---*---o---o---o---o master ------------ -you could run `git rebase master topic`, to keep yourself -up-to-date even before your topic is ready to be sent upstream. -This would result in falling back to three-way merge, and it -would conflict the same way the test merge you resolved earlier. -'git-rerere' is run by 'git-rebase' to help you resolve this +you could run `git rebase master topic`, to bring yourself +up-to-date before your topic is ready to be sent upstream. +This would result in falling back to a three-way merge, and it +would conflict the same way as the test merge you resolved earlier. +'git-rerere' will be run by 'git-rebase' to help you resolve this conflict. diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 1c9cc28895..974d9f527f 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -14,6 +14,7 @@ SYNOPSIS [ \--max-age=timestamp ] [ \--min-age=timestamp ] [ \--sparse ] + [ \--merges ] [ \--no-merges ] [ \--first-parent ] [ \--remove-empty ] @@ -83,7 +84,7 @@ between the two operands. The following two commands are equivalent: $ git rev-list A...B ----------------------------------------------------------------------- -'git-rev-list' is a very essential git program, since it +'rev-list' is a very essential git command, since it provides the ability to build and traverse commit ancestry graphs. For this reason, it has a lot of different options that enables it to be used by commands as different as 'git-bisect' and diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 52c353e674..82045a2522 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -30,6 +30,16 @@ OPTIONS Only meaningful in `--parseopt` mode. Tells the option parser to echo out the first `--` met instead of skipping it. +--stop-at-non-option:: + Only meaningful in `--parseopt` mode. Lets the option parser stop at + the first non-option argument. This can be used to parse sub-commands + that take options themself. + +--sq-quote:: + Use 'git-rev-parse' in shell quoting mode (see SQ-QUOTE + section below). In contrast to the `--sq` option below, this + mode does only quoting. Nothing else is done to command input. + --revs-only:: Do not output flags and parameters not meant for 'git-rev-list' command. @@ -64,7 +74,8 @@ OPTIONS properly quoted for consumption by shell. Useful when you expect your parameter to contain whitespaces and newlines (e.g. when using pickaxe `-S` with - 'git-diff-\*'). + 'git-diff-\*'). In contrast to the `--sq-quote` option, + the command input is still interpreted as usual. --not:: When showing object names, prefix them with '{caret}' and @@ -406,6 +417,33 @@ C? option C with an optional argument" eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?` ------------ +SQ-QUOTE +-------- + +In `--sq-quote` mode, 'git-rev-parse' echoes on the standard output a +single line suitable for `sh(1)` `eval`. This line is made by +normalizing the arguments following `--sq-quote`. Nothing other than +quoting the arguments is done. + +If you want command input to still be interpreted as usual by +'git-rev-parse' before the output is shell quoted, see the `--sq` +option. + +Example +~~~~~~~ + +------------ +$ cat >your-git-script.sh <<\EOF +#!/bin/sh +args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments +command="git frotz -n24 $args" # and use it inside a handcrafted + # command line +eval "$command" +EOF + +$ sh your-git-script.sh "a b'c" +------------ + EXAMPLES -------- diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 794224b1b3..d6b192b7b9 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -14,6 +14,10 @@ SYNOPSIS DESCRIPTION ----------- Takes the patches given on the command line and emails them out. +Patches can be specified as files, directories (which will send all +files in the directory), or directly as a revision list. In the +last case, any format accepted by linkgit:git-format-patch[1] can +be passed to git send-email. The header of the email is configurable by command line options. If not specified on the command line, the user will be prompted with a ReadLine @@ -39,6 +43,10 @@ OPTIONS Composing ~~~~~~~~~ +--annotate:: + Review and edit each patch you're about to send. See the + CONFIGURATION section for 'sendemail.multiedit'. + --bcc=<address>:: Specify a "Bcc:" value for each email. Default is the value of 'sendemail.bcc'. @@ -51,11 +59,6 @@ The --bcc option must be repeated for each user you want on the bcc list. + The --cc option must be repeated for each user you want on the cc list. ---annotate:: - Review each patch you're about to send in an editor. The setting - 'sendemail.multiedit' defines if this will spawn one editor per patch - or one for all of them at once. - --compose:: Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an introductory message for the patch series. @@ -67,11 +70,16 @@ In-Reply-To headers specified in the message. If the body of the message and In-Reply-To headers will be used unless they are removed. + Missing From or In-Reply-To headers will be prompted for. ++ +See the CONFIGURATION section for 'sendemail.multiedit'. --from=<address>:: - Specify the sender of the emails. This will default to - the value GIT_COMMITTER_IDENT, as returned by "git var -l". - The user will still be prompted to confirm this entry. + Specify the sender of the emails. If not specified on the command line, + the value of the 'sendemail.from' configuration option is used. If + neither the command line option nor 'sendemail.from' are set, then the + user will be prompted for the value. The default for the prompt will be + the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not + set, as returned by "git var -l". --in-reply-to=<identifier>:: Specify the contents of the first In-Reply-To header. @@ -135,7 +143,9 @@ user is prompted for a password while the input is masked for privacy. --smtp-server-port=<port>:: Specifies a port different from the default port (SMTP servers typically listen to smtp port 25 and ssmtp port - 465). This can be set with 'sendemail.smtpserverport'. + 465); symbolic port names (e.g. "submission" instead of 465) + are also accepted. The port can also be set with the + 'sendemail.smtpserverport' configuration variable. --smtp-ssl:: Legacy alias for '--smtp-encryption ssl'. @@ -155,7 +165,7 @@ Automating Output of this command must be single email address per line. Default is the value of 'sendemail.cccmd' configuration value. ---[no-]chain-reply-to=<identifier>:: +--[no-]chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with "--no-chain-reply-to", all emails after the first will be sent as replies to the first email sent. When using @@ -183,12 +193,12 @@ Automating - 'self' will avoid including the sender - 'cc' will avoid including anyone mentioned in Cc lines in the patch header except for self (use 'self' for that). -- 'ccbody' will avoid including anyone mentioned in Cc lines in the +- 'bodycc' will avoid including anyone mentioned in Cc lines in the patch body (commit message) except for self (use 'self' for that). - 'sob' will avoid including anyone mentioned in Signed-off-by lines except for self (use 'self' for that). - 'cccmd' will avoid running the --cc-cmd. -- 'body' is equivalent to 'sob' + 'ccbody' +- 'body' is equivalent to 'sob' + 'bodycc' - 'all' will suppress all auto cc values. -- + @@ -202,10 +212,22 @@ specified, as well as 'body' if --no-signed-off-cc is specified. value; if that is unspecified, default to --no-suppress-from. --[no-]thread:: - If this is set, the In-Reply-To header will be set on each email sent. - If disabled with "--no-thread", no emails will have the In-Reply-To - header set. Default is the value of the 'sendemail.thread' configuration - value; if that is unspecified, default to --thread. + If this is set, the In-Reply-To and References headers will be + added to each email sent. Whether each mail refers to the + previous email (`deep` threading per 'git format-patch' + wording) or to the first email (`shallow` threading) is + governed by "--[no-]chain-reply-to". ++ +If disabled with "--no-thread", those headers will not be added +(unless specified with --in-reply-to). Default is the value of the +'sendemail.thread' configuration value; if that is unspecified, +default to --thread. ++ +It is up to the user to ensure that no In-Reply-To header already +exists when 'git send-email' is asked to add it (especially note that +'git format-patch' can be configured to do the threading itself). +Failure to do so may not produce the expected result in the +recipient's MUA. Administering @@ -230,6 +252,12 @@ have been specified, in which case default to 'compose'. --dry-run:: Do everything except actually send the emails. +--[no-]format-patch:: + When an argument may be understood either as a reference or as a file name, + choose to understand it as a format-patch argument ('--format-patch') + or as a file name ('--no-format-patch'). By default, when such a conflict + occurs, git send-email will fail. + --quiet:: Make git-send-email less verbose. One line per email should be all that is output. @@ -246,12 +274,6 @@ have been specified, in which case default to 'compose'. Default is the value of 'sendemail.validate'; if this is not set, default to '--validate'. ---[no-]format-patch:: - When an argument may be understood either as a reference or as a file name, - choose to understand it as a format-patch argument ('--format-patch') - or as a file name ('--no-format-patch'). By default, when such a conflict - occurs, git send-email will fail. - CONFIGURATION ------------- diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 51a4e9d6d7..89ec5364ec 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -8,9 +8,11 @@ git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -'git show-branch' [--all] [--remotes] [--topo-order] [--current] +'git show-branch' [--all] [--remotes] [--topo-order | --date-order] + [--current] [--color | --no-color] [--more=<n> | --list | --independent | --merge-base] - [--no-name | --sha1-name] [--topics] [<rev> | <glob>]... + [--no-name | --sha1-name] [--topics] + [<rev> | <glob>]... 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION @@ -57,6 +59,11 @@ OPTIONS appear in topological order (i.e., descendant commits are shown before their parents). +--date-order:: + This option is similar to '--topo-order' in the sense that no + parent comes before all of its children, but otherwise commits + are ordered according to their commit date. + --sparse:: By default, the output omits merges that are reachable from only one tip being shown. This option makes them @@ -107,6 +114,14 @@ OPTIONS When no explicit <ref> parameter is given, it defaults to the current branch (or `HEAD` if it is detached). +--color:: + Color the status sign (one of these: `*` `!` `+` `-`) of each commit + corresponding to the branch it's in. + +--no-color:: + Turn off colored output, even when the configuration file gives the + default to color output. + Note that --more, --list, --independent and --merge-base options are mutually exclusive. diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 2f173fff35..f4429bdc68 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -9,8 +9,9 @@ SYNOPSIS -------- [verse] 'git show-ref' [-q|--quiet] [--verify] [-h|--head] [-d|--dereference] - [-s|--hash] [--abbrev] [--tags] [--heads] [--] <pattern>... -'git show-ref' --exclude-existing[=pattern] + [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] + [--heads] [--] <pattern>... +'git show-ref' --exclude-existing[=<pattern>] < ref-list DESCRIPTION ----------- @@ -24,7 +25,7 @@ The --exclude-existing form is a filter that does the inverse, it shows the refs from stdin that don't exist in the local repository. Use of this utility is encouraged in favor of directly accessing files under -in the `.git` directory. +the `.git` directory. OPTIONS ------- @@ -48,9 +49,9 @@ OPTIONS appended. -s:: ---hash:: +--hash[=<n>]:: - Only show the SHA1 hash, not the reference name. When also using + Only show the SHA1 hash, not the reference name. When combined with --dereference the dereferenced tag will still be shown after the SHA1. --verify:: @@ -59,11 +60,10 @@ OPTIONS Aside from returning an error code of 1, it will also print an error message if '--quiet' was not specified. ---abbrev:: ---abbrev=len:: +--abbrev[=<n>]:: Abbreviate the object name. When using `--hash`, you do - not have to say `--hash --abbrev`; `--hash=len` would do. + not have to say `--hash --abbrev`; `--hash=n` would do. -q:: --quiet:: @@ -71,8 +71,7 @@ OPTIONS Do not print any results to stdout. When combined with '--verify' this can be used to silently check if a reference exists. ---exclude-existing:: ---exclude-existing=pattern:: +--exclude-existing[=<pattern>]:: Make 'git-show-ref' act as a filter that reads refs from stdin of the form "^(?:<anything>\s)?<refname>(?:\^\{\})?$" and performs the diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 051f94d26f..3ff653de84 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,10 +9,11 @@ SYNOPSIS -------- [verse] 'git stash' list [<options>] -'git stash' (show | drop | pop ) [<stash>] -'git stash' apply [--index] [<stash>] +'git stash' show [<stash>] +'git stash' drop [-q|--quiet] [<stash>] +'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [--keep-index] [<message>]] +'git stash' [save [--keep-index] [-q|--quiet] [<message>]] 'git stash' clear 'git stash' create @@ -41,7 +42,7 @@ is also possible). OPTIONS ------- -save [--keep-index] [<message>]:: +save [--keep-index] [-q|--quiet] [<message>]:: Save your local modifications to a new 'stash', and run `git reset --hard` to revert them. This is the default action when no @@ -65,7 +66,8 @@ stash@{1}: On master: 9cc0589... Add git-stash ---------------------------------------------------------------- + The command takes options applicable to the 'git-log' -command to control what is shown and how. See linkgit:git-log[1]. +command to control what is shown and how. If no options are set, the +default is `-n 10`. See linkgit:git-log[1]. show [<stash>]:: @@ -75,19 +77,27 @@ show [<stash>]:: it will accept any format known to 'git-diff' (e.g., `git stash show -p stash@\{1}` to view the second most recent stash in patch form). -apply [--index] [<stash>]:: +pop [--index] [-q|--quiet] [<stash>]:: - Restore the changes recorded in the stash on top of the current - working tree state. When no `<stash>` is given, applies the latest - one. The working directory must match the index. + Remove a single stashed state from the stash list and apply it + on top of the current working tree state, i.e., do the inverse + operation of `git stash save`. The working directory must + match the index. + -This operation can fail with conflicts; you need to resolve them -by hand in the working tree. +Applying the state can fail with conflicts; in this case, it is not +removed from the stash list. You need to resolve the conflicts by hand +and call `git stash drop` manually afterwards. + If the `--index` option is used, then tries to reinstate not only the working tree's changes, but also the index's ones. However, this can fail, when you have conflicts (which are stored in the index, where you therefore can no longer apply the changes as they were originally). ++ +When no `<stash>` is given, `stash@\{0}` is assumed. + +apply [--index] [-q|--quiet] [<stash>]:: + + Like `pop`, but do not remove the state from the stash list. branch <branchname> [<stash>]:: @@ -107,17 +117,11 @@ clear:: Remove all the stashed states. Note that those states will then be subject to pruning, and may be difficult or impossible to recover. -drop [<stash>]:: +drop [-q|--quiet] [<stash>]:: Remove a single stashed state from the stash list. When no `<stash>` is given, it removes the latest one. i.e. `stash@\{0}` -pop [<stash>]:: - - Remove a single stashed state from the stash list and apply on top - of the current working tree state. When no `<stash>` is given, - `stash@\{0}` is assumed. See also `apply`. - create:: Create a stash (which is a regular commit object) and return its @@ -163,7 +167,7 @@ $ git pull file foobar not up to date, cannot merge. $ git stash $ git pull -$ git stash apply +$ git stash pop ---------------------------------------------------------------- Interrupted workflow:: @@ -192,7 +196,7 @@ You can use 'git-stash' to simplify the above, like this: $ git stash $ edit emergency fix $ git commit -a -m "Fix in a hurry" -$ git stash apply +$ git stash pop # ... continue hacking ... ---------------------------------------------------------------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 3b8df44673..7dd73ae14e 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,11 +9,13 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b branch] [--] <repository> <path> +'git submodule' [--quiet] add [-b branch] + [--reference <repository>] [--] <repository> <path> 'git submodule' [--quiet] status [--cached] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] -'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--] [<path>...] -'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] +'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] + [--reference <repository>] [--merge] [--] [<path>...] +'git submodule' [--quiet] summary [--cached] [--summary-limit <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach <command> 'git submodule' [--quiet] sync [--] [<path>...] @@ -113,7 +115,9 @@ init:: update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. - This will make the submodules HEAD be detached. + This will make the submodules HEAD be detached unless '--rebase' or + '--merge' is specified or the key `submodule.$name.update` is set to + `rebase` or `merge`. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the @@ -137,8 +141,9 @@ foreach:: the processing to terminate. This can be overridden by adding '|| :' to the end of the command. + -As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will -show the path and currently checked out commit for each submodule. +As an example, +git submodule foreach \'echo $path {backtick}git +rev-parse HEAD{backtick}'+ will show the path and currently checked out +commit for each submodule. sync:: Synchronizes submodules' remote URL configuration setting @@ -177,6 +182,33 @@ OPTIONS This option is only valid for the update command. Don't fetch new objects from the remote site. +--merge:: + This option is only valid for the update command. + Merge the commit recorded in the superproject into the current branch + of the submodule. If this option is given, the submodule's HEAD will + not be detached. If a merge failure prevents this process, you will + have to resolve the resulting conflicts within the submodule with the + usual conflict resolution tools. + If the key `submodule.$name.update` is set to `merge`, this option is + implicit. + +--rebase:: + This option is only valid for the update command. + Rebase the current branch onto the commit recorded in the + superproject. If this option is given, the submodule's HEAD will not + be detached. If a a merge failure prevents this process, you will have + to resolve these failures with linkgit:git-rebase[1]. + If the key `submodule.$name.update` is set to `rebase`, this option is + implicit. + +--reference <repository>:: + This option is only valid for add and update commands. These + commands sometimes need to clone a remote repository. In this case, + this option will be passed to the linkgit:git-clone[1] command. ++ +*NOTE*: Do *not* use this option unless you have read the note +for linkgit:git-clone[1]'s --reference and --shared options carefully. + <path>...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 1c40894669..22a0389f1e 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -3,7 +3,7 @@ git-svn(1) NAME ---- -git-svn - Bidirectional operation between a single Subversion branch and git +git-svn - Bidirectional operation between a Subversion repository and git SYNOPSIS -------- @@ -11,27 +11,25 @@ SYNOPSIS DESCRIPTION ----------- -'git-svn' is a simple conduit for changesets between Subversion and git. +'git svn' is a simple conduit for changesets between Subversion and git. It provides a bidirectional flow of changes between a Subversion and a git repository. -'git-svn' can track a single Subversion branch simply by using a -URL to the branch, follow branches laid out in the Subversion recommended -method (trunk, branches, tags directories) with the --stdlayout option, or -follow branches in any layout with the -T/-t/-b options (see options to -'init' below, and also the 'clone' command). +'git svn' can track a standard Subversion repository, +following the common "trunk/branches/tags" layout, with the --stdlayout option. +It can also follow branches and tags in any layout with the -T/-t/-b options +(see options to 'init' below, and also the 'clone' command). -Once tracking a Subversion branch (with any of the above methods), the git +Once tracking a Subversion repository (with any of the above methods), the git repository can be updated from Subversion by the 'fetch' command and Subversion updated from git by the 'dcommit' command. COMMANDS -------- --- 'init':: Initializes an empty git repository with additional - metadata directories for 'git-svn'. The Subversion URL + metadata directories for 'git svn'. The Subversion URL may be specified as a command-line argument, or as full URL arguments to -T/-t/-b. Optionally, the target directory to operate on can be specified as a second @@ -48,8 +46,11 @@ COMMANDS --stdlayout;; These are optional command-line options for init. Each of these flags can point to a relative repository path - (--tags=project/tags') or a full url - (--tags=https://foo.org/project/tags). The option --stdlayout is + (--tags=project/tags) or a full url + (--tags=https://foo.org/project/tags). + You can specify more than one --tags and/or --branches options, in case + your Subversion repository places tags or branches under multiple paths. + The option --stdlayout is a shorthand way of setting trunk,tags,branches as the relative paths, which is the Subversion default. If any of the other options are given as well, they take precedence. @@ -61,16 +62,6 @@ COMMANDS Set the 'useSvnsyncProps' option in the [svn-remote] config. --rewrite-root=<URL>;; Set the 'rewriteRoot' option in the [svn-remote] config. ---use-log-author;; - When retrieving svn commits into git (as part of fetch, rebase, or - dcommit operations), look for the first From: or Signed-off-by: line - in the log message and use that as the author string. ---add-author-from;; - When committing to svn from git (as part of commit or dcommit - operations), if the existing log message doesn't already have a - From: or Signed-off-by: line, append a From: line based on the - git commit's author string. If you use this, then --use-log-author - will retrieve a valid author string for all commits. --username=<USER>;; For transports that SVN handles authentication for (http, https, and plain svn), specify the username. For other @@ -89,6 +80,17 @@ 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'. +--no-minimize-url;; + When tracking multiple directories (using --stdlayout, + --branches, or --tags options), git svn will attempt to connect + to the root (or highest allowed level) of the Subversion + repository. This default allows better tracking of history if + entire projects are moved within a repository, but may cause + issues on repositories where read access restrictions are in + place. Passing '--no-minimize-url' will allow git svn to + accept URLs as-is without attempting to connect to a higher + level directory. This option is off by default when only + one URL/branch is tracked (it would do little good). 'fetch':: Fetch unfetched revisions from the Subversion remote we are @@ -98,12 +100,12 @@ COMMANDS --localtime;; Store Git commit times in the local timezone instead of UTC. This - makes 'git-log' (even without --date=local) show the same times + makes 'git log' (even without --date=local) show the same times that `svn log` would in the local timezone. --parent;; Fetch only from the SVN parent of the current HEAD. - ++ This doesn't interfere with interoperating with the Subversion repository you cloned from, but if you wish for your local Git repository to be able to interoperate with someone else's local Git @@ -116,20 +118,39 @@ the same local timezone. The '--ignore-paths' option should match for every 'fetch' (including automatic fetches due to 'clone', 'dcommit', 'rebase', etc) on a given repository. - ++ +[verse] config key: svn-remote.<name>.ignore-paths - - If the ignore-paths config key is set and the command - line option is also given, both regular expressions - will be used. - ++ +If the ignore-paths config key is set and the command line option is +also given, both regular expressions will be used. ++ Examples: ++ +-- +Skip "doc*" directory for every fetch;; ++ +------------------------------------------------------------------------ +--ignore-paths="^doc" +------------------------------------------------------------------------ - --ignore-paths="^doc" - skip "doc*" directory for every - fetch. +Skip "branches" and "tags" of first level directories;; ++ +------------------------------------------------------------------------ +--ignore-paths="^[^/]+/(?:branches|tags)" +------------------------------------------------------------------------ +-- - --ignore-paths="^[^/]+/(?:branches|tags)" - skip - "branches" and "tags" of first level directories. +--use-log-author;; + When retrieving svn commits into git (as part of fetch, rebase, or + dcommit operations), look for the first From: or Signed-off-by: line + in the log message and use that as the author string. +--add-author-from;; + When committing to svn from git (as part of commit or dcommit + operations), if the existing log message doesn't already have a + From: or Signed-off-by: line, append a From: line based on the + git commit's author string. If you use this, then --use-log-author + will retrieve a valid author string for all commits. 'clone':: Runs 'init' and 'fetch'. It will automatically create a @@ -137,29 +158,29 @@ Examples: or if a second argument is passed; it will create a directory and work within that. It accepts all arguments that the 'init' and 'fetch' commands accept; with the exception of - '--fetch-all'. After a repository is cloned, the 'fetch' - command will be able to update revisions without affecting - the working tree; and the 'rebase' command will be able - to update the working tree with the latest changes. + '--fetch-all' and '--parent'. After a repository is cloned, + the 'fetch' command will be able to update revisions without + affecting the working tree; and the 'rebase' command will be + able to update the working tree with the latest changes. 'rebase':: This fetches revisions from the SVN parent of the current HEAD and rebases the current (uncommitted to SVN) work against it. - -This works similarly to `svn update` or 'git-pull' except that -it preserves linear history with 'git-rebase' instead of -'git-merge' for ease of dcommitting with 'git-svn'. - -This accepts all options that 'git-svn fetch' and 'git-rebase' ++ +This works similarly to `svn update` or 'git pull' except that +it preserves linear history with 'git rebase' instead of +'git merge' for ease of dcommitting with 'git svn'. ++ +This accepts all options that 'git svn fetch' and 'git rebase' accept. However, '--fetch-all' only fetches from the current [svn-remote], and not all [svn-remote] definitions. - -Like 'git-rebase'; this requires that the working tree be clean ++ +Like 'git rebase'; this requires that the working tree be clean and have no uncommitted changes. -l;; --local;; - Do not fetch remotely; only run 'git-rebase' against the + Do not fetch remotely; only run 'git rebase' against the last fetched commit from the upstream SVN. 'dcommit':: @@ -167,11 +188,12 @@ and have no uncommitted changes. repository, and then rebase or reset (depending on whether or not there is a diff between SVN and head). This will create a revision in SVN for each commit in git. - It is recommended that you run 'git-svn' fetch and rebase (not + It is recommended that you run 'git svn' fetch and rebase (not pull or merge) your commits against the latest changes in the SVN repository. - An optional command-line argument may be specified as an - alternative to HEAD. + An optional revision or branch argument may be specified, and + causes 'git svn' to do all work on that revision/branch + instead of HEAD. This is advantageous over 'set-tree' (below) because it produces cleaner, more linear history. + @@ -179,18 +201,17 @@ and have no uncommitted changes. After committing, do not rebase or reset. --commit-url <URL>;; Commit to this SVN URL (the full path). This is intended to - allow existing git-svn repositories created with one transport + allow existing 'git svn' repositories created with one transport method (e.g. `svn://` or `http://` for anonymous read) to be reused if a user is later given access to an alternate transport method (e.g. `svn+ssh://` or `https://`) for commit. - ++ +[verse] config key: svn-remote.<name>.commiturl - config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) - - Using this option for any other purpose (don't ask) - is very strongly discouraged. --- ++ +Using this option for any other purpose (don't ask) is very strongly +discouraged. 'branch':: Create a branch in the SVN repository. @@ -204,6 +225,20 @@ config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) Create a tag by using the tags_subdir instead of the branches_subdir specified during git svn init. +-d;; +--destination;; + 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 ++ + git config --get-all svn-remote.<name>.branches + git config --get-all svn-remote.<name>.tags ++ +where <name> is the name of the SVN repository as specified by the -R option to +'init' (or "svn" by default). + 'tag':: Create a tag in the SVN repository. This is a shorthand for 'branch -t'. @@ -215,10 +250,12 @@ config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) The following features from `svn log' are supported: + -- +-r <n>[:<n>];; --revision=<n>[:<n>];; is supported, non-numeric args are not: HEAD, NEXT, BASE, PREV, etc ... --v/--verbose;; +-v;; +--verbose;; it's not completely compatible with the --verbose output in svn log, but reasonably close. --limit=<n>;; @@ -241,7 +278,7 @@ NOTE: SVN itself only stores times in UTC and nothing else. The regular svn client converts the UTC time to the local time (or based on the TZ= environment). This command has the same behaviour. + -Any other arguments are passed directly to 'git-log' +Any other arguments are passed directly to 'git log' 'blame':: Show what revision and author last modified each line of a file. The @@ -249,15 +286,14 @@ Any other arguments are passed directly to 'git-log' `svn blame' by default. Like the SVN blame command, local uncommitted changes in the working copy are ignored; the version of the file in the HEAD revision is annotated. Unknown - arguments are passed directly to 'git-blame'. + arguments are passed directly to 'git blame'. + --git-format;; - Produce output in the same format as 'git-blame', but with + Produce output in the same format as 'git blame', but with SVN revision numbers instead of git commit hashes. In this mode, changes that haven't been committed to SVN (including local working-copy edits) are shown as revision 0. --- 'find-rev':: When given an SVN revision number of the form 'rN', returns the corresponding git commit hash (this can optionally be followed by a @@ -271,7 +307,7 @@ Any other arguments are passed directly to 'git-log' absolutely no attempts to do patching when committing to SVN, it simply overwrites files with those specified in the tree or commit. All merging is assumed to have taken place - independently of 'git-svn' functions. + independently of 'git svn' functions. 'create-ignore':: Recursively finds the svn:ignore property on directories and @@ -286,12 +322,12 @@ Any other arguments are passed directly to 'git-log' 'commit-diff':: Commits the diff of two tree-ish arguments from the - command-line. This command does not rely on being inside an `git-svn + command-line. This command does not rely on being inside an `git svn init`-ed repository. This command takes three arguments, (a) the original tree to diff against, (b) the new tree result, (c) the URL of the target Subversion repository. The final argument - (URL) may be omitted if you are working from a 'git-svn'-aware - repository (that has been `init`-ed with 'git-svn'). + (URL) may be omitted if you are working from a 'git svn'-aware + repository (that has been `init`-ed with 'git svn'). The -r<revision> option is required for this. 'info':: @@ -313,108 +349,170 @@ Any other arguments are passed directly to 'git-log' Shows the Subversion externals. Use -r/--revision to specify a specific revision. --- +'gc':: + Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn + and remove $GIT_DIR/svn/<refname>index files in .git/svn. + +'reset':: + Undoes the effects of 'fetch' back to the specified revision. + This allows you to re-'fetch' an SVN revision. Normally the + contents of an SVN revision should never change and 'reset' + should not be necessary. However, if SVN permissions change, + or if you alter your --ignore-paths option, a 'fetch' may fail + with "not found in commit" (file not previously visible) or + "checksum mismatch" (missed a modification). If the problem + file cannot be ignored forever (with --ignore-paths) the only + way to repair the repo is to use 'reset'. ++ +Only the rev_map and refs/remotes/git-svn are changed. Follow 'reset' +with a 'fetch' and then 'git reset' or 'git rebase' to move local +branches onto the new tree. + +-r <n>;; +--revision=<n>;; + Specify the most recent revision to keep. All later revisions + are discarded. +-p;; +--parent;; + Discard the specified revision as well, keeping the nearest + parent instead. +Example:;; +Assume you have local changes in "master", but you need to refetch "r2". ++ +------------ + r1---r2---r3 remotes/git-svn + \ + A---B master +------------ ++ +Fix the ignore-paths or SVN permissions problem that caused "r2" to +be incomplete in the first place. Then: ++ +[verse] +git svn reset -r2 -p +git svn fetch ++ +------------ + r1---r2'--r3' remotes/git-svn + \ + r2---r3---A---B master +------------ ++ +Then fixup "master" with 'git rebase'. +Do NOT use 'git merge' or your history will not be compatible with a +future 'dcommit'! ++ +[verse] +git rebase --onto remotes/git-svn A^ master ++ +------------ + r1---r2'--r3' remotes/git-svn + \ + A'--B' master +------------ OPTIONS ------- --- --shared[={false|true|umask|group|all|world|everybody}]:: --template=<template_directory>:: Only used with the 'init' command. - These are passed directly to 'git-init'. + These are passed directly to 'git init'. -r <ARG>:: --revision <ARG>:: - -Used with the 'fetch' command. - + Used with the 'fetch' command. ++ This allows revision ranges for partial/cauterized history to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), $NUMBER:HEAD, and BASE:$NUMBER are all supported. - ++ This can allow you to make partial mirrors when running fetch; but is generally not recommended because history will be skipped and lost. -:: --stdin:: - -Only used with the 'set-tree' command. - + Only used with the 'set-tree' command. ++ Read a list of commits from stdin and commit them in reverse order. Only the leading sha1 is read from each line, so -'git-rev-list --pretty=oneline' output can be used. +'git rev-list --pretty=oneline' output can be used. --rmdir:: - -Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. - + Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. ++ Remove directories from the SVN tree if there are no files left behind. SVN can version empty directories, and they are not removed by default if there are no files left in them. git cannot version empty directories. Enabling this flag will make the commit to SVN act like git. - ++ +[verse] config key: svn.rmdir -e:: --edit:: - -Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. - + Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. ++ Edit the commit message before committing to SVN. This is off by default for objects that are commits, and forced on when committing tree objects. - ++ +[verse] config key: svn.edit -l<num>:: --find-copies-harder:: - -Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. - -They are both passed directly to 'git-diff-tree'; see + Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. ++ +They are both passed directly to 'git diff-tree'; see linkgit:git-diff-tree[1] for more information. - ++ [verse] config key: svn.l config key: svn.findcopiesharder -A<filename>:: --authors-file=<filename>:: - -Syntax is compatible with the file used by 'git-cvsimport': - + Syntax is compatible with the file used by 'git cvsimport': ++ ------------------------------------------------------------------------ loginname = Joe User <user@example.com> ------------------------------------------------------------------------ - -If this option is specified and 'git-svn' encounters an SVN -committer name that does not exist in the authors-file, 'git-svn' ++ +If this option is specified and 'git svn' encounters an SVN +committer name that does not exist in the authors-file, 'git svn' will abort operation. The user will then have to add the -appropriate entry. Re-running the previous 'git-svn' command +appropriate entry. Re-running the previous 'git svn' command after the authors-file is modified should continue operation. - ++ +[verse] config key: svn.authorsfile +--authors-prog=<filename>:: + If this option is specified, for each SVN committer name that + does not exist in the authors file, the given file is executed + with the committer name as the first argument. The program is + expected to return a single line of the form "Name <email>", + which will be treated as if included in the authors file. + -q:: --quiet:: - Make 'git-svn' less verbose. Specify a second time to make it + Make 'git svn' less verbose. Specify a second time to make it even less verbose. --repack[=<n>]:: --repack-flags=<flags>:: - -These should help keep disk usage sane for large fetches -with many revisions. - + These should help keep disk usage sane for large fetches with + many revisions. ++ --repack takes an optional argument for the number of revisions to fetch before repacking. This defaults to repacking every 1000 commits fetched if no argument is specified. - ---repack-flags are passed directly to 'git-repack'. - ++ +--repack-flags are passed directly to 'git repack'. ++ [verse] config key: svn.repack config key: svn.repackflags @@ -423,41 +521,36 @@ config key: svn.repackflags --merge:: -s<strategy>:: --strategy=<strategy>:: - -These are only used with the 'dcommit' and 'rebase' commands. - -Passed directly to 'git-rebase' when using 'dcommit' if a -'git-reset' cannot be used (see 'dcommit'). + These are only used with the 'dcommit' and 'rebase' commands. ++ +Passed directly to 'git rebase' when using 'dcommit' if a +'git reset' cannot be used (see 'dcommit'). -n:: --dry-run:: - -This can be used with the 'dcommit', 'rebase', 'branch' and 'tag' -commands. - + This can be used with the 'dcommit', 'rebase', 'branch' and + 'tag' commands. ++ For 'dcommit', print out the series of git arguments that would show which diffs would be committed to SVN. - ++ For 'rebase', display the local branch associated with the upstream svn repository associated with the current branch and the URL of svn repository that will be fetched from. - ++ For 'branch' and 'tag', display the urls that will be used for copying when creating the branch or tag. --- ADVANCED OPTIONS ---------------- --- -i<GIT_SVN_ID>:: --id <GIT_SVN_ID>:: - -This sets GIT_SVN_ID (instead of using the environment). This -allows the user to override the default refname to fetch from -when tracking a single URL. The 'log' and 'dcommit' commands -no longer require this switch as an argument. + This sets GIT_SVN_ID (instead of using the environment). This + allows the user to override the default refname to fetch from + when tracking a single URL. The 'log' and 'dcommit' commands + no longer require this switch as an argument. -R<remote name>:: --svn-remote <remote name>:: @@ -471,33 +564,30 @@ no longer require this switch as an argument. started tracking a branch and never tracked the trunk it was descended from. This feature is enabled by default, use --no-follow-parent to disable it. - ++ +[verse] config key: svn.followparent --- CONFIG FILE-ONLY OPTIONS ------------------------ --- svn.noMetadata:: svn-remote.<name>.noMetadata:: - -This gets rid of the 'git-svn-id:' lines at the end of every commit. - -If you lose your .git/svn/git-svn/.rev_db file, 'git-svn' will not + This gets rid of the 'git-svn-id:' lines at the end of every commit. ++ +If you lose your .git/svn/git-svn/.rev_db file, 'git svn' will not be able to rebuild it and you won't be able to fetch again, either. This is fine for one-shot imports. - -The 'git-svn log' command will not work on repositories using ++ +The 'git svn log' command will not work on repositories using this, either. Using this conflicts with the 'useSvmProps' option for (hopefully) obvious reasons. svn.useSvmProps:: svn-remote.<name>.useSvmProps:: - -This allows 'git-svn' to re-map repository URLs and UUIDs from -mirrors created using SVN::Mirror (or svk) for metadata. - + This allows 'git svn' to re-map repository URLs and UUIDs from + mirrors created using SVN::Mirror (or svk) for metadata. ++ If an SVN revision has a property, "svm:headrev", it is likely that the revision was created by SVN::Mirror (also used by SVK). The property contains a repository UUID and a revision. We want @@ -514,23 +604,22 @@ svn-remote.<name>.useSvnsyncprops:: svn-remote.<name>.rewriteRoot:: This allows users to create repositories from alternate - URLs. For example, an administrator could run 'git-svn' on the + URLs. For example, an administrator could run 'git svn' on the server locally (accessing via file://) but wish to distribute the repository with a public http:// or svn:// URL in the metadata so users of it will see the public URL. svn.brokenSymlinkWorkaround:: -This disables potentially expensive checks to workaround broken symlinks -checked into SVN by broken clients. Set this option to "false" if you -track a SVN repository with many empty blobs that are not symlinks. -This option may be changed while "git-svn" is running and take effect on -the next revision fetched. If unset, git-svn assumes this option to be -"true". - --- + This disables potentially expensive checks to workaround + broken symlinks checked into SVN by broken clients. Set this + option to "false" if you track a SVN repository with many + empty blobs that are not symlinks. This option may be changed + while 'git svn' is running and take effect on the next + revision fetched. If unset, 'git svn' assumes this option to + be "true". Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps -options all affect the metadata generated and used by 'git-svn'; they +options all affect the metadata generated and used by 'git svn'; they *must* be set in the configuration file before any history is imported and these settings should never be changed once they are set. @@ -548,7 +637,7 @@ Tracking and contributing to the trunk of a Subversion-managed project: git svn clone http://svn.example.com/project/trunk # Enter the newly cloned directory: cd trunk -# You should be on master branch, double-check with git-branch +# You should be on master branch, double-check with 'git branch' git branch # Do some work and commit locally to git: git commit ... @@ -579,12 +668,12 @@ Tracking and contributing to an entire Subversion-managed project # of dcommit/rebase/show-ignore should be the same as above. ------------------------------------------------------------------------ -The initial 'git-svn clone' can be quite time-consuming +The initial 'git svn clone' can be quite time-consuming (especially for large Subversion repositories). If multiple people (or one person with multiple machines) want to use -'git-svn' to interact with the same Subversion repository, you can -do the initial 'git-svn clone' to a repository on a server and -have each person clone that repository with 'git-clone': +'git svn' to interact with the same Subversion repository, you can +do the initial 'git svn clone' to a repository on a server and +have each person clone that repository with 'git clone': ------------------------------------------------------------------------ # Do the initial import on a server @@ -598,7 +687,7 @@ have each person clone that repository with 'git-clone': git fetch # Create a local branch from one of the branches just fetched git checkout -b master FETCH_HEAD -# Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) +# Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server) git svn init http://svn.example.com/project # Pull the latest changes from Subversion git svn rebase @@ -607,7 +696,7 @@ have each person clone that repository with 'git-clone': REBASE VS. PULL/MERGE --------------------- -Originally, 'git-svn' recommended that the 'remotes/git-svn' branch be +Originally, 'git svn' recommended that the 'remotes/git-svn' branch be pulled or merged from. This is because the author favored `git svn set-tree B` to commit a single head rather than the `git svn set-tree A..B` notation to commit multiple commits. @@ -615,14 +704,14 @@ pulled or merged from. This is because the author favored If you use `git svn set-tree A..B` to commit several diffs and you do not have the latest remotes/git-svn merged into my-branch, you should use `git svn rebase` to update your work branch instead of `git pull` or -`git merge`. `pull`/`merge' can cause non-linear history to be flattened +`git merge`. `pull`/`merge` can cause non-linear history to be flattened when committing into SVN, which can lead to merge commits reversing previous commits in SVN. DESIGN PHILOSOPHY ----------------- Merge tracking in Subversion is lacking and doing branched development -with Subversion can be cumbersome as a result. While 'git-svn' can track +with Subversion can be cumbersome as a result. While 'git svn' can track copy history (including branches and tags) for repositories adopting a standard layout, it cannot yet represent merge history that happened inside git back upstream to SVN users. Therefore it is advised that @@ -633,25 +722,25 @@ CAVEATS ------- For the sake of simplicity and interoperating with a less-capable system -(SVN), it is recommended that all 'git-svn' users clone, fetch and dcommit -directly from the SVN server, and avoid all 'git-clone'/'pull'/'merge'/'push' +(SVN), it is recommended that all 'git svn' users clone, fetch and dcommit +directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push' operations between git repositories and branches. The recommended method of exchanging code between git branches and users is -'git-format-patch' and 'git-am', or just 'dcommit'ing to the SVN repository. +'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository. -Running 'git-merge' or 'git-pull' is NOT recommended on a branch you +Running 'git merge' or 'git pull' is NOT recommended on a branch you plan to 'dcommit' from. Subversion does not represent merges in any reasonable or useful fashion; so users using Subversion cannot see any merges you've made. Furthermore, if you merge or pull from a git branch that is a mirror of an SVN branch, 'dcommit' may commit to the wrong branch. -'git-clone' does not clone branches under the refs/remotes/ hierarchy or -any 'git-svn' metadata, or config. So repositories created and managed with -using 'git-svn' should use 'rsync' for cloning, if cloning is to be done +'git clone' does not clone branches under the refs/remotes/ hierarchy or +any 'git svn' metadata, or config. So repositories created and managed with +using 'git svn' should use 'rsync' for cloning, if cloning is to be done at all. -Since 'dcommit' uses rebase internally, any git branches you 'git-push' to +Since 'dcommit' uses rebase internally, any git branches you 'git push' to before 'dcommit' on will require forcing an overwrite of the existing ref on the remote repository. This is generally considered bad practice, see the linkgit:git-push[1] documentation for details. @@ -661,6 +750,16 @@ already dcommitted. It is considered bad practice to --amend commits you've already pushed to a remote repository for other users, and dcommit with SVN is analogous to that. +When using multiple --branches or --tags, 'git svn' does not automatically +handle name collisions (for example, if two branches from different paths have +the same name, or if a branch and a tag have the same name). In these cases, +use 'init' to set up your git repository then, before your first 'fetch', edit +the .git/config file so that the branches and tags are associated with +different name spaces. For example: + + branches = stable/*:refs/remotes/svn/stable/* + branches = debug/*:refs/remotes/svn/debug/* + BUGS ---- @@ -677,7 +776,7 @@ for git to detect them. CONFIGURATION ------------- -'git-svn' stores [svn-remote] configuration information in the +'git svn' stores [svn-remote] configuration information in the repository .git/config file. It is similar the core git [remote] sections except 'fetch' keys do not accept glob arguments; but they are instead handled by the 'branches' @@ -698,7 +797,7 @@ Keep in mind that the '\*' (asterisk) wildcard of the local ref however the remote wildcard may be anywhere as long as it's an independent path component (surrounded by '/' or EOL). This type of configuration is not automatically created by 'init' and -should be manually entered with a text-editor or using 'git-config'. +should be manually entered with a text-editor or using 'git config'. SEE ALSO -------- diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 210fde03a1..6392538807 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -14,9 +14,9 @@ DESCRIPTION Given one argument, reads which branch head the given symbolic ref refers to and outputs its path, relative to the `.git/` directory. Typically you would give `HEAD` as the <name> -argument to see on which branch your working tree is on. +argument to see which branch your working tree is on. -Give two arguments, create or update a symbolic ref <name> to +Given two arguments, creates or updates a symbolic ref <name> to point at the given branch <ref>. A symbolic ref is a regular file that stores a string that diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index 26d3850e73..c8899d528a 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -12,7 +12,8 @@ SYNOPSIS DESCRIPTION ----------- -Creates a tree object using the current index. +Creates a tree object using the current index. The name of the new +tree object is printed to standard output. The index must be in a fully merged state. diff --git a/Documentation/git.txt b/Documentation/git.txt index 9d8f236fe8..20b573e37c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,7 +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.6.3/git.html[documentation for release 1.6.3] +* link:v1.6.4.4/git.html[documentation for release 1.6.4.4] + +* release notes for + link:RelNotes-1.6.4.4.txt[1.6.4.4], + link:RelNotes-1.6.4.3.txt[1.6.4.3], + link:RelNotes-1.6.4.2.txt[1.6.4.2], + link:RelNotes-1.6.4.1.txt[1.6.4.1], + link:RelNotes-1.6.4.txt[1.6.4]. + +* link:v1.6.3.4/git.html[documentation for release 1.6.3.4] + +* release notes for + link:RelNotes-1.6.3.4.txt[1.6.3.4], + link:RelNotes-1.6.3.3.txt[1.6.3.3], + link:RelNotes-1.6.3.2.txt[1.6.3.2], + link:RelNotes-1.6.3.1.txt[1.6.3.1], + link:RelNotes-1.6.3.txt[1.6.3]. * release notes for link:RelNotes-1.6.2.5.txt[1.6.2.5], @@ -227,6 +243,8 @@ The link:user-manual.html#git-concepts[git concepts chapter of the user-manual] and linkgit:gitcore-tutorial[7] both provide introductions to the underlying git architecture. +See linkgit:gitworkflows[7] for an overview of recommended workflows. + See also the link:howto-index.html[howto] documents for some useful examples. @@ -313,7 +331,7 @@ Synching repositories include::cmds-synchingrepositories.txt[] -The following are helper programs used by the above; end users +The following are helper commands used by the above; end users typically do not use them directly. include::cmds-synchelpers.txt[] @@ -644,7 +662,8 @@ SEE ALSO linkgit:gittutorial[7], linkgit:gittutorial-2[7], link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7], linkgit:gitglossary[7], linkgit:gitcore-tutorial[7], -linkgit:gitcli[7], link:user-manual.html[The Git User's Manual] +linkgit:gitcli[7], link:user-manual.html[The Git User's Manual], +linkgit:gitworkflows[7] GIT --- diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index aaa073efc8..1195e83b6e 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -404,7 +404,7 @@ Performing a three-way merge The attribute `merge` affects how three versions of a file is merged when a file-level merge is necessary during `git merge`, -and other programs such as `git revert` and `git cherry-pick`. +and other commands such as `git revert` and `git cherry-pick`. Set:: diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 7ba5e589d7..b3640c4e64 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -12,7 +12,7 @@ git * DESCRIPTION ----------- -This tutorial explains how to use the "core" git programs to set up and +This tutorial explains how to use the "core" git commands to set up and work with a git repository. If you just need to use git as a revision control system you may prefer @@ -1328,7 +1328,7 @@ into it later. Obviously, this repository creation needs to be done only once. [NOTE] -'git-push' uses a pair of programs, +'git-push' uses a pair of commands, 'git-send-pack' on your local machine, and 'git-receive-pack' on the remote machine. The communication between the two over the network internally uses an SSH connection. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 1c736738cc..acc408d7e6 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -26,8 +26,11 @@ executable by default. This document describes the currently defined hooks. +HOOKS +----- + applypatch-msg --------------- +~~~~~~~~~~~~~~ This hook is invoked by 'git-am' script. It takes a single parameter, the name of the file that holds the proposed commit @@ -43,7 +46,7 @@ The default 'applypatch-msg' hook, when enabled, runs the 'commit-msg' hook, if the latter is enabled. pre-applypatch --------------- +~~~~~~~~~~~~~~ This hook is invoked by 'git-am'. It takes no parameter, and is invoked after the patch is applied, but before a commit is made. @@ -58,7 +61,7 @@ The default 'pre-applypatch' hook, when enabled, runs the 'pre-commit' hook, if the latter is enabled. post-applypatch ---------------- +~~~~~~~~~~~~~~~ This hook is invoked by 'git-am'. It takes no parameter, and is invoked after the patch is applied and a commit is made. @@ -67,7 +70,7 @@ This hook is meant primarily for notification, and cannot affect the outcome of 'git-am'. pre-commit ----------- +~~~~~~~~~~ This hook is invoked by 'git-commit', and can be bypassed with `\--no-verify` option. It takes no parameter, and is @@ -84,7 +87,7 @@ variable `GIT_EDITOR=:` if the command will not bring up an editor to modify the commit message. prepare-commit-msg ------------------- +~~~~~~~~~~~~~~~~~~ This hook is invoked by 'git-commit' right after preparing the default log message, and before the editor is started. @@ -109,7 +112,7 @@ The sample `prepare-commit-msg` hook that comes with git comments out the `Conflicts:` part of a merge's commit message. commit-msg ----------- +~~~~~~~~~~ This hook is invoked by 'git-commit', and can be bypassed with `\--no-verify` option. It takes a single parameter, the @@ -126,7 +129,7 @@ The default 'commit-msg' hook, when enabled, detects duplicate "Signed-off-by" lines, and aborts the commit if one is found. post-commit ------------ +~~~~~~~~~~~ This hook is invoked by 'git-commit'. It takes no parameter, and is invoked after a commit is made. @@ -135,14 +138,14 @@ This hook is meant primarily for notification, and cannot affect 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. post-checkout ------------ +~~~~~~~~~~~~~ This hook is invoked when a 'git-checkout' is run after having updated the worktree. The hook is given three parameters: the ref of the previous HEAD, @@ -160,7 +163,7 @@ differences from the previous HEAD if different, or set working dir metadata properties. post-merge ------------ +~~~~~~~~~~ This hook is invoked by 'git-merge', which happens when a 'git-pull' is done on a local repository. The hook takes a single parameter, a status @@ -175,7 +178,7 @@ for an example of how to do this. [[pre-receive]] pre-receive ------------ +~~~~~~~~~~~ This hook is invoked by 'git-receive-pack' on the remote repository, which happens when a 'git-push' is done on a local repository. @@ -204,7 +207,7 @@ for the user. [[update]] update ------- +~~~~~~ This hook is invoked by 'git-receive-pack' on the remote repository, which happens when a 'git-push' is done on a local repository. @@ -247,7 +250,7 @@ unannotated tags to be pushed. [[post-receive]] post-receive ------------- +~~~~~~~~~~~~ This hook is invoked by 'git-receive-pack' on the remote repository, which happens when a 'git-push' is done on a local repository. @@ -277,7 +280,7 @@ emails. [[post-update]] post-update ------------ +~~~~~~~~~~~ This hook is invoked by 'git-receive-pack' on the remote repository, which happens when a 'git-push' is done on a local repository. @@ -308,7 +311,7 @@ Both standard output and standard error output are forwarded to for the user. pre-auto-gc ------------ +~~~~~~~~~~~ This hook is invoked by 'git-gc --auto'. It takes no parameter, and exiting with non-zero status from this script causes the 'git-gc --auto' diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index d1a17e2625..5daf750d19 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -30,6 +30,17 @@ submodule.<name>.path:: submodule.<name>.url:: Defines an url from where the submodule repository can be cloned. +submodule.<name>.update:: + Defines what to do when the submodule is updated by the superproject. + If 'checkout' (the default), the new commit specified in the + superproject will be checked out in the submodule on a detached HEAD. + If 'rebase', the current branch of the submodule will be rebased onto + the commit specified in the superproject. If 'merge', the commit + specified in the superproject will be merged into the current branch + in the submodule. + This config option is overridden if 'git submodule update' is given + the '--merge' or '--rebase' options. + EXAMPLES -------- diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index c5d5596d89..cf0689cfeb 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -332,11 +332,11 @@ alice$ git log -p HEAD..FETCH_HEAD ------------------------------------------------ This operation is safe even if Alice has uncommitted local changes. -The range notation HEAD..FETCH_HEAD" means "show everything that is reachable -from the FETCH_HEAD but exclude anything that is reachable from HEAD. +The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable +from the FETCH_HEAD but exclude anything that is reachable from HEAD". Alice already knows everything that leads to her current state (HEAD), -and reviewing what Bob has in his state (FETCH_HEAD) that she has not -seen with this command +and reviews what Bob has in his state (FETCH_HEAD) that she has not +seen with this command. If Alice wants to visualize what Bob did since their histories forked she can issue the following command: @@ -375,9 +375,9 @@ it easier: alice$ git remote add bob /home/bob/myrepo ------------------------------------------------ -With this, Alice can perform the first part of the "pull" operation alone using the -'git-fetch' command without merging them with her own branch, -using: +With this, Alice can perform the first part of the "pull" operation +alone using the 'git-fetch' command without merging them with her own +branch, using: ------------------------------------- alice$ git fetch bob @@ -566,22 +566,22 @@ $ git log v2.5.. Makefile # commits since v2.5 which modify You can also give 'git-log' a "range" of commits where the first is not necessarily an ancestor of the second; for example, if the tips of -the branches "stable-release" and "master" diverged from a common +the branches "stable" and "master" diverged from a common commit some time ago, then ------------------------------------- -$ git log stable..experimental +$ git log stable..master ------------------------------------- -will list commits made in the experimental branch but not in the +will list commits made in the master branch but not in the stable branch, while ------------------------------------- -$ git log experimental..stable +$ git log master..stable ------------------------------------- will show the list of commits made on the stable branch but not -the experimental branch. +the master branch. The 'git-log' command has a weakness: it must present commits in a list. When the history has lines of development that diverged and @@ -650,6 +650,9 @@ digressions that may be interesting at this point are: smart enough to perform a close-to-optimal search even in the case of complex non-linear history with lots of merged branches. + * linkgit:gitworkflows[7]: Gives an overview of recommended + workflows. + * link:everyday.html[Everyday GIT with 20 Commands Or So] * linkgit:gitcvs-migration[7]: Git for CVS users. @@ -661,6 +664,7 @@ linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], linkgit:git-help[1], +linkgit:gitworkflows[7], link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 4832bc75e2..c0f96e7070 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -23,7 +23,7 @@ merge.tool:: Controls which merge resolution program is used by linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", - "diffuse", "ecmerge", "tortoisemerge", and + "diffuse", "ecmerge", "tortoisemerge", "araxis", and "opendiff". Any other value is treated is custom merge tool and there must be a corresponding mergetool.<tool>.cmd option. diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 637b53f898..adadf8e4bf 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -39,7 +39,8 @@ --squash:: Produce the working tree and index state as if a real - merge happened, but do not actually make a commit or + merge happened (except for the merge information), + but do not actually make a commit or move the `HEAD`, nor record `$GIT_DIR/MERGE_HEAD` to cause the next `git commit` command to create a merge commit. This allows you to create a single commit on diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 11eec941df..bf66116d61 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -201,6 +201,10 @@ endif::git-rev-list[] Stop when a given path disappears from the tree. +--merges:: + + Print only merge commits. + --no-merges:: Do not print commits with more than one parent. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index e66ca9f70c..50f9e9ac17 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -60,13 +60,13 @@ Steps to parse options . in `cmd_foo(int argc, const char **argv, const char *prefix)` call - argc = parse_options(argc, argv, builtin_foo_options, builtin_foo_usage, flags); + argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags); + `parse_options()` will filter out the processed options of `argv[]` and leave the non-option arguments in `argv[]`. `argc` is updated appropriately because of the assignment. + -You can also pass NULL instead of a usage array as fourth parameter of +You can also pass NULL instead of a usage array as the fifth parameter of parse_options(), to avoid displaying a help screen with usage info and option list. This should only be done if necessary, e.g. to implement a limited parser for only a subset of the options that needs to be run @@ -137,6 +137,10 @@ There are some macros to easily define options: Introduce a boolean option. If used, `int_var` is bitwise-ored with `mask`. +`OPT_NEGBIT(short, long, &int_var, description, mask)`:: + Introduce a boolean option. + If used, `int_var` is bitwise-anded with the inverted `mask`. + `OPT_SET_INT(short, long, &int_var, description, integer)`:: Introduce a boolean option. If used, set `int_var` to `integer`. @@ -163,9 +167,22 @@ There are some macros to easily define options: and the result will be put into `var`. See 'Option Callbacks' below for a more elaborate description. +`OPT_FILENAME(short, long, &var, description)`:: + Introduce an option with a filename argument. + The filename will be prefixed by passing the filename along with + the prefix argument of `parse_options()` to `prefix_filename()`. + `OPT_ARGUMENT(long, description)`:: Introduce a long-option argument that will be kept in `argv[]`. +`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: + Recognize numerical options like -123 and feed the integer as + if it was an argument to the function given by `func_ptr`. + The result will be put into `var`. There can be only one such + option definition. It cannot be negated and it takes no + arguments. Short options that happen to be digits take + precedence over it. + The last element of the array must be `OPT_END()`. @@ -198,7 +215,7 @@ The function must be defined in this form: The callback mechanism is as follows: -* Inside `funct`, the only interesting member of the structure +* Inside `func`, the only interesting member of the structure given by `opt` is the void pointer `opt->value`. `\*opt->value` will be the value that is saved into `var`, if you use `OPT_CALLBACK()`. diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt index 073b22bd83..c54b17db69 100644 --- a/Documentation/technical/api-remote.txt +++ b/Documentation/technical/api-remote.txt @@ -18,6 +18,10 @@ struct remote An array of all of the url_nr URLs configured for the remote +`pushurl`:: + + An array of all of the pushurl_nr push URLs configured for the remote + `push`:: An array of refspecs configured for pushing, with diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index 41ec7774f4..2a0e7b8944 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -27,10 +27,13 @@ config file would appear like this: ------------ [remote "<name>"] url = <url> + pushurl = <pushurl> push = <refspec> fetch = <refspec> ------------ +The `<pushurl>` is used for pushes only. It is optional and defaults +to `<url>`. Named file in `$GIT_DIR/remotes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index dbbeb7e7c7..67ebffa568 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1520,10 +1520,10 @@ $ git commit -a -m "blorpl: typofix" ------------------------------------------------ After that, you can go back to what you were working on with -`git stash apply`: +`git stash pop`: ------------------------------------------------ -$ git stash apply +$ git stash pop ------------------------------------------------ @@ -4131,7 +4131,7 @@ What does this mean? `git rev-list` is the original version of the revision walker, which _always_ printed a list of revisions to stdout. It is still functional, -and needs to, since most new Git programs start out as scripts using +and needs to, since most new Git commands start out as scripts using `git rev-list`. `git rev-parse` is not as important any more; it was only used to filter out |