1Everyday GIT With 20 Commands Or So 2=================================== 3 4GIT suite has over 100 commands, and the manual page for each of 5them discusses what the command does and how it is used in 6detail, but until you know what command should be used in order 7to achieve what you want to do, you cannot tell which manual 8page to look at, and if you know that already you do not need 9the manual. 10 11Does that mean you need to know all of them before you can use 12git? Not at all. Depending on the role you play, the set of 13commands you need to know is slightly different, but in any case 14what you need to learn is far smaller than the full set of 15commands to carry out your day-to-day work. This document is to 16serve as a cheat-sheet and a set of pointers for people playing 17various roles. 18 19<<Basic Repository>> commands are needed by people who has a 20repository --- that is everybody, because every working tree of 21git is a repository. 22 23In addition, <<Individual Developer (Standalone)>> commands are 24essential for anybody who makes a commit, even for somebody who 25works alone. 26 27If you work with other people, you will need commands listed in 28<<Individual Developer (Participant)>> section as well. 29 30People who play <<Integrator>> role need to learn some more 31commands in addition to the above. 32 33<<Repository Administration>> commands are for system 34administrators who are responsible to care and feed git 35repositories to support developers. 36 37 38Basic Repository[[Basic Repository]] 39------------------------------------ 40 41Everybody uses these commands to feed and care git repositories. 42 43 * gitlink:git-init-db[1] or gitlink:git-clone[1] to create a 44 new repository. 45 46 * gitlink:git-fsck-objects[1] to validate the repository. 47 48 * gitlink:git-prune[1] to garbage collect crufts in the 49 repository. 50 51 * gitlink:git-repack[1] to pack loose objects for efficiency. 52 53Individual Developer (Standalone)[[Individual Developer (Standalone)]] 54---------------------------------------------------------------------- 55 56A standalone individual developer does not exchange patches with 57other poeple, and works alone in a single repository, using the 58following commands. 59 60 * gitlink:git-show-branch[1] to see where you are. 61 62 * gitlink:git-log[1] to see what happened. 63 64 * gitlink:git-whatchanged[1] to find out where things have 65 come from. 66 67 * gitlink:git-checkout[1] and gitlink:git-branch[1] to switch 68 branches. 69 70 * gitlink:git-add[1] and gitlink:git-update-index[1] to manage 71 the index file. 72 73 * gitlink:git-diff[1] and gitlink:git-status[1] to see what 74 you are in the middle of doing. 75 76 * gitlink:git-commit[1] to advance the current branch. 77 78 * gitlink:git-reset[1] and gitlink:git-checkout[1] (with 79 pathname parameters) to undo changes. 80 81 * gitlink:git-pull[1] with "." as the remote to merge between 82 local branches. 83 84 * gitlink:git-rebase[1] to maintain topic branches. 85 86 * gitlink:git-tag[1] to mark known point. 87 88Examples 89~~~~~~~~ 90 91* Extract a tarball and create a working tree and a new repository to keep track of it. 92------------ 93$ tar zxf frotz.tar.gz 94$ cd frotz 95$ git-init-db 96$ git add . <1> 97$ git commit -m 'import of frotz source tree.' 98$ git tag v2.43 <2> 99 100<1> add everything under the current directory. 101<2> make a lightweight, unannotated tag. 102------------ 103 104* Create a topic branch and develop 105------------ 106$ git checkout -b alsa-audio <1> 107$ edit/compile/test 108$ git checkout -- curses/ux_audio_oss.c <2> 109$ git add curses/ux_audio_alsa.c <3> 110$ edit/compile/test 111$ git diff <4> 112$ git commit -a -s <5> 113$ edit/compile/test 114$ git reset --soft HEAD^ <6> 115$ edit/compile/test 116$ git diff ORIG_HEAD <7> 117$ git commit -a -c ORIG_HEAD <8> 118$ git checkout master <9> 119$ git pull . alsa-audio <10> 120$ git log --since='3 days ago' <11> 121$ git log v2.43.. curses/ <12> 122 123<1> create a new topic branch. 124<2> revert your botched changes in "curses/ux_audio_oss.c". 125<3> you need to tell git if you added a new file; removal and 126modification will be caught if you do "commit -a" later. 127<4> to see what changes you are committing. 128<5> commit everything as you have tested, with your sign-off. 129<6> take the last commit back, keeping what is in the working tree. 130<7> look at the changes since the premature commit we took back. 131<8> redo the commit undone in the previous step, using the message 132you originally wrote. 133<9> switch to the master branch. 134<10> merge a topic branch into your master branch 135<11> or --since='aug 1', --max-count=10 136<12> view only the changes that touch what's in curses/ 137directory, since v2.43 tag. 138------------ 139 140 141Individual Developer (Participant)[[Individual Developer (Participant)]] 142------------------------------------------------------------------------ 143 144A developer working as a participant in a group project needs to 145learn how to communicate with others, and uses these commands in 146addition to the ones needed by a standalone developer. 147 148 * gitlink:git-pull[1] from "origin" to keep up-to-date with 149 the upstream. 150 151 * gitlink:git-push[1] to shared repository if you adopt CVS 152 style shared repository workflow. 153 154 * gitlink:git-format-patch[1] to prepare e-mail submission, if 155 you adopt Linux kernel-style public forum workflow. 156 157 158Examples 159~~~~~~~~ 160 161* Clone the upstream and work on it. Feed changes to upstream. 162------------ 163$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6 164$ cd my2.6 165$ edit/compile/test; git commit -a -s <1> 166$ git format-patch master <2> 167$ git pull <3> 168$ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> 169$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> 170$ git reset --hard ORIG_HEAD <6> 171$ git prune <7> 172 173<1> repeat as needed. 174<2> extract patches from your branch for e-mail submission. 175<3> "pull" fetches from "origin" by default and merges. 176<4> look at the changes since last time we checked, only in the 177area we are interested in. 178<5> fetch from a specific branch from a specific repository and and merge. 179<6> revert the pull. 180<7> garbage collect leftover objects from reverted pull. 181------------ 182 183* Branch off of a specific tag. 184------------ 185$ git checkout -b private2.6.14 v2.6.14 <1> 186$ edit/compile/test; git commit -a 187$ git checkout master 188$ git format-patch -k -m --stdout v2.6.14..private2.6.14 | 189 git am -3 -k <2> 190 191<1> create a private branch based on a well known (but somewhat behind) 192tag. 193<2> forward port all changes in private2.6.14 branch to master branch 194without a formal "merging". 195------------ 196 197 198Integrator[[Integrator]] 199------------------------ 200 201A fairly central person acting as the integrator in a group 202project receives changes made by others, reviews and integrates 203them and publishes the result for others to use, using these 204commands in addition to the ones needed by participants. 205 206 * gitlink:git-am[1] to apply patches e-mailed in from your 207 contributors. 208 209 * gitlink:git-pull[1] to merge from your trusted lieutenants. 210 211 * gitlink:git-format-patch[1] to prepare and send suggested 212 alternative to contributors. 213 214 * gitlink:git-revert[1] to undo botched commits. 215 216 * gitlink:git-push[1] to publish the bleeding edge. 217 218 219Examples 220~~~~~~~~ 221 222* My typical GIT day. 223------------ 224$ git status <1> 225$ git show-branch <2> 226$ mailx <3> 227& s 2 3 4 5 ./+to-apply 228& s 7 8 ./+hold-linus 229& q 230$ git checkout master 231$ git am -3 -i -s -u ./+to-apply <4> 232$ compile/test 233$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5> 234$ git checkout pu && git reset --hard master <6> 235$ git pull . topic/one topic/two && git pull . hold/linus <7> 236$ git fetch ko master:refs/tags/ko-master && 237 git show-branch master ko-master <8> 238$ git push ko <9> 239$ git checkout maint 240$ git cherry-pick master~4 <10> 241$ compile/test 242$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <11> 243$ git push ko v0.99.9x <12> 244 245<1> see what I was in the middle of doing, if any. 246<2> see what topic branches I have and think about how ready 247they are. 248<3> read mails, save ones that are applicable, and save others 249that are not quite ready. 250<4> apply them, interactively, with my sign-offs. 251<5> create topic branch as needed and apply, again with my 252sign-offs. 253<6> restart "pu" every time from the master. 254<7> and bundle topic branches still cooking. 255<8> make sure I did not accidentally rewound master beyond what I 256already pushed out. 257<9> push out the bleeding edge. 258<10> backport a critical fix. 259<11> create a signed tag. 260<12> push the tag out. 261------------ 262 263 264Repository Administration[[Repository Administration]] 265------------------------------------------------------ 266 267A repository administrator uses the following tools to set up 268and maintain access to the repository by developers. 269 270 * gitlink:git-daemon[1] to allow anonymous download from 271 repository. 272 273 * gitlink:git-shell[1] can be used as a 'restricted login shell' 274 for shared central repository users. 275 276 * link:howto/update-hook-example.txt[update hook howto] has a 277 good example of managing a shared central repository. 278