[or-cvs] [githax/master] Make the Howto document generic.
Nick Mathewson
nickm at seul.org
Thu Apr 30 04:35:58 UTC 2009
Author: Nick Mathewson <nickm at torproject.org>
Date: Thu, 30 Apr 2009 00:35:18 -0400
Subject: Make the Howto document generic.
Commit: ca588321fb0c4de39ff44d53be8ca51ad08fe0d2
Howto-tor.txt and Howto-thandy are gone. Howto.txt now refers to
"a project" and "software", and the identifier PROJECT.
---
doc/Howto-thandy.txt | 388 -------------------------------------------------
doc/Howto-tor.txt | 362 ----------------------------------------------
doc/Howto.txt | 391 ++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 391 insertions(+), 750 deletions(-)
delete mode 100644 doc/Howto-thandy.txt
delete mode 100644 doc/Howto-tor.txt
create mode 100644 doc/Howto.txt
diff --git a/doc/Howto-thandy.txt b/doc/Howto-thandy.txt
deleted file mode 100644
index 132ff32..0000000
--- a/doc/Howto-thandy.txt
+++ /dev/null
@@ -1,388 +0,0 @@
-How to use Git to work on Thandy
-================================
-
-Before you start
-----------------
-
-First, read and understand the Git Tutorial (man gittutorial) and maybe
-gittutorial-2. It is very short and helpful.
-
-If you have more time, read the Git user manual.
-
-
-
-If you know how to use Git
---------------------------
-
-If you know how to use Git, all you need to know is that the official
-Thandy repository is at
- git://git.torproject.org/git/thandy
-and that if you're updating the official repository (we will tell you
-if you're such a person), ssh access is at:
- ssh://git.torproject.org/var/cache/git/thandy
-
-There. Done. Go use git; you know How.
-
-If you don't know how to use Git: Setting up your git
------------------------------------------------------
-
-First, make sure you have Git 1.5.x or later installed. Using earlier
-versions should probably still work, but I don't have experience with them,
-so I can't help you.
-
-Second, setup Git so that it knows how to attribute your commits. This is
-done using git config:
-
------
-% git config --global user.name "Nick Mathewson"
-% git config --global user.email "nickm at torproject.org"
------
-
-except you shouldn't claim to be me. Make sure to tell us what you
-set there if you have ever committed to svn, so we can attribute those svn
-commits to you.
-
-This should add the following lines into your ~/.gitconfig file:
-
-------------------------------
-[user]
- name = Nick Mathewson
- email = nickm at torproject.org
-------------------------------
-
-If you already have set up a global .gitconfig, but you want to use a
-different name or email for Thandy, you can override the global user settings
-by running 'git config' without the '--global' argument from inside a
-repository. Before you can do that, though, you'll need to fetch Thandy's
-repository.
-
-If you don't know how to use Git: Getting started
--------------------------------------------------
-
-Now we can fetch the repository! I like to do all my development under
-~/src/projectname, so I'll start with:
-
------
-% cd src
-% git clone git://git.torproject.org/git/thandy
------
-
-There's now a '~/src/thandy' directory with the latest Thandy in it. I
-can build and edit and mess with this source to my heart's content.
-
-All the Git metadata for my project lives in ~/src/thandy/.git , so it's
-safe to move your checkout around wherever or rename it if you don't
-like it.
-
-Let's mess around with the repository a bit.
-
------
-% git status
-# On branch master
-nothing to commit (working directory clean)
------
-
-This means we're on the 'master' branch, with no local changes. The
-master branch of a repository is like the 'trunk' branch in Subversion.
-
-In Git, branches are cheap and local. It's good practice to start a new
-cheap local branch whenever you start working on a new feature or set of
-features. This makes our commits neater, and makes it easier to hold
-off on pushing work into the mainline.
-
-Let's pretend we're adding FTP support to Thandy. We'll want to make a
-new branch to work on it, like this:
-
------
-% git checkout -b ftp
------
-
-The checkout command switches branches. Using the '-b' switch makes it
-create a new branch. By default, it starts the branch based on the
-current branch. We could also have said 'git checkout -b ftp master' to
-make it start at the master branch explicitly.
-
-Anyway, let's see if it worked!
-
------
-% git branch
-* ftp
- master
------
-
-Yup. There are two branches, and we're on a branch called 'ftp'.
-
-You can do a lot of other things with the 'git branch' command. For
-more information on git branch, just type 'git help branch'. For that
-matter, you can get help on any git command with 'git help commandname'.
-
-Now let's say we have work to commit on our branch. The easiest way to
-commit all of our changes is to say:
-
------
-% git commit -a
------
-
-This asks us for a commit message, and commits every changed file.
-
-If we only want to commit some files, or if we want to add new files
-that were not previously in the repository, we use the 'git add' command
-to tell Git what to commit, and then we use 'git commit' without the
-'-a' flag to commit them.
-
------
-% git add changedFile1
-% git add changedFile2
-% git add newfile
-% git commit
------
-
-The files that have been added but not yet committed are in a structure
-called the "index". You can change your mind about a file you have
-added to the index with 'git reset'. You can throw away all local
-non-added changes to a file with 'git checkout'.
-
-
-----
-% git add file1
-% git add file2
-
- (Oh wait, I don't want to commit file2!)
-% git reset file2
-file2: needs update
-% git commit
-% git status
-# On branch ftp
-# Changed but not updated:
-# (use "git add <file>..." to update what will be committed)
-#
-# modified: file2
-#
-no changes added to commit (use "git add" and/or "git commit -a")
-
-
- (On second thought, I don't want my changes to file2 at all.)
-% git checkout file2
-----
-
-There are more options to reset, add, and checkout that you will
-eventually want to know about, but that should be enough for now.
-
-To see what changes you've made on the ftp branch, you can do
-
-----
-% git log master..ftp
-----
-
-You can just say "git log master.." if you're on the ftp branch. If you
-want to see the associated patches one by one, along with the log, say
-'git log -p master..". (The 'master..ftp' notation means, "Show me
-every commit that's in ftp but not in master.")
-
-If you say 'git diff master' instead of 'git log master..', you can
-see the changes you've made in unified diff format. You can also say
-'git diff' to see the changes that are in your working directory but not
-in your index,
-'git diff --cached' to see the changes in your index, and
-'git diff HEAD' to see all the changes since your last commit.
-
-If you want to generate a set of patches to mail to the maintainer,
-use 'git format-patch' instead of diff or log.
-
-A NOTE ON COMMIT MESSAGES: Many Git tools (like the commit emails, and
-the shortlogs) will give better output if commit messages come in a
-special format. The first line of the commit message should be a short
-"Subject", summarizing the contents of the commit. There should then be
-a blank line, and the rest of your commit message, in as many paragraphs
-as you want.
-
-
-Staying up to date.
--------------------
-
-
-While you work, there's an upstream repository that's changing too.
-You can update your copy of it with
-
------
-% git fetch git://git.torproject.org/git/thandy
------
-
-That's pretty verbose. Fortunately, since you started by cloning from
-that URL, it has the alias "origin":
-
------
-% git fetch origin
------
-
-You can use the 'git remote' command to create aliases for other remote
-repositories. Run 'git help remote' to learn more.
-
-You might have noticed that after you fetched the origin, you didn't
-see any changes in your branches. That's because "fetch" by default
-only downloads things; it doesn't merge them. To fetch and merge at the
-same time, use "git pull" in the master branch:
-
-----
-% git checkout master
-% git pull
-----
-
-Assuming there are no changes in your master branch, this will cause a
-'fast-forward' merge: all the changes from upstream get appended to your
-history, and the head of the 'master' branch now just points at them.
-
-If there are changes, git will try to merge for you.
-
-`git pull` is essentially just `git fetch` followed by `git merge`. If you
-already have work that is based on a remote branch, you may want to "rebase"
-instead of letting `git merge` create an implicit merge commit:
-
------
-% git fetch origin
-% git rebase origin/master
------
-
-(Rebase with caution! See notes on rebasing below.)
-
-Now, what should we do about our local ftp branch? It's still based on
-the pre-pull version. We have a few choices.
-
-1. We could let it stay based on the old version until we're ready to
- merge it into our master branch, or send it in as a patch, or
- whatever.
-
-2. We could merge in changes from the master branch:
-
------
-% git checkout ftp
-% git merge master
------
-
- This might create a new merge commit, as appropriate.
-
-3. We could "rebase" the ftp branch to the head of the master. This, in
- effect, makes a new ftp branch against the head of master, and copies
- over all the commits from the old ftp branch into new commits onto
- the new ftp branch.
-
------
-% git checkout ftp
-% git rebase master
------
-
- This is a fine thing to do on a _local_ branch, but you should never
- do it (or any other kind of "history rewriting") on a branch you have
- published to others.
-
-
-
-Sharing with others.
---------------------
-
-It's nice to have a public repository that other people can pull from.
-You can set one up pretty easily if you have a Unix machine, or an
-account on Moria.
-
-The writeup in the Git manual at:
-
-http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories
-
-is really all you need to read here. If you have an account on Moria,
-just do:
-
------
-% mkdir ~/git
-% cd ~/git
-% git clone --bare /var/cache/git/thandy.git thandy.git
-% touch thandy.git/git-daemon-export-ok
------
-
-And now you have a new Git repository that other people can fetch from
-git://git.torproject.org/~USERNAME/git/thandy
-
-For you, that's ssh://git.torproject.org/~USERNAME/git/thandy : you can
-follow the instructions at
-
-http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#pushing-changes-to-a-public-repository
-
-to push branches to your public repository.
-
-
-If you don't have an account on Moria, see the rest of the documentation
-in that part of the Git manual. Or go use github: it's pretty neat.
-
-
-Merging from others
--------------------
-
-As mentioned above, you can specify additional remotes for your git
-repository. Let's say Nick has published his ftp branch, and you want to
-give it a shot. It is not yet ready to be merged to the master branch, so
-you cannot just pull from the master branch. Nick tells you his branch is
-called ftp, and his repository lives at
-git://git.torproject.org/~nickm/git/thandy.
-
-Now it's time for you to add a remote for nicks repository, get his
-published branches, and make a local branch that tracks his ftp branch:
-
------
-%git remote add nick git://git.torproject.org/~nickm/git/thandy
-%git fetch nick
-%git checkout -b nick_ftp nick/ftp
------
-
-This will have switched you to your new local branch nick_ftp, and you can
-build and test the ftp stuff that nick made. If you're done with testing,
-just type
-
------
-%git checkout master
------
-
-to go back to your master branch. Maybe, a few days later, Nick has made
-some changes that you would like to look at. First, you fetch his stuff
-again and switch to your local branch that tracks his ftp branch:
-
------
-%git fetch nick
-%git checkout nick_ftp
------
-
-git will tell you that there has been an update to the branch that you
-checked out. To get the new stuff in, and rebase any changes that you may
-have made in the meantime, type:
-
------
-%git rebase
------
-
-This fast-forwards the branch if you haven't made changes, or first
-applies the changes from nick's repository and the replays your changes on
-top of the result. If you then want to make a patch based on your changes
-to send to nick, it's easy. Use git format-patch (see above).
-
-If you want to actually merge his ftp branch into one of your other local
-branches called $branch, do this:
-
------
-%git checkout $branch
-%git merge nick_ftp
------
-
-Git will automatically merge nick_ftp into $branch.
-
-Further reading
----------------
-
-To see how the git folks do it:
-
-http://www.kernel.org/pub/software/scm/git/docs/howto/maintain-git.txt
-
-For a better understanding of how merging and rebasing work:
-
-http://www.kernel.org/pub/software/scm/git/docs/git-merge.html
-http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html
-
-And the Git tutorial which is also a good guide to get started:
-http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
diff --git a/doc/Howto-tor.txt b/doc/Howto-tor.txt
deleted file mode 100644
index 5392ab1..0000000
--- a/doc/Howto-tor.txt
+++ /dev/null
@@ -1,362 +0,0 @@
-How to use Git to work on Tor
-=============================
-
-TODO: Find some way to unify this with TODO-thandy.txt again.
-
-Before you start
-----------------
-
-First, read and understand the Git Tutorial (man gittutorial) and maybe
-gittutorial-2. It is very short and helpful.
-
-If you have more time, read the Git user manual.
-
-You should make sure that you have a decent version of Git installed. In
-practice, this is 1.5.x or later. Older versions of Git are much harder to
-use.
-
-If you know how to use Git
---------------------------
-
-If you know how to use Git, all you need to know is that the official
-Tor repository is at
- git://git.torproject.org/git/tor
-and that if you're updating the official repository (we will tell you
-if you're such a person), ssh access is at:
- ssh://git.torproject.org/git/tor
-
-There. Done. Go use git; you know How.
-
-If you don't know how to use Git: Setting up your git
------------------------------------------------------
-
-First, make sure you have Git 1.5.x or later installed. Using earlier
-versions should probably still work, but I don't have experience with them,
-so I can't help you.
-
-Second, edit your ~/.gitconfig file so that Git commits from you have a
-useful name attached. It should look something like
-
-------------------------------
-[user]
- name = Nick Mathewson
- email = nickm at torproject.org
-------------------------------
-
-except that you shouldn't claim to be me. Make sure to tell us what you
-set there if you have ever committed to svn, so we can attribute those svn
-commits to you.
-
-
-If you don't know how to use Git: Getting started
--------------------------------------------------
-
-Now we can fetch the repository! I like to do all my development under
-~/src/projectname, so I'll start with:
-
------
-% cd src
-% git clone git://git.torproject.org/git/tor
------
-
-There's now a '~/src/tor' directory with the latest Tor in it. I
-can build and edit and mess with this source to my heart's content.
-
-All the Git metadata for the project lives in ~/src/tor/.git , so it's
-safe to move your checkout around wherever or rename it if you don't
-like it.
-
-Let's mess around with the repository a bit.
-
------
-% git status
-# On branch master
-nothing to commit (working directory clean)
------
-
-This means we're on the 'master' branch, with no local changes. The
-master branch of a repository is like the 'trunk' branch in Subversion.
-
-In Git, branches are cheap and local. It's good practice to start a new
-cheap local branch whenever you start working on a new feature or set of
-features. This makes our commits neater, and makes it easier to hold
-off on pushing work into the mainline.
-
-Let's pretend we're adding UDP support to Tor. We'll want to make a
-new branch to work on it, like this:
-
------
-% git checkout -b udp
------
-
-The checkout command switches branches. Using the '-b' switch makes it
-create a new branch. By default, it starts the branch based on the
-current branch. We could also have said 'git checkout -b udp master' to
-make it start at the master branch explicitly.
-
-Anyway, let's see if it worked!
-
------
-% git branch
-* udp
- master
------
-
-Yup. There are two branches, and we're on a branch called 'udp'.
-
-You can do a lot of other things with the 'git branch' command. For
-more information on git branch, just type 'git help branch'. For that
-matter, you can get help on any git command with 'git help commandname'.
-
-Now let's say we have work to commit on our branch. The easiest way to
-commit all of our changes is to say:
-
------
-% git commit -a
------
-
-This asks us for a commit message, and commits every changed file.
-
-If we only want to commit some files, or if we want to add new files
-that were not previously in the repository, we use the 'git add' command
-to tell Git what to commit, and then we use 'git commit' without the
-'-a' flag to commit them.
-
------
-% git add changedFile1
-% git add changedFile2
-% git add newfile
-% git commit
------
-
-The files that have been added but not yet committed are in a structure
-called the "index". You can change your mind about a file you have
-added to the index with 'git reset'. You can throw away all local
-non-added changes to a file with 'git checkout'.
-
-
-----
-% git add file1
-% git add file2
-
- (Oh wait, I don't want to commit file2!)
-% git reset file2
-file2: needs update
-% git commit
-% git status
-# On branch udp
-# Changed but not updated:
-# (use "git add <file>..." to update what will be committed)
-#
-# modified: file2
-#
-no changes added to commit (use "git add" and/or "git commit -a")
-
-
- (On second thought, I don't want my changes to file2 at all.)
-% git checkout file2
-----
-
-There are more options to reset, add, and checkout that you will
-eventually want to know about, but that should be enough for now.
-
-To see what changes you've made on the udp branch, you can do
-
-----
-% git log master..udp
-----
-
-You can just say "git log master.." if you're on the udp branch. If you
-want to see the associated patches one by one, along with the log, say
-'git log -p master..". (The 'master..udp' notation means, "Show me
-every commit that's in ftp but not in master.")
-
-If you say 'git diff master' instead of 'git log master..', you can
-see the changes you've made in unified diff format. You can also say
-'git diff' to see the changes that are in your working directory but not
-in your index,
-'git diff --cached' to see the changes in your index, and
-'git diff HEAD' to see all the changes since your last commit.
-
-If you want to generate a set of patches to mail to the maintainer,
-use 'git format-patch' instead of diff or log.
-
-A NOTE ON COMMIT MESSAGES: Many Git tools (like the commit emails, and
-the shortlogs) will give better output if commit messages come in a
-special format. The first line of the commit message should be a short
-"Subject", summarizing the contents of the commit. There should then be
-a blank line, and the rest of your commit message, in as many paragraphs
-as you want.
-
-
-Staying up to date.
--------------------
-
-
-While you work, there's an upstream repository that's changing too.
-You can update your copy of it with
-
------
-% git fetch git://git.torproject.org/git/tor
------
-
-That's pretty verbose. Fortunately, since you started by cloning from
-that URL, it has the alias "origin":
-
------
-% git fetch origin
------
-
-You can use the 'git remote' command to create aliases for other remote
-repositories. Run 'git help remote' to learn more.
-
-You might have noticed that after you fetched the origin, you didn't
-see any changes in your branches. That's because "fetch" by default
-only downloads things; it doesn't merge them. To fetch and merge at the
-same time, use "git pull" in the master branch:
-
-----
-% git checkout master
-% git pull
-----
-
-Assuming there are no changes in your master branch, this will cause a
-'fast-forward' merge: all the changes from upstream get appended to your
-history, and the head of the 'master' branch now just points at them.
-
-If there are changes, git will try to merge for you.
-
-Now, what should we do about our local ftp branch? It's still based on
-the pre-pull version. We have a few choices.
-
-1. We could let it stay based on the old version until we're ready to
- merge it into our master branch, or send it in as a patch, or
- whatever.
-
-2. We could merge in changes from the master branch:
-
------
-% git checkout ftp
-% git merge master
------
-
- This might create a new merge commit, as appropriate.
-
-3. We could "rebase" the ftp branch to the head of the master. This, in
- effect, makes a new ftp branch against the head of master, and copies
- over all the commits from the old ftp branch into new commits onto
- the new ftp branch.
-
------
-% git checkout ftp
-% git rebase master
------
-
- This is a fine thing to do on a _local_ branch, but you should never
- do it (or any other kind of "history rewriting") on a branch you have
- published to others.
-
-
-
-Sharing with others.
---------------------
-
-It's nice to have a public repository that other people can pull from.
-You can set one up pretty easily if you have a Unix machine, or an
-account on Moria.
-
-The writeup in the Git manual at:
-
-http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories
-
-is really all you need to read here. If you have an account on Moria,
-just do:
-
------
-% mkdir ~/git
-% cd ~/git
-% git clone --bare /var/cache/git/tor.git thor.git
-% touch tor.git/git-daemon-export-ok
------
-
-And now you have a new Git repository that other people can fetch from
-git://git.torproject.org/~USERNAME/git/tor
-
-For you, that's ssh://git.torproject.org/~USERNAME/git/tor : you can
-follow the instructions at
-
-http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#pushing-changes-to-a-public-repository
-
-to push branches to your public repository.
-
-
-If you don't have an account on Moria, see the rest of the documentation
-in that part of the Git manual. Or go use github: it's pretty neat.
-
-
-Merging from others
--------------------
-
-As mentioned above, you can specify additional remotes for your git
-repository. Let's say Nick has published his ftp branch, and you want to
-give it a shot. It is not yet ready to be merged to the master branch, so
-you cannot just pull from the master branch. Nick tells you his branch is
-called ftp, and his repository lives at
-git://git.torproject.org/~nickm/git/tor.
-
-Now it's time for you to add a remote for nicks repository, get his
-published branches, and make a local branch that tracks his ftp branch:
-
------
-%git remote add nick git://git.torproject.org/~nickm/git/tor
-%git fetch nick
-%git checkout -b nick_ftp nick/ftp
------
-
-This will have switched you to your new local branch nick_ftp, and you can
-build and test the ftp stuff that nick made. If you're done with testing,
-just type
-
------
-%git checkout master
------
-
-to go back to your master branch. Maybe, a few days later, Nick has made
-some changes that you would like to look at. First, you fetch his stuff
-again and switch to your local branch that tracks his ftp branch:
-
------
-%git fetch nick
-%git checkout nick_ftp
------
-
-git will tell you that there has been an update to the branch that you
-checked out. To get the new stuff in, and rebase any changes that you may
-have made in the meantime, type:
-
------
-%git rebase
------
-
-This fast-forwards the branch if you haven't made changes, or first
-applies the changes from nick's repository and the replays your changes on
-top of the result. If you then want to make a patch based on your changes
-to send to nick, it's easy. Use git format-patch (see above).
-
-If you want to actually merge his ftp branch into one of your other local
-branches called $branch, do this:
-
------
-%git checkout $branch
-%git merge nick_ftp
------
-
-Git will automatically merge nick_ftp into $branch.
-
-Further reading
----------------
-
-To see how the git folks do it:
-
-http://www.kernel.org/pub/software/scm/git/docs/howto/maintain-git.txt
-
diff --git a/doc/Howto.txt b/doc/Howto.txt
new file mode 100644
index 0000000..07d55bb
--- /dev/null
+++ b/doc/Howto.txt
@@ -0,0 +1,391 @@
+How to use Git to work with Tor software
+========================================
+
+Before you start
+----------------
+
+First, read and understand the Git Tutorial (man gittutorial) and maybe
+gittutorial-2. It is very short and helpful.
+
+If you have more time, read the Git user manual.
+
+
+
+If you know how to use Git
+--------------------------
+
+If you know how to use Git, all you need to know is that the official
+Thandy repository is at
+ git://git.torproject.org/git/PROJECT
+and that if you're updating the official repository (we will tell you
+if you're such a person), ssh access is at:
+ ssh://git.torproject.org/var/cache/git/PROJECT
+
+(For the main Tor software, PROJECT is "tor". For Thandy, PROJECT
+is "thandy". And so on.)
+
+There. Done. Go use git; you know How.
+
+If you don't know how to use Git: Setting up your git
+-----------------------------------------------------
+
+First, make sure you have Git 1.5.x or later installed. Using earlier
+versions should probably still work, but I don't have experience with them,
+so I can't help you.
+
+Second, setup Git so that it knows how to attribute your commits. This is
+done using git config:
+
+-----
+% git config --global user.name "Nick Mathewson"
+% git config --global user.email "nickm at torproject.org"
+-----
+
+except you shouldn't claim to be me. Make sure to tell us what you
+set there if you have ever committed to svn, so we can attribute those svn
+commits to you.
+
+This should add the following lines into your ~/.gitconfig file:
+
+------------------------------
+[user]
+ name = Nick Mathewson
+ email = nickm at torproject.org
+------------------------------
+
+If you already have set up a global .gitconfig, but you want to use a
+different name or email for this repository, you can override the global user
+settings by running 'git config' without the '--global' argument from inside
+a repository. Before you can do that, though, you'll need to fetch the
+repository.
+
+If you don't know how to use Git: Getting started
+-------------------------------------------------
+
+Now we can fetch the repository! I like to do all my development under
+~/src/projectname, so I'll start with:
+
+-----
+% cd src
+% git clone git://git.torproject.org/git/PROJECT
+-----
+
+There's now a '~/src/PROJECT' directory with the latest version in it. I
+can build and edit and mess with this source to my heart's content.
+
+All the Git metadata for my project lives in ~/src/PROJECT/.git , so it's
+safe to move your checkout around wherever or rename it if you don't
+like it.
+
+Let's mess around with the repository a bit.
+
+-----
+% git status
+# On branch master
+nothing to commit (working directory clean)
+-----
+
+This means we're on the 'master' branch, with no local changes. The
+master branch of a repository is like the 'trunk' branch in Subversion.
+
+In Git, branches are cheap and local. It's good practice to start a new
+cheap local branch whenever you start working on a new feature or set of
+features. This makes our commits neater, and makes it easier to hold
+off on pushing work into the mainline.
+
+Let's pretend we're adding FTP support to the software. We'll want to make a
+new branch to work on it, like this:
+
+-----
+% git checkout -b ftp
+-----
+
+The checkout command switches branches. Using the '-b' switch makes it
+create a new branch. By default, it starts the branch based on the
+current branch. We could also have said 'git checkout -b ftp master' to
+make it start at the master branch explicitly.
+
+Anyway, let's see if it worked!
+
+-----
+% git branch
+* ftp
+ master
+-----
+
+Yup. There are two branches, and we're on a branch called 'ftp'.
+
+You can do a lot of other things with the 'git branch' command. For
+more information on git branch, just type 'git help branch'. For that
+matter, you can get help on any git command with 'git help commandname'.
+
+Now let's say we have work to commit on our branch. The easiest way to
+commit all of our changes is to say:
+
+-----
+% git commit -a
+-----
+
+This asks us for a commit message, and commits every changed file.
+
+If we only want to commit some files, or if we want to add new files
+that were not previously in the repository, we use the 'git add' command
+to tell Git what to commit, and then we use 'git commit' without the
+'-a' flag to commit them.
+
+-----
+% git add changedFile1
+% git add changedFile2
+% git add newfile
+% git commit
+-----
+
+The files that have been added but not yet committed are in a structure
+called the "index". You can change your mind about a file you have
+added to the index with 'git reset'. You can throw away all local
+non-added changes to a file with 'git checkout'.
+
+
+----
+% git add file1
+% git add file2
+
+ (Oh wait, I don't want to commit file2!)
+% git reset file2
+file2: needs update
+% git commit
+% git status
+# On branch ftp
+# Changed but not updated:
+# (use "git add <file>..." to update what will be committed)
+#
+# modified: file2
+#
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
+ (On second thought, I don't want my changes to file2 at all.)
+% git checkout file2
+----
+
+There are more options to reset, add, and checkout that you will
+eventually want to know about, but that should be enough for now.
+
+To see what changes you've made on the ftp branch, you can do
+
+----
+% git log master..ftp
+----
+
+You can just say "git log master.." if you're on the ftp branch. If you
+want to see the associated patches one by one, along with the log, say
+'git log -p master..". (The 'master..ftp' notation means, "Show me
+every commit that's in ftp but not in master.")
+
+If you say 'git diff master' instead of 'git log master..', you can
+see the changes you've made in unified diff format. You can also say
+'git diff' to see the changes that are in your working directory but not
+in your index,
+'git diff --cached' to see the changes in your index, and
+'git diff HEAD' to see all the changes since your last commit.
+
+If you want to generate a set of patches to mail to the maintainer,
+use 'git format-patch' instead of diff or log.
+
+A NOTE ON COMMIT MESSAGES: Many Git tools (like the commit emails, and
+the shortlogs) will give better output if commit messages come in a
+special format. The first line of the commit message should be a short
+"Subject", summarizing the contents of the commit. There should then be
+a blank line, and the rest of your commit message, in as many paragraphs
+as you want.
+
+
+Staying up to date.
+-------------------
+
+
+While you work, there's an upstream repository that's changing too.
+You can update your copy of it with
+
+-----
+% git fetch git://git.torproject.org/git/PROJECT
+-----
+
+That's pretty verbose. Fortunately, since you started by cloning from
+that URL, it has the alias "origin":
+
+-----
+% git fetch origin
+-----
+
+You can use the 'git remote' command to create aliases for other remote
+repositories. Run 'git help remote' to learn more.
+
+You might have noticed that after you fetched the origin, you didn't
+see any changes in your branches. That's because "fetch" by default
+only downloads things; it doesn't merge them. To fetch and merge at the
+same time, use "git pull" in the master branch:
+
+----
+% git checkout master
+% git pull
+----
+
+Assuming there are no changes in your master branch, this will cause a
+'fast-forward' merge: all the changes from upstream get appended to your
+history, and the head of the 'master' branch now just points at them.
+
+If there are changes, git will try to merge for you.
+
+`git pull` is essentially just `git fetch` followed by `git merge`. If you
+already have work that is based on a remote branch, you may want to "rebase"
+instead of letting `git merge` create an implicit merge commit:
+
+-----
+% git fetch origin
+% git rebase origin/master
+-----
+
+(Rebase with caution! See notes on rebasing below.)
+
+Now, what should we do about our local ftp branch? It's still based on
+the pre-pull version. We have a few choices.
+
+1. We could let it stay based on the old version until we're ready to
+ merge it into our master branch, or send it in as a patch, or
+ whatever.
+
+2. We could merge in changes from the master branch:
+
+-----
+% git checkout ftp
+% git merge master
+-----
+
+ This might create a new merge commit, as appropriate.
+
+3. We could "rebase" the ftp branch to the head of the master. This, in
+ effect, makes a new ftp branch against the head of master, and copies
+ over all the commits from the old ftp branch into new commits onto
+ the new ftp branch.
+
+-----
+% git checkout ftp
+% git rebase master
+-----
+
+ This is a fine thing to do on a _local_ branch, but you should never
+ do it (or any other kind of "history rewriting") on a branch you have
+ published to others.
+
+
+
+Sharing with others.
+--------------------
+
+It's nice to have a public repository that other people can pull from.
+You can set one up pretty easily if you have a Unix machine, or an
+account on Moria.
+
+The writeup in the Git manual at:
+
+http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories
+
+is really all you need to read here. If you have an account on Moria,
+just do:
+
+-----
+% mkdir ~/git
+% cd ~/git
+% git clone --bare /git/PROJECT.git PROJECT.git
+% touch PROJECT.git/git-daemon-export-ok
+-----
+
+And now you have a new Git repository that other people can fetch from
+git://git.torproject.org/~USERNAME/git/PROJECT
+
+For you, that's ssh://git.torproject.org/~USERNAME/git/PROJECT : you can
+follow the instructions at
+
+http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#pushing-changes-to-a-public-repository
+
+to push branches to your public repository.
+
+
+If you don't have an account on Moria, see the rest of the documentation
+in that part of the Git manual. Or go use github: it's pretty neat.
+
+
+Merging from others
+-------------------
+
+As mentioned above, you can specify additional remotes for your git
+repository. Let's say Nick has published his ftp branch, and you want to
+give it a shot. It is not yet ready to be merged to the master branch, so
+you cannot just pull from the master branch. Nick tells you his branch is
+called ftp, and his repository lives at
+git://git.torproject.org/~nickm/git/PROJECT.
+
+Now it's time for you to add a remote for nicks repository, get his
+published branches, and make a local branch that tracks his ftp branch:
+
+-----
+%git remote add nick git://git.torproject.org/~nickm/git/PROJECT
+%git fetch nick
+%git checkout -b nick_ftp nick/ftp
+-----
+
+This will have switched you to your new local branch nick_ftp, and you can
+build and test the ftp stuff that nick made. If you're done with testing,
+just type
+
+-----
+%git checkout master
+-----
+
+to go back to your master branch. Maybe, a few days later, Nick has made
+some changes that you would like to look at. First, you fetch his stuff
+again and switch to your local branch that tracks his ftp branch:
+
+-----
+%git fetch nick
+%git checkout nick_ftp
+-----
+
+git will tell you that there has been an update to the branch that you
+checked out. To get the new stuff in, and rebase any changes that you may
+have made in the meantime, type:
+
+-----
+%git rebase
+-----
+
+This fast-forwards the branch if you haven't made changes, or first
+applies the changes from nick's repository and the replays your changes on
+top of the result. If you then want to make a patch based on your changes
+to send to nick, it's easy. Use git format-patch (see above).
+
+If you want to actually merge his ftp branch into one of your other local
+branches called $branch, do this:
+
+-----
+%git checkout $branch
+%git merge nick_ftp
+-----
+
+Git will automatically merge nick_ftp into $branch.
+
+Further reading
+---------------
+
+To see how the git folks do it:
+
+http://www.kernel.org/pub/software/scm/git/docs/howto/maintain-git.txt
+
+For a better understanding of how merging and rebasing work:
+
+http://www.kernel.org/pub/software/scm/git/docs/git-merge.html
+http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html
+
+And the Git tutorial which is also a good guide to get started:
+http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
--
1.5.6.5
More information about the tor-commits
mailing list