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