diff options
author | Holger Weiss <holger@zedat.fu-berlin.de> | 2014-01-11 16:38:18 (GMT) |
---|---|---|
committer | Holger Weiss <holger@zedat.fu-berlin.de> | 2014-01-11 16:38:18 (GMT) |
commit | 7b0fa5d642466e7cdd0d326658c3c06c27f8a1ec (patch) | |
tree | 1bd1fe366d4063f29ed6930b0750c6bd7a72b7e9 /web/input/doc/faq/git.md | |
parent | 16bf58546355690e0d9cf4e7d181255aac73b5c6 (diff) | |
download | site-7b0fa5d642466e7cdd0d326658c3c06c27f8a1ec.tar.gz |
Import most FAQ items from old web site
Import most of the FAQ entries from our old web site. A few outdated
questions have been omitted, many of the imported ones were updated in
one way or another, and the order of the development-related questions
has been changed. Also, the phrasing of some questions has been
modified (just to make the headings shorter).
For the record, this is the original list of questions from the old web
site:
General
-------
* Who controls the Nagios Plugins project?
* What license is Nagios Plugins distributed under?
* Who owns the copyright for the Nagios Plugin code?
* Can I submit a patch to this project?
* Do you accept donations?
Compiling
---------
* ./configure appears to hang
* check_ldap, check_radius or check_pgsql don't compile even though
configure output says the required libraries are present
* How come check_http/check_tcp doesn't work with --ssl?
* How do I compile the Nagios::Plugin perl module?
* I can't compile check_mysql on solaris
* I get '":types" is not exported by the Params::Validate module' when
running tests
* Why does Solaris use pst3 for check_procs?
Installing
----------
* Some of the root plugins (check_dhcp and check_icmp) haven't been
installed. What's happening?
* Why aren't my plugins installed as the nagios user? And what about
root plugins?
Development
-----------
* How do I use Git?
* Can I add extra tests to the C routines?
* Can I use the Nagios Plugins in my own project?
* How can I find out more about writing a plugin?
* How do I make changes on nagiosmib?
* How do I prove the C routines work?
* How do I use and update Gnulib?
* How do I use the Nagios::Plugin perl module?
* How do the test parameters in NPTest.pm work?
* Private C APIs
Diffstat (limited to 'web/input/doc/faq/git.md')
-rw-r--r-- | web/input/doc/faq/git.md | 197 |
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 @@ | |||
1 | title: Git | ||
2 | parent: FAQ | ||
3 | --- | ||
4 | |||
5 | # How do I use Git? | ||
6 | |||
7 | After 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 | ||
9 | to Git. | ||
10 | |||
11 | ## Differences Between Git and SVN | ||
12 | |||
13 | There 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 | ||
15 | mean we can’t have a central shared Git repository (and we indeed have one), | ||
16 | this means distributed development can occur around that central repository. | ||
17 | Another visible difference is that Git have more stages between the working | ||
18 | directory 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 | ||
20 | as a staging area. When you commit with **git commit**, only the changes in | ||
21 | the index are considered. After committing, the changes are still local. To | ||
22 | share it with others, you have to push it to a remote repository, or gave | ||
23 | someone pull from your publicly accessible repository (in most case you will | ||
24 | still have to push changes there, unless if you were running a git daemon | ||
25 | straight off your working repository). Finally you can’t miss the fact that | ||
26 | there is no more revision numbers, and the distributed nature of Git is the | ||
27 | reason for that: there is absolutely no way a single number could be tracked | ||
28 | in a distributed way. Instead Git uses SHA1 hashes to identify commits (as | ||
29 | well as other objects in the repository). Each branch and tag refer to an | ||
30 | object name (SHA1 hash), and each commits have one or more parents (commit | ||
31 | objects). Although SHA1 hashes are 40 digits long, with Git you only have to | ||
32 | type a handful of digits to reference one. | ||
33 | |||
34 | ## Cloning a Project | ||
35 | |||
36 | To work on a project you first have to clone it. This creates your own local | ||
37 | repository and until you want to distribute your change or merge changes from | ||
38 | someone else everything that follows can happen offline. If you have push | ||
39 | access, run the command: | ||
40 | |||
41 | git clone git@github.com:nagios-plugins/nagios-plugins.git | ||
42 | |||
43 | If you just want a local copy or wish to clone it to your workstation, you can | ||
44 | run this command instead: | ||
45 | |||
46 | git clone git://github.com/nagios-plugins/nagios-plugins.git | ||
47 | |||
48 | This will create a directory called `nagios-plugins` in your current directory | ||
49 | with 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 | |||
54 | You can edit the files in the working area. To check the status, use: | ||
55 | |||
56 | git status | ||
57 | |||
58 | This will show a list of changes in the working directory. Newly made changes | ||
59 | appear in *red*, while changes added to the index are shown in green. You can | ||
60 | use **git diff** to see changes between the current working directory and the | ||
61 | index (untracked files will not be shown). | ||
62 | |||
63 | ## Committing Files | ||
64 | |||
65 | Use **git add** to specify which new files/changes you want to commit; this | ||
66 | will 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 | ||
69 | between HEAD and the index) with **git diff --cached**, and then commit them | ||
70 | with: | ||
71 | |||
72 | git commit | ||
73 | |||
74 | Add a comment (you have read the [Development Guidelines][guidelines], right? | ||
75 | :-)). This commit will be local (affecting only your own repository) so you | ||
76 | will 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 | ||
78 | clone of your local repository). If the change is from a contributor, set the | ||
79 | author at commit time: | ||
80 | |||
81 | git commit --author="Jane Doe <jane@example.com>" | ||
82 | |||
83 | If you realize that you forgot something in your commit and haven’t pushed it | ||
84 | yet 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 | ||
86 | this will cause non-linear updates and should be done only if the developers | ||
87 | using your repository are aware of it. | ||
88 | |||
89 | ## Reverting Local Modifications | ||
90 | |||
91 | You can revert local modifications with the following steps. First, if you | ||
92 | have already staged the changes you will have to unstage them. As indicated | ||
93 | in the **git status** message you can do so with the following command: | ||
94 | |||
95 | git reset HEAD <file> | ||
96 | |||
97 | Then you can revert unstaged changes with: | ||
98 | |||
99 | git checkout <file> | ||
100 | |||
101 | If you have already committed changes locally and need to undo your commit(s), | ||
102 | you can use **git reset**. First find the commit names with **git log** and | ||
103 | then do either one of these: To keep local modifications (you can commit them | ||
104 | again, stash them, etc.) | ||
105 | |||
106 | git reset --soft <commit> | ||
107 | |||
108 | Note 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. | ||
110 | To discard local modifications (if you lose important changes with this | ||
111 | command you may be able to recover them with **git reflog** and **git checkout | ||
112 | <commit\>**): | ||
113 | |||
114 | git reset --hard <file> | ||
115 | |||
116 | Do not reset changes that have already been pushed to remote repositories as | ||
117 | this will cause non-linear updates. If you do so, developers using those | ||
118 | repositories should be aware of it. | ||
119 | |||
120 | ## Merging Remote Changes | ||
121 | |||
122 | When you work on your local repository you’ll need to keep it up to date with | ||
123 | the development tree. This is very similar to **svn update** with the | ||
124 | difference that it can’t be done if the working tree has any unmerged changes. | ||
125 | If you do, either commit them or put them aside (Tip: **git stash**). If you | ||
126 | cloned from the main Git repository, this command will do a fetch then merge | ||
127 | any new changes: | ||
128 | |||
129 | git pull | ||
130 | |||
131 | You can also merge changes from any other fork of the repository. This | ||
132 | usually happens if someone ask you to pull from his own repo for some fix or | ||
133 | enhancements. Together with **--no-commit** you will have a chance to review | ||
134 | the 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 | |||
140 | Once you’re done with your commits and after pulling from the main repository, | ||
141 | you can push you change back to it. If you cloned using the *push* url this | ||
142 | command will push the master branch: | ||
143 | |||
144 | git push | ||
145 | |||
146 | It you’re trying to push something that would generate merge conflicts, the | ||
147 | push will be rejected. You will have yo do a pull first, fix the any | ||
148 | conflicts locally and then push again. If your commits are local (you haven’t | ||
149 | pulled them from someone else or published them somewhere) you can rebase to | ||
150 | avoid a merge: | ||
151 | |||
152 | git pull --rebase | ||
153 | |||
154 | Like a merge, this may generate conflicts and let you fix them, but instead of | ||
155 | creating a merge commit on top of the others, it will undo your commits, | ||
156 | fast-forward and apply your commits again. This is cleaner but doesn’t play | ||
157 | well when it rewrites already published history. | ||
158 | |||
159 | ## Going Further | ||
160 | |||
161 | This is a very quick introduction to Git. There are a lot more useful | ||
162 | commands for manipulating changes and working with others. They are all very | ||
163 | well 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 | ||
165 | look into some of the references listed below, or into a book such as [Scott | ||
166 | Chacon][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: # %--> | ||