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