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