aboutsummaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJunio C Hamano <junkio@cox.net>2006-01-12 14:04:36 -0800
committerJunio C Hamano <junkio@cox.net>2006-01-13 16:52:37 -0800
commit1be0659efca4a1f69c851f95563e930d70d8baf2 (patch)
tree2141250aceef41362c4bc636c4642690e4afb6fe /Documentation
parent19205acfc29b6d39b5643a7f9a2448f89df14355 (diff)
downloadgit-1be0659efca4a1f69c851f95563e930d70d8baf2.tar.gz
git-1be0659efca4a1f69c851f95563e930d70d8baf2.tar.xz
checkout: merge local modifications while switching branches.
* Instead of going interactive, introduce a command line switch '-m' to allow merging changes when normal two-way merge by read-tree prevents branch switching. * Leave the unmerged stages intact if automerge fails, but reset index entries of cleanly merged paths to that of the new branch, so that "git diff" (not "git diff HEAD") would show the local modifications. * Swap the order of trees in read-tree three-way merge used in the fallback, so that `git diff` to show the conflicts become more natural. * Describe the new option and give more examples in the documentation. Signed-off-by: Junio C Hamano <junkio@cox.net>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/git-checkout.txt76
1 files changed, 69 insertions, 7 deletions
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9442c66b1..df9a61867 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -7,7 +7,7 @@ git-checkout - Checkout and switch to a branch.
SYNOPSIS
--------
-'git-checkout' [-f] [-b <new_branch>] [<branch>] [<paths>...]
+'git-checkout' [-f] [-b <new_branch>] [-m] [<branch>] [<paths>...]
DESCRIPTION
-----------
@@ -34,6 +34,19 @@ OPTIONS
-b::
Create a new branch and start it at <branch>.
+-m::
+ If you have local modifications to a file that is
+ different between the current branch and the branch you
+ are switching to, the command refuses to switch
+ branches, to preserve your modifications in context.
+ With this option, a three-way merge between the current
+ branch, your working tree contents, and the new branch
+ is done, and you will be on the new branch.
++
+When a merge conflict happens, the index entries for conflicting
+paths are left unmerged, and you need to resolve the conflicts
+and mark the resolved paths with `git update-index`.
+
<new_branch>::
Name for the new branch.
@@ -42,13 +55,13 @@ OPTIONS
commit. Defaults to HEAD.
-EXAMPLE
--------
+EXAMPLES
+--------
-The following sequence checks out the `master` branch, reverts
+. The following sequence checks out the `master` branch, reverts
the `Makefile` to two revisions back, deletes hello.c by
mistake, and gets it back from the index.
-
++
------------
$ git checkout master <1>
$ git checkout master~2 Makefile <2>
@@ -59,15 +72,64 @@ $ git checkout hello.c <3>
<2> take out a file out of other commit
<3> or "git checkout -- hello.c", as in the next example.
------------
-
++
If you have an unfortunate branch that is named `hello.c`, the
last step above would be confused as an instruction to switch to
that branch. You should instead write:
-
++
------------
$ git checkout -- hello.c
------------
+. After working in a wrong branch, switching to the correct
+branch you would want to is done with:
++
+------------
+$ git checkout mytopic
+------------
++
+However, your "wrong" branch and correct "mytopic" branch may
+differ in files that you have locally modified, in which case,
+the above checkout would fail like this:
++
+------------
+$ git checkout mytopic
+fatal: Entry 'frotz' not uptodate. Cannot merge.
+------------
++
+You can give the `-m` flag to the command, which would try a
+three-way merge:
++
+------------
+$ git checkout -m mytopic
+Auto-merging frotz
+------------
++
+After this three-way merge, the local modifications are _not_
+registered in your index file, so `git diff` would show you what
+changes you made since the tip of the new branch.
+
+. When a merge conflict happens during switching branches with
+the `-m` option, you would see something like this:
++
+------------
+$ git checkout -m mytopic
+Auto-merging frotz
+merge: warning: conflicts during merge
+ERROR: Merge conflict in frotz
+fatal: merge program failed
+------------
++
+At this point, `git diff` shows the changes cleanly merged as in
+the previous example, as well as the changes in the conflicted
+files. Edit and resolve the conflict and mark it resolved with
+`git update-index` as usual:
++
+------------
+$ edit frotz
+$ git update-index frotz
+------------
+
Author
------