From 1e2ccd3abc8f5d96244806f753568493c3e77d4c Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 12 Dec 2005 23:24:06 -0800 Subject: [PATCH] Documentation: more examples. Signed-off-by: Junio C Hamano --- Documentation/everyday.txt | 99 +++++++++++++++++++++++++++------- Documentation/git-am.txt | 2 +- Documentation/git-branch.txt | 26 +++++++++ Documentation/git-checkout.txt | 10 ++-- Documentation/git-clone.txt | 21 ++++++++ Documentation/git-init-db.txt | 7 ++- Documentation/git-reset.txt | 70 ++++++++++++++++++++++++ 7 files changed, 209 insertions(+), 26 deletions(-) diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index 88df3ffc28..88bd88963a 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -50,6 +50,35 @@ Everybody uses these commands to feed and care git repositories. * gitlink:git-repack[1] to pack loose objects for efficiency. +Examples +~~~~~~~~ + +Check health and remove cruft:: ++ +------------ +$ git fsck-objects <1> +$ git prune +$ git count-objects <2> +$ git repack <3> +$ git prune <4> + +<1> running without "--full" is usually cheap and assures the +repository health reasonably well. +<2> check how many loose objects there are and how much +diskspace is wasted by not repacking. +<3> without "-a" repacks incrementally. repacking every 4-5MB +of loose objects accumulation may be a good rule of thumb. +<4> after repack, prune removes the duplicate loose objects. +------------ + +Repack a small project into single pack:: ++ +------------ +$ git repack -a -d <1> +$ git prune +------------ + + Individual Developer (Standalone)[[Individual Developer (Standalone)]] ---------------------------------------------------------------------- @@ -88,7 +117,8 @@ following commands. Examples ~~~~~~~~ -* Extract a tarball and create a working tree and a new repository to keep track of it. +Extract a tarball and create a working tree and a new repository to keep track of it:: ++ ------------ $ tar zxf frotz.tar.gz $ cd frotz @@ -101,7 +131,8 @@ $ git tag v2.43 <2> <2> make a lightweight, unannotated tag. ------------ -* Create a topic branch and develop +Create a topic branch and develop:: ++ ------------ $ git checkout -b alsa-audio <1> $ edit/compile/test @@ -158,12 +189,13 @@ addition to the ones needed by a standalone developer. Examples ~~~~~~~~ -* Clone the upstream and work on it. Feed changes to upstream. +Clone the upstream and work on it. Feed changes to upstream:: ++ ------------ $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6 $ cd my2.6 $ edit/compile/test; git commit -a -s <1> -$ git format-patch master <2> +$ git format-patch origin <2> $ git pull <3> $ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> @@ -180,7 +212,8 @@ area we are interested in. <7> garbage collect leftover objects from reverted pull. ------------ -* Branch off of a specific tag. +Branch off of a specific tag:: ++ ------------ $ git checkout -b private2.6.14 v2.6.14 <1> $ edit/compile/test; git commit -a @@ -219,7 +252,8 @@ commands in addition to the ones needed by participants. Examples ~~~~~~~~ -* My typical GIT day. +My typical GIT day:: ++ ------------ $ git status <1> $ git show-branch <2> @@ -231,16 +265,17 @@ $ git checkout master $ git am -3 -i -s -u ./+to-apply <4> $ compile/test $ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5> -$ git checkout pu && git reset --hard master <6> -$ git pull . topic/one topic/two && git pull . hold/linus <7> +$ git checkout topic/one && git rebase master <6> +$ git checkout pu && git reset --hard master <7> +$ git pull . topic/one topic/two && git pull . hold/linus <8> $ git fetch ko master:refs/tags/ko-master && - git show-branch master ko-master <8> -$ git push ko <9> + git show-branch master ko-master <9> +$ git push ko <10> $ git checkout maint -$ git cherry-pick master~4 <10> +$ git cherry-pick master~4 <11> $ compile/test -$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <11> -$ git push ko v0.99.9x <12> +$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <12> +$ git push ko v0.99.9x <13> <1> see what I was in the middle of doing, if any. <2> see what topic branches I have and think about how ready @@ -250,14 +285,16 @@ that are not quite ready. <4> apply them, interactively, with my sign-offs. <5> create topic branch as needed and apply, again with my sign-offs. -<6> restart "pu" every time from the master. -<7> and bundle topic branches still cooking. -<8> make sure I did not accidentally rewound master beyond what I +<6> rebase internal topic branch that has not been merged to the +master, nor exposed as a part of a stable branch. +<7> restart "pu" every time from the master. +<8> and bundle topic branches still cooking. +<9> make sure I did not accidentally rewound master beyond what I already pushed out. -<9> push out the bleeding edge. -<10> backport a critical fix. -<11> create a signed tag. -<12> push the tag out. +<10> push out the bleeding edge. +<11> backport a critical fix. +<12> create a signed tag. +<13> push the tag out. ------------ @@ -276,3 +313,25 @@ and maintain access to the repository by developers. * link:howto/update-hook-example.txt[update hook howto] has a good example of managing a shared central repository. + +Examples +~~~~~~~~ + +Run git-daemon to serve /pub/scm from inetd:: ++ +------------ +$ grep git /etc/inet.conf +git stream tcp nowait nobody /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm +------------ + +Give push/pull only access to developers:: ++ +------------ +$ grep git /etc/shells +/usr/bin/git-shell +$ grep git /etc/passwd +alice:x:1000:1000::/home/alice:/usr/bin/git-shell +bob:x:1001:1001::/home/bob:/usr/bin/git-shell +cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell +david:x:1003:1003::/home/david:/usr/bin/git-shell +------------ diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 6645e82b84..a415fe24c3 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -69,7 +69,7 @@ recover from this in one of two ways: . hand resolve the conflict in the working directory, and update the index file to bring it in a state that the patch should - have produced. Then run the command with '--resume' option. + have produced. Then run the command with '--resolved' option. The command refuses to process new mailboxes while `.dotest` directory exists, so if you decide to start over from scratch, diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 98014f6d9b..d20b475735 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -32,6 +32,32 @@ start-point:: Where to create the branch; defaults to HEAD. This option has no meaning with -d and -D. + +Examples +~~~~~~~~ + +Start development off of a know tag:: ++ +------------ +$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 +$ cd my2.6 +$ git branch my2.6.14 v2.6.14 <1> +$ git checkout my2.6.14 + +<1> These two steps are the same as "checkout -b my2.6.14 v2.6.14". +------------ + +Delete unneeded branch:: ++ +------------ +$ git clone git://git.kernel.org/.../git.git my.git +$ cd my.git +$ git branch -D todo <1> + +<1> delete todo branch even if the "master" branch does not have all +commits from todo branch. +------------ + Author ------ Written by Linus Torvalds and Junio C Hamano diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index b7bb1b4c74..9442c66b18 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -50,10 +50,14 @@ the `Makefile` to two revisions back, deletes hello.c by mistake, and gets it back from the index. ------------ -$ git checkout master -$ git checkout master~2 Makefile +$ git checkout master <1> +$ git checkout master~2 Makefile <2> $ rm -f hello.c -$ git checkout hello.c +$ git checkout hello.c <3> + +<1> switch branch +<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 diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 83f58ae536..8410a6d381 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -74,10 +74,31 @@ OPTIONS for "host.xz:foo/.git"). Cloning into an existing directory is not allowed. +Examples +~~~~~~~~ + +Clone from upstream:: ++ +------------ +$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 +$ cd my2.6 +$ make +------------ + + +Make a local clone that borrows from the current directory, without checking things out:: ++ +------------ +$ git clone -l -s -n . ../copy +$ cd copy +$ git show-branch +------------ + Author ------ Written by Linus Torvalds + Documentation -------------- Documentation by Junio C Hamano and the git-list . diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 4486f0c1cf..6deef92508 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -40,9 +40,12 @@ Start a new git repository for an existing code base:: + ---------------- $ cd /path/to/my/codebase -$ git-init-db ----------------- +$ git-init-db <1> +$ git-add . <2> +<1> prepare /path/to/my/codebase/.git directory +<2> add all existing file to the index +---------------- Author diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 6af3a4fdb9..02048918bf 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -42,6 +42,76 @@ OPTIONS :: Commit to make the current HEAD. +Examples +~~~~~~~~ + +Undo a commit and redo:: ++ +------------ +$ git commit ... +$ git reset --soft HEAD^ <1> +$ edit <2> +$ git commit -a -c ORIG_HEAD <3> + +<1> 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". +<2> make corrections to working tree files. +<3> "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. +------------ + +Undo commits permanently:: ++ +------------ +$ git commit ... +$ git reset --hard HEAD~3 <1> + +<1> 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. +------------ + +Undo a commit, making it a topic branch:: ++ +------------ +$ git branch topic/wip <1> +$ git reset --hard HEAD~3 <2> +$ git checkout topic/wip <3> + +<1> 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. +<2> Rewind the master branch to get rid of those three commits. +<3> Switch to "topic/wip" branch and keep working. +------------ + +Undo update-index:: ++ +------------ +$ edit <1> +$ git-update-index frotz.c filfre.c +$ mailx <2> +$ git reset <3> +$ git pull git://info.example.com/ nitfol <4> + +<1> 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. +<2> somebody asks you to pull, and the changes sounds worthy of merging. +<3> 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. +<4> then you can pull and merge, leaving frotz.c and filfre.c +changes still in the working tree. +------------ + + Author ------ Written by Junio C Hamano and Linus Torvalds