1GITTUTORIAL(7)                    Git Manual                    GITTUTORIAL(7)
2
3
4

NAME

6       gittutorial - A tutorial introduction to git (for version 1.5.1 or
7       newer)
8

SYNOPSIS

10       git *
11

DESCRIPTION

13       This tutorial explains how to import a new project into git, make
14       changes to it, and share changes with other developers.
15
16       If you are instead primarily interested in using git to fetch a
17       project, for example, to test the latest version, you may prefer to
18       start with the first two chapters of The Git User’s Manual[1].
19
20       First, note that you can get documentation for a command such as git
21       log --graph with:
22
23           $ man git-log
24
25
26       or:
27
28           $ git help log
29
30
31       With the latter, you can use the manual viewer of your choice; see git-
32       help(1) for more information.
33
34       It is a good idea to introduce yourself to git with your name and
35       public email address before doing any operation. The easiest way to do
36       so is:
37
38           $ git config --global user.name "Your Name Comes Here"
39           $ git config --global user.email you@yourdomain.example.com
40
41

IMPORTING A NEW PROJECT

43       Assume you have a tarball project.tar.gz with your initial work. You
44       can place it under git revision control as follows.
45
46           $ tar xzf project.tar.gz
47           $ cd project
48           $ git init
49
50
51       Git will reply
52
53           Initialized empty Git repository in .git/
54
55
56       You’ve now initialized the working directory—you may notice a new
57       directory created, named ".git".
58
59       Next, tell git to take a snapshot of the contents of all files under
60       the current directory (note the .), with git add:
61
62           $ git add .
63
64
65       This snapshot is now stored in a temporary staging area which git calls
66       the "index". You can permanently store the contents of the index in the
67       repository with git commit:
68
69           $ git commit
70
71
72       This will prompt you for a commit message. You’ve now stored the first
73       version of your project in git.
74

MAKING CHANGES

76       Modify some files, then add their updated contents to the index:
77
78           $ git add file1 file2 file3
79
80
81       You are now ready to commit. You can see what is about to be committed
82       using git diff with the --cached option:
83
84           $ git diff --cached
85
86
87       (Without --cached, git diff will show you any changes that you’ve made
88       but not yet added to the index.) You can also get a brief summary of
89       the situation with git status:
90
91           $ git status
92           # On branch master
93           # Changes to be committed:
94           #   (use "git reset HEAD <file>..." to unstage)
95           #
96           #       modified:   file1
97           #       modified:   file2
98           #       modified:   file3
99           #
100
101
102       If you need to make any further adjustments, do so now, and then add
103       any newly modified content to the index. Finally, commit your changes
104       with:
105
106           $ git commit
107
108
109       This will again prompt you for a message describing the change, and
110       then record a new version of the project.
111
112       Alternatively, instead of running git add beforehand, you can use
113
114           $ git commit -a
115
116
117       which will automatically notice any modified (but not new) files, add
118       them to the index, and commit, all in one step.
119
120       A note on commit messages: Though not required, it’s a good idea to
121       begin the commit message with a single short (less than 50 character)
122       line summarizing the change, followed by a blank line and then a more
123       thorough description. Tools that turn commits into email, for example,
124       use the first line on the Subject: line and the rest of the commit in
125       the body.
126

GIT TRACKS CONTENT NOT FILES

128       Many revision control systems provide an add command that tells the
129       system to start tracking changes to a new file. Git’s add command does
130       something simpler and more powerful: git add is used both for new and
131       newly modified files, and in both cases it takes a snapshot of the
132       given files and stages that content in the index, ready for inclusion
133       in the next commit.
134

VIEWING PROJECT HISTORY

136       At any point you can view the history of your changes using
137
138           $ git log
139
140
141       If you also want to see complete diffs at each step, use
142
143           $ git log -p
144
145
146       Often the overview of the change is useful to get a feel of each step
147
148           $ git log --stat --summary
149
150

MANAGING BRANCHES

