1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
title: Git
parent: FAQ
---
# How do I use Git?
After the 1.4.13 release, the [Nagios Plugins Development Team][team] moved to
[Git][git] for its code repositories. This document is a quick introduction
to Git.
## Differences Between Git and SVN
There is one huge difference between Git and SVN: Git is a distributed SCM
(Source Code Management system) while SVN is a centralized one. This doesn’t
mean we can’t have a central shared Git repository (and we indeed have one),
this means distributed development can occur around that central repository.
Another visible difference is that Git have more stages between the working
directory and the repository. When you want to add files or changes, you use
**git add**. This adds the changes to the repository index, which can be seen
as a staging area. When you commit with **git commit**, only the changes in
the index are considered. After committing, the changes are still local. To
share it with others, you have to push it to a remote repository, or gave
someone pull from your publicly accessible repository (in most case you will
still have to push changes there, unless if you were running a git daemon
straight off your working repository). Finally you can’t miss the fact that
there is no more revision numbers, and the distributed nature of Git is the
reason for that: there is absolutely no way a single number could be tracked
in a distributed way. Instead Git uses SHA1 hashes to identify commits (as
well as other objects in the repository). Each branch and tag refer to an
object name (SHA1 hash), and each commits have one or more parents (commit
objects). Although SHA1 hashes are 40 digits long, with Git you only have to
type a handful of digits to reference one.
## Cloning a Project
To work on a project you first have to clone it. This creates your own local
repository and until you want to distribute your change or merge changes from
someone else everything that follows can happen offline. If you have push
access, run the command:
git clone git@github.com:nagios-plugins/nagios-plugins.git
If you just want a local copy or wish to clone it to your workstation, you can
run this command instead:
git clone git://github.com/nagios-plugins/nagios-plugins.git
This will create a directory called `nagios-plugins` in your current directory
with all the `master` code and history (this is roughly equivalent to CVS/SVN
`HEAD`). Change directory to `nagios-plugins`.
## Editing Files
You can edit the files in the working area. To check the status, use:
git status
This will show a list of changes in the working directory. Newly made changes
appear in *red*, while changes added to the index are shown in green. You can
use **git diff** to see changes between the current working directory and the
index (untracked files will not be shown).
## Committing Files
Use **git add** to specify which new files/changes you want to commit; this
will add the changes to the index. You can select only partial diffs with
**git add -p** too. If you want to commit everything you can use **git commit
-a** directly. You can see the changes you are about to commit (difference
between HEAD and the index) with **git diff --cached**, and then commit them
with:
git commit
Add a comment (you have read the [Development Guidelines][guidelines], right?
:-)). This commit will be local (affecting only your own repository) so you
will have to either push your changes, or have someone to pull them from you
(in the latter case you will most likely still push to a publicly accessible
clone of your local repository). If the change is from a contributor, set the
author at commit time:
git commit --author="Jane Doe <jane@example.com>"
If you realize that you forgot something in your commit and haven’t pushed it
yet to a remote repository, you can amend your last commit with **git commit
--amend**. You can also amend after a push and force the next update, however
this will cause non-linear updates and should be done only if the developers
using your repository are aware of it.
## Reverting Local Modifications
You can revert local modifications with the following steps. First, if you
have already staged the changes you will have to unstage them. As indicated
in the **git status** message you can do so with the following command:
git reset HEAD <file>
Then you can revert unstaged changes with:
git checkout <file>
If you have already committed changes locally and need to undo your commit(s),
you can use **git reset**. First find the commit names with **git log** and
then do either one of these: To keep local modifications (you can commit them
again, stash them, etc.)
git reset --soft <commit>
Note that for the purpose of “re-doing” the last commit, **git commit
--amend** will be much easier than a reset/commit with the same end result.
To discard local modifications (if you lose important changes with this
command you may be able to recover them with **git reflog** and **git checkout
<commit\>**):
git reset --hard <file>
Do not reset changes that have already been pushed to remote repositories as
this will cause non-linear updates. If you do so, developers using those
repositories should be aware of it.
## Merging Remote Changes
When you work on your local repository you’ll need to keep it up to date with
the development tree. This is very similar to **svn update** with the
difference that it can’t be done if the working tree has any unmerged changes.
If you do, either commit them or put them aside (Tip: **git stash**). If you
cloned from the main Git repository, this command will do a fetch then merge
any new changes:
git pull
You can also merge changes from any other fork of the repository. This
usually happens if someone ask you to pull from his own repo for some fix or
enhancements. Together with **--no-commit** you will have a chance to review
the changes and make any relevant correction before the merge. Example:
git pull --no-commit git://example.com/path/to/repo.git master
## Merging Back to the Main Repository
Once you’re done with your commits and after pulling from the main repository,
you can push you change back to it. If you cloned using the *push* url this
command will push the master branch:
git push
It you’re trying to push something that would generate merge conflicts, the
push will be rejected. You will have yo do a pull first, fix the any
conflicts locally and then push again. If your commits are local (you haven’t
pulled them from someone else or published them somewhere) you can rebase to
avoid a merge:
git pull --rebase
Like a merge, this may generate conflicts and let you fix them, but instead of
creating a merge commit on top of the others, it will undo your commits,
fast-forward and apply your commits again. This is cleaner but doesn’t play
well when it rewrites already published history.
## Going Further
This is a very quick introduction to Git. There are a lot more useful
commands for manipulating changes and working with others. They are all very
well documented (see **git help [-a]** for a list of commands, **git help
<cmd\>** or **git <cmd\> --help** shows the man page). You might also want to
look into some of the references listed below, or into a book such as [Scott
Chacon][scott]'s [Pro Git][book].
## References
- Intro to Distributed Version Control (Illustrated)
<http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/>
- A tutorial introduction to Git
<https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html>
- Everyday Git With 20 Commands Or So
<http://www.kernel.org/pub/software/scm/git/docs/everyday.html>
- Git User’s Manual
<http://www.kernel.org/pub/software/scm/git/docs/user-manual.html>
- Git - SVN Crash Course
<http://git.or.cz/course/svn.html>
- Git QuickStart
<http://git.or.cz/gitwiki/QuickStart>
- Git CheatSheet
<http://git.or.cz/gitwiki/GitCheatSheet>
- Understanding Git Conceptually
<http://www.eecs.harvard.edu/~cduan/technical/git/>
- The Git Parable
<http://tom.preston-werner.com/2009/05/19/the-git-parable.html>
- Git for Computer Scientists
<http://eagain.net/articles/git-for-computer-scientists/>
[team]: team.html "Nagios Plugins Development Team"
[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines"
[git]: http://git-scm.com/ "Git"
[scott]: http://scottchacon.com/ "Scott Chacon"
[book]: http://git-scm.com/book "Pro Git"
<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
|
