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