From c1fbf0e52e0f2e063b917147242f91942bd036dd Mon Sep 17 00:00:00 2001 From: Holger Weiss Date: Sat, 11 Jan 2014 22:58:40 +0100 Subject: doc/faq/git.md: Add various minor improvements Apply a few fixes and improvements throughout the text. diff --git a/web/input/doc/faq/git.md b/web/input/doc/faq/git.md index 53260ec..5503166 100644 --- a/web/input/doc/faq/git.md +++ b/web/input/doc/faq/git.md @@ -17,10 +17,10 @@ means distributed development can occur around that central repository. Git has an additional stage between the working directory and the repository. The idea is that you might be working on multiple unrelated things without wanting to commit all changes in one go. Therefore, the changes that should -be committed must first be added to the repository *index*, which can be seen -as a staging area. This is usually done with **git add**, both for new files -*and* for changes to existing ones. When you commit using **git commit**, -only the changes in the index are considered. +be committed must first be added to the so-called *index*, which can be seen +as a staging area of the repository. This is usually done with **git add**, +both for new files *and* for changes to existing ones. When you commit using +**git commit**, only the changes in the index are considered. After committing, the changes are still local. To share them with others, you have to push them to a remote repository, or have someone pull from your @@ -39,9 +39,9 @@ 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: +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 to the Nagios Plugins repository, run the command: git clone git@github.com:nagios-plugins/nagios-plugins.git @@ -50,9 +50,9 @@ 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`. +This will create a directory called `nagios-plugins` with all the `master` +code and history (this is roughly equivalent to CVS/SVN `HEAD`). Change +directory to `nagios-plugins`. ## Editing Files @@ -61,7 +61,7 @@ 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 +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). @@ -70,25 +70,25 @@ index (untracked files will not be shown). 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: +-a** directly. You can see the changes you are about to commit (the +difference between HEAD and the index) with **git diff --staged**, 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: +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 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 " 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 +this will cause non-linear updates and should be done only if all developers using your repository are aware of it. ## Reverting Local Modifications @@ -119,46 +119,46 @@ command you may be able to recover them with **git reflog** and **git checkout git reset --hard 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 +this will cause non-linear updates. If you do so, all 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 +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: +If you do, either commit them or put them aside (hint: **git stash**). If you +cloned from the main Git repository, this command will do a fetch and 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 +usually happens if someone asks 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: +Once you’re done with your commits, and after pulling from the main +repository, you can push your changes 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: +push will be rejected. You will have to do a pull first, fix 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 +fast-forward and apply your commits again. This is cleaner, but doesn’t play well when it rewrites already published history. ## Going Further @@ -168,7 +168,8 @@ 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 ** or **git --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]. +Chacon][scott]'s [Pro Git][book-home] (which is [freely available][book-free] +on the [Git web site][git]). ## References @@ -195,6 +196,7 @@ Chacon][scott]'s [Pro Git][book]. [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" +[book-home]: http://www.apress.com/9781430218333 "Pro Git at Apress" +[book-free]: http://git-scm.com/book "Pro Git for Free" -- cgit v0.10-9-g596f