path: root/Documentation
diff options
authorJunio C Hamano <>2007-11-19 07:56:01 (GMT)
committerJunio C Hamano <>2007-11-19 07:56:01 (GMT)
commit154c7d0759b6885034bffa7a34d464d703fc8bb3 (patch)
tree9a53213c3c9d39643d7451cb57316935eb634f5f /Documentation
parent005e2dfdf299a7d869fa9ec819171fba574f42eb (diff)
parentc251005c7a5279166a27d4d06854f0c3d26e8208 (diff)
Merge branch 'maint' of git:// into maint
* 'maint' of git:// 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
Diffstat (limited to 'Documentation')
4 files changed, 81 insertions, 13 deletions
diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt
index c126038..c3f0be5 100644
--- a/Documentation/core-tutorial.txt
+++ b/Documentation/core-tutorial.txt
@@ -1082,11 +1082,6 @@ server like git Native transport does. Any stock HTTP server
that does not even support directory index would suffice. But
you must prepare your repository with `git-update-server-info`
to help dumb transport downloaders.
-There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload`
-programs, which are 'commit walkers'; they outlived their
-usefulness when git Native and SSH transports were introduced,
-and not used by `git pull` or `git push` scripts.
Once you fetch from the remote repository, you `merge` that
with your current branch.
diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt
index 9b5f86f..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)
-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
@@ -14,12 +14,12 @@ SYNOPSIS
Acts as a filter, extracting the commit ID stored in archives created by
-git-tar-tree. It reads only the first 1024 bytes of input, thus its
+gitlink:git-archive[1]. It reads only the first 1024 bytes of input, thus its
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-tar-tree or if the first parameter of git-tar-tree 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 c386dd0..886bc03 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -91,7 +91,7 @@ $ git remote
$ git branch -r
-$ git remote add linux-nfs git://
+$ git remote add linux-nfs git://
$ git remote
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index c7fdf25..c027353 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
@@ -2554,6 +2561,72 @@ branches into their own work.
For true distributed development that supports proper merging,
published branches should never be rewritten.
+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
Advanced branch management