diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/RelNotes-1.5.3.6.txt | 45 | ||||
-rw-r--r-- | Documentation/RelNotes-1.5.4.txt | 44 | ||||
-rw-r--r-- | Documentation/config.txt | 8 | ||||
-rw-r--r-- | Documentation/diff-options.txt | 24 | ||||
-rw-r--r-- | Documentation/git-clone.txt | 1 | ||||
-rw-r--r-- | Documentation/git-diff.txt | 1 | ||||
-rw-r--r-- | Documentation/git-format-patch.txt | 1 | ||||
-rw-r--r-- | Documentation/git-get-tar-commit-id.txt | 4 | ||||
-rw-r--r-- | Documentation/git-ls-files.txt | 5 | ||||
-rw-r--r-- | Documentation/git-reflog.txt | 15 | ||||
-rw-r--r-- | Documentation/git-remote.txt | 2 | ||||
-rw-r--r-- | Documentation/git-rev-parse.txt | 76 | ||||
-rw-r--r-- | Documentation/git-svn.txt | 6 | ||||
-rw-r--r-- | Documentation/git.txt | 1 | ||||
-rw-r--r-- | Documentation/howto/maintain-git.txt | 277 | ||||
-rw-r--r-- | Documentation/urls.txt | 6 | ||||
-rw-r--r-- | Documentation/user-manual.txt | 87 |
17 files changed, 573 insertions, 30 deletions
diff --git a/Documentation/RelNotes-1.5.3.6.txt b/Documentation/RelNotes-1.5.3.6.txt index 06e44f7735..069a2b2cf9 100644 --- a/Documentation/RelNotes-1.5.3.6.txt +++ b/Documentation/RelNotes-1.5.3.6.txt @@ -4,18 +4,45 @@ GIT v1.5.3.6 Release Notes Fixes since v1.5.3.5 -------------------- - * git-cvsexportcommit handles root commits better; + * git-cvsexportcommit handles root commits better. * git-svn dcommit used to clobber when sending a series of - patches; + patches. + + * git-svn dcommit failed after attempting to rebase when + started with a dirty index; now it stops upfront. * git-grep sometimes refused to work when your index was - unmerged; + unmerged. - * Quite a lot of documentation clarifications. + * "git-grep -A1 -B2" acted as if it was told to run "git -A1 -B21". + + * git-hash-object did not honor configuration variables, such as + core.compression. + + * git-index-pack choked on a huge pack on 32-bit machines, even when + large file offsets are supported. + + * atom feeds from git-web said "10" for the month of November. + + * a memory leak in commit walker was plugged. + + * When git-send-email inserted the original author's From: + address in body, it did not mark the message with + Content-type: as needed. --- -exec >/var/tmp/1 -O=v1.5.3.5-32-gcb6c162 -echo O=`git describe refs/heads/maint` -git shortlog --no-merges $O..refs/heads/maint + * git-revert and git-cherry-pick incorrectly refused to start + when the work tree was dirty. + + * git-clean did not honor core.excludesfile configuration. + + * git-add mishandled ".gitignore" files when applying them to + subdirectories. + + * While importing a too branchy history, git-fastimport did not + honor delta depth limit properly. + + * Support for zlib implementations that lack ZLIB_VERNUM and definition + of deflateBound() has been added. + + * Quite a lot of documentation clarifications. diff --git a/Documentation/RelNotes-1.5.4.txt b/Documentation/RelNotes-1.5.4.txt index 93fb9c914c..a4a2a7f429 100644 --- a/Documentation/RelNotes-1.5.4.txt +++ b/Documentation/RelNotes-1.5.4.txt @@ -32,6 +32,11 @@ Updates since v1.5.3 (read: safer than the usual one) after the user accumulates too many loose objects. + * You need to explicitly set clean.requireForce to "false" to allow + git-clean without -f to do any damage (lack of the configuration + variable used to mean "do not require", but we now use the safer + default). + * git-push has been rewritten in C. * git-push learned --dry-run option to show what would happen @@ -52,11 +57,39 @@ Updates since v1.5.3 * git-lost-found was deprecated in favor of git-fsck's --lost-found option. + * "git log" learned --early-output option to help interactive + GUI implementations. + * git-svnimport was removed in favor of git-svn. * git-bisect learned "skip" action to mark untestable commits. - * rename detection diff family, while detecting exact matches, + * git-format-patch learned "format.numbered" configuration variable + to automatically turn --numbered option on when more than one + commits are formatted. + + * git-ls-files learned "--exclude-standard" to use the canned + set of exclude files. + + * git-rebase now detaches head during its operation, so after a + successful "git rebase" operation, the reflog entry branch@{1} + for the current branch points at the commit before the rebase + was started. + + * "git-tag -a -f existing" begins the editor session using the + existing annotation message. + + * "git cvsexportcommit" learned -w option to specify and switch + to the CVS working directory. + + * "git checkout" from a subdirectory learned to use "../path" + to allow checking out a path outside the current directory + without cd'ing up. + + * Output processing for '--pretty=format:<user format>' has + been optimized. + + * Rename detection diff family, while detecting exact matches, has been greatly optimized. * Example update and post-receive hooks have been improved. @@ -77,8 +110,15 @@ Fixes since v1.5.3 All of the fixes in v1.5.3 maintenance series are included in this release, unless otherwise noted. + * git-svn talking with the SVN over http will correctly quote branch + and project names. + + * "git rev-list --objects A..B" choked when the lower boundary + of the range involved a subproject. This fix is also queued + for 'maint' (but not in there yet). + -- exec >/var/tmp/1 -O=v1.5.3.5-618-g5d4138a +O=v1.5.3.6-727-g5d3d1ca echo O=`git describe refs/heads/master` git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/config.txt b/Documentation/config.txt index 6dc9f3ed02..39d1ef5298 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -226,13 +226,15 @@ core.compression:: An integer -1..9, indicating a default compression level. -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being slowest. + If set, this provides a default to other compression variables, + such as 'core.loosecompression' and 'pack.compression'. core.loosecompression:: An integer -1..9, indicating the compression level for objects that are not in a pack file. -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being slowest. If not set, defaults to core.compression. If that is - not set, defaults to 0 (best speed). + not set, defaults to 1 (best speed). core.packedGitWindowSize:: Number of bytes of a pack file to map into memory in a @@ -648,7 +650,9 @@ pack.compression:: in a pack file. -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being slowest. If not set, defaults to core.compression. If that is - not set, defaults to -1. + not set, defaults to -1, the zlib default, which is "a default + compromise between speed and compression (currently equivalent + to level 6)." pack.deltaCacheSize:: The maximum memory in bytes used for caching deltas in diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index b1f528ae88..e4af393515 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -1,5 +1,25 @@ +// Please don't remove this comment as asciidoc behaves badly when +// the first non-empty line is ifdef/ifndef. The symptom is that +// without this comment the <git-diff-core> attribute conditionally +// defined below ends up being defined unconditionally. +// Last checked with asciidoc 7.0.2. + +ifndef::git-format-patch[] +ifndef::git-diff[] +:git-diff-core: 1 +endif::git-diff[] +endif::git-format-patch[] + +ifdef::git-format-patch[] -p:: - Generate patch (see section on generating patches) + Generate patches without diffstat. +endif::git-format-patch[] + +ifndef::git-format-patch[] +-p:: + Generate patch (see section on generating patches). + {git-diff? This is the default.} +endif::git-format-patch[] -u:: Synonym for "-p". @@ -13,6 +33,7 @@ --raw:: Generate the raw format. + {git-diff-core? This is the default.} --patch-with-raw:: Synonym for "-p --raw". @@ -41,6 +62,7 @@ --patch-with-stat:: Synonym for "-p --stat". + {git-format-patch? This is the default.} -z:: NUL-line termination on output. This affects the --raw diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 14e58f3866..c90bcece24 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -130,6 +130,7 @@ OPTIONS for "host.xz:foo/.git"). Cloning into an existing directory is not allowed. +:git-clone: 1 include::urls.txt[] Examples diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 11c4216c4a..2808a5ec44 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -75,6 +75,7 @@ and the range notations ("<commit>..<commit>" and OPTIONS ------- +:git-diff: 1 include::diff-options.txt[] <path>...:: diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 9d4bae2f60..6fb9429851 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -66,6 +66,7 @@ reference. OPTIONS ------- +:git-format-patch: 1 include::diff-options.txt[] -<n>:: diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 76316bbc9e..60d1c52f44 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -3,7 +3,7 @@ git-get-tar-commit-id(1) NAME ---- -git-get-tar-commit-id - Extract commit ID from an archive created using git-tar-tree +git-get-tar-commit-id - Extract commit ID from an archive created using git-archive SYNOPSIS @@ -19,7 +19,7 @@ runtime is not influenced by the size of <tarfile> very much. If no commit ID is found, git-get-tar-commit-id quietly exists with a return code of 1. This can happen if <tarfile> had not been created -using git-archive or if the <treeish> parameter of git-archive had been +using git-archive or if the first parameter of git-archive had been a tree ID instead of a commit ID or tag. diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 9e454f0a4d..2ec0c0d270 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -15,6 +15,7 @@ SYNOPSIS [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] + [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] [--full-name] [--abbrev] [--] [<file>]\* @@ -77,6 +78,10 @@ OPTIONS read additional exclude patterns that apply only to the directory and its subdirectories in <file>. +--exclude-standard:: + Add the standard git exclusions: .git/info/exclude, .gitignore + in each directory, and the user's global exclusion file. + --error-unmatch:: If any <file> does not appear in the index, treat this as an error (return 1). diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 5c7316ceb8..25003c3866 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -19,7 +19,7 @@ depending on the subcommand: git reflog expire [--dry-run] [--stale-fix] [--verbose] [--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>... -git reflog [show] [log-options] +git reflog [show] [log-options] [<ref>] Reflog is a mechanism to record when the tip of branches are updated. This command is to manage the information recorded in it. @@ -32,9 +32,16 @@ directly by the end users -- instead, see gitlink:git-gc[1]. The subcommand "show" (which is also the default, in the absence of any subcommands) will take all the normal log options, and show the log of -`HEAD`, which will cover all recent actions, including branch switches. -It is basically an alias for 'git log -g --abbrev-commit ---pretty=oneline', see gitlink:git-log[1]. +the reference provided in the command-line (or `HEAD`, by default). +The reflog will cover all recent actions (HEAD reflog records branch switching +as well). It is an alias for 'git log -g --abbrev-commit --pretty=oneline'; +see gitlink:git-log[1]. + +The reflog is useful in various git commands, to specify the old value +of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be +two moves ago", `master@\{one.week.ago\}` means "where master used to +point to one week ago", and so on. See gitlink:git-rev-parse[1] for +more details. OPTIONS diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 0da8704a25..4b263c249c 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -101,7 +101,7 @@ $ git remote origin $ git branch -r origin/master -$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git +$ git remote add linux-nfs git://linux-nfs.org/pub/linux/nfs-2.6.git $ git remote linux-nfs origin diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 4758c33dee..329fce0aab 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -23,6 +23,13 @@ distinguish between them. OPTIONS ------- +--parseopt:: + Use `git-rev-parse` in option parsing mode (see PARSEOPT section below). + +--keep-dash-dash:: + Only meaningful in `--parseopt` mode. Tells the option parser to echo + out the first `--` met instead of skipping it. + --revs-only:: Do not output flags and parameters not meant for `git-rev-list` command. @@ -288,10 +295,75 @@ Here are a handful examples: C^@ I J F F^! D G H D F +PARSEOPT +-------- + +In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell +scripts the same facilities C builtins have. It works as an option normalizer +(e.g. splits single switches aggregate values), a bit like `getopt(1)` does. + +It takes on the standard input the specification of the options to parse and +understand, and echoes on the standard output a line suitable for `sh(1)` `eval` +to replace the arguments with normalized ones. In case of error, it outputs +usage on the standard error stream, and exits with code 129. + +Input Format +~~~~~~~~~~~~ + +`git-rev-parse --parseopt` input format is fully text based. It has two parts, +separated by a line that contains only `--`. The lines before the separator +(should be more than one) are used for the usage. +The lines after the separator describe the options. + +Each line of options has this format: + +------------ +<opt_spec><arg_spec>? SP+ help LF +------------ + +`<opt_spec>`:: + its format is the short option character, then the long option name + separated by a comma. Both parts are not required, though at least one + is necessary. `h,help`, `dry-run` and `f` are all three correct + `<opt_spec>`. + +`<arg_spec>`:: + an `<arg_spec>` tells the option parser if the option has an argument + (`=`), an optional one (`?` though its use is discouraged) or none + (no `<arg_spec>` in that case). + +The remainder of the line, after stripping the spaces, is used +as the help associated to the option. + +Blank lines are ignored, and lines that don't match this specification are used +as option group headers (start the line with a space to create such +lines on purpose). + +Example +~~~~~~~ + +------------ +OPTS_SPEC="\ +some-command [options] <args>... + +some-command does foo and bar! +-- +h,help show the help + +foo some nifty option --foo +bar= some cool option --bar with an argument + + An option group Header +C? option C with an optional argument" + +eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?` +------------ + + Author ------ -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net> +Written by Linus Torvalds <torvalds@osdl.org> . +Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org> Documentation -------------- diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 488e4b1caf..918a9928b1 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -193,6 +193,12 @@ Any other arguments are passed directly to `git log' repository (that has been init-ed with git-svn). The -r<revision> option is required for this. +'info':: + Shows information about a file or directory similar to what + `svn info' provides. Does not currently support a -r/--revision + argument. Use the --url option to output only the value of the + 'URL:' field. + -- OPTIONS diff --git a/Documentation/git.txt b/Documentation/git.txt index 6db7ae1ea7..546020100a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -46,6 +46,7 @@ Documentation for older releases are available here: * link:v1.5.3/git.html[documentation for release 1.5.3] * release notes for + link:RelNotes-1.5.3.6.txt[1.5.3.6], link:RelNotes-1.5.3.5.txt[1.5.3.5], link:RelNotes-1.5.3.4.txt[1.5.3.4], link:RelNotes-1.5.3.3.txt[1.5.3.3], diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt new file mode 100644 index 0000000000..4357e26913 --- /dev/null +++ b/Documentation/howto/maintain-git.txt @@ -0,0 +1,277 @@ +From: Junio C Hamano <gitster@pobox.com> +Date: Wed, 21 Nov 2007 16:32:55 -0800 +Subject: Addendum to "MaintNotes" +Abstract: Imagine that git development is racing along as usual, when our friendly + neighborhood maintainer is struck down by a wayward bus. Out of the + hordes of suckers (loyal developers), you have been tricked (chosen) to + step up as the new maintainer. This howto will show you "how to" do it. + +The maintainer's git time is spent on three activities. + + - Communication (60%) + + Mailing list discussions on general design, fielding user + questions, diagnosing bug reports; reviewing, commenting on, + suggesting alternatives to, and rejecting patches. + + - Integration (30%) + + Applying new patches from the contributors while spotting and + correcting minor mistakes, shuffling the integration and + testing branches, pushing the results out, cutting the + releases, and making announcements. + + - Own development (10%) + + Scratching my own itch and sending proposed patch series out. + +The policy on Integration is informally mentioned in "A Note +from the maintainer" message, which is periodically posted to +this mailing list after each feature release is made. + +The policy. + + - Feature releases are numbered as vX.Y.Z and are meant to + contain bugfixes and enhancements in any area, including + functionality, performance and usability, without regression. + + - Maintenance releases are numbered as vX.Y.Z.W and are meant + to contain only bugfixes for the corresponding vX.Y.Z feature + release and earlier maintenance releases vX.Y.Z.V (V < W). + + - 'master' branch is used to prepare for the next feature + release. In other words, at some point, the tip of 'master' + branch is tagged with vX.Y.Z. + + - 'maint' branch is used to prepare for the next maintenance + release. After the feature release vX.Y.Z is made, the tip + of 'maint' branch is set to that release, and bugfixes will + accumulate on the branch, and at some point, the tip of the + branch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on. + + - 'next' branch is used to publish changes (both enhancements + and fixes) that (1) have worthwhile goal, (2) are in a fairly + good shape suitable for everyday use, (3) but have not yet + demonstrated to be regression free. New changes are tested + in 'next' before merged to 'master'. + + - 'pu' branch is used to publish other proposed changes that do + not yet pass the criteria set for 'next'. + + - The tips of 'master', 'maint' and 'next' branches will always + fast forward, to allow people to build their own + customization on top of them. + + - Usually 'master' contains all of 'maint', 'next' contains all + of 'master' and 'pu' contains all of 'next'. + + - The tip of 'master' is meant to be more stable than any + tagged releases, and the users are encouraged to follow it. + + - The 'next' branch is where new action takes place, and the + users are encouraged to test it so that regressions and bugs + are found before new topics are merged to 'master'. + + +A typical git day for the maintainer implements the above policy +by doing the following: + + - Scan mailing list and #git channel log. Respond with review + comments, suggestions etc. Kibitz. Collect potentially + usable patches from the mailing list. Patches about a single + topic go to one mailbox (I read my mail in Gnus, and type + \C-o to save/append messages in files in mbox format). + + - Review the patches in the saved mailboxes. Edit proposed log + message for typofixes and clarifications, and add Acks + collected from the list. Edit patch to incorporate "Oops, + that should have been like this" fixes from the discussion. + + - Classify the collected patches and handle 'master' and + 'maint' updates: + + - Obviously correct fixes that pertain to the tip of 'maint' + are directly applied to 'maint'. + + - Obviously correct fixes that pertain to the tip of 'master' + are directly applied to 'master'. + + This step is done with "git am". + + $ git checkout master ;# or "git checkout maint" + $ git am -3 -s mailbox + $ make test + + - Merge downwards (maint->master): + + $ git checkout master + $ git merge maint + $ make test + + - Review the last issue of "What's cooking" message, review the + topics scheduled for merging upwards (topic->master and + topic->maint), and merge. + + $ git checkout master ;# or "git checkout maint" + $ git merge ai/topic ;# or "git merge ai/maint-topic" + $ git log -p ORIG_HEAD.. ;# final review + $ git diff ORIG_HEAD.. ;# final review + $ make test ;# final review + $ git branch -d ai/topic ;# or "git branch -d ai/maint-topic" + + - Merge downwards (maint->master) if needed: + + $ git checkout master + $ git merge maint + $ make test + + - Merge downwards (master->next) if needed: + + $ git checkout next + $ git merge master + $ make test + + - Handle the remaining patches: + + - Anything unobvious that is applicable to 'master' (in other + words, does not depend on anything that is still in 'next' + and not in 'master') is applied to a new topic branch that + is forked from the tip of 'master'. This includes both + enhancements and unobvious fixes to 'master'. A topic + branch is named as ai/topic where "ai" is typically + author's initial and "topic" is a descriptive name of the + topic (in other words, "what's the series is about"). + + - An unobvious fix meant for 'maint' is applied to a new + topic branch that is forked from the tip of 'maint'. The + topic is named as ai/maint-topic. + + - Changes that pertain to an existing topic are applied to + the branch, but: + + - obviously correct ones are applied first; + + - questionable ones are discarded or applied to near the tip; + + - Replacement patches to an existing topic are accepted only + for commits not in 'next'. + + The above except the "replacement" are all done with: + + $ git am -3 -s mailbox + + while patch replacement is often done by: + + $ git format-patch ai/topic~$n..ai/topic ;# export existing + + then replace some parts with the new patch, and reapplying: + + $ git reset --hard ai/topic~$n + $ git am -3 -s 000*.txt + + The full test suite is always run for 'maint' and 'master' + after patch application; for topic branches the tests are run + as time permits. + + - Update "What's cooking" message to review the updates to + existing topics, newly added topics and graduated topics. + + This step is helped with Meta/UWC script (where Meta/ contains + a checkout of the 'todo' branch). + + - Merge topics to 'next'. For each branch whose tip is not + merged to 'next', one of three things can happen: + + - The commits are all next-worthy; merge the topic to next: + + $ git checkout next + $ git merge ai/topic ;# or "git merge ai/maint-topic" + $ make test + + - The new parts are of mixed quality, but earlier ones are + next-worthy; merge the early parts to next: + + $ git checkout next + $ git merge ai/topic~2 ;# the tip two are dubious + $ make test + + - Nothing is next-worthy; do not do anything. + + - Rebase topics that do not have any commit in next yet. This + step is optional but sometimes is worth doing when an old + series that is not in next can take advantage of low-level + framework change that is merged to 'master' already. + + $ git rebase master ai/topic + + This step is helped with Meta/git-topic.perl script to + identify which topic is rebaseable. There also is a + pre-rebase hook to make sure that topics that are already in + 'next' are not rebased beyond the merged commit. + + - Rebuild "pu" to merge the tips of topics not in 'next'. + + $ git checkout pu + $ git reset --hard next + $ git merge ai/topic ;# repeat for all remaining topics + $ make test + + This step is helped with Meta/PU script + + - Push four integration branches to a private repository at + k.org and run "make test" on all of them. + + - Push four integration branches to /pub/scm/git/git.git at + k.org. This triggers its post-update hook which: + + (1) runs "git pull" in $HOME/git-doc/ repository to pull + 'master' just pushed out; + + (2) runs "make doc" in $HOME/git-doc/, install the generated + documentation in staging areas, which are separate + repositories that have html and man branches checked + out. + + (3) runs "git commit" in the staging areas, and run "git + push" back to /pub/scm/git/git.git/ to update the html + and man branches. + + (4) installs generated documentation to /pub/software/scm/git/docs/ + to be viewed from http://www.kernel.org/ + + - Fetch html and man branches back from k.org, and push four + integration branches and the two documentation branches to + repo.or.cz + + +Some observations to be made. + + * Each topic is tested individually, and also together with + other topics cooking in 'next'. Until it matures, none part + of it is merged to 'master'. + + * A topic already in 'next' can get fixes while still in + 'next'. Such a topic will have many merges to 'next' (in + other words, "git log --first-parent next" will show many + "Merge ai/topic to next" for the same topic. + + * An unobvious fix for 'maint' is cooked in 'next' and then + merged to 'master' to make extra sure it is Ok and then + merged to 'maint'. + + * Even when 'next' becomes empty (in other words, all topics + prove stable and are merged to 'master' and "git diff master + next" shows empty), it has tons of merge commits that will + never be in 'master'. + + * In principle, "git log --first-parent master..next" should + show nothing but merges (in practice, there are fixup commits + and reverts that are not merges). + + * Commits near the tip of a topic branch that are not in 'next' + are fair game to be discarded, replaced or rewritten. + Commits already merged to 'next' will not be. + + * Being in the 'next' branch is not a guarantee for a topic to + be included in the next feature release. Being in the + 'master' branch typically is. diff --git a/Documentation/urls.txt b/Documentation/urls.txt index e67f9140ab..4f667382ec 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -36,5 +36,11 @@ To sync with a local directory, you can use: - file:///path/to/repo.git/ =============================================================== +ifndef::git-clone[] They are mostly equivalent, except when cloning. See gitlink:git-clone[1] for details. +endif::git-clone[] + +ifdef::git-clone[] +They are equivalent, except the former implies --local option. +endif::git-clone[] diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index c7cfbbccfc..3661879f1a 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -658,16 +658,23 @@ gitlink:git-diff[1]: $ git diff master..test ------------------------------------------------- -Sometimes what you want instead is a set of patches: +That will produce the diff between the tips of the two branches. If +you'd prefer to find the diff from their common ancestor to test, you +can use three dots instead of two: + +------------------------------------------------- +$ git diff master...test +------------------------------------------------- + +Sometimes what you want instead is a set of patches; for this you can +use gitlink:git-format-patch[1]: ------------------------------------------------- $ git format-patch master..test ------------------------------------------------- will generate a file with a patch for each commit reachable from test -but not from master. Note that if master also has commits which are -not reachable from test, then the combined result of these patches -will not be the same as the diff produced by the git-diff example. +but not from master. [[viewing-old-file-versions]] Viewing old file versions @@ -1567,9 +1574,9 @@ old history using, for example, $ git log master@{1} ------------------------------------------------- -This lists the commits reachable from the previous version of the head. -This syntax can be used with any git command that accepts a commit, -not just with git log. Some other examples: +This lists the commits reachable from the previous version of the +"master" branch head. This syntax can be used with any git command +that accepts a commit, not just with git log. Some other examples: ------------------------------------------------- $ git show master@{2} # See where the branch pointed 2, @@ -2554,6 +2561,72 @@ branches into their own work. For true distributed development that supports proper merging, published branches should never be rewritten. +[[bisect-merges]] +Why bisecting merge commits can be harder than bisecting linear history +----------------------------------------------------------------------- + +The gitlink:git-bisect[1] command correctly handles history that +includes merge commits. However, when the commit that it finds is a +merge commit, the user may need to work harder than usual to figure out +why that commit introduced a problem. + +Imagine this history: + +................................................ + ---Z---o---X---...---o---A---C---D + \ / + o---o---Y---...---o---B +................................................ + +Suppose that on the upper line of development, the meaning of one +of the functions that exists at Z is changed at commit X. The +commits from Z leading to A change both the function's +implementation and all calling sites that exist at Z, as well +as new calling sites they add, to be consistent. There is no +bug at A. + +Suppose that in the meantime on the lower line of development somebody +adds a new calling site for that function at commit Y. The +commits from Z leading to B all assume the old semantics of that +function and the callers and the callee are consistent with each +other. There is no bug at B, either. + +Suppose further that the two development lines merge cleanly at C, +so no conflict resolution is required. + +Nevertheless, the code at C is broken, because the callers added +on the lower line of development have not been converted to the new +semantics introduced on the upper line of development. So if all +you know is that D is bad, that Z is good, and that +gitlink:git-bisect[1] identifies C as the culprit, how will you +figure out that the problem is due to this change in semantics? + +When the result of a git-bisect is a non-merge commit, you should +normally be able to discover the problem by examining just that commit. +Developers can make this easy by breaking their changes into small +self-contained commits. That won't help in the case above, however, +because the problem isn't obvious from examination of any single +commit; instead, a global view of the development is required. To +make matters worse, the change in semantics in the problematic +function may be just one small part of the changes in the upper +line of development. + +On the other hand, if instead of merging at C you had rebased the +history between Z to B on top of A, you would have gotten this +linear history: + +................................................................ + ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D* +................................................................ + +Bisecting between Z and D* would hit a single culprit commit Y*, +and understanding why Y* was broken would probably be easier. + +Partly for this reason, many experienced git users, even when +working on an otherwise merge-heavy project, keep the history +linear by rebasing against the latest upstream version before +publishing. + [[advanced-branch-management]] Advanced branch management ========================== |