1 files changed, 404 insertions, 0 deletions
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
new file mode 100644
index 0000000..fa79b01
--- /dev/null
+++ b/Documentation/tutorial.txt
@@ -0,0 +1,404 @@
+A tutorial introduction to git
+==============================
+
+This tutorial explains how to import a new project into git, make
+changes to it, and share changes with other developers.
+
+First, note that you can get documentation for a command such as "git
+diff" with:
+
+------------------------------------------------
+$ man git-diff
+------------------------------------------------
+
+Importing a new project
+-----------------------
+
+Assume you have a tarball project.tar.gz with your initial work.  You
+can place it under git revision control as follows.
+
+------------------------------------------------
+$ tar xzf project.tar.gz
+$ cd project
+$ git init-db
+------------------------------------------------
+
+Git will reply
+
+------------------------------------------------
+defaulting to local storage area
+------------------------------------------------
+
+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
+
+------------------------------------------------
+$ git add .
+------------------------------------------------
+
+Finally,
+
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
+
+will prompt you for a commit message, then record the current state
+of all the files to the repository.
+
+Try modifying some files, then run
+
+------------------------------------------------
+$ git diff
+------------------------------------------------
+
+to review your changes.  When you're done,
+
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
+
+will again prompt your for a message describing the change, and then
+record the new versions of the modified files.
+
+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
+thorough description.  Tools that turn commits into email, for
+example, use the first line on the Subject line and the rest of the
+commit in the body.
+
+To add a new file, first create the file, then
+
+------------------------------------------------
+$ git add path/to/new/file
+------------------------------------------------
+
+then commit as usual.  No special command is required when removing a
+file; just remove it, then commit.
+
+At any point you can view the history of your changes using
+
+------------------------------------------------
+$ git whatchanged
+------------------------------------------------
+
+If you also want to see complete diffs at each step, use
+
+------------------------------------------------
+$ git whatchanged -p
+------------------------------------------------
+
+Managing branches
+-----------------
+
+A single git repository can maintain multiple branches of
+development.  To create a new branch named "experimental", use
+
+------------------------------------------------
+$ git branch experimental
+------------------------------------------------
+
+If you now run
+
+------------------------------------------------
+$ git branch
+------------------------------------------------
+
+you'll get a list of all existing branches:
+
+------------------------------------------------
+  experimental
+* master
+------------------------------------------------
+
+The "experimental" branch is the one you just created, and the
+"master" branch is a default branch that was created for you
+automatically.  The asterisk marks the branch you are currently on;
+type
+
+------------------------------------------------
+$ git checkout experimental
+------------------------------------------------
+
+to switch to the experimental branch.  Now edit a file, commit the
+change, and switch back to the master branch:
+
+------------------------------------------------
+(edit file)
+$ git commit -a
+$ git checkout master
+------------------------------------------------
+
+Check that the change you made is no longer visible, since it was
+made on the experimental branch and you're back on the master branch.
+
+You can make a different change on the master branch:
+
+------------------------------------------------
+(edit file)
+$ git commit -a
+------------------------------------------------
+
+at this point the two branches have diverged, with different changes
+made in each.  To merge the changes made in the two branches, run
+
+------------------------------------------------
+$ git pull . experimental
+------------------------------------------------
+
+If the changes don't conflict, you're done.  If there are conflicts,
+markers will be left in the problematic files showing the conflict;
+
+------------------------------------------------
+$ git diff
+------------------------------------------------
+
+will show this.  Once you've edited the files to resolve the
+conflicts,
+
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
+
+will commit the result of the merge. Finally,
+
+------------------------------------------------
+$ gitk
+------------------------------------------------
+
+will show a nice graphical representation of the resulting history.
+
+If you develop on a branch crazy-idea, then regret it, you can always
+delete the branch with
+
+-------------------------------------
+$ git branch -D crazy-idea
+-------------------------------------
+
+Branches are cheap and easy, so this is a good way to try something
+out.
+
+Using git for collaboration
+---------------------------
+
+Suppose that Alice has started a new project with a git repository in
+/home/alice/project, and that Bob, who has a home directory on the
+same machine, wants to contribute.
+
+Bob begins with:
+
+------------------------------------------------
+$ git clone /home/alice/project myrepo
+------------------------------------------------
+
+This creates a new directory "myrepo" containing a clone of Alice's
+repository.  The clone is on an equal footing with the original
+project, posessing its own copy of the original project's history.
+
+Bob then makes some changes and commits them:
+
+------------------------------------------------
+(edit files)
+$ git commit -a
+(repeat as necessary)
+------------------------------------------------
+
+When he's ready, he tells Alice to pull changes from the repository
+at /home/bob/myrepo.  She does this with:
+
+------------------------------------------------
+$ cd /home/alice/project
+$ git pull /home/bob/myrepo
+------------------------------------------------
+
+This actually pulls changes from the branch in Bob's repository named
+"master".  Alice could request a different branch by adding the name
+of the branch to the end of the git pull command line.
+
+This merges Bob's changes into her repository; "git whatchanged" will
+now show the new commits.  If Alice has made her own changes in the
+meantime, then Bob's changes will be merged in, and she will need to
+manually fix any conflicts.
+
+A more cautious Alice might wish to examine Bob's changes before
+pulling them.  She can do this by creating a temporary branch just
+for the purpose of studying Bob's changes:
+
+-------------------------------------
+$ git fetch /home/bob/myrepo master:bob-incoming
+-------------------------------------
+
+which fetches the changes from Bob's master branch into a new branch
+named bob-incoming.  (Unlike git pull, git fetch just fetches a copy
+of Bob's line of development without doing any merging).  Then
+
+-------------------------------------
+$ git whatchanged -p master..bob-incoming
+-------------------------------------
+
+shows a list of all the changes that Bob made since he branched from
+Alice's master branch.
+
+After examing those changes, and possibly fixing things, Alice can
+pull the changes into her master branch:
+
+-------------------------------------
+$ git checkout master
+$ git pull . bob-incoming
+-------------------------------------
+
+The last command is a pull from the "bob-incoming" branch in Alice's
+own repository.
+
+Later, Bob can update his repo with Alice's latest changes using
+
+-------------------------------------
+$ git pull
+-------------------------------------
+
+Note that he doesn't need to give the path to Alice's repository;
+when Bob cloned Alice's repository, git stored the location of her
+repository in the file .git/remotes/origin, and that location is used
+as the default for pulls.
+
+Bob may also notice a branch in his repository that he didn't create:
+
+-------------------------------------
+$ git branch
+* master
+  origin
+-------------------------------------
+
+The "origin" branch, which was created automatically by "git clone",
+is a pristine copy of Alice's master branch; Bob should never commit
+to it.
+
+If Bob later decides to work from a different host, he can still
+perform clones and pulls using the ssh protocol:
+
+-------------------------------------
+$ git clone alice.org:/home/alice/project myrepo
+-------------------------------------
+
+Alternatively, git has a native protocol, or can use rsync or http;
+see gitlink: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
+link:cvs-migration.html[git for CVS users].
+
+Keeping track of history
+------------------------
+
+Git history is represented as a series of interrelated commits.  The
+most recent commit in the currently checked-out branch can always be
+referred to as HEAD, and the "parent" of any commit can always be
+referred to by appending a caret, "^", to the end of the name of the
+commit.  So, for example,
+
+-------------------------------------
+git diff HEAD^ HEAD
+-------------------------------------
+
+shows the difference between the most-recently checked-in state of
+the tree and the previous state, and
+
+-------------------------------------
+git diff HEAD^^ HEAD^
+-------------------------------------
+
+shows the difference between that previous state and the state two
+commits ago.  Also, HEAD~5 can be used as a shorthand for HEAD{caret}{caret}{caret}{caret}{caret},
+and more generally HEAD~n can refer to the nth previous commit.
+Commits representing merges have more than one parent, and you can
+specify which parent to follow in that case; see
+gitlink:git-rev-parse[1].
+
+The name of a branch can also be used to refer to the most recent
+commit on that branch; so you can also say things like
+
+-------------------------------------
+git diff HEAD experimental
+-------------------------------------
+
+to see the difference between the most-recently committed tree in
+the current branch and the most-recently committed tree in the
+experimental branch.
+
+But you may find it more useful to see the list of commits made in
+the experimental branch but not in the current branch, and
+
+-------------------------------------
+git whatchanged HEAD..experimental
+-------------------------------------
+
+will do that, just as
+
+-------------------------------------
+git whatchanged experimental..HEAD
+-------------------------------------
+
+will show the list of commits made on the HEAD but not included in
+experimental.
+
+You can also give commits convenient names of your own: after running
+
+-------------------------------------
+$ git-tag v2.5 HEAD^^
+-------------------------------------
+
+you can refer to HEAD^^ 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.
+
+You can revisit the old state of a tree, and make further
+modifications if you wish, using git branch: the command
+
+-------------------------------------
+$ git branch stable-release v2.5
+-------------------------------------
+
+will create a new branch named "stable-release" starting from the
+commit which you tagged with the name v2.5.
+
+You can reset the state of any branch to an earlier commit at any
+time with
+
+-------------------------------------
+$ git reset --hard v2.5
+-------------------------------------
+
+This will remove all later commits from this branch and reset the
+working tree to the state it had when the given commit was made.  If
+this branch is the only branch containing the later commits, those
+later changes will be lost.  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.
+
+Next Steps
+----------
+
+Some good commands to explore next:
+
+  * gitlink:git-diff[1]: This flexible command does much more than
+    we've seen in the few examples above.
+
+  * gitlink:git-format-patch[1], gitlink: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
+    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
+    smart enough to perform a close-to-optimal search even in the
+    case of complex non-linear history with lots of merged branches.
+
+Other good starting points include link:everyday.html[Everday GIT
+with 20 Commands Or So] and link:cvs-migration.html[git for CVS
+users].  Also, link:core-tutorial.html[A short git tutorial] gives an
+introduction to lower-level git commands for advanced users and
+developers.