]>
Commit | Line | Data |
---|---|---|
b27a23e3 CC |
1 | gittutorial(7) |
2 | ============== | |
3 | ||
4 | NAME | |
5 | ---- | |
022cf2bf | 6 | gittutorial - A tutorial introduction to Git |
b27a23e3 CC |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
7791a1d9 | 10 | [verse] |
b27a23e3 CC |
11 | git * |
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
8c7fa247 | 15 | |
2de9b711 | 16 | This tutorial explains how to import a new project into Git, make |
927a503c | 17 | changes to it, and share changes with other developers. |
8c7fa247 | 18 | |
2de9b711 | 19 | If you are instead primarily interested in using Git to fetch a project, |
cd50aba9 BF |
20 | for example, to test the latest version, you may prefer to start with |
21 | the first two chapters of link:user-manual.html[The Git User's Manual]. | |
22 | ||
46e56e81 | 23 | First, note that you can get documentation for a command such as |
483bc4f0 | 24 | `git log --graph` with: |
8c7fa247 | 25 | |
927a503c | 26 | ------------------------------------------------ |
3861cd55 | 27 | $ man git-log |
927a503c | 28 | ------------------------------------------------ |
8c7fa247 | 29 | |
6e702c24 CC |
30 | or: |
31 | ||
32 | ------------------------------------------------ | |
33 | $ git help log | |
34 | ------------------------------------------------ | |
35 | ||
36 | With the latter, you can use the manual viewer of your choice; see | |
37 | linkgit:git-help[1] for more information. | |
38 | ||
2de9b711 | 39 | It is a good idea to introduce yourself to Git with your name and |
c14261ea NP |
40 | public email address before doing any operation. The easiest |
41 | way to do so is: | |
66589230 JH |
42 | |
43 | ------------------------------------------------ | |
e0d10e1c TP |
44 | $ git config --global user.name "Your Name Comes Here" |
45 | $ git config --global user.email you@yourdomain.example.com | |
66589230 JH |
46 | ------------------------------------------------ |
47 | ||
48 | ||
927a503c BF |
49 | Importing a new project |
50 | ----------------------- | |
8c7fa247 | 51 | |
927a503c | 52 | Assume you have a tarball project.tar.gz with your initial work. You |
2de9b711 | 53 | can place it under Git revision control as follows. |
8c7fa247 | 54 | |
8db9307c | 55 | ------------------------------------------------ |
dcc6e28f | 56 | $ tar xzf project.tar.gz |
927a503c | 57 | $ cd project |
515377ea | 58 | $ git init |
8db9307c | 59 | ------------------------------------------------ |
8c7fa247 | 60 | |
927a503c | 61 | Git will reply |
8c7fa247 | 62 | |
927a503c | 63 | ------------------------------------------------ |
ef0a89a6 | 64 | Initialized empty Git repository in .git/ |
927a503c | 65 | ------------------------------------------------ |
8c7fa247 | 66 | |
927a503c | 67 | You've now initialized the working directory--you may notice a new |
93f9cc67 BF |
68 | directory created, named ".git". |
69 | ||
2de9b711 | 70 | Next, tell Git to take a snapshot of the contents of all files under the |
0b444cdb | 71 | current directory (note the '.'), with 'git add': |
8c7fa247 | 72 | |
8db9307c | 73 | ------------------------------------------------ |
927a503c | 74 | $ git add . |
8db9307c | 75 | ------------------------------------------------ |
8c7fa247 | 76 | |
2de9b711 | 77 | This snapshot is now stored in a temporary staging area which Git calls |
93f9cc67 | 78 | the "index". You can permanently store the contents of the index in the |
0b444cdb | 79 | repository with 'git commit': |
8c7fa247 | 80 | |
927a503c | 81 | ------------------------------------------------ |
66589230 | 82 | $ git commit |
927a503c | 83 | ------------------------------------------------ |
8c7fa247 | 84 | |
93f9cc67 | 85 | This will prompt you for a commit message. You've now stored the first |
2de9b711 | 86 | version of your project in Git. |
8c7fa247 | 87 | |
84dee6bb BF |
88 | Making changes |
89 | -------------- | |
90 | ||
93f9cc67 | 91 | Modify some files, then add their updated contents to the index: |
8c7fa247 | 92 | |
8db9307c | 93 | ------------------------------------------------ |
93f9cc67 | 94 | $ git add file1 file2 file3 |
8db9307c | 95 | ------------------------------------------------ |
8c7fa247 | 96 | |
93f9cc67 | 97 | You are now ready to commit. You can see what is about to be committed |
0b444cdb | 98 | using 'git diff' with the --cached option: |
93f9cc67 BF |
99 | |
100 | ------------------------------------------------ | |
101 | $ git diff --cached | |
102 | ------------------------------------------------ | |
103 | ||
0b444cdb | 104 | (Without --cached, 'git diff' will show you any changes that |
93f9cc67 | 105 | you've made but not yet added to the index.) You can also get a brief |
0b444cdb | 106 | summary of the situation with 'git status': |
93f9cc67 BF |
107 | |
108 | ------------------------------------------------ | |
109 | $ git status | |
8942821e SN |
110 | On branch master |
111 | Changes to be committed: | |
7560f547 | 112 | Your branch is up to date with 'origin/master'. |
80f537f7 | 113 | (use "git restore --staged <file>..." to unstage) |
8942821e SN |
114 | |
115 | modified: file1 | |
116 | modified: file2 | |
117 | modified: file3 | |
118 | ||
93f9cc67 BF |
119 | ------------------------------------------------ |
120 | ||
121 | If you need to make any further adjustments, do so now, and then add any | |
122 | newly modified content to the index. Finally, commit your changes with: | |
8c7fa247 | 123 | |
927a503c | 124 | ------------------------------------------------ |
c1d179f8 | 125 | $ git commit |
927a503c | 126 | ------------------------------------------------ |
f2416c27 | 127 | |
2feaf4e9 | 128 | This will again prompt you for a message describing the change, and then |
93f9cc67 | 129 | record a new version of the project. |
84dee6bb | 130 | |
0b444cdb | 131 | Alternatively, instead of running 'git add' beforehand, you can use |
66589230 JH |
132 | |
133 | ------------------------------------------------ | |
134 | $ git commit -a | |
135 | ------------------------------------------------ | |
8c7fa247 | 136 | |
93f9cc67 BF |
137 | which will automatically notice any modified (but not new) files, add |
138 | them to the index, and commit, all in one step. | |
84dee6bb | 139 | |
927a503c BF |
140 | A note on commit messages: Though not required, it's a good idea to |
141 | begin the commit message with a single short (less than 50 character) | |
142 | line summarizing the change, followed by a blank line and then a more | |
52ffe995 JW |
143 | thorough description. The text up to the first blank line in a commit |
144 | message is treated as the commit title, and that title is used | |
2de9b711 | 145 | throughout Git. For example, linkgit:git-format-patch[1] turns a |
52ffe995 JW |
146 | commit into email, and it uses the title on the Subject line and the |
147 | rest of the commit in the body. | |
8c7fa247 | 148 | |
366bfcb6 NP |
149 | Git tracks content not files |
150 | ---------------------------- | |
151 | ||
483bc4f0 JN |
152 | Many revision control systems provide an `add` command that tells the |
153 | system to start tracking changes to a new file. Git's `add` command | |
0b444cdb | 154 | does something simpler and more powerful: 'git add' is used both for new |
93f9cc67 BF |
155 | and newly modified files, and in both cases it takes a snapshot of the |
156 | given files and stages that content in the index, ready for inclusion in | |
157 | the next commit. | |
8c7fa247 | 158 | |
23c9ccb2 BF |
159 | Viewing project history |
160 | ----------------------- | |
8c7fa247 | 161 | |
927a503c | 162 | At any point you can view the history of your changes using |
8c7fa247 | 163 | |
927a503c | 164 | ------------------------------------------------ |
67e6e5c4 | 165 | $ git log |
927a503c | 166 | ------------------------------------------------ |
8c7fa247 | 167 | |
927a503c | 168 | If you also want to see complete diffs at each step, use |
8c7fa247 | 169 | |
927a503c | 170 | ------------------------------------------------ |
67e6e5c4 | 171 | $ git log -p |
927a503c | 172 | ------------------------------------------------ |
8c7fa247 | 173 | |
c1d179f8 JH |
174 | Often the overview of the change is useful to get a feel of |
175 | each step | |
176 | ||
177 | ------------------------------------------------ | |
178 | $ git log --stat --summary | |
179 | ------------------------------------------------ | |
180 | ||
927a503c BF |
181 | Managing branches |
182 | ----------------- | |
2a29da7c | 183 | |
2de9b711 | 184 | A single Git repository can maintain multiple branches of |
927a503c | 185 | development. To create a new branch named "experimental", use |
8c7fa247 | 186 | |
927a503c BF |
187 | ------------------------------------------------ |
188 | $ git branch experimental | |
189 | ------------------------------------------------ | |
8c7fa247 | 190 | |
927a503c | 191 | If you now run |
8c7fa247 | 192 | |
927a503c BF |
193 | ------------------------------------------------ |
194 | $ git branch | |
195 | ------------------------------------------------ | |
8c7fa247 | 196 | |
927a503c | 197 | you'll get a list of all existing branches: |
8c7fa247 | 198 | |
8db9307c | 199 | ------------------------------------------------ |
927a503c BF |
200 | experimental |
201 | * master | |
8db9307c | 202 | ------------------------------------------------ |
8c7fa247 | 203 | |
927a503c BF |
204 | The "experimental" branch is the one you just created, and the |
205 | "master" branch is a default branch that was created for you | |
206 | automatically. The asterisk marks the branch you are currently on; | |
207 | type | |
8c7fa247 | 208 | |
927a503c | 209 | ------------------------------------------------ |
328c6cb8 | 210 | $ git switch experimental |
927a503c | 211 | ------------------------------------------------ |
8c7fa247 | 212 | |
927a503c BF |
213 | to switch to the experimental branch. Now edit a file, commit the |
214 | change, and switch back to the master branch: | |
8c7fa247 | 215 | |
927a503c BF |
216 | ------------------------------------------------ |
217 | (edit file) | |
218 | $ git commit -a | |
328c6cb8 | 219 | $ git switch master |
927a503c | 220 | ------------------------------------------------ |
8c7fa247 | 221 | |
927a503c BF |
222 | Check that the change you made is no longer visible, since it was |
223 | made on the experimental branch and you're back on the master branch. | |
8c7fa247 | 224 | |
927a503c | 225 | You can make a different change on the master branch: |
8c7fa247 | 226 | |
927a503c BF |
227 | ------------------------------------------------ |
228 | (edit file) | |
229 | $ git commit -a | |
230 | ------------------------------------------------ | |
8c7fa247 | 231 | |
927a503c | 232 | at this point the two branches have diverged, with different changes |
59427063 | 233 | made in each. To merge the changes made in experimental into master, run |
ed616049 | 234 | |
927a503c | 235 | ------------------------------------------------ |
c14261ea | 236 | $ git merge experimental |
927a503c BF |
237 | ------------------------------------------------ |
238 | ||
239 | If the changes don't conflict, you're done. If there are conflicts, | |
240 | markers will be left in the problematic files showing the conflict; | |
8c7fa247 | 241 | |
8db9307c | 242 | ------------------------------------------------ |
927a503c | 243 | $ git diff |
8db9307c | 244 | ------------------------------------------------ |
8c7fa247 | 245 | |
927a503c BF |
246 | will show this. Once you've edited the files to resolve the |
247 | conflicts, | |
8c7fa247 | 248 | |
8db9307c | 249 | ------------------------------------------------ |
927a503c | 250 | $ git commit -a |
8db9307c | 251 | ------------------------------------------------ |
8c7fa247 | 252 | |
927a503c | 253 | will commit the result of the merge. Finally, |
8c7fa247 | 254 | |
8db9307c | 255 | ------------------------------------------------ |
927a503c | 256 | $ gitk |
8db9307c | 257 | ------------------------------------------------ |
8c7fa247 | 258 | |
927a503c | 259 | will show a nice graphical representation of the resulting history. |
8c7fa247 | 260 | |
9c9410e1 SB |
261 | At this point you could delete the experimental branch with |
262 | ||
263 | ------------------------------------------------ | |
264 | $ git branch -d experimental | |
265 | ------------------------------------------------ | |
266 | ||
267 | This command ensures that the changes in the experimental branch are | |
268 | already in the current branch. | |
269 | ||
927a503c BF |
270 | If you develop on a branch crazy-idea, then regret it, you can always |
271 | delete the branch with | |
8c7fa247 | 272 | |
927a503c BF |
273 | ------------------------------------- |
274 | $ git branch -D crazy-idea | |
275 | ------------------------------------- | |
8c7fa247 | 276 | |
927a503c BF |
277 | Branches are cheap and easy, so this is a good way to try something |
278 | out. | |
8c7fa247 | 279 | |
2de9b711 | 280 | Using Git for collaboration |
927a503c | 281 | --------------------------- |
3eb5128a | 282 | |
2de9b711 | 283 | Suppose that Alice has started a new project with a Git repository in |
927a503c BF |
284 | /home/alice/project, and that Bob, who has a home directory on the |
285 | same machine, wants to contribute. | |
3eb5128a | 286 | |
927a503c | 287 | Bob begins with: |
3eb5128a | 288 | |
8db9307c | 289 | ------------------------------------------------ |
5d5e88af | 290 | bob$ git clone /home/alice/project myrepo |
8db9307c | 291 | ------------------------------------------------ |
3eb5128a | 292 | |
927a503c BF |
293 | This creates a new directory "myrepo" containing a clone of Alice's |
294 | repository. The clone is on an equal footing with the original | |
abda1ef5 | 295 | project, possessing its own copy of the original project's history. |
927a503c BF |
296 | |
297 | Bob then makes some changes and commits them: | |
ed616049 | 298 | |
927a503c BF |
299 | ------------------------------------------------ |
300 | (edit files) | |
5d5e88af | 301 | bob$ git commit -a |
927a503c BF |
302 | (repeat as necessary) |
303 | ------------------------------------------------ | |
ed616049 | 304 | |
927a503c BF |
305 | When he's ready, he tells Alice to pull changes from the repository |
306 | at /home/bob/myrepo. She does this with: | |
ed616049 | 307 | |
927a503c | 308 | ------------------------------------------------ |
5d5e88af IK |
309 | alice$ cd /home/alice/project |
310 | alice$ git pull /home/bob/myrepo master | |
927a503c | 311 | ------------------------------------------------ |
ed616049 | 312 | |
c1ff284a | 313 | This merges the changes from Bob's "master" branch into Alice's |
93ee7823 | 314 | current branch. If Alice has made her own changes in the meantime, |
c30e5673 | 315 | then she may need to manually fix any conflicts. |
2ae6c706 | 316 | |
93ee7823 BF |
317 | The "pull" command thus performs two operations: it fetches changes |
318 | from a remote branch, then merges them into the current branch. | |
2ae6c706 | 319 | |
dc29bc8b JH |
320 | Note that in general, Alice would want her local changes committed before |
321 | initiating this "pull". If Bob's work conflicts with what Alice did since | |
322 | their histories forked, Alice will use her working tree and the index to | |
323 | resolve conflicts, and existing local changes will interfere with the | |
2de9b711 | 324 | conflict resolution process (Git will still perform the fetch but will |
dc29bc8b JH |
325 | refuse to merge --- Alice will have to get rid of her local changes in |
326 | some way and pull again when this happens). | |
327 | ||
328 | Alice can peek at what Bob did without merging first, using the "fetch" | |
329 | command; this allows Alice to inspect what Bob did, using a special | |
330 | symbol "FETCH_HEAD", in order to determine if he has anything worth | |
331 | pulling, like this: | |
332 | ||
333 | ------------------------------------------------ | |
334 | alice$ git fetch /home/bob/myrepo master | |
53d1589f | 335 | alice$ git log -p HEAD..FETCH_HEAD |
dc29bc8b JH |
336 | ------------------------------------------------ |
337 | ||
338 | This operation is safe even if Alice has uncommitted local changes. | |
21d777f2 TLSC |
339 | The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable |
340 | from the FETCH_HEAD but exclude anything that is reachable from HEAD". | |
53d1589f | 341 | Alice already knows everything that leads to her current state (HEAD), |
21d777f2 TLSC |
342 | and reviews what Bob has in his state (FETCH_HEAD) that she has not |
343 | seen with this command. | |
53d1589f PC |
344 | |
345 | If Alice wants to visualize what Bob did since their histories forked | |
346 | she can issue the following command: | |
347 | ||
348 | ------------------------------------------------ | |
349 | $ gitk HEAD..FETCH_HEAD | |
350 | ------------------------------------------------ | |
351 | ||
352 | This uses the same two-dot range notation we saw earlier with 'git log'. | |
353 | ||
354 | Alice may want to view what both of them did since they forked. | |
355 | She can use three-dot form instead of the two-dot form: | |
356 | ||
357 | ------------------------------------------------ | |
358 | $ gitk HEAD...FETCH_HEAD | |
359 | ------------------------------------------------ | |
360 | ||
361 | This means "show everything that is reachable from either one, but | |
362 | exclude anything that is reachable from both of them". | |
363 | ||
364 | Please note that these range notation can be used with both gitk | |
365 | and "git log". | |
dc29bc8b JH |
366 | |
367 | After inspecting what Bob did, if there is nothing urgent, Alice may | |
368 | decide to continue working without pulling from Bob. If Bob's history | |
369 | does have something Alice would immediately need, Alice may choose to | |
370 | stash her work-in-progress first, do a "pull", and then finally unstash | |
371 | her work-in-progress on top of the resulting history. | |
372 | ||
c1ff284a JH |
373 | When you are working in a small closely knit group, it is not |
374 | unusual to interact with the same repository over and over | |
375 | again. By defining 'remote' repository shorthand, you can make | |
376 | it easier: | |
377 | ||
378 | ------------------------------------------------ | |
5d5e88af | 379 | alice$ git remote add bob /home/bob/myrepo |
c1ff284a JH |
380 | ------------------------------------------------ |
381 | ||
21d777f2 | 382 | With this, Alice can perform the first part of the "pull" operation |
0b444cdb | 383 | alone using the 'git fetch' command without merging them with her own |
21d777f2 | 384 | branch, using: |
2a29da7c | 385 | |
927a503c | 386 | ------------------------------------- |
5d5e88af | 387 | alice$ git fetch bob |
927a503c | 388 | ------------------------------------- |
2a29da7c | 389 | |
c1ff284a | 390 | Unlike the longhand form, when Alice fetches from Bob using a |
0b444cdb | 391 | remote repository shorthand set up with 'git remote', what was |
0e615b25 | 392 | fetched is stored in a remote-tracking branch, in this case |
c1ff284a | 393 | `bob/master`. So after this: |
a7333f9e | 394 | |
927a503c | 395 | ------------------------------------- |
5d5e88af | 396 | alice$ git log -p master..bob/master |
927a503c | 397 | ------------------------------------- |
a7333f9e | 398 | |
927a503c BF |
399 | shows a list of all the changes that Bob made since he branched from |
400 | Alice's master branch. | |
a7333f9e | 401 | |
c1ff284a | 402 | After examining those changes, Alice |
c14261ea | 403 | could merge the changes into her master branch: |
ed616049 | 404 | |
927a503c | 405 | ------------------------------------- |
5d5e88af | 406 | alice$ git merge bob/master |
927a503c | 407 | ------------------------------------- |
ed616049 | 408 | |
60109d0e MM |
409 | This `merge` can also be done by 'pulling from her own remote-tracking |
410 | branch', like this: | |
93ee7823 BF |
411 | |
412 | ------------------------------------- | |
5d5e88af | 413 | alice$ git pull . remotes/bob/master |
93ee7823 BF |
414 | ------------------------------------- |
415 | ||
c1ff284a | 416 | Note that git pull always merges into the current branch, |
02783075 | 417 | regardless of what else is given on the command line. |
93ee7823 | 418 | |
927a503c | 419 | Later, Bob can update his repo with Alice's latest changes using |
ed616049 | 420 | |
927a503c | 421 | ------------------------------------- |
5d5e88af | 422 | bob$ git pull |
927a503c | 423 | ------------------------------------- |
ed616049 | 424 | |
927a503c | 425 | Note that he doesn't need to give the path to Alice's repository; |
2de9b711 | 426 | when Bob cloned Alice's repository, Git stored the location of her |
d66409f0 BF |
427 | repository in the repository configuration, and that location is |
428 | used for pulls: | |
2a29da7c | 429 | |
927a503c | 430 | ------------------------------------- |
5d5e88af | 431 | bob$ git config --get remote.origin.url |
8960b5a7 | 432 | /home/alice/project |
927a503c | 433 | ------------------------------------- |
2a29da7c | 434 | |
0b444cdb | 435 | (The complete configuration created by 'git clone' is visible using |
483bc4f0 | 436 | `git config -l`, and the linkgit:git-config[1] man page |
d66409f0 BF |
437 | explains the meaning of each option.) |
438 | ||
439 | Git also keeps a pristine copy of Alice's master branch under the | |
440 | name "origin/master": | |
441 | ||
442 | ------------------------------------- | |
5d5e88af | 443 | bob$ git branch -r |
d66409f0 BF |
444 | origin/master |
445 | ------------------------------------- | |
2a29da7c | 446 | |
927a503c BF |
447 | If Bob later decides to work from a different host, he can still |
448 | perform clones and pulls using the ssh protocol: | |
2a29da7c | 449 | |
927a503c | 450 | ------------------------------------- |
5d5e88af | 451 | bob$ git clone alice.org:/home/alice/project myrepo |
927a503c | 452 | ------------------------------------- |
2a29da7c | 453 | |
0d0bac67 | 454 | Alternatively, Git has a native protocol, or can use http; |
5162e697 | 455 | see linkgit:git-pull[1] for details. |
0c04094b | 456 | |
927a503c | 457 | Git can also be used in a CVS-like mode, with a central repository |
5162e697 | 458 | that various users push changes to; see linkgit:git-push[1] and |
6998e4db | 459 | linkgit:gitcvs-migration[7]. |
0c04094b | 460 | |
f1fe3846 BF |
461 | Exploring history |
462 | ----------------- | |
0c04094b | 463 | |
f1fe3846 | 464 | Git history is represented as a series of interrelated commits. We |
0b444cdb | 465 | have already seen that the 'git log' command can list those commits. |
f1fe3846 BF |
466 | Note that first line of each git log entry also gives a name for the |
467 | commit: | |
c9517341 | 468 | |
927a503c | 469 | ------------------------------------- |
f1fe3846 BF |
470 | $ git log |
471 | commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 | |
472 | Author: Junio C Hamano <junkio@cox.net> | |
473 | Date: Tue May 16 17:18:22 2006 -0700 | |
474 | ||
475 | merge-base: Clarify the comments on post processing. | |
927a503c | 476 | ------------------------------------- |
0c04094b | 477 | |
0b444cdb | 478 | We can give this name to 'git show' to see the details about this |
f1fe3846 | 479 | commit. |
0c04094b | 480 | |
927a503c | 481 | ------------------------------------- |
f1fe3846 | 482 | $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 |
927a503c | 483 | ------------------------------------- |
0c04094b | 484 | |
c1d179f8 | 485 | But there are other ways to refer to commits. You can use any initial |
f1fe3846 | 486 | part of the name that is long enough to uniquely identify the commit: |
0c04094b | 487 | |
f1fe3846 BF |
488 | ------------------------------------- |
489 | $ git show c82a22c39c # the first few characters of the name are | |
490 | # usually enough | |
491 | $ git show HEAD # the tip of the current branch | |
492 | $ git show experimental # the tip of the "experimental" branch | |
493 | ------------------------------------- | |
494 | ||
9c9410e1 SB |
495 | Every commit usually has one "parent" commit |
496 | which points to the previous state of the project: | |
0c04094b | 497 | |
927a503c | 498 | ------------------------------------- |
f1fe3846 BF |
499 | $ git show HEAD^ # to see the parent of HEAD |
500 | $ git show HEAD^^ # to see the grandparent of HEAD | |
501 | $ git show HEAD~4 # to see the great-great grandparent of HEAD | |
927a503c | 502 | ------------------------------------- |
e7c1ca42 | 503 | |
f1fe3846 BF |
504 | Note that merge commits may have more than one parent: |
505 | ||
506 | ------------------------------------- | |
507 | $ git show HEAD^1 # show the first parent of HEAD (same as HEAD^) | |
508 | $ git show HEAD^2 # show the second parent of HEAD | |
509 | ------------------------------------- | |
44760f1d | 510 | |
f1fe3846 | 511 | You can also give commits names of your own; after running |
3eb5128a | 512 | |
927a503c | 513 | ------------------------------------- |
b1889c36 | 514 | $ git tag v2.5 1b2e1d63ff |
927a503c | 515 | ------------------------------------- |
3eb5128a | 516 | |
f1fe3846 BF |
517 | you can refer to 1b2e1d63ff by the name "v2.5". If you intend to |
518 | share this name with other people (for example, to identify a release | |
519 | version), you should create a "tag" object, and perhaps sign it; see | |
5162e697 | 520 | linkgit:git-tag[1] for details. |
f1fe3846 | 521 | |
2de9b711 | 522 | Any Git command that needs to know a commit can take any of these |
f1fe3846 | 523 | names. For example: |
3eb5128a | 524 | |
927a503c | 525 | ------------------------------------- |
f1fe3846 BF |
526 | $ git diff v2.5 HEAD # compare the current HEAD to v2.5 |
527 | $ git branch stable v2.5 # start a new branch named "stable" based | |
528 | # at v2.5 | |
529 | $ git reset --hard HEAD^ # reset your current branch and working | |
37425065 | 530 | # directory to its state at HEAD^ |
927a503c | 531 | ------------------------------------- |
c9517341 | 532 | |
f1fe3846 BF |
533 | Be careful with that last command: in addition to losing any changes |
534 | in the working directory, it will also remove all later commits from | |
535 | this branch. If this branch is the only branch containing those | |
0b444cdb | 536 | commits, they will be lost. Also, don't use 'git reset' on a |
a9d1836b JH |
537 | publicly-visible branch that other developers pull from, as it will |
538 | force needless merges on other developers to clean up the history. | |
0b444cdb | 539 | If you need to undo changes that you have pushed, use 'git revert' |
6e2e1cfb | 540 | instead. |
c9517341 | 541 | |
0b444cdb | 542 | The 'git grep' command can search for strings in any version of your |
f1fe3846 | 543 | project, so |
c9517341 | 544 | |
927a503c | 545 | ------------------------------------- |
f1fe3846 | 546 | $ git grep "hello" v2.5 |
927a503c | 547 | ------------------------------------- |
c9517341 | 548 | |
abda1ef5 | 549 | searches for all occurrences of "hello" in v2.5. |
2a29da7c | 550 | |
0b444cdb | 551 | If you leave out the commit name, 'git grep' will search any of the |
f1fe3846 | 552 | files it manages in your current directory. So |
2a29da7c | 553 | |
927a503c | 554 | ------------------------------------- |
f1fe3846 | 555 | $ git grep "hello" |
dc5f9239 JH |
556 | ------------------------------------- |
557 | ||
2de9b711 | 558 | is a quick way to search just the files that are tracked by Git. |
927a503c | 559 | |
2de9b711 | 560 | Many Git commands also take sets of commits, which can be specified |
0b444cdb | 561 | in a number of ways. Here are some examples with 'git log': |
927a503c BF |
562 | |
563 | ------------------------------------- | |
f1fe3846 BF |
564 | $ git log v2.5..v2.6 # commits between v2.5 and v2.6 |
565 | $ git log v2.5.. # commits since v2.5 | |
566 | $ git log --since="2 weeks ago" # commits from the last 2 weeks | |
567 | $ git log v2.5.. Makefile # commits since v2.5 which modify | |
568 | # Makefile | |
927a503c | 569 | ------------------------------------- |
6f60300b | 570 | |
0b444cdb | 571 | You can also give 'git log' a "range" of commits where the first is not |
f1fe3846 | 572 | necessarily an ancestor of the second; for example, if the tips of |
21d777f2 | 573 | the branches "stable" and "master" diverged from a common |
f1fe3846 BF |
574 | commit some time ago, then |
575 | ||
576 | ------------------------------------- | |
21d777f2 | 577 | $ git log stable..master |
f1fe3846 BF |
578 | ------------------------------------- |
579 | ||
21d777f2 | 580 | will list commits made in the master branch but not in the |
f1fe3846 BF |
581 | stable branch, while |
582 | ||
583 | ------------------------------------- | |
21d777f2 | 584 | $ git log master..stable |
f1fe3846 BF |
585 | ------------------------------------- |
586 | ||
587 | will show the list of commits made on the stable branch but not | |
21d777f2 | 588 | the master branch. |
f1fe3846 | 589 | |
0b444cdb | 590 | The 'git log' command has a weakness: it must present commits in a |
f1fe3846 | 591 | list. When the history has lines of development that diverged and |
0b444cdb | 592 | then merged back together, the order in which 'git log' presents |
f1fe3846 BF |
593 | those commits is meaningless. |
594 | ||
c7719fbe | 595 | Most projects with multiple contributors (such as the Linux kernel, |
2de9b711 | 596 | or Git itself) have frequent merges, and 'gitk' does a better job of |
f1fe3846 BF |
597 | visualizing their history. For example, |
598 | ||
599 | ------------------------------------- | |
600 | $ gitk --since="2 weeks ago" drivers/ | |
601 | ------------------------------------- | |
602 | ||
603 | allows you to browse any commits from the last 2 weeks of commits | |
2be1bc48 BF |
604 | that modified files under the "drivers" directory. (Note: you can |
605 | adjust gitk's fonts by holding down the control key while pressing | |
606 | "-" or "+".) | |
f1fe3846 BF |
607 | |
608 | Finally, most commands that take filenames will optionally allow you | |
609 | to precede any filename by a commit, to specify a particular version | |
38573864 | 610 | of the file: |
f1fe3846 BF |
611 | |
612 | ------------------------------------- | |
613 | $ git diff v2.5:Makefile HEAD:Makefile.in | |
614 | ------------------------------------- | |
927a503c | 615 | |
0b444cdb | 616 | You can also use 'git show' to see any such file: |
38573864 BF |
617 | |
618 | ------------------------------------- | |
9c9410e1 | 619 | $ git show v2.5:Makefile |
38573864 BF |
620 | ------------------------------------- |
621 | ||
927a503c BF |
622 | Next Steps |
623 | ---------- | |
624 | ||
e31952da BF |
625 | This tutorial should be enough to perform basic distributed revision |
626 | control for your projects. However, to fully understand the depth | |
2de9b711 | 627 | and power of Git you need to understand two simple ideas on which it |
e31952da BF |
628 | is based: |
629 | ||
630 | * The object database is the rather elegant system used to | |
631 | store the history of your project--files, directories, and | |
632 | commits. | |
633 | ||
634 | * The index file is a cache of the state of a directory tree, | |
635 | used to create commits, check out working directories, and | |
636 | hold the various trees involved in a merge. | |
637 | ||
6998e4db | 638 | Part two of this tutorial explains the object |
e31952da | 639 | database, the index file, and a few other odds and ends that you'll |
2de9b711 | 640 | need to make the most of Git. You can find it at linkgit:gittutorial-2[7]. |
e31952da | 641 | |
cd50aba9 | 642 | If you don't want to continue with that right away, a few other |
e31952da | 643 | digressions that may be interesting at this point are: |
927a503c | 644 | |
5162e697 | 645 | * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert |
927a503c | 646 | series of git commits into emailed patches, and vice versa, |
c7719fbe | 647 | useful for projects such as the Linux kernel which rely heavily |
927a503c BF |
648 | on emailed patches. |
649 | ||
5162e697 | 650 | * linkgit:git-bisect[1]: When there is a regression in your |
927a503c BF |
651 | project, one way to track down the bug is by searching through |
652 | the history to find the exact commit that's to blame. Git bisect | |
653 | can help you perform a binary search for that commit. It is | |
654 | smart enough to perform a close-to-optimal search even in the | |
655 | case of complex non-linear history with lots of merged branches. | |
656 | ||
801a011d TR |
657 | * linkgit:gitworkflows[7]: Gives an overview of recommended |
658 | workflows. | |
659 | ||
673151a9 | 660 | * linkgit:giteveryday[7]: Everyday Git with 20 Commands Or So. |
e31952da | 661 | |
6998e4db | 662 | * linkgit:gitcvs-migration[7]: Git for CVS users. |
b27a23e3 CC |
663 | |
664 | SEE ALSO | |
665 | -------- | |
666 | linkgit:gittutorial-2[7], | |
667 | linkgit:gitcvs-migration[7], | |
497c8331 CC |
668 | linkgit:gitcore-tutorial[7], |
669 | linkgit:gitglossary[7], | |
6e702c24 | 670 | linkgit:git-help[1], |
801a011d | 671 | linkgit:gitworkflows[7], |
673151a9 | 672 | linkgit:giteveryday[7], |
b27a23e3 CC |
673 | link:user-manual.html[The Git User's Manual] |
674 | ||
675 | GIT | |
676 | --- | |
941b9c52 | 677 | Part of the linkgit:git[1] suite |