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 commands 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-switch[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-restore[1] to undo changes.
  55
  56   * linkgit:git-merge[1] to merge between local branches.
  57
  58   * linkgit:git-rebase[1] to maintain topic branches.
  59
  60   * linkgit:git-tag[1] to mark a known point.
  61
  62 Examples
  63 ~~~~~~~~
  64
  65 Use a tarball as a starting point for a new repository.::
  66 +
  67 ------------
  68 $ tar zxf frotz.tar.gz
  69 $ cd frotz
  70 $ git init
  71 $ git add . <1>
  72 $ git commit -m "import of frotz source tree."
  73 $ git tag v2.43 <2>
  74 ------------
  75 +
  76 <1> add everything under the current directory.
  77 <2> make a lightweight, unannotated tag.
  78
  79 Create a topic branch and develop.::
  80 +
  81 ------------
  82 $ git switch -c alsa-audio <1>
  83 $ edit/compile/test
  84 $ git restore curses/ux_audio_oss.c <2>
  85 $ git add curses/ux_audio_alsa.c <3>
  86 $ edit/compile/test
  87 $ git diff HEAD <4>
  88 $ git commit -a -s <5>
  89 $ edit/compile/test
  90 $ git diff HEAD^ <6>
  91 $ git commit -a --amend <7>
  92 $ git switch master <8>
  93 $ git merge alsa-audio <9>
  94 $ git log --since='3 days ago' <10>
  95 $ git log v2.43.. curses/ <11>
  96 ------------
  97 +
  98 <1> create a new topic branch.
  99 <2> revert your botched changes in `curses/ux_audio_oss.c`.
 100 <3> you need to tell Git if you added a new file; removal and
 101 modification will be caught if you do `git commit -a` later.
 102 <4> to see what changes you are committing.
 103 <5> commit everything, as you have tested, with your sign-off.
 104 <6> look at all your changes including the previous commit.
 105 <7> amend the previous commit, adding all your new changes,
 106 using your original message.
 107 <8> switch to the master branch.
 108 <9> merge a topic branch into your master branch.
 109 <10> review commit logs; other forms to limit output can be
 110 combined and include `-10` (to show up to 10 commits),
 111 `--until=2005-12-10`, etc.
 112 <11> view only the changes that touch what's in `curses/`
 113 directory, since `v2.43` tag.
 114
 115
 116 Individual Developer (Participant)[[PARTICIPANT]]
 117 -------------------------------------------------
 118
 119 A developer working as a participant in a group project needs to
 120 learn how to communicate with others, and uses these commands in
 121 addition to the ones needed by a standalone developer.
 122
 123   * linkgit:git-clone[1] from the upstream to prime your local
 124     repository.
 125
 126   * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin"
 127     to keep up-to-date with the upstream.
 128
 129   * linkgit:git-push[1] to shared repository, if you adopt CVS
 130     style shared repository workflow.
 131
 132   * linkgit:git-format-patch[1] to prepare e-mail submission, if
 133     you adopt Linux kernel-style public forum workflow.
 134
 135   * linkgit:git-send-email[1] to send your e-mail submission without
 136     corruption by your MUA.
 137
 138   * linkgit:git-request-pull[1] to create a summary of changes
 139     for your upstream to pull.
 140
 141
 142 Examples
 143 ~~~~~~~~
 144
 145 Clone the upstream and work on it.  Feed changes to upstream.::
 146 +
 147 ------------
 148 $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
 149 $ cd my2.6
 150 $ git switch -c mine master <1>
 151 $ edit/compile/test; git commit -a -s <2>
 152 $ git format-patch master <3>
 153 $ git send-email --to="person <email@example.com>" 00*.patch <4>
 154 $ git switch master <5>
 155 $ git pull <6>
 156 $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>
 157 $ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>
 158 $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <9>
 159 $ git reset --hard ORIG_HEAD <10>
 160 $ git gc <11>
 161 ------------
 162 +
 163 <1> checkout a new branch `mine` from master.
 164 <2> repeat as needed.
 165 <3> extract patches from your branch, relative to master,
 166 <4> and email them.
 167 <5> return to `master`, ready to see what's new
 168 <6> `git pull` fetches from `origin` by default and merges into the
 169 current branch.
 170 <7> immediately after pulling, look at the changes done upstream
 171 since last time we checked, only in the
 172 area we are interested in.
 173 <8> check the branch names in an external repository (if not known).
 174 <9> fetch from a specific branch `ALL` from a specific repository
 175 and merge it.
 176 <10> revert the pull.
 177 <11> garbage collect leftover objects from reverted pull.
 178
 179
 180 Push into another repository.::
 181 +
 182 ------------
 183 satellite$ git clone mothership:frotz frotz <1>
 184 satellite$ cd frotz
 185 satellite$ git config --get-regexp '^(remote|branch)\.' <2>
 186 remote.origin.url mothership:frotz
 187 remote.origin.fetch refs/heads/*:refs/remotes/origin/*
 188 branch.master.remote origin
 189 branch.master.merge refs/heads/master
 190 satellite$ git config remote.origin.push \
 191            +refs/heads/*:refs/remotes/satellite/* <3>
 192 satellite$ edit/compile/test/commit
 193 satellite$ git push origin <4>
 194
 195 mothership$ cd frotz
 196 mothership$ git switch master
 197 mothership$ git merge satellite/master <5>
 198 ------------
 199 +
 200 <1> mothership machine has a frotz repository under your home
 201 directory; clone from it to start a repository on the satellite
 202 machine.
 203 <2> clone sets these configuration variables by default.
 204 It arranges `git pull` to fetch and store the branches of mothership
 205 machine to local `remotes/origin/*` remote-tracking branches.
 206 <3> arrange `git push` to push all local branches to
 207 their corresponding branch of the mothership machine.
 208 <4> push will stash all our work away on `remotes/satellite/*`
 209 remote-tracking branches on the mothership machine.  You could use this
 210 as a back-up method. Likewise, you can pretend that mothership
 211 "fetched" from you (useful when access is one sided).
 212 <5> on mothership machine, merge the work done on the satellite
 213 machine into the master branch.
 214
 215 Branch off of a specific tag.::
 216 +
 217 ------------
 218 $ git switch -c private2.6.14 v2.6.14 <1>
 219 $ edit/compile/test; git commit -a
 220 $ git checkout master
 221 $ git cherry-pick v2.6.14..private2.6.14 <2>
 222 ------------
 223 +
 224 <1> create a private branch based on a well known (but somewhat behind)
 225 tag.
 226 <2> forward port all changes in `private2.6.14` branch to `master` branch
 227 without a formal "merging". Or longhand +
 228 `git format-patch -k -m --stdout v2.6.14..private2.6.14 |
 229   git am -3 -k`
 230
 231 An alternate participant submission mechanism is using the
 232 `git request-pull` or pull-request mechanisms (e.g. as used on
 233 GitHub (www.github.com) to notify your upstream of your
 234 contribution.
 235
 236 Integrator[[INTEGRATOR]]
 237 ------------------------
 238
 239 A fairly central person acting as the integrator in a group
 240 project receives changes made by others, reviews and integrates
 241 them and publishes the result for others to use, using these
 242 commands in addition to the ones needed by participants.
 243
 244 This section can also be used by those who respond to `git
 245 request-pull` or pull-request on GitHub (www.github.com) to
 246 integrate the work of others into their history. A sub-area
 247 lieutenant for a repository will act both as a participant and
 248 as an integrator.
 249
 250
 251   * linkgit:git-am[1] to apply patches e-mailed in from your
 252     contributors.
 253
 254   * linkgit:git-pull[1] to merge from your trusted lieutenants.
 255
 256   * linkgit:git-format-patch[1] to prepare and send suggested
 257     alternative to contributors.
 258
 259   * linkgit:git-revert[1] to undo botched commits.
 260
 261   * linkgit:git-push[1] to publish the bleeding edge.
 262
 263
 264 Examples
 265 ~~~~~~~~
 266
 267 A typical integrator's Git day.::
 268 +
 269 ------------
 270 $ git status <1>
 271 $ git branch --no-merged master <2>
 272 $ mailx <3>
 273 & s 2 3 4 5 ./+to-apply
 274 & s 7 8 ./+hold-linus
 275 & q
 276 $ git switch -c topic/one master
 277 $ git am -3 -i -s ./+to-apply <4>
 278 $ compile/test
 279 $ git switch -c hold/linus && git am -3 -i -s ./+hold-linus <5>
 280 $ git switch topic/one && git rebase master <6>
 281 $ git switch -C seen next <7>
 282 $ git merge topic/one topic/two && git merge hold/linus <8>
 283 $ git switch maint
 284 $ git cherry-pick master~4 <9>
 285 $ compile/test
 286 $ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>
 287 $ git fetch ko && for branch in master maint next seen <11>
 288     do
 289         git show-branch ko/$branch $branch <12>
 290     done
 291 $ git push --follow-tags ko <13>
 292 ------------
 293 +
 294 <1> see what you were in the middle of doing, if anything.
 295 <2> see which branches haven't been merged into `master` yet.
 296 Likewise for any other integration branches e.g. `maint`, `next`
 297 and `seen`.
 298 <3> read mails, save ones that are applicable, and save others
 299 that are not quite ready (other mail readers are available).
 300 <4> apply them, interactively, with your sign-offs.
 301 <5> create topic branch as needed and apply, again with sign-offs.
 302 <6> rebase internal topic branch that has not been merged to the
 303 master or exposed as a part of a stable branch.
 304 <7> restart `seen` every time from the next.
 305 <8> and bundle topic branches still cooking.
 306 <9> backport a critical fix.
 307 <10> create a signed tag.
 308 <11> make sure master was not accidentally rewound beyond that
 309 already pushed out.
 310 <12> In the output from `git show-branch`, `master` should have
 311 everything `ko/master` has, and `next` should have
 312 everything `ko/next` has, etc.
 313 <13> push out the bleeding edge, together with new tags that point
 314 into the pushed history.
 315
 316 In this example, the `ko` shorthand points at the Git maintainer's
 317 repository at kernel.org, and looks like this:
 318
 319 ------------
 320 (in .git/config)
 321 [remote "ko"]
 322         url = kernel.org:/pub/scm/git/git.git
 323         fetch = refs/heads/*:refs/remotes/ko/*
 324         push = refs/heads/master
 325         push = refs/heads/next
 326         push = +refs/heads/seen
 327         push = refs/heads/maint
 328 ------------
 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