152       A single git repository can maintain multiple branches of development.
153       To create a new branch named "experimental", use
154
155           $ git branch experimental
156
157
158       If you now run
159
160           $ git branch
161
162
163       you’ll get a list of all existing branches:
164
165             experimental
166           * master
167
168
169       The "experimental" branch is the one you just created, and the "master"
170       branch is a default branch that was created for you automatically. The
171       asterisk marks the branch you are currently on; type
172
173           $ git checkout experimental
174
175
176       to switch to the experimental branch. Now edit a file, commit the
177       change, and switch back to the master branch:
178
179           (edit file)
180           $ git commit -a
181           $ git checkout master
182
183
184       Check that the change you made is no longer visible, since it was made
185       on the experimental branch and you’re back on the master branch.
186
187       You can make a different change on the master branch:
188
189           (edit file)
190           $ git commit -a
191
192
193       at this point the two branches have diverged, with different changes
194       made in each. To merge the changes made in experimental into master,
195       run
196
197           $ git merge experimental
198
199
200       If the changes don’t conflict, you’re done. If there are conflicts,
201       markers will be left in the problematic files showing the conflict;
202
203           $ git diff
204
205
206       will show this. Once you’ve edited the files to resolve the conflicts,
207
208           $ git commit -a
209
210
211       will commit the result of the merge. Finally,
212
213           $ gitk
214
215
216       will show a nice graphical representation of the resulting history.
217
218       At this point you could delete the experimental branch with
219
220           $ git branch -d experimental
221
222
223       This command ensures that the changes in the experimental branch are
224       already in the current branch.
225
226       If you develop on a branch crazy-idea, then regret it, you can always
227       delete the branch with
228
229           $ git branch -D crazy-idea
230
231
232       Branches are cheap and easy, so this is a good way to try something
233       out.
234

USING GIT FOR COLLABORATION

236       Suppose that Alice has started a new project with a git repository in
237       /home/alice/project, and that Bob, who has a home directory on the same
238       machine, wants to contribute.
239
240       Bob begins with:
241
242           bob$ git clone /home/alice/project myrepo
243
244
245       This creates a new directory "myrepo" containing a clone of Alice’s
246       repository. The clone is on an equal footing with the original project,
247       possessing its own copy of the original project’s history.
248
249       Bob then makes some changes and commits them:
250
251           (edit files)
252           bob$ git commit -a
253           (repeat as necessary)
254
255
256       When he’s ready, he tells Alice to pull changes from the repository at
257       /home/bob/myrepo. She does this with:
258
259           alice$ cd /home/alice/project
260           alice$ git pull /home/bob/myrepo master
261
262
263       This merges the changes from Bob’s "master" branch into Alice’s current
264       branch. If Alice has made her own changes in the meantime, then she may
265       need to manually fix any conflicts.
266
267       The "pull" command thus performs two operations: it fetches changes
268       from a remote branch, then merges them into the current branch.
269
270       Note that in general, Alice would want her local changes committed
271       before initiating this "pull". If Bob’s work conflicts with what Alice
272       did since their histories forked, Alice will use her working tree and
273       the index to resolve conflicts, and existing local changes will
274       interfere with the conflict resolution process (git will still perform
275       the fetch but will refuse to merge --- Alice will have to get rid of
276       her local changes in some way and pull again when this happens).
277
278       Alice can peek at what Bob did without merging first, using the "fetch"
279       command; this allows Alice to inspect what Bob did, using a special
280       symbol "FETCH_HEAD", in order to determine if he has anything worth
281       pulling, like this:
282
283           alice$ git fetch /home/bob/myrepo master
284           alice$ git log -p HEAD..FETCH_HEAD
285
286
287       This operation is safe even if Alice has uncommitted local changes. The
288       range notation "HEAD..FETCH_HEAD" means "show everything that is
289       reachable from the FETCH_HEAD but exclude anything that is reachable
290       from HEAD". Alice already knows everything that leads to her current
291       state (HEAD), and reviews what Bob has in his state (FETCH_HEAD) that
292       she has not seen with this command.
293
294       If Alice wants to visualize what Bob did since their histories forked
295       she can issue the following command:
296
297           $ gitk HEAD..FETCH_HEAD
298
299
300       This uses the same two-dot range notation we saw earlier with git log.
301
302       Alice may want to view what both of them did since they forked. She can
303       use three-dot form instead of the two-dot form:
304
305           $ gitk HEAD...FETCH_HEAD
306
307
308       This means "show everything that is reachable from either one, but
309       exclude anything that is reachable from both of them".
310
311       Please note that these range notation can be used with both gitk and
312       "git log".
313
314       After inspecting what Bob did, if there is nothing urgent, Alice may
315       decide to continue working without pulling from Bob. If Bob’s history
316       does have something Alice would immediately need, Alice may choose to
317       stash her work-in-progress first, do a "pull", and then finally unstash
318       her work-in-progress on top of the resulting history.
319
320       When you are working in a small closely knit group, it is not unusual
321       to interact with the same repository over and over again. By defining
322       remote repository shorthand, you can make it easier:
323
324           alice$ git remote add bob /home/bob/myrepo
325
326
327       With this, Alice can perform the first part of the "pull" operation
328       alone using the git fetch command without merging them with her own
329       branch, using:
330
331           alice$ git fetch bob
332
333
334       Unlike the longhand form, when Alice fetches from Bob using a remote
335       repository shorthand set up with git remote, what was fetched is stored
336       in a remote tracking branch, in this case bob/master. So after this:
337
338           alice$ git log -p master..bob/master
339
340
341       shows a list of all the changes that Bob made since he branched from
342       Alice’s master branch.
343
344       After examining those changes, Alice could merge the changes into her
345       master branch:
346
347           alice$ git merge bob/master
348
349
350       This merge can also be done by pulling from her own remote tracking
351       branch, like this:
352
353           alice$ git pull . remotes/bob/master
354
355
356       Note that git pull always merges into the current branch, regardless of
357       what else is given on the command line.
358
359       Later, Bob can update his repo with Alice’s latest changes using
360
361           bob$ git pull
362
363
364       Note that he doesn’t need to give the path to Alice’s repository; when
365       Bob cloned Alice’s repository, git stored the location of her
366       repository in the repository configuration, and that location is used
367       for pulls:
368
369           bob$ git config --get remote.origin.url
370           /home/alice/project
371
372
373       (The complete configuration created by git clone is visible using git
374       config -l, and the git-config(1) man page explains the meaning of each
375       option.)
376
377       Git also keeps a pristine copy of Alice’s master branch under the name
378       "origin/master":
379
380           bob$ git branch -r
381             origin/master
382
383
384       If Bob later decides to work from a different host, he can still
385       perform clones and pulls using the ssh protocol:
386
387           bob$ git clone alice.org:/home/alice/project myrepo
388
389
390       Alternatively, git has a native protocol, or can use rsync or http; see
391       git-pull(1) for details.
392
393       Git can also be used in a CVS-like mode, with a central repository that
394       various users push changes to; see git-push(1) and gitcvs-migration(7).
395

