..
.TH "GIT-BRANCH" 1 "" "" ""
.SH NAME
-git-branch \- Create a new branch, or remove an old one
+git-branch \- List, create, or delete branches.
.SH "SYNOPSIS"
.nf
-\fIgit\-branch\fR [[\-f] <branchname> [<start\-point>]]
-\fIgit\-branch\fR (\-d | \-D) <branchname>
+\fIgit\-branch\fR [\-r]
+\fIgit\-branch\fR [\-f] <branchname> [<start\-point>]
+\fIgit\-branch\fR (\-d | \-D) <branchname>...
.fi
.SH "DESCRIPTION"
-If no argument is provided, show available branches and mark current branch with star\&. Otherwise, create a new branch of name <branchname>\&. If a starting point is also specified, that will be where the branch is created, otherwise it will be created at the current HEAD\&.
+With no arguments given (or just \-r) a list of available branches will be shown, the current branch will be highlighted with an asterisk\&.
-With a \-d or \-D option, <branchname> will be deleted\&.
+In its second form, a new branch named <branchname> will be created\&. It will start out with a head equal to the one given as <start\-point>\&. If no <start\-point> is given, the branch will be created with a head equal to that of the currently checked out branch\&.
+
+
+With a \-d or \-D option, <branchname> will be deleted\&. You may specify more than one branch for deletion\&.
.SH "OPTIONS"
.TP
\-f
-Force a reset of <branchname> to <start\-point> (or current head)\&.
+Force the creation of a new branch even if it means deleting a branch that already exists with the same name\&.
+
+.TP
+\-r
+List only the "remote" branches\&.
.TP
<branchname>
.TP
<start\-point>
-Where to create the branch; defaults to HEAD\&. This option has no meaning with \-d and \-D\&.
+The new branch will be created with a HEAD equal to this\&. It may be given as a branch name, a commit\-id, or a tag\&. If this option is omitted, the current branch is assumed\&.
-.SS "Examples"
+.SH "EXAMPLES"
.TP
Start development off of a known tag
.nf
$ git clone git://git\&.kernel\&.org/pub/scm/\&.\&.\&./linux\-2\&.6 my2\&.6
$ cd my2\&.6
-$ git branch my2\&.6\&.14 v2\&.6\&.14
+$ git branch my2\&.6\&.14 v2\&.6\&.14 \fB(1)\fR
$ git checkout my2\&.6\&.14
-
- These two steps are the same as "checkout \-b my2\&.6\&.14 v2\&.6\&.14"\&.
.fi
+.sp
+\fB1. \fRThis step and the next one could be combined into a single step with "checkout \-b my2\&.6\&.14 v2\&.6\&.14"\&.
+.br
+
.TP
Delete unneeded branch
.nf
$ git clone git://git\&.kernel\&.org/\&.\&.\&./git\&.git my\&.git
$ cd my\&.git
-$ git branch \-D todo
-
- delete todo branch even if the "master" branch does not have all
-commits from todo branch\&.
+$ git branch \-D todo \fB(1)\fR
.fi
+.sp
+\fB1. \fRdelete todo branch even if the "master" branch does not have all commits from todo branch\&.
+.br
+
+
+.SH "NOTES"
+
+
+If you are creating a branch that you want to immediately checkout, it's easier to use the git checkout command with its \-b option to create a branch and check it out with a single command\&.
.SH "AUTHOR"
1.
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\&.
-
.nf
-$ git checkout master
-$ git checkout master~2 Makefile
+$ git checkout master \fB(1)\fR
+$ git checkout master~2 Makefile \fB(2)\fR
$ rm \-f hello\&.c
-$ git checkout hello\&.c
-
- switch branch
- take out a file out of other commit
- or "git checkout \-\- hello\&.c", as in the next example\&.
+$ git checkout hello\&.c \fB(3)\fR
.fi
-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:
+.sp
+\fB1. \fRswitch branch
+.br
+\fB2. \fRtake out a file out of other commit
+.br
+\fB3. \fRrestore hello\&.c from HEAD of current branch
+
+If you have an unfortunate branch that is named hello\&.c, this step would be confused as an instruction to switch to that branch\&. You should instead write:
.nf
$ git checkout \-\- hello\&.c
.fi
+.br
+
.TP
2.
After working in a wrong branch, switching to the correct branch would be done using:
Various ways to check your working tree
.nf
-$ git diff
-$ git diff \-\-cached
-$ git diff HEAD
-
- changes in the working tree since your last git\-update\-index\&.
- changes between the index and your last commit; what you
-would be committing if you run "git commit" without "\-a" option\&.
- changes in the working tree since your last commit; what you
-would be committing if you run "git commit \-a"
+$ git diff \fB(1)\fR
+$ git diff \-\-cached \fB(2)\fR
+$ git diff HEAD \fB(3)\fR
.fi
+.sp
+\fB1. \fRchanges in the working tree since your last git\-update\-index\&.
+.br
+\fB2. \fRchanges between the index and your last commit; what you would be committing if you run "git commit" without "\-a" option\&.
+.br
+\fB3. \fRchanges in the working tree since your last commit; what you would be committing if you run "git commit \-a"
+.br
+
.TP
Comparing with arbitrary commits
.nf
-$ git diff test
-$ git diff HEAD \-\- \&./test
-$ git diff HEAD^ HEAD
-
- instead of using the tip of the current branch, compare with the
-tip of "test" branch\&.
- instead of comparing with the tip of "test" branch, compare with
-the tip of the current branch, but limit the comparison to the
-file "test"\&.
- compare the version before the last commit and the last commit\&.
+$ git diff test \fB(1)\fR
+$ git diff HEAD \-\- \&./test \fB(2)\fR
+$ git diff HEAD^ HEAD \fB(3)\fR
.fi
+.sp
+\fB1. \fRinstead of using the tip of the current branch, compare with the tip of "test" branch\&.
+.br
+\fB2. \fRinstead of comparing with the tip of "test" branch, compare with the tip of the current branch, but limit the comparison to the file "test"\&.
+.br
+\fB3. \fRcompare the version before the last commit and the last commit\&.
+.br
+
.TP
Limiting the diff output
.nf
-$ git diff \-\-diff\-filter=MRC
-$ git diff \-\-name\-status \-r
-$ git diff arch/i386 include/asm\-i386
-
- show only modification, rename and copy, but not addition
-nor deletion\&.
- show only names and the nature of change, but not actual
-diff output\&. \-\-name\-status disables usual patch generation
-which in turn also disables recursive behaviour, so without \-r
-you would only see the directory name if there is a change in a
-file in a subdirectory\&.
- limit diff output to named subtrees\&.
+$ git diff \-\-diff\-filter=MRC \fB(1)\fR
+$ git diff \-\-name\-status \-r \fB(2)\fR
+$ git diff arch/i386 include/asm\-i386 \fB(3)\fR
.fi
+.sp
+\fB1. \fRshow only modification, rename and copy, but not addition nor deletion\&.
+.br
+\fB2. \fRshow only names and the nature of change, but not actual diff output\&. \-\-name\-status disables usual patch generation which in turn also disables recursive behaviour, so without \-r you would only see the directory name if there is a change in a file in a subdirectory\&.
+.br
+\fB3. \fRlimit diff output to named subtrees\&.
+.br
+
.TP
Munging the diff output
.nf
-$ git diff \-\-find\-copies\-harder \-B \-C
-$ git diff \-R
-
- spend extra cycles to find renames, copies and complete
-rewrites (very expensive)\&.
- output diff in reverse\&.
+$ git diff \-\-find\-copies\-harder \-B \-C \fB(1)\fR
+$ git diff \-R \fB(2)\fR
.fi
+.sp
+\fB1. \fRspend extra cycles to find renames, copies and complete rewrites (very expensive)\&.
+.br
+\fB2. \fRoutput diff in reverse\&.
+.br
+
.SH "AUTHOR"
.nf
$ cd /path/to/my/codebase
-$ git\-init\-db
-$ git\-add \&.
-
- prepare /path/to/my/codebase/\&.git directory
- add all existing file to the index
+$ git\-init\-db \fB(1)\fR
+$ git\-add \&. \fB(2)\fR
.fi
+.sp
+\fB1. \fRprepare /path/to/my/codebase/\&.git directory
+.br
+\fB2. \fRadd all existing file to the index
+.br
+
.SH "AUTHOR"
Shows the commit logs\&.
-The command takes options applicable to the \fB:git\-rev\-list\fR(1) command to control what is shown and how, and options applicable to the \fB:git\-diff\-tree\fR(1) commands to control how the change each commit introduces are shown\&.
+The command takes options applicable to the \fBgit\-rev\-list\fR(1) command to control what is shown and how, and options applicable to the \fBgit\-diff\-tree\fR(1) commands to control how the change each commit introduces are shown\&.
This manual page describes only the most frequently used options\&.
.nf
$ git commit \&.\&.\&.
-$ git reset \-\-soft HEAD^
-$ edit
-$ git commit \-a \-c ORIG_HEAD
-
- This is most often done when you remembered what you
-just committed is incomplete, or you misspelled your commit
-message, or both\&. Leaves working tree as it was before "reset"\&.
- make corrections to working tree files\&.
- "reset" copies the old head to \&.git/ORIG_HEAD; redo the
-commit by starting with its log message\&. If you do not need to
-edit the message further, you can give \-C option instead\&.
+$ git reset \-\-soft HEAD^ \fB(1)\fR
+$ edit \fB(2)\fR
+$ git commit \-a \-c ORIG_HEAD \fB(3)\fR
.fi
+.sp
+\fB1. \fRThis is most often done when you remembered what you just committed is incomplete, or you misspelled your commit message, or both\&. Leaves working tree as it was before "reset"\&.
+.br
+\fB2. \fRmake corrections to working tree files\&.
+.br
+\fB3. \fR"reset" copies the old head to \&.git/ORIG_HEAD; redo the commit by starting with its log message\&. If you do not need to edit the message further, you can give \-C option instead\&.
+.br
+
.TP
Undo commits permanently
.nf
$ git commit \&.\&.\&.
-$ git reset \-\-hard HEAD~3
-
- The last three commits (HEAD, HEAD^, and HEAD~2) were bad
-and you do not want to ever see them again\&. Do *not* do this if
-you have already given these commits to somebody else\&.
+$ git reset \-\-hard HEAD~3 \fB(1)\fR
.fi
+.sp
+\fB1. \fRThe last three commits (HEAD, HEAD^, and HEAD~2) were bad and you do not want to ever see them again\&. Do \fInot\fR do this if you have already given these commits to somebody else\&.
+.br
+
.TP
Undo a commit, making it a topic branch
.nf
-$ git branch topic/wip
-$ git reset \-\-hard HEAD~3
-$ git checkout topic/wip
-
- You have made some commits, but realize they were premature
-to be in the "master" branch\&. You want to continue polishing
-them in a topic branch, so create "topic/wip" branch off of the
-current HEAD\&.
- Rewind the master branch to get rid of those three commits\&.
- Switch to "topic/wip" branch and keep working\&.
+$ git branch topic/wip \fB(1)\fR
+$ git reset \-\-hard HEAD~3 \fB(2)\fR
+$ git checkout topic/wip \fB(3)\fR
.fi
+.sp
+\fB1. \fRYou have made some commits, but realize they were premature to be in the "master" branch\&. You want to continue polishing them in a topic branch, so create "topic/wip" branch off of the current HEAD\&.
+.br
+\fB2. \fRRewind the master branch to get rid of those three commits\&.
+.br
+\fB3. \fRSwitch to "topic/wip" branch and keep working\&.
+.br
+
.TP
Undo update\-index
.nf
-$ edit
+$ edit \fB(1)\fR
$ git\-update\-index frotz\&.c filfre\&.c
-$ mailx
-$ git reset
-$ git pull git://info\&.example\&.com/ nitfol
-
- you are happily working on something, and find the changes
-in these files are in good order\&. You do not want to see them
-when you run "git diff", because you plan to work on other files
-and changes with these files are distracting\&.
- somebody asks you to pull, and the changes sounds worthy of merging\&.
- however, you already dirtied the index (i\&.e\&. your index does
-not match the HEAD commit)\&. But you know the pull you are going
-to make does not affect frotz\&.c nor filfre\&.c, so you revert the
-index changes for these two files\&. Your changes in working tree
-remain there\&.
- then you can pull and merge, leaving frotz\&.c and filfre\&.c
-changes still in the working tree\&.
+$ mailx \fB(2)\fR
+$ git reset \fB(3)\fR
+$ git pull git://info\&.example\&.com/ nitfol \fB(4)\fR
.fi
+.sp
+\fB1. \fRyou are happily working on something, and find the changes in these files are in good order\&. You do not want to see them when you run "git diff", because you plan to work on other files and changes with these files are distracting\&.
+.br
+\fB2. \fRsomebody asks you to pull, and the changes sounds worthy of merging\&.
+.br
+\fB3. \fRhowever, you already dirtied the index (i\&.e\&. your index does not match the HEAD commit)\&. But you know the pull you are going to make does not affect frotz\&.c nor filfre\&.c, so you revert the index changes for these two files\&. Your changes in working tree remain there\&.
+.br
+\fB4. \fRthen you can pull and merge, leaving frotz\&.c and filfre\&.c changes still in the working tree\&.
+.br
+
.TP
Undo a merge or pull
.nf
-$ git pull
+$ git pull \fB(1)\fR
Trying really trivial in\-index merge\&.\&.\&.
fatal: Merge requires file\-level merging
Nope\&.
Auto\-merging nitfol
CONFLICT (content): Merge conflict in nitfol
Automatic merge failed/prevented; fix up by hand
-$ git reset \-\-hard
-
- try to update from the upstream resulted in a lot of
-conflicts; you were not ready to spend a lot of time merging
-right now, so you decide to do that later\&.
- "pull" has not made merge commit, so "git reset \-\-hard"
-which is a synonym for "git reset \-\-hard HEAD" clears the mess
-from the index file and the working tree\&.
-
-$ git pull \&. topic/branch
+$ git reset \-\-hard \fB(2)\fR
+$ git pull \&. topic/branch \fB(3)\fR
Updating from 41223\&.\&.\&. to 13134\&.\&.\&.
Fast forward
-$ git reset \-\-hard ORIG_HEAD
-
- merge a topic branch into the current branch, which resulted
-in a fast forward\&.
- but you decided that the topic branch is not ready for public
-consumption yet\&. "pull" or "merge" always leaves the original
-tip of the current branch in ORIG_HEAD, so resetting hard to it
-brings your index file and the working tree back to that state,
-and resets the tip of the branch to that commit\&.
+$ git reset \-\-hard ORIG_HEAD \fB(4)\fR
.fi
+.sp
+\fB1. \fRtry to update from the upstream resulted in a lot of conflicts; you were not ready to spend a lot of time merging right now, so you decide to do that later\&.
+.br
+\fB2. \fR"pull" has not made merge commit, so "git reset \-\-hard" which is a synonym for "git reset \-\-hard HEAD" clears the mess from the index file and the working tree\&.
+.br
+\fB3. \fRmerge a topic branch into the current branch, which resulted in a fast forward\&.
+.br
+\fB4. \fRbut you decided that the topic branch is not ready for public consumption yet\&. "pull" or "merge" always leaves the original tip of the current branch in ORIG_HEAD, so resetting hard to it brings your index file and the working tree back to that state, and resets the tip of the branch to that commit\&.
+.br
+
.TP
Interrupted workflow
.nf
$ git checkout feature ;# you were working in "feature" branch and
$ work work work ;# got interrupted
-$ git commit \-a \-m 'snapshot WIP'
+$ git commit \-a \-m 'snapshot WIP' \fB(1)\fR
$ git checkout master
$ fix fix fix
$ git commit ;# commit with real log
$ git checkout feature
-$ git reset \-\-soft HEAD^ ;# go back to WIP state
-$ git reset
-
- This commit will get blown away so a throw\-away log message is OK\&.
- This removes the 'WIP' commit from the commit history, and sets
- your working tree to the state just before you made that snapshot\&.
- After , the index file still has all the WIP changes you
- committed in \&. This sets it to the last commit you were
- basing the WIP changes on\&.
+$ git reset \-\-soft HEAD^ ;# go back to WIP state \fB(2)\fR
+$ git reset \fB(3)\fR
.fi
+.sp
+\fB1. \fRThis commit will get blown away so a throw\-away log message is OK\&.
+.br
+\fB2. \fRThis removes the \fIWIP\fR commit from the commit history, and sets your working tree to the state just before you made that snapshot\&.
+.br
+\fB3. \fRAt this point the index file still has all the WIP changes you committed as \fIsnapshot WIP\fR\&. This updates the index to show your WIP files as uncommitted\&.
+.br
+
.SH "AUTHOR"
To pretend you have a file with mode and sha1 at path, say:
-.IP
+.nf
$ git\-update\-index \-\-cacheinfo mode sha1 path
+.fi
+
\fI\-\-info\-only\fR is used to register files without placing them in the object database\&. This is useful for status\-only repositories\&.
For example, starting with this index:
-.IP
+.nf
$ git ls\-files \-s
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0 frotz
+.fi
+
you can feed the following input to \-\-index\-info:
-.IP
+.nf
$ git update\-index \-\-index\-info
0 0000000000000000000000000000000000000000 frotz
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz
100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz
+.fi
+
The first line of the input feeds 0 as the mode to remove the path; the SHA1 does not matter as long as it is well formatted\&. Then the second and third line feeds stage 1 and stage 2 entries for that path\&. After the above, we would end up with this:
-.IP
+.nf
$ git ls\-files \-s
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz
100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz
+.fi
+
.SH "USING "ASSUME UNCHANGED" BIT"
To update and refresh only the files already checked out:
-.IP
+.nf
$ git\-checkout\-index \-n \-f \-a && git\-update\-index \-\-ignore\-missing \-\-refresh
+.fi
-On an inefficient filesystem with core\&.ignorestat set:
+.TP
+On an inefficient filesystem with core\&.ignorestat set
-.IP
-$ git update\-index \-\-really\-refresh
-$ git update\-index \-\-no\-assume\-unchanged foo\&.c
-$ git diff \-\-name\-only
+.nf
+$ git update\-index \-\-really\-refresh \fB(1)\fR
+$ git update\-index \-\-no\-assume\-unchanged foo\&.c \fB(2)\fR
+$ git diff \-\-name\-only \fB(3)\fR
$ edit foo\&.c
-$ git diff \-\-name\-only
+$ git diff \-\-name\-only \fB(4)\fR
M foo\&.c
-$ git update\-index foo\&.c
-$ git diff \-\-name\-only
+$ git update\-index foo\&.c \fB(5)\fR
+$ git diff \-\-name\-only \fB(6)\fR
$ edit foo\&.c
-$ git diff \-\-name\-only
-$ git update\-index \-\-no\-assume\-unchanged foo\&.c
-$ git diff \-\-name\-only
+$ git diff \-\-name\-only \fB(7)\fR
+$ git update\-index \-\-no\-assume\-unchanged foo\&.c \fB(8)\fR
+$ git diff \-\-name\-only \fB(9)\fR
M foo\&.c
+.fi
+.sp
+\fB1. \fRforces lstat(2) to set "assume unchanged" bits for paths that match index\&.
+.br
+\fB2. \fRmark the path to be edited\&.
+.br
+\fB3. \fRthis does lstat(2) and finds index matches the path\&.
+.br
+\fB4. \fRthis does lstat(2) and finds index does \fInot\fR match the path\&.
+.br
+\fB5. \fRregistering the new version to index sets "assume unchanged" bit\&.
+.br
+\fB6. \fRand it is assumed unchanged\&.
+.br
+\fB7. \fReven after you edit it\&.
+.br
+\fB8. \fRyou can tell about the change after the fact\&.
+.br
+\fB9. \fRnow it checks with lstat(2) and finds it has been changed\&.
+.br
+
- forces lstat(2) to set "assume unchanged" bits for paths
- that match index\&.
- mark the path to be edited\&.
- this does lstat(2) and finds index matches the path\&.
- this does lstat(2) and finds index does not match the path\&.
- registering the new version to index sets "assume unchanged" bit\&.
- and it is assumed unchanged\&.
-(16) even after you edit it\&.
-(17) you can tell about the change after the fact\&.
-(18) now it checks with lstat(2) and finds it has been changed\&.
.SH "CONFIGURATION"
projects / git.git / commitdiff