summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2007-11-19 08:19:15 (GMT)
committerJunio C Hamano <gitster@pobox.com>2007-11-19 08:19:15 (GMT)
commit5d1d1c14790cf74eb0d630c4404114206061232d (patch)
tree335c531a9a7115e4a965277e54cd07781c86481d
parent8d3f1743103daafab20b6c7b34c1690ecc5af837 (diff)
parent154c7d0759b6885034bffa7a34d464d703fc8bb3 (diff)
downloadgit-5d1d1c14790cf74eb0d630c4404114206061232d.zip
git-5d1d1c14790cf74eb0d630c4404114206061232d.tar.gz
git-5d1d1c14790cf74eb0d630c4404114206061232d.tar.bz2
Merge branch 'maint'
* maint: Documentation: Fix references to deprecated commands user-manual: mention "..." in "Generating diffs", etc. user-manual: Add section "Why bisecting merge commits can be harder ..." git-remote.txt: fix example url
-rw-r--r--Documentation/git-get-tar-commit-id.txt4
-rw-r--r--Documentation/git-remote.txt2
-rw-r--r--Documentation/user-manual.txt81
3 files changed, 80 insertions, 7 deletions
diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt
index 76316bb..60d1c52 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-remote.txt b/Documentation/git-remote.txt
index 0da8704..4b263c2 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/user-manual.txt b/Documentation/user-manual.txt
index 518b7b5..3661879 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
@@ -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
==========================