Documentation/giteveryday.txt

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