]>
Commit | Line | Data |
---|---|---|
927a503c BF |
1 | A tutorial introduction to git |
2 | ============================== | |
8c7fa247 | 3 | |
927a503c BF |
4 | This tutorial explains how to import a new project into git, make |
5 | changes to it, and share changes with other developers. | |
8c7fa247 | 6 | |
927a503c BF |
7 | First, note that you can get documentation for a command such as "git |
8 | diff" with: | |
8c7fa247 | 9 | |
927a503c BF |
10 | ------------------------------------------------ |
11 | $ man git-diff | |
12 | ------------------------------------------------ | |
8c7fa247 | 13 | |
927a503c BF |
14 | Importing a new project |
15 | ----------------------- | |
8c7fa247 | 16 | |
927a503c BF |
17 | Assume you have a tarball project.tar.gz with your initial work. You |
18 | can place it under git revision control as follows. | |
8c7fa247 | 19 | |
8db9307c | 20 | ------------------------------------------------ |
dcc6e28f | 21 | $ tar xzf project.tar.gz |
927a503c BF |
22 | $ cd project |
23 | $ git init-db | |
8db9307c | 24 | ------------------------------------------------ |
8c7fa247 | 25 | |
927a503c | 26 | Git will reply |
8c7fa247 | 27 | |
927a503c | 28 | ------------------------------------------------ |
f2416c27 | 29 | defaulting to local storage area |
927a503c | 30 | ------------------------------------------------ |
8c7fa247 | 31 | |
927a503c BF |
32 | You've now initialized the working directory--you may notice a new |
33 | directory created, named ".git". Tell git that you want it to track | |
34 | every file under the current directory with | |
8c7fa247 | 35 | |
8db9307c | 36 | ------------------------------------------------ |
927a503c | 37 | $ git add . |
8db9307c | 38 | ------------------------------------------------ |
8c7fa247 | 39 | |
927a503c | 40 | Finally, |
8c7fa247 | 41 | |
927a503c BF |
42 | ------------------------------------------------ |
43 | $ git commit -a | |
44 | ------------------------------------------------ | |
8c7fa247 | 45 | |
927a503c BF |
46 | will prompt you for a commit message, then record the current state |
47 | of all the files to the repository. | |
8c7fa247 | 48 | |
927a503c | 49 | Try modifying some files, then run |
8c7fa247 | 50 | |
8db9307c | 51 | ------------------------------------------------ |
927a503c | 52 | $ git diff |
8db9307c | 53 | ------------------------------------------------ |
8c7fa247 | 54 | |
927a503c | 55 | to review your changes. When you're done, |
8c7fa247 | 56 | |
927a503c BF |
57 | ------------------------------------------------ |
58 | $ git commit -a | |
59 | ------------------------------------------------ | |
f2416c27 | 60 | |
927a503c BF |
61 | will again prompt your for a message describing the change, and then |
62 | record the new versions of the modified files. | |
8c7fa247 | 63 | |
927a503c BF |
64 | A note on commit messages: Though not required, it's a good idea to |
65 | begin the commit message with a single short (less than 50 character) | |
66 | line summarizing the change, followed by a blank line and then a more | |
67 | thorough description. Tools that turn commits into email, for | |
68 | example, use the first line on the Subject line and the rest of the | |
69 | commit in the body. | |
8c7fa247 | 70 | |
927a503c | 71 | To add a new file, first create the file, then |
8c7fa247 | 72 | |
927a503c BF |
73 | ------------------------------------------------ |
74 | $ git add path/to/new/file | |
75 | ------------------------------------------------ | |
8c7fa247 | 76 | |
927a503c BF |
77 | then commit as usual. No special command is required when removing a |
78 | file; just remove it, then commit. | |
8c7fa247 | 79 | |
927a503c | 80 | At any point you can view the history of your changes using |
8c7fa247 | 81 | |
927a503c | 82 | ------------------------------------------------ |
67e6e5c4 | 83 | $ git log |
927a503c | 84 | ------------------------------------------------ |
8c7fa247 | 85 | |
927a503c | 86 | If you also want to see complete diffs at each step, use |
8c7fa247 | 87 | |
927a503c | 88 | ------------------------------------------------ |
67e6e5c4 | 89 | $ git log -p |
927a503c | 90 | ------------------------------------------------ |
8c7fa247 | 91 | |
927a503c BF |
92 | Managing branches |
93 | ----------------- | |
2a29da7c | 94 | |
927a503c BF |
95 | A single git repository can maintain multiple branches of |
96 | development. To create a new branch named "experimental", use | |
8c7fa247 | 97 | |
927a503c BF |
98 | ------------------------------------------------ |
99 | $ git branch experimental | |
100 | ------------------------------------------------ | |
8c7fa247 | 101 | |
927a503c | 102 | If you now run |
8c7fa247 | 103 | |
927a503c BF |
104 | ------------------------------------------------ |
105 | $ git branch | |
106 | ------------------------------------------------ | |
8c7fa247 | 107 | |
927a503c | 108 | you'll get a list of all existing branches: |
8c7fa247 | 109 | |
8db9307c | 110 | ------------------------------------------------ |
927a503c BF |
111 | experimental |
112 | * master | |
8db9307c | 113 | ------------------------------------------------ |
8c7fa247 | 114 | |
927a503c BF |
115 | The "experimental" branch is the one you just created, and the |
116 | "master" branch is a default branch that was created for you | |
117 | automatically. The asterisk marks the branch you are currently on; | |
118 | type | |
8c7fa247 | 119 | |
927a503c BF |
120 | ------------------------------------------------ |
121 | $ git checkout experimental | |
122 | ------------------------------------------------ | |
8c7fa247 | 123 | |
927a503c BF |
124 | to switch to the experimental branch. Now edit a file, commit the |
125 | change, and switch back to the master branch: | |
8c7fa247 | 126 | |
927a503c BF |
127 | ------------------------------------------------ |
128 | (edit file) | |
129 | $ git commit -a | |
130 | $ git checkout master | |
131 | ------------------------------------------------ | |
8c7fa247 | 132 | |
927a503c BF |
133 | Check that the change you made is no longer visible, since it was |
134 | made on the experimental branch and you're back on the master branch. | |
8c7fa247 | 135 | |
927a503c | 136 | You can make a different change on the master branch: |
8c7fa247 | 137 | |
927a503c BF |
138 | ------------------------------------------------ |
139 | (edit file) | |
140 | $ git commit -a | |
141 | ------------------------------------------------ | |
8c7fa247 | 142 | |
927a503c BF |
143 | at this point the two branches have diverged, with different changes |
144 | made in each. To merge the changes made in the two branches, run | |
ed616049 | 145 | |
927a503c BF |
146 | ------------------------------------------------ |
147 | $ git pull . experimental | |
148 | ------------------------------------------------ | |
149 | ||
150 | If the changes don't conflict, you're done. If there are conflicts, | |
151 | markers will be left in the problematic files showing the conflict; | |
8c7fa247 | 152 | |
8db9307c | 153 | ------------------------------------------------ |
927a503c | 154 | $ git diff |
8db9307c | 155 | ------------------------------------------------ |
8c7fa247 | 156 | |
927a503c BF |
157 | will show this. Once you've edited the files to resolve the |
158 | conflicts, | |
8c7fa247 | 159 | |
8db9307c | 160 | ------------------------------------------------ |
927a503c | 161 | $ git commit -a |
8db9307c | 162 | ------------------------------------------------ |
8c7fa247 | 163 | |
927a503c | 164 | will commit the result of the merge. Finally, |
8c7fa247 | 165 | |
8db9307c | 166 | ------------------------------------------------ |
927a503c | 167 | $ gitk |
8db9307c | 168 | ------------------------------------------------ |
8c7fa247 | 169 | |
927a503c | 170 | will show a nice graphical representation of the resulting history. |
8c7fa247 | 171 | |
927a503c BF |
172 | If you develop on a branch crazy-idea, then regret it, you can always |
173 | delete the branch with | |
8c7fa247 | 174 | |
927a503c BF |
175 | ------------------------------------- |
176 | $ git branch -D crazy-idea | |
177 | ------------------------------------- | |
8c7fa247 | 178 | |
927a503c BF |
179 | Branches are cheap and easy, so this is a good way to try something |
180 | out. | |
8c7fa247 | 181 | |
927a503c BF |
182 | Using git for collaboration |
183 | --------------------------- | |
3eb5128a | 184 | |
927a503c BF |
185 | Suppose that Alice has started a new project with a git repository in |
186 | /home/alice/project, and that Bob, who has a home directory on the | |
187 | same machine, wants to contribute. | |
3eb5128a | 188 | |
927a503c | 189 | Bob begins with: |
3eb5128a | 190 | |
8db9307c | 191 | ------------------------------------------------ |
927a503c | 192 | $ git clone /home/alice/project myrepo |
8db9307c | 193 | ------------------------------------------------ |
3eb5128a | 194 | |
927a503c BF |
195 | This creates a new directory "myrepo" containing a clone of Alice's |
196 | repository. The clone is on an equal footing with the original | |
197 | project, posessing its own copy of the original project's history. | |
198 | ||
199 | Bob then makes some changes and commits them: | |
ed616049 | 200 | |
927a503c BF |
201 | ------------------------------------------------ |
202 | (edit files) | |
203 | $ git commit -a | |
204 | (repeat as necessary) | |
205 | ------------------------------------------------ | |
ed616049 | 206 | |
927a503c BF |
207 | When he's ready, he tells Alice to pull changes from the repository |
208 | at /home/bob/myrepo. She does this with: | |
ed616049 | 209 | |
927a503c BF |
210 | ------------------------------------------------ |
211 | $ cd /home/alice/project | |
212 | $ git pull /home/bob/myrepo | |
213 | ------------------------------------------------ | |
ed616049 | 214 | |
927a503c BF |
215 | This actually pulls changes from the branch in Bob's repository named |
216 | "master". Alice could request a different branch by adding the name | |
217 | of the branch to the end of the git pull command line. | |
2ae6c706 | 218 | |
67e6e5c4 | 219 | This merges Bob's changes into her repository; "git log" will |
927a503c BF |
220 | now show the new commits. If Alice has made her own changes in the |
221 | meantime, then Bob's changes will be merged in, and she will need to | |
222 | manually fix any conflicts. | |
2ae6c706 | 223 | |
927a503c BF |
224 | A more cautious Alice might wish to examine Bob's changes before |
225 | pulling them. She can do this by creating a temporary branch just | |
226 | for the purpose of studying Bob's changes: | |
2a29da7c | 227 | |
927a503c BF |
228 | ------------------------------------- |
229 | $ git fetch /home/bob/myrepo master:bob-incoming | |
230 | ------------------------------------- | |
2a29da7c | 231 | |
927a503c BF |
232 | which fetches the changes from Bob's master branch into a new branch |
233 | named bob-incoming. (Unlike git pull, git fetch just fetches a copy | |
234 | of Bob's line of development without doing any merging). Then | |
a7333f9e | 235 | |
927a503c | 236 | ------------------------------------- |
67e6e5c4 | 237 | $ git log -p master..bob-incoming |
927a503c | 238 | ------------------------------------- |
a7333f9e | 239 | |
927a503c BF |
240 | shows a list of all the changes that Bob made since he branched from |
241 | Alice's master branch. | |
a7333f9e | 242 | |
927a503c BF |
243 | After examing those changes, and possibly fixing things, Alice can |
244 | pull the changes into her master branch: | |
ed616049 | 245 | |
927a503c BF |
246 | ------------------------------------- |
247 | $ git checkout master | |
248 | $ git pull . bob-incoming | |
249 | ------------------------------------- | |
ed616049 | 250 | |
927a503c BF |
251 | The last command is a pull from the "bob-incoming" branch in Alice's |
252 | own repository. | |
ed616049 | 253 | |
927a503c | 254 | Later, Bob can update his repo with Alice's latest changes using |
ed616049 | 255 | |
927a503c BF |
256 | ------------------------------------- |
257 | $ git pull | |
258 | ------------------------------------- | |
ed616049 | 259 | |
927a503c BF |
260 | Note that he doesn't need to give the path to Alice's repository; |
261 | when Bob cloned Alice's repository, git stored the location of her | |
262 | repository in the file .git/remotes/origin, and that location is used | |
263 | as the default for pulls. | |
ed616049 | 264 | |
927a503c | 265 | Bob may also notice a branch in his repository that he didn't create: |
2a29da7c | 266 | |
927a503c BF |
267 | ------------------------------------- |
268 | $ git branch | |
269 | * master | |
270 | origin | |
271 | ------------------------------------- | |
2a29da7c | 272 | |
927a503c BF |
273 | The "origin" branch, which was created automatically by "git clone", |
274 | is a pristine copy of Alice's master branch; Bob should never commit | |
275 | to it. | |
2a29da7c | 276 | |
927a503c BF |
277 | If Bob later decides to work from a different host, he can still |
278 | perform clones and pulls using the ssh protocol: | |
2a29da7c | 279 | |
927a503c BF |
280 | ------------------------------------- |
281 | $ git clone alice.org:/home/alice/project myrepo | |
282 | ------------------------------------- | |
2a29da7c | 283 | |
927a503c BF |
284 | Alternatively, git has a native protocol, or can use rsync or http; |
285 | see gitlink:git-pull[1] for details. | |
0c04094b | 286 | |
927a503c BF |
287 | Git can also be used in a CVS-like mode, with a central repository |
288 | that various users push changes to; see gitlink:git-push[1] and | |
289 | link:cvs-migration.html[git for CVS users]. | |
0c04094b | 290 | |
927a503c BF |
291 | Keeping track of history |
292 | ------------------------ | |
0c04094b | 293 | |
927a503c BF |
294 | Git history is represented as a series of interrelated commits. The |
295 | most recent commit in the currently checked-out branch can always be | |
296 | referred to as HEAD, and the "parent" of any commit can always be | |
297 | referred to by appending a caret, "^", to the end of the name of the | |
298 | commit. So, for example, | |
c9517341 | 299 | |
927a503c BF |
300 | ------------------------------------- |
301 | git diff HEAD^ HEAD | |
302 | ------------------------------------- | |
0c04094b | 303 | |
927a503c BF |
304 | shows the difference between the most-recently checked-in state of |
305 | the tree and the previous state, and | |
0c04094b | 306 | |
927a503c BF |
307 | ------------------------------------- |
308 | git diff HEAD^^ HEAD^ | |
309 | ------------------------------------- | |
0c04094b | 310 | |
927a503c | 311 | shows the difference between that previous state and the state two |
2eb063c9 | 312 | commits ago. Also, HEAD~5 can be used as a shorthand for HEAD{caret}{caret}{caret}{caret}{caret}, |
927a503c BF |
313 | and more generally HEAD~n can refer to the nth previous commit. |
314 | Commits representing merges have more than one parent, and you can | |
315 | specify which parent to follow in that case; see | |
316 | gitlink:git-rev-parse[1]. | |
0c04094b | 317 | |
927a503c BF |
318 | The name of a branch can also be used to refer to the most recent |
319 | commit on that branch; so you can also say things like | |
0c04094b | 320 | |
927a503c BF |
321 | ------------------------------------- |
322 | git diff HEAD experimental | |
323 | ------------------------------------- | |
e7c1ca42 | 324 | |
927a503c BF |
325 | to see the difference between the most-recently committed tree in |
326 | the current branch and the most-recently committed tree in the | |
327 | experimental branch. | |
44760f1d | 328 | |
927a503c BF |
329 | But you may find it more useful to see the list of commits made in |
330 | the experimental branch but not in the current branch, and | |
3eb5128a | 331 | |
927a503c | 332 | ------------------------------------- |
67e6e5c4 | 333 | git log HEAD..experimental |
927a503c | 334 | ------------------------------------- |
3eb5128a | 335 | |
927a503c | 336 | will do that, just as |
3eb5128a | 337 | |
927a503c | 338 | ------------------------------------- |
67e6e5c4 | 339 | git log experimental..HEAD |
927a503c | 340 | ------------------------------------- |
c9517341 | 341 | |
927a503c BF |
342 | will show the list of commits made on the HEAD but not included in |
343 | experimental. | |
c9517341 | 344 | |
927a503c | 345 | You can also give commits convenient names of your own: after running |
c9517341 | 346 | |
927a503c BF |
347 | ------------------------------------- |
348 | $ git-tag v2.5 HEAD^^ | |
349 | ------------------------------------- | |
c9517341 | 350 | |
927a503c BF |
351 | you can refer to HEAD^^ by the name "v2.5". If you intend to share |
352 | this name with other people (for example, to identify a release | |
353 | version), you should create a "tag" object, and perhaps sign it; see | |
354 | gitlink:git-tag[1] for details. | |
2a29da7c | 355 | |
927a503c BF |
356 | You can revisit the old state of a tree, and make further |
357 | modifications if you wish, using git branch: the command | |
2a29da7c | 358 | |
927a503c BF |
359 | ------------------------------------- |
360 | $ git branch stable-release v2.5 | |
dc5f9239 JH |
361 | ------------------------------------- |
362 | ||
927a503c BF |
363 | will create a new branch named "stable-release" starting from the |
364 | commit which you tagged with the name v2.5. | |
365 | ||
366 | You can reset the state of any branch to an earlier commit at any | |
367 | time with | |
368 | ||
369 | ------------------------------------- | |
370 | $ git reset --hard v2.5 | |
371 | ------------------------------------- | |
6f60300b | 372 | |
927a503c BF |
373 | This will remove all later commits from this branch and reset the |
374 | working tree to the state it had when the given commit was made. If | |
375 | this branch is the only branch containing the later commits, those | |
376 | later changes will be lost. Don't use "git reset" on a | |
377 | publicly-visible branch that other developers pull from, as git will | |
378 | be confused by history that disappears in this way. | |
379 | ||
380 | Next Steps | |
381 | ---------- | |
382 | ||
383 | Some good commands to explore next: | |
384 | ||
385 | * gitlink:git-diff[1]: This flexible command does much more than | |
386 | we've seen in the few examples above. | |
387 | ||
388 | * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert | |
389 | series of git commits into emailed patches, and vice versa, | |
390 | useful for projects such as the linux kernel which rely heavily | |
391 | on emailed patches. | |
392 | ||
393 | * gitlink:git-bisect[1]: When there is a regression in your | |
394 | project, one way to track down the bug is by searching through | |
395 | the history to find the exact commit that's to blame. Git bisect | |
396 | can help you perform a binary search for that commit. It is | |
397 | smart enough to perform a close-to-optimal search even in the | |
398 | case of complex non-linear history with lots of merged branches. | |
399 | ||
400 | Other good starting points include link:everyday.html[Everday GIT | |
401 | with 20 Commands Or So] and link:cvs-migration.html[git for CVS | |
402 | users]. Also, link:core-tutorial.html[A short git tutorial] gives an | |
403 | introduction to lower-level git commands for advanced users and | |
404 | developers. |