1Everyday GIT With 20 Commands Or So 2=================================== 3 4<<Basic Repository>> commands are needed by people who have a 5repository --- that is everybody, because every working tree of 6git is a repository. 7 8In addition, <<Individual Developer (Standalone)>> commands are 9essential for anybody who makes a commit, even for somebody who 10works alone. 11 12If you work with other people, you will need commands listed in 13the <<Individual Developer (Participant)>> section as well. 14 15People who play the <<Integrator>> role need to learn some more 16commands in addition to the above. 17 18<<Repository Administration>> commands are for system 19administrators who are responsible for the care and feeding 20of git repositories. 21 22 23Basic Repository[[Basic Repository]] 24------------------------------------ 25 26Everybody uses these commands to maintain git repositories. 27 28 * linkgit:git-init[1] or linkgit:git-clone[1] to create a 29 new repository. 30 31 * linkgit:git-fsck[1] to check the repository for errors. 32 33 * linkgit:git-gc[1] to do common housekeeping tasks such as 34 repack and prune. 35 36Examples 37~~~~~~~~ 38 39Check health and remove cruft.:: 40+ 41------------ 42$ git fsck <1> 43$ git count-objects <2> 44$ git gc <3> 45------------ 46+ 47<1> running without `\--full` is usually cheap and assures the 48repository health reasonably well. 49<2> check how many loose objects there are and how much 50disk space is wasted by not repacking. 51<3> repacks the local repository and performs other housekeeping tasks. 52 53Repack a small project into single pack.:: 54+ 55------------ 56$ git gc <1> 57------------ 58+ 59<1> pack all the objects reachable from the refs into one pack, 60then remove the other packs. 61 62 63Individual Developer (Standalone)[[Individual Developer (Standalone)]] 64---------------------------------------------------------------------- 65 66A standalone individual developer does not exchange patches with 67other people, and works alone in a single repository, using the 68following commands. 69 70 * linkgit:git-show-branch[1] to see where you are. 71 72 * linkgit:git-log[1] to see what happened. 73 74 * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch 75 branches. 76 77 * linkgit:git-add[1] to manage the index file. 78 79 * linkgit:git-diff[1] and linkgit:git-status[1] to see what 80 you are in the middle of doing. 81 82 * linkgit:git-commit[1] to advance the current branch. 83 84 * linkgit:git-reset[1] and linkgit:git-checkout[1] (with 85 pathname parameters) to undo changes. 86 87 * linkgit:git-merge[1] to merge between local branches. 88 89 * linkgit:git-rebase[1] to maintain topic branches. 90 91 * linkgit:git-tag[1] to mark known point. 92 93Examples 94~~~~~~~~ 95 96Use a tarball as a starting point for a new repository.:: 97+ 98------------ 99$ tar zxf frotz.tar.gz 100$ cd frotz 101$ git init 102$ git add . <1> 103$ git commit -m "import of frotz source tree." 104$ git tag v2.43 <2> 105------------ 106+ 107<1> add everything under the current directory. 108<2> make a lightweight, unannotated tag. 109 110Create a topic branch and develop.:: 111+ 112------------ 113$ git checkout -b alsa-audio <1> 114$ edit/compile/test 115$ git checkout -- curses/ux_audio_oss.c <2> 116$ git add curses/ux_audio_alsa.c <3> 117$ edit/compile/test 118$ git diff HEAD <4> 119$ git commit -a -s <5> 120$ edit/compile/test 121$ git reset --soft HEAD^ <6> 122$ edit/compile/test 123$ git diff ORIG_HEAD <7> 124$ git commit -a -c ORIG_HEAD <8> 125$ git checkout master <9> 126$ git merge alsa-audio <10> 127$ git log --since='3 days ago' <11> 128$ git log v2.43.. curses/ <12> 129------------ 130+ 131<1> create a new topic branch. 132<2> revert your botched changes in `curses/ux_audio_oss.c`. 133<3> you need to tell git if you added a new file; removal and 134modification will be caught if you do `git commit -a` later. 135<4> to see what changes you are committing. 136<5> commit everything as you have tested, with your sign-off. 137<6> take the last commit back, keeping what is in the working tree. 138<7> look at the changes since the premature commit we took back. 139<8> redo the commit undone in the previous step, using the message 140you originally wrote. 141<9> switch to the master branch. 142<10> merge a topic branch into your master branch. 143<11> review commit logs; other forms to limit output can be 144combined and include `\--max-count=10` (show 10 commits), 145`\--until=2005-12-10`, etc. 146<12> view only the changes that touch what's in `curses/` 147directory, since `v2.43` tag. 148 149 150Individual Developer (Participant)[[Individual Developer (Participant)]] 151------------------------------------------------------------------------ 152 153A developer working as a participant in a group project needs to 154learn how to communicate with others, and uses these commands in 155addition to the ones needed by a standalone developer. 156 157 * linkgit:git-clone[1] from the upstream to prime your local 158 repository. 159 160 * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin" 161 to keep up-to-date with the upstream. 162 163 * linkgit:git-push[1] to shared repository, if you adopt CVS 164 style shared repository workflow. 165 166 * linkgit:git-format-patch[1] to prepare e-mail submission, if 167 you adopt Linux kernel-style public forum workflow. 168 169Examples 170~~~~~~~~ 171 172Clone the upstream and work on it. Feed changes to upstream.:: 173+ 174------------ 175$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6 176$ cd my2.6 177$ edit/compile/test; git commit -a -s <1> 178$ git format-patch origin <2> 179$ git pull <3> 180$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> 181$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> 182$ git reset --hard ORIG_HEAD <6> 183$ git gc <7> 184$ git fetch --tags <8> 185------------ 186+ 187<1> repeat as needed. 188<2> extract patches from your branch for e-mail submission. 189<3> `git pull` fetches from `origin` by default and merges into the 190current branch. 191<4> immediately after pulling, look at the changes done upstream 192since last time we checked, only in the 193area we are interested in. 194<5> fetch from a specific branch from a specific repository and merge. 195<6> revert the pull. 196<7> garbage collect leftover objects from reverted pull. 197<8> from time to time, obtain official tags from the `origin` 198and store them under `.git/refs/tags/`. 199 200 201Push into another repository.:: 202+ 203------------ 204satellite$ git clone mothership:frotz frotz <1> 205satellite$ cd frotz 206satellite$ git config --get-regexp '^(remote|branch)\.' <2> 207remote.origin.url mothership:frotz 208remote.origin.fetch refs/heads/*:refs/remotes/origin/* 209branch.master.remote origin 210branch.master.merge refs/heads/master 211satellite$ git config remote.origin.push \ 212 master:refs/remotes/satellite/master <3> 213satellite$ edit/compile/test/commit 214satellite$ git push origin <4> 215 216mothership$ cd frotz 217mothership$ git checkout master 218mothership$ git merge satellite/master <5> 219------------ 220+ 221<1> mothership machine has a frotz repository under your home 222directory; clone from it to start a repository on the satellite 223machine. 224<2> clone sets these configuration variables by default. 225It arranges `git pull` to fetch and store the branches of mothership 226machine to local `remotes/origin/*` tracking branches. 227<3> arrange `git push` to push local `master` branch to 228`remotes/satellite/master` branch of the mothership machine. 229<4> push will stash our work away on `remotes/satellite/master` 230tracking branch on the mothership machine. You could use this as 231a back-up method. 232<5> on mothership machine, merge the work done on the satellite 233machine into the master branch. 234 235Branch off of a specific tag.:: 236+ 237------------ 238$ git checkout -b private2.6.14 v2.6.14 <1> 239$ edit/compile/test; git commit -a 240$ git checkout master 241$ git format-patch -k -m --stdout v2.6.14..private2.6.14 | 242 git am -3 -k <2> 243------------ 244+ 245<1> create a private branch based on a well known (but somewhat behind) 246tag. 247<2> forward port all changes in `private2.6.14` branch to `master` branch 248without a formal "merging". 249 250 251Integrator[[Integrator]] 252------------------------ 253 254A fairly central person acting as the integrator in a group 255project receives changes made by others, reviews and integrates 256them and publishes the result for others to use, using these 257commands in addition to the ones needed by participants. 258 259 * linkgit:git-am[1] to apply patches e-mailed in from your 260 contributors. 261 262 * linkgit:git-pull[1] to merge from your trusted lieutenants. 263 264 * linkgit:git-format-patch[1] to prepare and send suggested 265 alternative to contributors. 266 267 * linkgit:git-revert[1] to undo botched commits. 268 269 * linkgit:git-push[1] to publish the bleeding edge. 270 271 272Examples 273~~~~~~~~ 274 275My typical GIT day.:: 276+ 277------------ 278$ git status <1> 279$ git show-branch <2> 280$ mailx <3> 281& s 2 3 4 5 ./+to-apply 282& s 7 8 ./+hold-linus 283& q 284$ git checkout -b topic/one master 285$ git am -3 -i -s -u ./+to-apply <4> 286$ compile/test 287$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5> 288$ git checkout topic/one && git rebase master <6> 289$ git checkout pu && git reset --hard next <7> 290$ git merge topic/one topic/two && git merge hold/linus <8> 291$ git checkout maint 292$ git cherry-pick master~4 <9> 293$ compile/test 294$ git tag -s -m "GIT 0.99.9x" v0.99.9x <10> 295$ git fetch ko && git show-branch master maint 'tags/ko-*' <11> 296$ git push ko <12> 297$ git push ko v0.99.9x <13> 298------------ 299+ 300<1> see what I was in the middle of doing, if any. 301<2> see what topic branches I have and think about how ready 302they are. 303<3> read mails, save ones that are applicable, and save others 304that are not quite ready. 305<4> apply them, interactively, with my sign-offs. 306<5> create topic branch as needed and apply, again with my 307sign-offs. 308<6> rebase internal topic branch that has not been merged to the 309master, nor exposed as a part of a stable branch. 310<7> restart `pu` every time from the next. 311<8> and bundle topic branches still cooking. 312<9> backport a critical fix. 313<10> create a signed tag. 314<11> make sure I did not accidentally rewind master beyond what I 315already pushed out. `ko` shorthand points at the repository I have 316at kernel.org, and looks like this: 317+ 318------------ 319$ cat .git/remotes/ko 320URL: kernel.org:/pub/scm/git/git.git 321Pull: master:refs/tags/ko-master 322Pull: next:refs/tags/ko-next 323Pull: maint:refs/tags/ko-maint 324Push: master 325Push: next 326Push: +pu 327Push: maint 328------------ 329+ 330In the output from `git show-branch`, `master` should have 331everything `ko-master` has, and `next` should have 332everything `ko-next` has. 333 334<12> push out the bleeding edge. 335<13> push the tag out, too. 336 337 338Repository Administration[[Repository Administration]] 339------------------------------------------------------ 340 341A repository administrator uses the following tools to set up 342and maintain access to the repository by developers. 343 344 * linkgit:git-daemon[1] to allow anonymous download from 345 repository. 346 347 * linkgit:git-shell[1] can be used as a 'restricted login shell' 348 for shared central repository users. 349 350link:howto/update-hook-example.txt[update hook howto] has a good 351example of managing a shared central repository. 352 353 354Examples 355~~~~~~~~ 356We assume the following in /etc/services:: 357+ 358------------ 359$ grep 9418 /etc/services 360git 9418/tcp # Git Version Control System 361------------ 362 363Run git-daemon to serve /pub/scm from inetd.:: 364+ 365------------ 366$ grep git /etc/inetd.conf 367git stream tcp nowait nobody \ 368 /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm 369------------ 370+ 371The actual configuration line should be on one line. 372 373Run git-daemon to serve /pub/scm from xinetd.:: 374+ 375------------ 376$ cat /etc/xinetd.d/git-daemon 377# default: off 378# description: The git server offers access to git repositories 379service git 380{ 381 disable = no 382 type = UNLISTED 383 port = 9418 384 socket_type = stream 385 wait = no 386 user = nobody 387 server = /usr/bin/git-daemon 388 server_args = --inetd --export-all --base-path=/pub/scm 389 log_on_failure += USERID 390} 391------------ 392+ 393Check your xinetd(8) documentation and setup, this is from a Fedora system. 394Others might be different. 395 396Give push/pull only access to developers.:: 397+ 398------------ 399$ grep git /etc/passwd <1> 400alice:x:1000:1000::/home/alice:/usr/bin/git-shell 401bob:x:1001:1001::/home/bob:/usr/bin/git-shell 402cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell 403david:x:1003:1003::/home/david:/usr/bin/git-shell 404$ grep git /etc/shells <2> 405/usr/bin/git-shell 406------------ 407+ 408<1> log-in shell is set to /usr/bin/git-shell, which does not 409allow anything but `git push` and `git pull`. The users should 410get an ssh access to the machine. 411<2> in many distributions /etc/shells needs to list what is used 412as the login shell. 413 414CVS-style shared repository.:: 415+ 416------------ 417$ grep git /etc/group <1> 418git:x:9418:alice,bob,cindy,david 419$ cd /home/devo.git 420$ ls -l <2> 421 lrwxrwxrwx 1 david git 17 Dec 4 22:40 HEAD -> refs/heads/master 422 drwxrwsr-x 2 david git 4096 Dec 4 22:40 branches 423 -rw-rw-r-- 1 david git 84 Dec 4 22:40 config 424 -rw-rw-r-- 1 david git 58 Dec 4 22:40 description 425 drwxrwsr-x 2 david git 4096 Dec 4 22:40 hooks 426 -rw-rw-r-- 1 david git 37504 Dec 4 22:40 index 427 drwxrwsr-x 2 david git 4096 Dec 4 22:40 info 428 drwxrwsr-x 4 david git 4096 Dec 4 22:40 objects 429 drwxrwsr-x 4 david git 4096 Nov 7 14:58 refs 430 drwxrwsr-x 2 david git 4096 Dec 4 22:40 remotes 431$ ls -l hooks/update <3> 432 -r-xr-xr-x 1 david git 3536 Dec 4 22:40 update 433$ cat info/allowed-users <4> 434refs/heads/master alice\|cindy 435refs/heads/doc-update bob 436refs/tags/v[0-9]* david 437------------ 438+ 439<1> place the developers into the same git group. 440<2> and make the shared repository writable by the group. 441<3> use update-hook example by Carl from Documentation/howto/ 442for branch policy control. 443<4> alice and cindy can push into master, only bob can push into doc-update. 444david is the release manager and is the only person who can 445create and push version tags. 446 447HTTP server to support dumb protocol transfer.:: 448+ 449------------ 450dev$ git update-server-info <1> 451dev$ ftp user@isp.example.com <2> 452ftp> cp -r .git /home/user/myproject.git 453------------ 454+ 455<1> make sure your info/refs and objects/info/packs are up-to-date 456<2> upload to public HTTP server hosted by your ISP.