]>
Commit | Line | Data |
---|---|---|
992cb206 | 1 | giteveryday(7) |
f3f38c7d | 2 | ============== |
992cb206 PO |
3 | |
4 | NAME | |
5 | ---- | |
6 | giteveryday - A useful minimum set of commands for Everyday Git | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | ||
48a8c26c | 11 | Everyday Git With 20 Commands Or So |
db9536c8 | 12 | |
992cb206 PO |
13 | DESCRIPTION |
14 | ----------- | |
db9536c8 | 15 | |
992cb206 PO |
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. | |
db9536c8 | 18 | |
992cb206 PO |
19 | * <<STANDALONE,Individual Developer (Standalone)>> commands are essential |
20 | for anybody who makes a commit, even for somebody who works alone. | |
db9536c8 | 21 | |
992cb206 PO |
22 | * If you work with other people, you will need commands listed in |
23 | the <<PARTICIPANT,Individual Developer (Participant)>> section as well. | |
db9536c8 | 24 | |
992cb206 PO |
25 | * People who play the <<INTEGRATOR,Integrator>> role need to learn some |
26 | more commands in addition to the above. | |
db9536c8 | 27 | |
992cb206 PO |
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 | ----------------------------------------------- | |
db9536c8 JH |
35 | |
36 | A standalone individual developer does not exchange patches with | |
7872b188 | 37 | other people, and works alone in a single repository, using the |
db9536c8 JH |
38 | following commands. |
39 | ||
bce02c1b AK |
40 | * linkgit:git-init[1] to create a new repository. |
41 | ||
5162e697 | 42 | * linkgit:git-log[1] to see what happened. |
db9536c8 | 43 | |
328c6cb8 | 44 | * linkgit:git-switch[1] and linkgit:git-branch[1] to switch |
db9536c8 JH |
45 | branches. |
46 | ||
5162e697 | 47 | * linkgit:git-add[1] to manage the index file. |
44db136c | 48 | |
5162e697 | 49 | * linkgit:git-diff[1] and linkgit:git-status[1] to see what |
44db136c | 50 | you are in the middle of doing. |
db9536c8 | 51 | |
5162e697 | 52 | * linkgit:git-commit[1] to advance the current branch. |
db9536c8 | 53 | |
80f537f7 | 54 | * linkgit:git-restore[1] to undo changes. |
db9536c8 | 55 | |
5162e697 | 56 | * linkgit:git-merge[1] to merge between local branches. |
db9536c8 | 57 | |
5162e697 | 58 | * linkgit:git-rebase[1] to maintain topic branches. |
db9536c8 | 59 | |
992cb206 | 60 | * linkgit:git-tag[1] to mark a known point. |
db9536c8 | 61 | |
44db136c JH |
62 | Examples |
63 | ~~~~~~~~ | |
64 | ||
268b827d | 65 | Use a tarball as a starting point for a new repository.:: |
1e2ccd3a | 66 | + |
44db136c JH |
67 | ------------ |
68 | $ tar zxf frotz.tar.gz | |
69 | $ cd frotz | |
3e5970a4 | 70 | $ git init |
180c4746 | 71 | $ git add . <1> |
d336fc09 | 72 | $ git commit -m "import of frotz source tree." |
180c4746 | 73 | $ git tag v2.43 <2> |
48aeecdc SE |
74 | ------------ |
75 | + | |
180c4746 JH |
76 | <1> add everything under the current directory. |
77 | <2> make a lightweight, unannotated tag. | |
44db136c | 78 | |
01f49e34 | 79 | Create a topic branch and develop.:: |
1e2ccd3a | 80 | + |
44db136c | 81 | ------------ |
328c6cb8 | 82 | $ git switch -c alsa-audio <1> |
180c4746 | 83 | $ edit/compile/test |
80f537f7 | 84 | $ git restore curses/ux_audio_oss.c <2> |
180c4746 JH |
85 | $ git add curses/ux_audio_alsa.c <3> |
86 | $ edit/compile/test | |
268b827d | 87 | $ git diff HEAD <4> |
180c4746 | 88 | $ git commit -a -s <5> |
44db136c | 89 | $ edit/compile/test |
992cb206 PO |
90 | $ git diff HEAD^ <6> |
91 | $ git commit -a --amend <7> | |
328c6cb8 | 92 | $ git switch master <8> |
992cb206 PO |
93 | $ git merge alsa-audio <9> |
94 | $ git log --since='3 days ago' <10> | |
95 | $ git log v2.43.. curses/ <11> | |
48aeecdc SE |
96 | ------------ |
97 | + | |
180c4746 | 98 | <1> create a new topic branch. |
268b827d | 99 | <2> revert your botched changes in `curses/ux_audio_oss.c`. |
2de9b711 | 100 | <3> you need to tell Git if you added a new file; removal and |
268b827d | 101 | modification will be caught if you do `git commit -a` later. |
180c4746 | 102 | <4> to see what changes you are committing. |
992cb206 PO |
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), | |
6cf378f0 | 111 | `--until=2005-12-10`, etc. |
992cb206 | 112 | <11> view only the changes that touch what's in `curses/` |
268b827d | 113 | directory, since `v2.43` tag. |
44db136c JH |
114 | |
115 | ||
992cb206 PO |
116 | Individual Developer (Participant)[[PARTICIPANT]] |
117 | ------------------------------------------------- | |
db9536c8 JH |
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 | ||
5162e697 | 123 | * linkgit:git-clone[1] from the upstream to prime your local |
01f49e34 JH |
124 | repository. |
125 | ||
5162e697 | 126 | * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin" |
01f49e34 | 127 | to keep up-to-date with the upstream. |
db9536c8 | 128 | |
5162e697 | 129 | * linkgit:git-push[1] to shared repository, if you adopt CVS |
db9536c8 JH |
130 | style shared repository workflow. |
131 | ||
5162e697 | 132 | * linkgit:git-format-patch[1] to prepare e-mail submission, if |
db9536c8 JH |
133 | you adopt Linux kernel-style public forum workflow. |
134 | ||
992cb206 PO |
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 | ||
44db136c JH |
142 | Examples |
143 | ~~~~~~~~ | |
144 | ||
01f49e34 | 145 | Clone the upstream and work on it. Feed changes to upstream.:: |
1e2ccd3a | 146 | + |
44db136c JH |
147 | ------------ |
148 | $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6 | |
149 | $ cd my2.6 | |
328c6cb8 | 150 | $ git switch -c mine master <1> |
992cb206 PO |
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> | |
328c6cb8 | 154 | $ git switch master <5> |
992cb206 PO |
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> | |
48aeecdc SE |
161 | ------------ |
162 | + | |
992cb206 PO |
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 | |
d808111e | 169 | current branch. |
992cb206 | 170 | <7> immediately after pulling, look at the changes done upstream |
d808111e | 171 | since last time we checked, only in the |
180c4746 | 172 | area we are interested in. |
992cb206 PO |
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. | |
01f49e34 JH |
178 | |
179 | ||
180 | Push into another repository.:: | |
181 | + | |
182 | ------------ | |
268b827d | 183 | satellite$ git clone mothership:frotz frotz <1> |
01f49e34 | 184 | satellite$ cd frotz |
e0d10e1c | 185 | satellite$ git config --get-regexp '^(remote|branch)\.' <2> |
268b827d JH |
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 | |
e0d10e1c | 190 | satellite$ git config remote.origin.push \ |
992cb206 | 191 | +refs/heads/*:refs/remotes/satellite/* <3> |
01f49e34 JH |
192 | satellite$ edit/compile/test/commit |
193 | satellite$ git push origin <4> | |
194 | ||
195 | mothership$ cd frotz | |
328c6cb8 | 196 | mothership$ git switch master |
268b827d | 197 | mothership$ git merge satellite/master <5> |
48aeecdc SE |
198 | ------------ |
199 | + | |
01f49e34 JH |
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. | |
268b827d JH |
203 | <2> clone sets these configuration variables by default. |
204 | It arranges `git pull` to fetch and store the branches of mothership | |
bc6dafc1 | 205 | machine to local `remotes/origin/*` remote-tracking branches. |
992cb206 PO |
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). | |
01f49e34 JH |
212 | <5> on mothership machine, merge the work done on the satellite |
213 | machine into the master branch. | |
44db136c | 214 | |
01f49e34 | 215 | Branch off of a specific tag.:: |
1e2ccd3a | 216 | + |
44db136c | 217 | ------------ |
328c6cb8 | 218 | $ git switch -c private2.6.14 v2.6.14 <1> |
44db136c JH |
219 | $ edit/compile/test; git commit -a |
220 | $ git checkout master | |
992cb206 | 221 | $ git cherry-pick v2.6.14..private2.6.14 <2> |
48aeecdc SE |
222 | ------------ |
223 | + | |
44db136c JH |
224 | <1> create a private branch based on a well known (but somewhat behind) |
225 | tag. | |
268b827d | 226 | <2> forward port all changes in `private2.6.14` branch to `master` branch |
992cb206 PO |
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` | |
44db136c | 230 | |
992cb206 PO |
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. | |
44db136c | 235 | |
992cb206 | 236 | Integrator[[INTEGRATOR]] |
db9536c8 JH |
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 | ||
992cb206 PO |
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 | |
928f0ab4 | 246 | integrate the work of others into their history. A sub-area |
992cb206 PO |
247 | lieutenant for a repository will act both as a participant and |
248 | as an integrator. | |
249 | ||
250 | ||
5162e697 | 251 | * linkgit:git-am[1] to apply patches e-mailed in from your |
db9536c8 JH |
252 | contributors. |
253 | ||
5162e697 | 254 | * linkgit:git-pull[1] to merge from your trusted lieutenants. |
db9536c8 | 255 | |
5162e697 | 256 | * linkgit:git-format-patch[1] to prepare and send suggested |
db9536c8 JH |
257 | alternative to contributors. |
258 | ||
5162e697 | 259 | * linkgit:git-revert[1] to undo botched commits. |
db9536c8 | 260 | |
5162e697 | 261 | * linkgit:git-push[1] to publish the bleeding edge. |
db9536c8 JH |
262 | |
263 | ||
180c4746 JH |
264 | Examples |
265 | ~~~~~~~~ | |
266 | ||
992cb206 | 267 | A typical integrator's Git day.:: |
1e2ccd3a | 268 | + |
180c4746 JH |
269 | ------------ |
270 | $ git status <1> | |
992cb206 | 271 | $ git branch --no-merged master <2> |
180c4746 JH |
272 | $ mailx <3> |
273 | & s 2 3 4 5 ./+to-apply | |
274 | & s 7 8 ./+hold-linus | |
275 | & q | |
328c6cb8 | 276 | $ git switch -c topic/one master |
992cb206 | 277 | $ git am -3 -i -s ./+to-apply <4> |
180c4746 | 278 | $ compile/test |
328c6cb8 NTND |
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 pu next <7> | |
268b827d | 282 | $ git merge topic/one topic/two && git merge hold/linus <8> |
328c6cb8 | 283 | $ git switch maint |
01f49e34 | 284 | $ git cherry-pick master~4 <9> |
180c4746 | 285 | $ compile/test |
d336fc09 | 286 | $ git tag -s -m "GIT 0.99.9x" v0.99.9x <10> |
992cb206 PO |
287 | $ git fetch ko && for branch in master maint next pu <11> |
288 | do | |
289 | git show-branch ko/$branch $branch <12> | |
290 | done | |
291 | $ git push --follow-tags ko <13> | |
48aeecdc SE |
292 | ------------ |
293 | + | |
992cb206 PO |
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 `pu` (potential updates). | |
180c4746 | 298 | <3> read mails, save ones that are applicable, and save others |
992cb206 PO |
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. | |
1e2ccd3a | 302 | <6> rebase internal topic branch that has not been merged to the |
a58088ab | 303 | master or exposed as a part of a stable branch. |
268b827d | 304 | <7> restart `pu` every time from the next. |
1e2ccd3a | 305 | <8> and bundle topic branches still cooking. |
01f49e34 JH |
306 | <9> backport a critical fix. |
307 | <10> create a signed tag. | |
992cb206 | 308 | <11> make sure master was not accidentally rewound beyond that |
9574901c JS |
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 | |
992cb206 | 317 | repository at kernel.org, and looks like this: |
9574901c | 318 | |
53bcf78a | 319 | ------------ |
992cb206 PO |
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/pu | |
327 | push = refs/heads/maint | |
53bcf78a | 328 | ------------ |
180c4746 JH |
329 | |
330 | ||
992cb206 PO |
331 | Repository Administration[[ADMINISTRATION]] |
332 | ------------------------------------------- | |
db9536c8 JH |
333 | |
334 | A repository administrator uses the following tools to set up | |
335 | and maintain access to the repository by developers. | |
336 | ||
5162e697 | 337 | * linkgit:git-daemon[1] to allow anonymous download from |
db9536c8 JH |
338 | repository. |
339 | ||
5162e697 | 340 | * linkgit:git-shell[1] can be used as a 'restricted login shell' |
db9536c8 JH |
341 | for shared central repository users. |
342 | ||
992cb206 PO |
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 | ||
d5ff3b4b | 349 | link:howto/update-hook-example.html[update hook howto] has a good |
d808111e | 350 | example of managing a shared central repository. |
db9536c8 | 351 | |
992cb206 PO |
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. | |
1e2ccd3a JH |
356 | |
357 | Examples | |
358 | ~~~~~~~~ | |
f8a5da6d CC |
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 | ||
01f49e34 | 366 | Run git-daemon to serve /pub/scm from inetd.:: |
1e2ccd3a JH |
367 | + |
368 | ------------ | |
7872b188 | 369 | $ grep git /etc/inetd.conf |
01f49e34 | 370 | git stream tcp nowait nobody \ |
d9c04ba3 | 371 | /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm |
1e2ccd3a | 372 | ------------ |
01f49e34 JH |
373 | + |
374 | The actual configuration line should be on one line. | |
1e2ccd3a | 375 | |
c51901de HB |
376 | Run git-daemon to serve /pub/scm from xinetd.:: |
377 | + | |
378 | ------------ | |
379 | $ cat /etc/xinetd.d/git-daemon | |
380 | # default: off | |
2de9b711 | 381 | # description: The Git server offers access to Git repositories |
c51901de HB |
382 | service git |
383 | { | |
673151a9 PO |
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 | |
c51901de HB |
393 | } |
394 | ------------ | |
395 | + | |
396 | Check your xinetd(8) documentation and setup, this is from a Fedora system. | |
397 | Others might be different. | |
398 | ||
992cb206 PO |
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` | |
1e2ccd3a JH |
403 | + |
404 | ------------ | |
01f49e34 | 405 | $ grep git /etc/passwd <1> |
1e2ccd3a JH |
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 | |
01f49e34 JH |
410 | $ grep git /etc/shells <2> |
411 | /usr/bin/git-shell | |
48aeecdc SE |
412 | ------------ |
413 | + | |
01f49e34 | 414 | <1> log-in shell is set to /usr/bin/git-shell, which does not |
992cb206 PO |
415 | allow anything but `git push` and `git pull`. The users require |
416 | ssh access to the machine. | |
01f49e34 JH |
417 | <2> in many distributions /etc/shells needs to list what is used |
418 | as the login shell. | |
01f49e34 JH |
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 | |
48aeecdc SE |
443 | ------------ |
444 | + | |
01f49e34 JH |
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. | |
80248b2e | 452 | |
992cb206 PO |
453 | GIT |
454 | --- | |
455 | Part of the linkgit:git[1] suite |