-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
------------------------------------------------
------------------------------------------------
$ tar xzf project.tar.gz
$ cd project
-$ git init-db
+$ git init
------------------------------------------------
Git will reply
------------------------------------------------
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 with (notice the dot '.'
-that means the current directory):
+directory created, named ".git".
+
+Next, tell git to take a snapshot of the contents of all files under the
+current directory (note the '.'), with linkgit: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 linkgit: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.
-Try modifying some files, then run
+Making changes
+--------------
+
+Modify some files, then add their updated contents to the index:
------------------------------------------------
-$ git diff
+$ git add file1 file2 file3
+------------------------------------------------
+
+You are now ready to commit. You can see what is about to be committed
+using linkgit:git-diff[1] with the --cached option:
+
+------------------------------------------------
+$ git diff --cached
------------------------------------------------
-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:
+(Without --cached, linkgit: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 linkgit: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 file...
$ git commit
------------------------------------------------
This will again prompt your for a message describing the change, and then
-record the new versions of the files you listed. It is cumbersome
-to list all files and you can say `git commit -a` (which stands for 'all')
-instead of running `git add` beforehand.
+record a new version of the project.
+
+Alternatively, instead of running `git add` beforehand, you can use
------------------------------------------------
$ git commit -a
------------------------------------------------
+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)
line summarizing the change, followed by a blank line and then a more
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:
+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.
-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.
-
- 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 command line.
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 linkgit:git-config[1] man page
explains the meaning of each option.)
Git also keeps a pristine copy of Alice's master branch under the
-------------------------------------
Alternatively, git has a native protocol, or can use rsync or http;
-see gitlink:git-pull[1] for details.
+see linkgit:git-pull[1] for details.
Git can also be used in a CVS-like mode, with a central repository
-that various users push changes to; see gitlink:git-push[1] and
+that various users push changes to; see linkgit:git-push[1] and
link:cvs-migration.html[git for CVS users].
Exploring history
you can refer to 1b2e1d63ff by the name "v2.5". If you intend to
share this name with other people (for example, to identify a release
version), you should create a "tag" object, and perhaps sign it; see
-gitlink:git-tag[1] for details.
+linkgit:git-tag[1] for details.
Any git command that needs to know a commit can take any of these
names. For example:
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 linkgit: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
+ * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert
series of git commits into emailed patches, and vice versa,
useful for projects such as the linux kernel which rely heavily
on emailed patches.
- * gitlink:git-bisect[1]: When there is a regression in your
+ * linkgit:git-bisect[1]: When there is a regression in your
project, one way to track down the bug is by searching through
the history to find the exact commit that's to blame. Git bisect
can help you perform a binary search for that commit. It is