From 8391c60b6e08604e7023a8fff74350d6b35974af Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Fri, 2 Nov 2007 22:54:31 -0400 Subject: [PATCH 1/4] git-remote.txt: fix example url If I'm going to use a real example as a URL, I suppose I should get it right.... Signed-off-by: J. Bruce Fields --- Documentation/git-remote.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index c386dd0168..886bc03c4a 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -91,7 +91,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 From 3fb00282538409daf4d05ce4631a2c3eae235c69 Mon Sep 17 00:00:00 2001 From: Steffen Prohaska Date: Sat, 10 Nov 2007 14:49:54 +0100 Subject: [PATCH 2/4] user-manual: Add section "Why bisecting merge commits can be harder ..." This commit adds a discussion of the challenge of bisecting merge commits to the user manual. The original author is Junio C Hamano , who posted the text to the mailing list . His email was adapted for the manual. The discussion is added to "Rewriting history and maintainig patch series". The text added requires good understanding of merging and rebasing. Therefore it should not be placed too early in the manual. Right after the section on "Problems with rewriting history", the discussion of bisect gives another reason for linearizing as much of the history as possible. The text includes suggestions and fixes by Ralf Wildenhues and Benoit Sigoure . Signed-off-by: Steffen Prohaska Signed-off-by: J. Bruce Fields --- Documentation/user-manual.txt | 66 +++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index c7fdf25e27..e399685d6c 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -2554,6 +2554,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 ========================== From 5b98d9bca16e19710380d2d03f704de9eb98621d Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 18 Nov 2007 19:18:27 -0500 Subject: [PATCH 3/4] user-manual: mention "..." in "Generating diffs", etc. We should mention the use of the "..." syntax for git-diff here. The note about the difference between diff and the combined output of git-format-patch then no longer fits so well, so remove it. Add a reference to the git-format-patch[1] manpage. Signed-off-by: J. Bruce Fields --- Documentation/user-manual.txt | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index e399685d6c..c027353337 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 From c251005c7a5279166a27d4d06854f0c3d26e8208 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 18 Nov 2007 20:50:57 -0500 Subject: [PATCH 4/4] Documentation: Fix references to deprecated commands ... by changing git-tar-tree reference to git-archive and removing seemingly unrelevant footnote about git-ssh-{fetch,upload}. Signed-off-by: Jonas Fonseca Signed-off-by: J. Bruce Fields --- Documentation/core-tutorial.txt | 5 ----- Documentation/git-get-tar-commit-id.txt | 6 +++--- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index c126038c1f..c3f0be535d 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 9b5f86fc30..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 @@ -14,12 +14,12 @@ SYNOPSIS DESCRIPTION ----------- 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 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 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.