From ff65000a1149a1bad6d7d9f6bf6ec5194f5c850d Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sat, 29 Apr 2006 07:02:25 +0000 Subject: [PATCH] Autogenerated man pages for v1.3.1-g8971 --- man1/git-branch.1 | 46 ++++++++----- man1/git-checkout.1 | 22 ++++--- man1/git-diff.1 | 78 +++++++++++----------- man1/git-init-db.1 | 13 ++-- man1/git-log.1 | 2 +- man1/git-reset.1 | 139 +++++++++++++++++++--------------------- man1/git-update-index.1 | 73 +++++++++++++-------- 7 files changed, 207 insertions(+), 166 deletions(-) diff --git a/man1/git-branch.1 b/man1/git-branch.1 index 6d363bc2c..33a9ae23d 100755 --- a/man1/git-branch.1 +++ b/man1/git-branch.1 @@ -19,21 +19,25 @@ .. .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] []] -\fIgit\-branch\fR (\-d | \-D) +\fIgit\-branch\fR [\-r] +\fIgit\-branch\fR [\-f] [] +\fIgit\-branch\fR (\-d | \-D) ... .fi .SH "DESCRIPTION" -If no argument is provided, show available branches and mark current branch with star\&. Otherwise, create a new branch of name \&. 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, will be deleted\&. +In its second form, a new branch named will be created\&. It will start out with a head equal to the one given as \&. If no 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, will be deleted\&. You may specify more than one branch for deletion\&. .SH "OPTIONS" @@ -47,7 +51,11 @@ Delete a branch irrespective of its index status\&. .TP \-f -Force a reset of to (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 @@ -55,9 +63,9 @@ The name of the branch to create or delete\&. .TP -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 @@ -65,11 +73,13 @@ 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 @@ -77,11 +87,17 @@ 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" diff --git a/man1/git-checkout.1 b/man1/git-checkout.1 index 7e3735671..90274b81a 100755 --- a/man1/git-checkout.1 +++ b/man1/git-checkout.1 @@ -65,22 +65,26 @@ Branch to checkout; may be any object ID that resolves to a commit\&. Defaults t 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: diff --git a/man1/git-diff.1 b/man1/git-diff.1 index 063e11472..86567ac31 100755 --- a/man1/git-diff.1 +++ b/man1/git-diff.1 @@ -57,62 +57,66 @@ The arguments are also passed to git\-diff\-* commands\&. 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" diff --git a/man1/git-init-db.1 b/man1/git-init-db.1 index a0babda96..626d9924f 100755 --- a/man1/git-init-db.1 +++ b/man1/git-init-db.1 @@ -62,12 +62,15 @@ Start a new git repository for an existing code base .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" diff --git a/man1/git-log.1 b/man1/git-log.1 index 7cc88c355..530c27220 100755 --- a/man1/git-log.1 +++ b/man1/git-log.1 @@ -31,7 +31,7 @@ git-log \- Show commit logs 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\&. diff --git a/man1/git-reset.1 b/man1/git-reset.1 index d6860d43d..bfa0082fd 100755 --- a/man1/git-reset.1 +++ b/man1/git-reset.1 @@ -61,76 +61,74 @@ Undo a commit and redo .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\&. @@ -138,28 +136,22 @@ 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 @@ -168,21 +160,22 @@ Suppose you are interrupted by an urgent fix request while you are in the middle .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" diff --git a/man1/git-update-index.1 b/man1/git-update-index.1 index e61a10606..df57aceb3 100755 --- a/man1/git-update-index.1 +++ b/man1/git-update-index.1 @@ -134,8 +134,10 @@ For example, you'd want to do this after doing a "git\-read\-tree", to link up t 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\&. @@ -170,24 +172,30 @@ To place a higher stage entry to the index, the path should first be removed by 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" @@ -204,36 +212,49 @@ The command looks at core\&.ignorestat configuration variable\&. When this is tr 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" -- 2.26.2