EXPLORING HISTORY

397       Git history is represented as a series of interrelated commits. We have
398       already seen that the git log command can list those commits. Note that
399       first line of each git log entry also gives a name for the commit:
400
401           $ git log
402           commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
403           Author: Junio C Hamano <junkio@cox.net>
404           Date:   Tue May 16 17:18:22 2006 -0700
405
406               merge-base: Clarify the comments on post processing.
407
408
409       We can give this name to git show to see the details about this commit.
410
411           $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
412
413
414       But there are other ways to refer to commits. You can use any initial
415       part of the name that is long enough to uniquely identify the commit:
416
417           $ git show c82a22c39c   # the first few characters of the name are
418                                   # usually enough
419           $ git show HEAD         # the tip of the current branch
420           $ git show experimental # the tip of the "experimental" branch
421
422
423       Every commit usually has one "parent" commit which points to the
424       previous state of the project:
425
426           $ git show HEAD^  # to see the parent of HEAD
427           $ git show HEAD^^ # to see the grandparent of HEAD
428           $ git show HEAD~4 # to see the great-great grandparent of HEAD
429
430
431       Note that merge commits may have more than one parent:
432
433           $ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
434           $ git show HEAD^2 # show the second parent of HEAD
435
436
437       You can also give commits names of your own; after running
438
439           $ git tag v2.5 1b2e1d63ff
440
441
442       you can refer to 1b2e1d63ff by the name "v2.5". If you intend to share
443       this name with other people (for example, to identify a release
444       version), you should create a "tag" object, and perhaps sign it; see
445       git-tag(1) for details.
446
447       Any git command that needs to know a commit can take any of these
448       names. For example:
449
450           $ git diff v2.5 HEAD     # compare the current HEAD to v2.5
451           $ git branch stable v2.5 # start a new branch named "stable" based
452                                    # at v2.5
453           $ git reset --hard HEAD^ # reset your current branch and working
454                                    # directory to its state at HEAD^
455
456
457       Be careful with that last command: in addition to losing any changes in
458       the working directory, it will also remove all later commits from this
459       branch. If this branch is the only branch containing those commits,
460       they will be lost. Also, don’t use git reset on a publicly-visible
461       branch that other developers pull from, as it will force needless
462       merges on other developers to clean up the history. If you need to undo
463       changes that you have pushed, use git revert instead.
464
465       The git grep command can search for strings in any version of your
466       project, so
467
468           $ git grep "hello" v2.5
469
470
471       searches for all occurrences of "hello" in v2.5.
472
473       If you leave out the commit name, git grep will search any of the files
474       it manages in your current directory. So
475
476           $ git grep "hello"
477
478
479       is a quick way to search just the files that are tracked by git.
480
481       Many git commands also take sets of commits, which can be specified in
482       a number of ways. Here are some examples with git log:
483
484           $ git log v2.5..v2.6            # commits between v2.5 and v2.6
485           $ git log v2.5..                # commits since v2.5
486           $ git log --since="2 weeks ago" # commits from the last 2 weeks
487           $ git log v2.5.. Makefile       # commits since v2.5 which modify
488                                           # Makefile
489
490
491       You can also give git log a "range" of commits where the first is not
492       necessarily an ancestor of the second; for example, if the tips of the
493       branches "stable" and "master" diverged from a common commit some time
494       ago, then
495
496           $ git log stable..master
497
498
499       will list commits made in the master branch but not in the stable
500       branch, while
501
502           $ git log master..stable
503
504
505       will show the list of commits made on the stable branch but not the
506       master branch.
507
508       The git log command has a weakness: it must present commits in a list.
509       When the history has lines of development that diverged and then merged
510       back together, the order in which git log presents those commits is
511       meaningless.
512
513       Most projects with multiple contributors (such as the Linux kernel, or
514       git itself) have frequent merges, and gitk does a better job of
515       visualizing their history. For example,
516
517           $ gitk --since="2 weeks ago" drivers/
518
519
520       allows you to browse any commits from the last 2 weeks of commits that
521       modified files under the "drivers" directory. (Note: you can adjust
522       gitk’s fonts by holding down the control key while pressing "-" or
523       "+".)
524
525       Finally, most commands that take filenames will optionally allow you to
526       precede any filename by a commit, to specify a particular version of
527       the file:
528
529           $ git diff v2.5:Makefile HEAD:Makefile.in
530
531
532       You can also use git show to see any such file:
533
534           $ git show v2.5:Makefile
535
536

