Git User's Manual (for version 1.5.3 or newer)

ChapterÂ 1, Repositories and Branches and ChapterÂ 2, Exploring git history explain how to fetch and study a project using gitâread these chapters to learn how to build and test a particular version of a software project, search for @@ -304,10 +304,11 @@ display options.

Note that git log starts with the most recent commit and backwards through the parents; however, since git history can contain multiple independent lines of development, the particular order that commits are listed in may be somewhat arbitrary.

Generating diffs

You can generate diffs between any two versions using -git-diff(1):

$Â gitÂ diffÂ master..test

Sometimes what you want instead is a set of patches:

$Â 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.

Viewing old file versions

You can always view an old version of a file by just checking out the +git-diff(1):

$Â gitÂ diffÂ master..test

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 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.

Viewing old file versions

You can always view an old version of a file by just checking out the correct revision first. But sometimes it is more convenient to be able to view an old version of a single file without checking anything out; this command does that:

$Â gitÂ showÂ v2.5:fs/locks.c

Before the colon may be anything that names a commit, and after it @@ -939,7 +940,7 @@ do
Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â ;;
Â Â Â Â Â Â Â Â esac
Â Â Â Â Â Â Â Â gitÂ logÂ origin/master..$branchÂ |Â gitÂ shortlog
-done

ChapterÂ 5.Â Rewriting history and maintaining patch series

Table of Contents

Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Modifying a single commit
Reordering or selecting from a patch series
Other tools
Problems with rewriting history
Why bisecting merge commits can be harder than bisecting linear history

Normally commits are only added to a project, never taken away or replaced. Git is designed with this assumption, and violating it will cause git's merge machinery (for example) to do the wrong thing.

However, there is a situation in which it can be useful to violate this assumption.

Creating the perfect patch series

Suppose you are a contributor to a large project, and you want to add a @@ -1035,7 +1036,41 @@ new. The results are likely to be unexpected.

You may still choose to pub and it may be useful for others to be able to fetch those branches in order to examine or test them, but they should not attempt to pull such branches into their own work.

For true distributed development that supports proper merging, -published branches should never be rewritten.

ChapterÂ 6.Â Advanced branch management

Table of Contents

Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches

Fetching individual branches

Instead of using git-remote(1), you can also choose just +published branches should never be rewritten.

Why bisecting merge commits can be harder than bisecting linear history

The 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 +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.

ChapterÂ 6.Â Advanced branch management

Table of Contents

Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches

Fetching individual branches

Instead of using git-remote(1), you can also choose just to update one branch at a time, and to store it locally under an arbitrary name:

$Â gitÂ fetchÂ originÂ todo:my-todo-work

The first argument, "origin", just tells git to fetch from the repository you originally cloned from. The second argument tells git @@ -1332,7 +1367,7 @@ column in the git-ls-files(1) outp number, and will take on values other than 0 for files with merge conflicts.

The index is thus a sort of temporary staging area, which is filled with a tree which you are in the process of working on.

If you blow the index away entirely, you generally haven't lost any -information as long as you have the name of the tree that it described.

You have to run git submodule update after git pull if you want to update -submodules, too.

Pitfalls with submodules

Always publish the submodule change before publishing the change to the +submodules, too.

Pitfalls with submodules

Always publish the submodule change before publishing the change to the superproject that references it. If you forget to publish the submodule change, others won't be able to clone the repository:

$Â cdÂ ~/git/super/a
$Â echoÂ iÂ addedÂ anotherÂ lineÂ toÂ thisÂ fileÂ >>Â a.txt
diff --git a/user-manual.txt b/user-manual.txt index 518b7b5c9..3661879f1 100644 --- a/user-manual.txt +++ b/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 ==========================

NAME

Author

Git User's Manual (for version 1.5.3 or newer)

Preface

Git User's Manual (for version 1.5.3 or newer)

Preface

Generating diffs

Viewing old file versions

Viewing old file versions

ChapterÂ 5.Â Rewriting history and maintaining patch series

ChapterÂ 5.Â Rewriting history and maintaining patch series

Creating the perfect patch series

ChapterÂ 6.Â Advanced branch management

Fetching individual branches

Why bisecting merge commits can be harder than bisecting linear history

ChapterÂ 6.Â Advanced branch management

Fetching individual branches

ChapterÂ 8.Â Submodules

ChapterÂ 8.Â Submodules

Pitfalls with submodules

Pitfalls with submodules