-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:
$ man git-diff
------------------------------------------------
-It is a good idea to introduce yourself to git before doing any
-operation. The easiest way to do so is:
+It is a good idea to introduce yourself to git with your name and
+public email address before doing any operation. The easiest
+way to do so is:
------------------------------------------------
-$ cat >~/.gitconfig <<\EOF
-[user]
- name = Your Name Comes Here
- email = you@yourdomain.example.com
-EOF
+$ 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>...'
+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.
- 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.
-
- 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
made in each. To merge the changes made in experimental into master, run
------------------------------------------------
-$ git pull . experimental
+$ git merge experimental
------------------------------------------------
If the changes don't conflict, you're done. If there are conflicts,
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. For example, Alice could create a temporary branch just to
-track Bob's changes, without merging them with her own, 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, Alice can perform the first operation alone using the
+"git fetch" command without merging them with her own branch,
+using:
-------------------------------------
-$ git fetch /home/bob/myrepo master:bob-incoming
+$ git fetch bob
-------------------------------------
-which fetches the changes from Bob's master branch into a new branch
-named bob-incoming. 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-incoming
+$ 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
-could pull the changes into her master branch:
+After examining those changes, Alice
+could merge the changes into her master branch:
-------------------------------------
-$ git checkout master
-$ git pull . bob-incoming
+$ git merge bob/master
-------------------------------------
-The last command is a pull from the "bob-incoming" 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 /home/bob/myrepo master:bob-incoming
+$ git pull . remotes/bob/master
-------------------------------------
-This is just like the "git pull /home/bob/myrepo master" that we saw
-before, except that it also stores the unmerged changes from bob's
-master branch in bob-incoming 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
-/home/bob/myrepo
+$ git config --get remote.origin.url
+/home/alice/project
-------------------------------------
(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