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