![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 1b9301304188ee2783a54ec60cdb88ed5714c9c4..118ff72869bc8011cbfe46c2bdeed8c0e67e6ab6 100644 (file)
-A tutorial introduction to git
-==============================
+A tutorial introduction to git (for version 1.5.1 or newer)
+===========================================================
This tutorial explains how to import a new project into git, make
changes to it, and share changes with other developers.
+If you are instead primarily interested in using git to fetch a project,
+for example, to test the latest version, you may prefer to start with
+the first two chapters of link:user-manual.html[The Git User's Manual].
+
First, note that you can get documentation for a command such as "git
diff" with:
way to do so is:
------------------------------------------------
-$ git repo-config --global user.name "Your Name Comes Here"
-$ git repo-config --global user.email you@yourdomain.example.com
+$ git config --global user.name "Your Name Comes Here"
+$ git config --global user.email you@yourdomain.example.com
------------------------------------------------
------------------------------------------------
You've now initialized the working directory--you may notice a new
-directory created, named ".git". Tell git that you want it to track
-every file under the current directory (note the '.') with:
+directory created, named ".git".
+
+Next, tell git to take a snapshot of the contents of all files under the
+current directory (note the '.'), with gitlink:git-add[1]:
------------------------------------------------
$ git add .
------------------------------------------------
-Finally,
+This snapshot is now stored in a temporary staging area which git calls
+the "index". You can permanently store the contents of the index in the
+repository with gitlink:git-commit[1]:
------------------------------------------------
$ git commit
------------------------------------------------
-will prompt you for a commit message, then record the current state
-of all the files to the repository.
+This will prompt you for a commit message. You've now stored the first
+version of your project in git.
Making changes
--------------
-Try modifying some files, then run
+Modify some files, then add their updated contents to the index:
------------------------------------------------
-$ git diff
+$ git add file1 file2 file3
------------------------------------------------
-to review your changes. When you're done, tell git that you
-want the updated contents of these files in the commit and then
-make a commit, like this:
+You are now ready to commit. You can see what is about to be committed
+using gitlink:git-diff[1] with the --cached option:
+
+------------------------------------------------
+$ git diff --cached
+------------------------------------------------
+
+(Without --cached, gitlink:git-diff[1] will show you any changes that
+you've made but not yet added to the index.) You can also get a brief
+summary of the situation with gitlink:git-status[1]:
+
+------------------------------------------------
+$ git status
+# On branch master
+# Changes to be committed:
+# (use "git reset HEAD <file>..." to unstage)
+#
+# modified: file1
+# modified: file2
+# modified: file3
+#
+------------------------------------------------
+
+If you need to make any further adjustments, do so now, and then add any
+newly modified content to the index. Finally, commit your changes with:
------------------------------------------------
-$ git add file1 file2 file3
$ git commit
------------------------------------------------
This will again prompt your for a message describing the change, and then
-record the new versions of the files you listed.
+record a new version of the project.
Alternatively, instead of running `git add` beforehand, you can use
$ git commit -a
------------------------------------------------
-which will automatically notice modified (but not new) files.
+which will automatically notice any modified (but not new) files, add
+them to the index, and commit, all in one step.
A note on commit messages: Though not required, it's a good idea to
begin the commit message with a single short (less than 50 character)
example, use the first line on the Subject: line and the rest of the
commit in the body.
-
Git tracks content not files
----------------------------
-With git you have to explicitly "add" all the changed _content_ you
-want to commit together. This can be done in a few different ways:
-
-1) By using 'git add <file_spec>...'
-
- This can be performed multiple times before a commit. Note that this
- is not only for adding new files. Even modified files must be
- added to the set of changes about to be committed. The "git status"
- command gives you a summary of what is included so far for the
- next commit. When done you should use the 'git commit' command to
- make it real.
+Many revision control systems provide an "add" command that tells the
+system to start tracking changes to a new file. Git's "add" command
+does something simpler and more powerful: `git add` is used both for new
+and newly modified files, and in both cases it takes a snapshot of the
+given files and stages that content in the index, ready for inclusion in
+the next commit.
- Note: don't forget to 'add' a file again if you modified it after the
- first 'add' and before 'commit'. Otherwise only the previous added
- state of that file will be committed. This is because git tracks
- content, so what you're really 'add'ing to the commit is the *content*
- of the file in the state it is in when you 'add' it.
-
-2) By using 'git commit -a' directly
-
- This is a quick way to automatically 'add' the content from all files
- that were modified since the previous commit, and perform the actual
- commit without having to separately 'add' them beforehand. This will
- not add content from new files i.e. files that were never added before.
- Those files still have to be added explicitly before performing a
- commit.
-
-But here's a twist. If you do 'git commit <file1> <file2> ...' then only
-the changes belonging to those explicitly specified files will be
-committed, entirely bypassing the current "added" changes. Those "added"
-changes will still remain available for a subsequent commit though.
-
-However, for normal usage you only have to remember 'git add' + 'git commit'
-and/or 'git commit -a'.
-
-
-Viewing the changelog
----------------------
+Viewing project history
+-----------------------
At any point you can view the history of your changes using
------------------------------------------------
$ cd /home/alice/project
-$ git remote add bob /home/bob/myrepo
-$ git pull bob master
+$ git pull /home/bob/myrepo master
------------------------------------------------
-First it adds the "remote" Bob's repository with the name "bob" and
-then it merges the changes from Bob's "master" branch into Alice's
+This merges the changes from Bob's "master" branch into Alice's
current branch. If Alice has made her own changes in the meantime,
then she may need to manually fix any conflicts. (Note that the
"master" argument in the above command is actually unnecessary, as it
The "pull" command thus performs two operations: it fetches changes
from a remote branch, then merges them into the current branch.
-You can perform the first operation alone using the "git fetch"
-command without merging them with her own branch, using:
+When you are working in a small closely knit group, it is not
+unusual to interact with the same repository over and over
+again. By defining 'remote' repository shorthand, you can make
+it easier:
+
+------------------------------------------------
+$ git remote add bob /home/bob/myrepo
+------------------------------------------------
+
+With this, you can perform the first operation alone using the
+"git fetch" command without merging them with her own branch,
+using:
-------------------------------------
$ git fetch bob
-------------------------------------
-which fetches the changes from Bob's branches. Then
+Unlike the longhand form, when Alice fetches from Bob using a
+remote repository shorthand set up with `git remote`, what was
+fetched is stored in a remote tracking branch, in this case
+`bob/master`. So after this:
-------------------------------------
$ git log -p master..bob/master
shows a list of all the changes that Bob made since he branched from
Alice's master branch.
-After examining those changes, and possibly fixing things, Alice
+After examining those changes, Alice
could merge the changes into her master branch:
-------------------------------------
-$ git checkout master
$ git merge bob/master
-------------------------------------
-The last command is a merge of the "bob/master" branch in Alice's
-own repository.
-
-Alice could also perform both steps at once with:
+This `merge` can also be done by 'pulling from her own remote
+tracking branch', like this:
-------------------------------------
-$ git pull bob
+$ git pull . remotes/bob/master
-------------------------------------
-This is just like the "git pull bob master" that we saw
-before, except that it also stores the unmerged changes from bob's
-master branch in bob/master before merging them into Alice's
-current branch. Note that git pull always merges into the current
-branch, regardless of what else is given on the commandline.
+Note that git pull always merges into the current branch,
+regardless of what else is given on the commandline.
Later, Bob can update his repo with Alice's latest changes using
used for pulls:
-------------------------------------
-$ git repo-config --get remote.origin.url
+$ git config --get remote.origin.url
/home/bob/myrepo
-------------------------------------
(The complete configuration created by git-clone is visible using
-"git repo-config -l", and the gitlink:git-repo-config[1] man page
+"git config -l", and the gitlink:git-config[1] man page
explains the meaning of each option.)
Git also keeps a pristine copy of Alice's master branch under the
Be careful with that last command: in addition to losing any changes
in the working directory, it will also remove all later commits from
this branch. If this branch is the only branch containing those
-commits, they will be lost. (Also, don't use "git reset" on a
-publicly-visible branch that other developers pull from, as git will
-be confused by history that disappears in this way.)
+commits, they will be lost. Also, don't use "git reset" on a
+publicly-visible branch that other developers pull from, as it will
+force needless merges on other developers to clean up the history.
+If you need to undo changes that you have pushed, use gitlink:git-revert[1]
+instead.
The git grep command can search for strings in any version of your
project, so
database, the index file, and a few other odds and ends that you'll
need to make the most of git.
-If you don't want to consider with that right away, a few other
+If you don't want to continue with that right away, a few other
digressions that may be interesting at this point are:
* gitlink:git-format-patch[1], gitlink:git-am[1]: These convert