NEXT STEPS

538       This tutorial should be enough to perform basic distributed revision
539       control for your projects. However, to fully understand the depth and
540       power of git you need to understand two simple ideas on which it is
541       based:
542
543       ·   The object database is the rather elegant system used to store the
544           history of your project—files, directories, and commits.
545
546       ·   The index file is a cache of the state of a directory tree, used to
547           create commits, check out working directories, and hold the various
548           trees involved in a merge.
549
550       Part two of this tutorial explains the object database, the index file,
551       and a few other odds and ends that you’ll need to make the most of git.
552       You can find it at gittutorial-2(7).
553
554       If you don’t want to continue with that right away, a few other
555       digressions that may be interesting at this point are:
556
557       ·    git-format-patch(1), git-am(1): These convert series of git
558           commits into emailed patches, and vice versa, useful for projects
559           such as the Linux kernel which rely heavily on emailed patches.
560
561       ·    git-bisect(1): When there is a regression in your project, one way
562           to track down the bug is by searching through the history to find
563           the exact commit that’s to blame. Git bisect can help you perform a
564           binary search for that commit. It is smart enough to perform a
565           close-to-optimal search even in the case of complex non-linear
566           history with lots of merged branches.
567
568       ·    gitworkflows(7): Gives an overview of recommended workflows.
569
570       ·    Everyday GIT with 20 Commands Or So[2]
571
572       ·    gitcvs-migration(7): Git for CVS users.
573

SEE ALSO

575       gittutorial-2(7), gitcvs-migration(7), gitcore-tutorial(7),
576       gitglossary(7), git-help(1), gitworkflows(7), Everyday git[2], The Git
577       User’s Manual[1]
578

GIT

580       Part of the git(1) suite.
581

NOTES

583        1. The Git User’s Manual
584           file:///usr/share/doc/git-1.7.1/user-manual.html
585
586        2. Everyday GIT with 20 Commands Or So
587           file:///usr/share/doc/git-1.7.1/everyday.html
588
589
590
591Git 1.7.1                         08/16/2017                    GITTUTORIAL(7)
Impressum