diff options
Diffstat (limited to 'Documentation')
44 files changed, 1597 insertions, 329 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.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.txt b/Documentation/RelNotes-1.6.4.txt index af68297af5..7a904419f7 100644 --- a/Documentation/RelNotes-1.6.4.txt +++ b/Documentation/RelNotes-1.6.4.txt @@ -22,13 +22,6 @@ 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. -When the user does not tell "git push" what to push, it has always -pushed matching refs. For some people it is unexpected, and a new -configuration variable push.default has been introduced to allow -changing a different default behaviour. To advertise the new feature, -a big warning is issued if this is not configured and a git push without -arguments is attempted. - Updates since v1.6.3 -------------------- @@ -38,26 +31,67 @@ Updates since v1.6.3 * gitweb Perl style clean-up. * git-svn updates, including a new --authors-prog option to map author - names by invoking an external program. + 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. + 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 log --graph" draws graphs more compactly by using horizonal lines + * "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). @@ -69,10 +103,17 @@ Updates since v1.6.3 * "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 ------------------ @@ -82,12 +123,25 @@ 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. ---- -exec >/var/tmp/1 -echo O=$(git describe master) -O=v1.6.3.1-168-g23807fa -git shortlog --no-merges $O..master ^maint + * 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/RelNotes-1.6.5.txt b/Documentation/RelNotes-1.6.5.txt new file mode 100644 index 0000000000..856047d16f --- /dev/null +++ b/Documentation/RelNotes-1.6.5.txt @@ -0,0 +1,51 @@ +GIT v1.6.5 Release Notes +======================== + +In git 1.7.0, which is planned to be the release after 1.6.5, "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. + +Also, "git push $there :$killed" to delete the branch $killed in a remote +repository $there, when $killed branch is the current branch pointed at by +its HEAD, will be refused by default. + +You can choose what should happen upon such a push by setting the +configuration variable receive.denyDeleteCurrent 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. + +Updates since v1.6.4 +-------------------- + +(subsystems) + +(portability) + +(performance) + +(usability, bells and whistles) + +(developers) + +Fixes since v1.6.4 +------------------ + +# All of the fixes in v1.6.4.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.4.X series. + + 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 3a86d1f8f0..c6f09f801a 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 @@ -456,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 @@ -1043,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 @@ -1319,6 +1328,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 @@ -1376,6 +1388,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/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-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-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..75b06f33e7 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,20 @@ marks the same across runs. allow that. So fake a tagger to be able to fast-import the output. +--no-data:: + Skip output of blob objects and instead refer to blobs via + their original SHA-1 hash. This is useful when rewriting the + directory structure or history of a repository without + touching the contents of individual files. Note that the + resulting stream can only be used by a repository which + already contains the necessary objects. + +[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-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-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-merge-base.txt b/Documentation/git-merge-base.txt index 767486c770..ce5b369985 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -8,12 +8,12 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- -'git merge-base' [--all] <commit> <commit>... +'git merge-base' [-a|--all] <commit> <commit>... DESCRIPTION ----------- -'git-merge-base' finds best common ancestor(s) between two commits to use +'git merge-base' finds best common ancestor(s) between two commits to use in a three-way merge. One common ancestor is 'better' than another common ancestor if the latter is an ancestor of the former. A common ancestor that does not have any better common ancestor is a 'best common @@ -27,8 +27,13 @@ commits on the command line. As the most common special case, specifying only two commits on the command line means computing the merge base between the given two commits. +As a consequence, the 'merge base' is not necessarily contained in each of the +commit arguments if more than two commits are specified. This is different +from linkgit:git-show-branch[1] when used with the `--merge-base` option. + OPTIONS ------- +-a:: --all:: Output all merge bases for the commits, instead of just one. 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-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..2653388fd8 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 diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 26f3b7b2b0..db1b71d248 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -236,6 +236,10 @@ OPTIONS 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-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..a765cfa4d2 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 ] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 4bbdd056da..82045a2522 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -30,6 +30,11 @@ 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 diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 7c5ce415c7..767cf4d4bd 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 @@ -138,8 +142,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); symbolic port names (e.g. "submission" instead of 465) + servers typically listen to smtp port 25, but may also listen to + submission port 587, or the common SSL smtp port 465); + symbolic port names (e.g. "submission" instead of 587) are also accepted. The port can also be set with the 'sendemail.smtpserverport' configuration variable. @@ -161,7 +166,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 @@ -189,12 +194,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. -- + @@ -208,10 +213,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 diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 89ec5364ec..734336119c 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -8,11 +8,12 @@ git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -'git show-branch' [--all] [--remotes] [--topo-order | --date-order] - [--current] [--color | --no-color] +'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order] + [--current] [--color | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [<rev> | <glob>]... + 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION @@ -81,9 +82,11 @@ OPTIONS Synonym to `--more=-1` --merge-base:: - Instead of showing the commit list, just act like the - 'git-merge-base -a' command, except that it can accept - more than two heads. + Instead of showing the commit list, determine possible + merge bases for the specified commits. All merge bases + will be contained in all specified commits. This is + different from how linkgit:git-merge-base[1] handles + the case of three or more commits. --independent:: Among the <reference>s given, display only the ones that 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 a42d4c85bd..1c64a02fe5 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 ) [<stash>] -'git stash' ( pop | 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 @@ -75,7 +76,7 @@ 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). -pop [<stash>]:: +pop [--index] [-q|--quiet] [<stash>]:: 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 @@ -93,7 +94,7 @@ longer apply the changes as they were originally). + When no `<stash>` is given, `stash@\{0}` is assumed. -apply [--index] [<stash>]:: +apply [--index] [-q|--quiet] [<stash>]:: Like `pop`, but do not remove the state from the stash list. @@ -115,7 +116,7 @@ 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}` diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 14256c695b..7dd73ae14e 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -13,9 +13,9 @@ SYNOPSIS [--reference <repository>] [--] <repository> <path> 'git submodule' [--quiet] status [--cached] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] -'git submodule' [--quiet] update [--init] [-N|--no-fetch] - [--reference <repository>] [--] [<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>...] @@ -115,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 @@ -139,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 @@ -179,6 +182,25 @@ 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, diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index ca3fc3de1f..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,116 +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. + 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 @@ -431,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>:: @@ -479,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 @@ -522,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. @@ -556,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 ... @@ -587,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 @@ -606,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 @@ -615,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. @@ -623,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 @@ -641,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. @@ -669,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 ---- @@ -685,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' @@ -706,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.txt b/Documentation/git.txt index 56d47709ac..5fd5953e29 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,16 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.6.3.2/git.html[documentation for release 1.6.3.2] +* link:v1.6.4/git.html[documentation for release 1.6.4] * release notes for + 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]. 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 c7fa949c28..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 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/pt_BR/gittutorial.txt b/Documentation/pt_BR/gittutorial.txt new file mode 100644 index 0000000000..81e7ad7df4 --- /dev/null +++ b/Documentation/pt_BR/gittutorial.txt @@ -0,0 +1,675 @@ +gittutorial(7) +============== + +NAME +---- +gittutorial - Um tutorial de introdução ao git (para versão 1.5.1 ou mais nova) + +SYNOPSIS +-------- +git * + +DESCRIPTION +----------- + +Este tutorial explica como importar um novo projeto para o git, +adicionar mudanças a ele, e compartilhar mudanças com outros +desenvolvedores. + +Se, ao invés disso, você está interessado primariamente em usar git para +obter um projeto, por exemplo, para testar a última versão, você pode +preferir começar com os primeiros dois capítulos de +link:user-manual.html[O Manual do Usuário Git]. + +Primeiro, note que você pode obter documentação para um comando como +`git log --graph` com: + +------------------------------------------------ +$ man git-log +------------------------------------------------ + +ou: + +------------------------------------------------ +$ git help log +------------------------------------------------ + +Com a última forma, você pode usar o visualizador de manual de sua +escolha; veja linkgit:git-help[1] para maior informação. + +É uma boa idéia informar ao git seu nome e endereço público de email +antes de fazer qualquer operação. A maneira mais fácil de fazê-lo é: + +------------------------------------------------ +$ git config --global user.name "Seu Nome Vem Aqui" +$ git config --global user.email voce@seudominio.exemplo.com +------------------------------------------------ + + +Importando um novo projeto +----------------------- + +Assuma que você tem um tarball project.tar.gz com seu trabalho inicial. +Você pode colocá-lo sob controle de revisão git da seguinte forma: + +------------------------------------------------ +$ tar xzf project.tar.gz +$ cd project +$ git init +------------------------------------------------ + +Git irá responder + +------------------------------------------------ +Initialized empty Git repository in .git/ +------------------------------------------------ + +Você agora iniciou seu diretório de trabalho--você deve ter notado um +novo diretório criado, com o nome de ".git". + +A seguir, diga ao git para gravar um instantâneo do conteúdo de todos os +arquivos sob o diretório corrente (note o '.'), com 'git-add': + +------------------------------------------------ +$ git add . +------------------------------------------------ + +Este instantâneo está agora armazenado em uma área temporária que o git +chama de "index" ou índice. Você pode armazenar permanentemente o +conteúdo do índice no repositório com 'git-commit': + +------------------------------------------------ +$ git commit +------------------------------------------------ + +Isto vai te pedir por uma mensagem de commit. Você agora gravou sua +primeira versão de seu projeto no git. + +Fazendo mudanças +-------------- + +Modifique alguns arquivos, e, então, adicione seu conteúdo atualizado ao +índice: + +------------------------------------------------ +$ git add file1 file2 file3 +------------------------------------------------ + +Você está agora pronto para fazer o commit. Você pode ver o que está +para ser gravado usando 'git-diff' com a opção --cached: + +------------------------------------------------ +$ git diff --cached +------------------------------------------------ + +(Sem --cached, o comando 'git-diff' irá te mostrar quaisquer mudanças +que você tenha feito mas ainda não adicionou ao índice.) Você também +pode obter um breve sumário da situação com 'git-status': + +------------------------------------------------ +$ git status +# On branch master +# Changes to be committed: +# (use "git reset HEAD <file>..." to unstage) +# +# modified: file1 +# modified: file2 +# modified: file3 +# +------------------------------------------------ + +Se você precisar fazer qualquer outro ajuste, faça-o agora, e, então, +adicione qualquer conteúdo modificado ao índice. Finalmente, grave suas +mudanças com: + +------------------------------------------------ +$ git commit +------------------------------------------------ + +Isto irá novamente te pedir por uma mensagem descrevendo a mudança, e, +então, gravar a nova versão do projeto. + +Alternativamente, ao invés de executar 'git-add' antes, você pode usar + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +o que irá automaticamente notar quaisquer arquivos modificados (mas não +novos), adicioná-los ao índices, e gravar, tudo em um único passo. + +Uma nota em mensagens de commit: Apesar de não ser exigido, é uma boa +idéia começar a mensagem com uma simples e curta (menos de 50 +caracteres) linha sumarizando a mudança, seguida de uma linha em branco +e, então, uma descrição mais detalhada. Ferramentas que transformam +commits em email, por exemplo, usam a primeira linha no campo de +cabeçalho Subject: e o resto no corpo. + +Git rastreia conteúdo, não arquivos +---------------------------- + +Muitos sistemas de controle de revisão provêem um comando `add` que diz +ao sistema para começar a rastrear mudanças em um novo arquivo. O +comando `add` do git faz algo mais simples e mais poderoso: 'git-add' é +usado tanto para arquivos novos e arquivos recentemente modificados, e +em ambos os casos, ele tira o instantâneo dos arquivos dados e armazena +o conteúdo no índice, pronto para inclusão do próximo commit. + +Visualizando história do projeto +----------------------- + +Em qualquer ponto você pode visualizar a história das suas mudanças +usando + +------------------------------------------------ +$ git log +------------------------------------------------ + +Se você também quer ver a diferença completa a cada passo, use + +------------------------------------------------ +$ git log -p +------------------------------------------------ + +Geralmente, uma visão geral da mudança é útil para ter a sensação de +cada passo + +------------------------------------------------ +$ git log --stat --summary +------------------------------------------------ + +Gerenciando "branches"/ramos +----------------- + +Um simples repositório git pode manter múltiplos ramos de +desenvolvimento. Para criar um novo ramo chamado "experimental", use + +------------------------------------------------ +$ git branch experimental +------------------------------------------------ + +Se você executar agora + +------------------------------------------------ +$ git branch +------------------------------------------------ + +você vai obter uma lista de todos os ramos existentes: + +------------------------------------------------ + experimental +* master +------------------------------------------------ + +O ramo "experimental" é o que você acaba de criar, e o ramo "master" é o +ramo padrão que foi criado pra você automaticamente. O asterisco marca +o ramo em que você está atualmente; digite + +------------------------------------------------ +$ git checkout experimental +------------------------------------------------ + +para mudar para o ramo experimental. Agora edite um arquivo, grave a +mudança, e mude de volta para o ramo master: + +------------------------------------------------ +(edita arquivo) +$ git commit -a +$ git checkout master +------------------------------------------------ + +Verifique que a mudança que você fez não está mais visível, já que ela +foi feita no ramo experimental e você está de volta ao ramo master. + +Você pode fazer uma mudança diferente no ramo master: + +------------------------------------------------ +(edit file) +$ git commit -a +------------------------------------------------ + +neste ponto, os dois ramos divergiram, com diferentes mudanças feitas em +cada um. Para unificar as mudanças feitas no experimental para o +master, execute + +------------------------------------------------ +$ git merge experimental +------------------------------------------------ + +Se as mudanças não conflitarem, estará pronto. Se existirem conflitos, +marcadores serão deixados nos arquivos problemáticos exibindo o +conflito; + +------------------------------------------------ +$ git diff +------------------------------------------------ + +vai exibir isto. Após você editar os arquivos para resolver os +conflitos, + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +irá gravar o resultado da unificação. Finalmente, + +------------------------------------------------ +$ gitk +------------------------------------------------ + +vai mostrar uma bela representação gráfica da história resultante. + +Neste ponto você pode remover seu ramo experimental com + +------------------------------------------------ +$ git branch -d experimental +------------------------------------------------ + +Este comando garante que as mudanças no ramo experimental já estão no +ramo atual. + +Se você desenvolve em um ramo ideia-louca, e se arrepende, você pode +sempre remover o ramo com + +------------------------------------- +$ git branch -D ideia-louca +------------------------------------- + +Ramos são baratos e fáceis, então isto é uma boa maneira de experimentar +alguma coisa. + +Usando git para colaboração +--------------------------- + +Suponha que Alice começou um novo projeto com um repositório git em +/home/alice/project, e que Bob, que tem um diretório home na mesma +máquina, quer contribuir. + +Bob começa com: + +------------------------------------------------ +bob$ git clone /home/alice/project myrepo +------------------------------------------------ + +Isso cria um novo diretório "myrepo" contendo um clone do repositório de +Alice. O clone está no mesmo pé que o projeto original, possuindo sua +própria cópia da história do projeto original. + +Bob então faz algumas mudanças e as grava: + +------------------------------------------------ +(editar arquivos) +bob$ git commit -a +(repetir conforme necessário) +------------------------------------------------ + +Quanto está pronto, ele diz a Alice para puxar as mudanças do +repositório em /home/bob/myrepo. Ela o faz com: + +------------------------------------------------ +alice$ cd /home/alice/project +alice$ git pull /home/bob/myrepo master +------------------------------------------------ + +Isto unifica as mudanças do ramo "master" do Bob ao ramo atual de Alice. +Se Alice fez suas próprias mudanças no intervalo, ela, então, pode +precisar corrigir manualmente quaisquer conflitos. (Note que o argumento +"master" no comando acima é, de fato, desnecessário, já que é o padrão.) + +O comando "pull" executa, então, duas operações: ele obtém mudanças de +um ramo remoto, e, então, as unifica no ramo atual. + +Note que, em geral, Alice gostaria que suas mudanças locais fossem +gravadas antes de iniciar este "pull". Se o trabalho de Bob conflita +com o que Alice fez desde que suas histórias se ramificaram, Alice irá +usar seu diretório de trabalho e o índice para resolver conflitos, e +mudanças locais existentes irão interferir com o processo de resolução +de conflitos (git ainda irá realizar a obtenção mas irá se recusar a +unificar --- Alice terá que se livrar de suas mudanças locais de alguma +forma e puxar de novo quando isso acontecer). + +Alice pode espiar o que Bob fez sem unificar primeiro, usando o comando +"fetch"; isto permite Alice inspecionar o que Bob fez, usando um símbolo +especial "FETCH_HEAD", com o fim de determinar se ele tem alguma coisa +que vale puxar, assim: + +------------------------------------------------ +alice$ git fetch /home/bob/myrepo master +alice$ git log -p HEAD..FETCH_HEAD +------------------------------------------------ + +Esta operação é segura mesmo se Alice tem mudanças locais não gravadas. +A notação de intervalo "HEAD..FETCH_HEAD" significa mostrar tudo que é +alcançável de FETCH_HEAD mas exclua tudo o que é alcançável de HEAD. +Alice já sabe tudo que leva a seu estado atual (HEAD), e revisa o que Bob +tem em seu estado (FETCH_HEAD) que ela ainda não viu com esse comando. + +Se Alice quer visualizar o que Bob fez desde que suas histórias se +ramificaram, ela pode disparar o seguinte comando: + +------------------------------------------------ +$ gitk HEAD..FETCH_HEAD +------------------------------------------------ + +Isto usa a mesma notação de intervalo que vimos antes com 'git log'. + +Alice pode querer ver o que ambos fizeram desde que ramificaram. Ela +pode usar a forma com três pontos ao invés da forma com dois pontos: + +------------------------------------------------ +$ gitk HEAD...FETCH_HEAD +------------------------------------------------ + +Isto significa "mostre tudo que é alcançável de qualquer um deles, mas +exclua tudo que é alcançável a partir de ambos". + +Por favor, note que essas notações de intervalo podem ser usadas tanto +com gitk quanto com "git log". + +Após inspecionar o que Bob fez, se não há nada urgente, Alice pode +decidir continuar trabalhando sem puxar de Bob. Se a história de Bob +tem alguma coisa que Alice precisa imediatamente, Alice pode optar por +separar seu trabalho em progresso primeiro, fazer um "pull", e, então, +finalmente, retomar seu trabalho em progresso em cima da história +resultante. + +Quando você está trabalhando em um pequeno grupo unido, não é incomum +interagir com o mesmo repositório várias e várias vezes. Definindo um +repositório remoto antes de tudo, você pode fazê-lo mais facilmente: + +------------------------------------------------ +alice$ git remote add bob /home/bob/myrepo +------------------------------------------------ + +Com isso, Alice pode executar a primeira parte da operação "pull" usando +o comando 'git-fetch' sem unificar suas mudanças com seu próprio ramo, +usando: + +------------------------------------- +alice$ git fetch bob +------------------------------------- + +Diferente da forma longa, quando Alice obteve de Bob usando um +repositório remoto antes definido com 'git-remote', o que foi obtido é +armazenado em um ramo remoto, neste caso `bob/master`. Então, após isso: + +------------------------------------- +alice$ git log -p master..bob/master +------------------------------------- + +mostra uma lista de todas as mudanças que Bob fez desde que ramificou do +ramo master de Alice. + +Após examinar essas mudanças, Alice pode unificá-las em seu ramo master: + +------------------------------------- +alice$ git merge bob/master +------------------------------------- + +Esse `merge` pode também ser feito puxando de seu próprio ramo remoto, +assim: + +------------------------------------- +alice$ git pull . remotes/bob/master +------------------------------------- + +Note que 'git pull' sempre unifica ao ramo atual, independente do que +mais foi passado na linha de comando. + +Depois, Bob pode atualizar seu repositório com as últimas mudanças de +Alice, usando + +------------------------------------- +bob$ git pull +------------------------------------- + +Note que ele não precisa dar o caminho do repositório de Alice; quando +Bob clonou seu repositório, o git armazenou a localização de seu +repositório na configuração do mesmo, e essa localização é usada +para puxar: + +------------------------------------- +bob$ git config --get remote.origin.url +/home/alice/project +------------------------------------- + +(A configuração completa criada por 'git-clone' é visível usando `git +config -l`, e a página de manual linkgit:git-config[1] explica o +significado de cada opção.) + +Git também mantém uma cópia limpa do ramo master de Alice sob o nome +"origin/master": + +------------------------------------- +bob$ git branch -r + origin/master +------------------------------------- + +Se Bob decidir depois em trabalhar em um host diferente, ele ainda pode +executar clones e puxar usando o protocolo ssh: + +------------------------------------- +bob$ git clone alice.org:/home/alice/project myrepo +------------------------------------- + +Alternativamente, o git tem um protocolo nativo, ou pode usar rsync ou +http; veja linkgit:git-pull[1] para detalhes. + +Git pode também ser usado em um modo parecido com CVS, com um +repositório central para o qual vários usuários empurram modificações; +veja linkgit:git-push[1] e linkgit:gitcvs-migration[7]. + +Explorando história +----------------- + +A história no git é representada como uma série de commits +interrelacionados. Nós já vimos que o comando 'git-log' pode listar +esses commits. Note que a primeira linha de cada entrada no log também +dá o nome para o commit: + +------------------------------------- +$ git log +commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 +Author: Junio C Hamano <junkio@cox.net> +Date: Tue May 16 17:18:22 2006 -0700 + + merge-base: Clarify the comments on post processing. +------------------------------------- + +Nós podemos dar este nome ao 'git-show' para ver os detalhes sobre este +commit. + +------------------------------------- +$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 +------------------------------------- + +Mas há outras formas de se referir aos commits. Você pode usar qualquer +parte inicial do nome que seja longo o bastante para identificar +unicamente o commit: + +------------------------------------- +$ git show c82a22c39c # os primeiros caracteres do nome são o bastante + # usualmente +$ git show HEAD # a ponta do ramo atual +$ git show experimental # a ponta do ramo "experimental" +------------------------------------- + +Todo commit normalmente tem um commit "pai" que aponta para o estado +anterior do projeto: + +------------------------------------- +$ git show HEAD^ # para ver o pai de HEAD +$ git show HEAD^^ # para ver o avô de HEAD +$ git show HEAD~4 # para ver o trisavô de HEAD +------------------------------------- + +Note que commits de unificação podem ter mais de um pai: + +------------------------------------- +$ git show HEAD^1 # mostra o primeiro pai de HEAD (o mesmo que HEAD^) +$ git show HEAD^2 # mostra o segundo pai de HEAD +------------------------------------- + +Você também pode dar aos commits nomes à sua escolha; após executar + +------------------------------------- +$ git tag v2.5 1b2e1d63ff +------------------------------------- + +você pode se referir a 1b2e1d63ff pelo nome "v2.5". Se você pretende +compartilhar esse nome com outras pessoas (por exemplo, para identificar +uma versão de lançamento), você deveria criar um objeto "tag", e talvez +assiná-lo; veja linkgit:git-tag[1] para detalhes. + +Qualquer comando git que precise conhecer um commit pode receber +quaisquer desses nomes. Por exemplo: + +------------------------------------- +$ git diff v2.5 HEAD # compara o HEAD atual com v2.5 +$ git branch stable v2.5 # inicia um novo ramo chamado "stable" baseado + # em v2.5 +$ git reset --hard HEAD^ # reseta seu ramo atual e seu diretório de + # trabalho a seu estado em HEAD^ +------------------------------------- + +Seja cuidadoso com o último comando: além de perder quaisquer mudanças +em seu diretório de trabalho, ele também remove todos os commits +posteriores desse ramo. Se esse ramo é o único ramo contendo esses +commits, eles serão perdidos. Também, não use 'git-reset' num ramo +publicamente visível de onde outros desenvolvedores puxam, já que vai +forçar unificações desnecessárias para que outros desenvolvedores limpem +a história. Se você precisa desfazer mudanças que você empurrou, use +'git-revert' no lugar. + +O comando 'git-grep' pode buscar strings em qualquer versão de seu +projeto, então + +------------------------------------- +$ git grep "hello" v2.5 +------------------------------------- + +procura por todas as ocorrências de "hello" em v2.5. + +Se você deixar de fora o nome do commit, 'git-grep' irá procurar +quaisquer dos arquivos que ele gerencia no diretório corrente. Então + +------------------------------------- +$ git grep "hello" +------------------------------------- + +é uma forma rápida de buscar somente os arquivos que são rastreados pelo +git. + +Muitos comandos git também recebem um conjunto de commits, o que pode +ser especificado de várias formas. Aqui estão alguns exemplos com 'git-log': + +------------------------------------- +$ git log v2.5..v2.6 # commits entre v2.5 e v2.6 +$ git log v2.5.. # commits desde v2.5 +$ git log --since="2 weeks ago" # commits das últimas 2 semanas +$ git log v2.5.. Makefile # commits desde v2.5 que modificam + # Makefile +------------------------------------- + +Você também pode dar ao 'git-log' um "intervalo" de commits onde o +primeiro não é necessariamente um ancestral do segundo; por exemplo, se +as pontas dos ramos "stable" e "master" divergiram de um commit +comum algum tempo atrás, então + +------------------------------------- +$ git log stable..master +------------------------------------- + +irá listar os commits feitos no ramo "master" mas não no ramo +"stable", enquanto + +------------------------------------- +$ git log master..stable +------------------------------------- + +irá listar a lista de commits feitos no ramo "stable" mas não no ramo +"master". + +O comando 'git-log' tem uma fraqueza: ele precisa mostrar os commits em +uma lista. Quando a história tem linhas de desenvolvimento que +divergiram e então foram unificadas novamente, a ordem em que 'git-log' +apresenta essas mudanças é irrelevante. + +A maioria dos projetos com múltiplos contribuidores (como o kernel +Linux, ou o próprio git) tem unificações frequentes, e 'gitk' faz um +trabalho melhor de visualizar sua história. Por exemplo, + +------------------------------------- +$ gitk --since="2 weeks ago" drivers/ +------------------------------------- + +permite a você navegar em quaisquer commits desde as últimas duas semanas +de commits que modificaram arquivos sob o diretório "drivers". (Nota: +você pode ajustar as fontes do gitk segurando a tecla control enquanto +pressiona "-" ou "+".) + +Finalmente, a maioria dos comandos que recebem nomes de arquivo permitirão +também, opcionalmente, preceder qualquer nome de arquivo por um +commit, para especificar uma versão particular do arquivo: + +------------------------------------- +$ git diff v2.5:Makefile HEAD:Makefile.in +------------------------------------- + +Você pode usar 'git-show' para ver tal arquivo: + +------------------------------------- +$ git show v2.5:Makefile +------------------------------------- + +Próximos passos +---------- + +Este tutorial deve ser o bastante para operar controle de revisão +distribuído básico para seus projetos. No entanto, para entender +plenamente a profundidade e o poder do git você precisa entender duas +idéias simples nas quais ele se baseia: + + * A base de objetos é um sistema bem elegante usado para armazenar a + história de seu projeto--arquivos, diretórios, e commits. + + * O arquivo de índice é um cache do estado de uma árvore de diretório, + usado para criar commits, restaurar diretórios de trabalho, e + armazenar as várias árvores envolvidas em uma unificação. + +A parte dois deste tutorial explica a base de objetos, o arquivo de +índice, e algumas outras coisinhas que você vai precisar pra usar o +máximo do git. Você pode encontrá-la em linkgit:gittutorial-2[7]. + +Se você não quiser continuar com o tutorial agora nesse momento, algumas +outras digressões que podem ser interessantes neste ponto são: + + * linkgit:git-format-patch[1], linkgit:git-am[1]: Estes convertem + séries de commits em patches para email, e vice-versa, úteis para + projetos como o kernel Linux que dependem fortemente de patches + enviados por email. + + * linkgit:git-bisect[1]: Quando há uma regressão em seu projeto, uma + forma de rastrear um bug é procurando pela história para encontrar o + commit culpado. Git bisect pode ajudar a executar uma busca binária + por esse commit. Ele é inteligente o bastante para executar uma + busca próxima da ótima mesmo no caso de uma história complexa + não-linear com muitos ramos unificados. + + * link:everyday.html[GIT diariamente com 20 e tantos comandos] + + * linkgit:gitcvs-migration[7]: Git para usuários de CVS. + +VEJA TAMBÉM +-------- +linkgit:gittutorial-2[7], +linkgit:gitcvs-migration[7], +linkgit:gitcore-tutorial[7], +linkgit:gitglossary[7], +linkgit:git-help[1], +link:everyday.html[git diariamente], +link:user-manual.html[O Manual do Usuário git] + +GIT +--- +Parte da suite linkgit:git[1]. 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-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/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt index e3ddf91284..55b728632c 100644 --- a/Documentation/technical/api-tree-walking.txt +++ b/Documentation/technical/api-tree-walking.txt @@ -1,12 +1,145 @@ tree walking API ================ -Talk about <tree-walk.h>, things like +The tree walking API is used to traverse and inspect trees. -* struct tree_desc -* init_tree_desc -* tree_entry_extract -* update_tree_entry -* get_tree_entry +Data Structures +--------------- -(JC, Linus) +`struct name_entry`:: + + An entry in a tree. Each entry has a sha1 identifier, pathname, and + mode. + +`struct tree_desc`:: + + A semi-opaque data structure used to maintain the current state of the + walk. ++ +* `buffer` is a pointer into the memory representation of the tree. It always +points at the current entry being visited. + +* `size` counts the number of bytes left in the `buffer`. + +* `entry` points to the current entry being visited. + +`struct traverse_info`:: + + A structure used to maintain the state of a traversal. ++ +* `prev` points to the traverse_info which was used to descend into the +current tree. If this is the top-level tree `prev` will point to +a dummy traverse_info. + +* `name` is the entry for the current tree (if the tree is a subtree). + +* `pathlen` is the length of the full path for the current tree. + +* `conflicts` can be used by callbacks to maintain directory-file conflicts. + +* `fn` is a callback called for each entry in the tree. See Traversing for more +information. + +* `data` can be anything the `fn` callback would want to use. + +Initializing +------------ + +`init_tree_desc`:: + + Initialize a `tree_desc` and decode its first entry. The buffer and + size parameters are assumed to be the same as the buffer and size + members of `struct tree`. + +`fill_tree_descriptor`:: + + Initialize a `tree_desc` and decode its first entry given the sha1 of + a tree. Returns the `buffer` member if the sha1 is a valid tree + identifier and NULL otherwise. + +`setup_traverse_info`:: + + Initialize a `traverse_info` given the pathname of the tree to start + traversing from. The `base` argument is assumed to be the `path` + member of the `name_entry` being recursed into unless the tree is a + top-level tree in which case the empty string ("") is used. + +Walking +------- + +`tree_entry`:: + + Visit the next entry in a tree. Returns 1 when there are more entries + left to visit and 0 when all entries have been visited. This is + commonly used in the test of a while loop. + +`tree_entry_len`:: + + Calculate the length of a tree entry's pathname. This utilizes the + memory structure of a tree entry to avoid the overhead of using a + generic strlen(). + +`update_tree_entry`:: + + Walk to the next entry in a tree. This is commonly used in conjunction + with `tree_entry_extract` to inspect the current entry. + +`tree_entry_extract`:: + + Decode the entry currently being visited (the one pointed to by + `tree_desc's` `entry` member) and return the sha1 of the entry. The + `pathp` and `modep` arguments are set to the entry's pathname and mode + respectively. + +`get_tree_entry`:: + + Find an entry in a tree given a pathname and the sha1 of a tree to + search. Returns 0 if the entry is found and -1 otherwise. The third + and fourth parameters are set to the entry's sha1 and mode + respectively. + +Traversing +---------- + +`traverse_trees`:: + + Traverse `n` number of trees in parallel. The `fn` callback member of + `traverse_info` is called once for each tree entry. + +`traverse_callback_t`:: + The arguments passed to the traverse callback are as follows: ++ +* `n` counts the number of trees being traversed. + +* `mask` has its nth bit set if something exists in the nth entry. + +* `dirmask` has its nth bit set if the nth tree's entry is a directory. + +* `entry` is an array of size `n` where the nth entry is from the nth tree. + +* `info` maintains the state of the traversal. + ++ +Returning a negative value will terminate the traversal. Otherwise the +return value is treated as an update mask. If the nth bit is set the nth tree +will be updated and if the bit is not set the nth tree entry will be the +same in the next callback invocation. + +`make_traverse_path`:: + + Generate the full pathname of a tree entry based from the root of the + traversal. For example, if the traversal has recursed into another + tree named "bar" the pathname of an entry "baz" in the "bar" + tree would be "bar/baz". + +`traverse_path_len`:: + + Calculate the length of a pathname returned by `make_traverse_path`. + This utilizes the memory structure of a tree entry to avoid the + overhead of using a generic strlen(). + +Authors +------- + +Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds +<torvalds@linux-foundation.org> 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` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |