--- a/DESIGN.txt
+++ b/DESIGN.txt
@@ -1,53 +1,57 @@
-GitHug, the Hg-Git Plugin
+Hg-Git Plugin Design Notes
+==========================
+
+This plugin is designed to allow you to push to a Git server over the Git protocol and to pull from a Git based project.  All data is stored in Hg native format with a mapping table.  People collaborating in Git should not  even be able to tell that you're using Hg to collaborate on their project (except for the '--HG--' section added to commit message). 
+
+Nothing should need to be kept in the Git format - you should be able to run 'hg gclear' at any time to wipe out the Git directory and everything can be rebuilt losslessly from the existing Hg data - it is a cache only.
+
+We are using the Dulwich library, which I've modified quite a bit - I'll have to get these changes back upstream at some point.
+
+I've been adding 'TODO' comments all over the place where I only partially implemented something so I could get the entire first draft of functionality completed.  The TODO areas should be mostly edge cases (executable bits, file rename info, tags, submodules, etc).
+
+Lossless Two Way
+================
+
+We need to store data that Git records that Merc does not in a git/extra_data file.  This would be parents over two and committer information (author will be mapped to Hg committer).  This way two Hg developers can collaborate without the Git transport messing up the local commits.
+
+Each Git commit should be reproducible as a Merc ID and vice versa on any system without losing data (ie changing the SHA).
+
+Branch Translation Policy
 =========================
 
-This plugin is designed to allow you to push to a Git server over the Git 
-protocol and to pull from a Git based project.  All data is stored in Hg
-native format with a mapping table.  People collaborating in Git should not 
-even be able to tell that you're using Hg to collaborate on their project. 
-Nothing should be kept in the Git format except perhaps for caching.
+Branches in Hg and Git are pretty different.  This is meant to provide a clear policy on how one is converted to the other.
 
-(Dulwich library)
+* Without Bookmarks: *
 
-= Lossless Two Way = 
-We need to store data that Git records that Merc does not in a git/extra_data file.  This would be parents over two and committer information (author will be mapped to Hg committer).  This way two Hg developers can collaborate without the Git transport messing up the local commits.
-Each Git commit should be reproducable as a Merc ID and vice versa on any system.
+If you don't have bookmarks enabled, Git simply maps your 'tip' to the 'master' branch of the repository you're pushing to, since that is the most commonly used default branch name.  Actually, pulling will map whatever the server points to as HEAD, but when pushing it will assume 'master' is your tip.
 
-= ISSUES =
-
-* currently sorts by date, though it should be sorting topologically.  if it gets to a commit where we haven't processed it's parents, it will probably fuck up.
-
-May need to use bookmarks extension to do everything better.
+	$ hg gpush origin        # will push tip to remote 'master'
+	$ hg gpush origin master # same as above
+	$ hg gpush origin --all  # same as above
 
-* Cloning from a Git Repository *
+If the remote server has divergent branches (branches with commits not reachable from HEAD) it will basically ignore them, not convert them into Hg changesets.  It will tell you this (and why) when fetched.
 
-hg init, hg add remote, hg gfetch, hg checkout
+Conversely, on pushing, Hg named branches are ignored if they are not reachable from traversing the parents of tip. (SC: is this best?)
 
-* Fetching from a Git Repository *
+* With Bookmarks: *
 
-hg gremote add (git-url)
+If you have bookmarks enabled, it will treat your bookmarks like Git branches and will only push up references if you specify them.
 
-hg gfetch origin (like a hg pull)
- - connects to server (upload-pack)
- - gets a list of server shas
- - sees what it does not have (maps all unmapped shas, checks list)
- - requests needed shas
- - fetches packfile
-    - explodes
-    - converts parent linages to hg changesets
-    - updates local parents
+	hg gpush origin        # will error, you have to specify a branch
+	hg gpush origin master # pushes the master branch
+	hg gpush origin --all  # pushes all local branches
+
+If a fetch gets branches, it _will_ import them and will create bookmarks that point to them, even if they have no common ancestors with the mainline (HEAD).
 
-* Pushing to a Git Repository *
+* Other points *
+
+If you do not specify a remote name, it will assume 'origin'.  This is helpful if you do not have bookmarks enabled as it will push tip automatically.  If you have bookmarks enabled this is not helpful because you have to specify a branch name after.
 
-hg gpush origin
-  - maps all unmapped shas
-  - connects to server
-  - needs/haves
-  - creates packfile of git versions of everything the server needs
-  - transfers it, updates local references (bookmarks?)
+Eventually, I would like to setup tracking branch refspecs much like Git - say 'this local branch pushes and pulls to/from this remote and branch', but that will be one of the last things done.
 
+Testing Hg-Git
+==============
 
-* Tests *
 Tests are implemented in the Mercurial-standard way of small shell scripts.
 The scripts are located in the tests directory, and to run them you should
 change to that directory and then run tests/run-tests.py from the Mercurial

new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+*Warning: This plugin is not yet stabilized. Use to help me identify bugs, but it will be a few weeks before its fully stable.*
+
+Hg-Git Mercurial Plugin
+=======================
+
+This is the Hg-Git plugin for Mercurial, adding the ability to push and pull to/from a Git server repository from Hg.  This means you can collaborate on Git based projects from Hg, or use a Git server as a collaboration point for a team with developers using both Git and Hg.
+
+The Hg-Git plugin can convert commits/changesets losslessly from one system to another, so you can push via an Hg repository and another Hg client can pull it and thier changeset node ids will be identical - Mercurial data does not get lost in translation (* not currently fully implemented, but it will!).  It is intended that Hg users may wish to use this to collaborate even if no Git users are involved in the project, as it may provide some advantages if you're using Bookmarks (see below).
+
+Dependencies
+============
+
+This plugin is implemented entirely in Python - there are no Git binary dependencies, you do not need to have Git installed on your system.  There are in fact no external dependencies currently other than Mercurial.  The plugin is known to work on Hg versions 1.1 and 1.2.
+
+Commands
+=========
+
+You can clone a Git repository from Hg by running `hg gclone [url]`.  It will create a directory appended with a '-hg', for example, if you were to run `hg gclone git://github.com/schacon/munger.git` it would clone the repository down into the directory 'munger-hg', then convert it to an Hg repository for you.
+
+	hg gclone git://github.com/schacon/munger.git
+	
+If you are starting from an existing Hg repository, you have to setup a Git repository somewhere that you have push access to, add it as a Git remote and then run `hg gpush` from within your project.  For example:
+
+	$ cd hg-git # (an Hg repository)
+	$ hg gremote add origin git@github.com/schacon/hg-git.git
+	$ hg push
+
+This will convert all our Hg data into Git objects and push them up to the Git server.
+	
+Now that you have an Hg repository that can push/pull to/from a Git repository, you can fetch updates with `hg gfetch`.
+
+	$ hg gfetch
+	
+That will pull down any commits that have been pushed to the server in the meantime and give you a new head that you can merge in.
+
+Hg Bookmarks Integration
+========================
+
+Hg-Git works will use your bookmarks if you have any or have the bookmarks extension enabled.  It will allow you to push your bookmarks up to the Git server as branches and will pull Git branches down and set them up as bookmarks if you want.
+
+This is actually pretty cool, since you can use this extension to transfer your Hg bookmarks via the Git protocol, rather than having to scp them, as the Hg transfer protocol does not currently support transferring bookmarks.
+
+Installing
+==========
+
+Clone this repository somewhere and make the 'extensions' section in your `~/.hgrc` file look something like this:
+
+	[extensions]
+	hgext.bookmarks =
+	hgext.hg-git = [path-to]/hg-git
+
+That will enable the Hg-Git extension for you.  The bookmarks section is not compulsory, but it makes some things a bit nicer for you.
+
+Authors
+========
+
+* Scott Chacon <schacon@gmail.com> - main development
+* Augie Fackler <durin42@gmail.com> - testing and moral support.
+* Dulwich Developers - most of this code depends on the awesome work they did.
+ 
+Sponsorship
+===========
+
+GitHub let me (Scott) work on this full time for several days, which is why this got done at all.  If you're looking for a free Git host to push your open source Hg projects to, do try us out (http://github.com).

--- a/TODO.txt
+++ b/TODO.txt
@@ -1,21 +1,21 @@
 GENERAL
 ==========
-* switch object mapping to hg->git since the many to one is that direction
 * respect file modes on conversions
 * explicit file renames
-* more tests?
-* bookmarks / tip / named branches - mapping policy to Git branches
-  - tracking branches?
+* more tests
 * submodules?
-* .gitignore, etc - try to convert?
+* .gitignore, etc - try to convert? 
+  - (probably not automatically, but perhaps a generator?)
 
 PUSH
 ==========
+* push with branch names (w/ proper error messages)
 * update 'remote' references after push confirmation
 * push confirmation? is there extra data after the packfile upload?
 * output something after process is complete (master -> master etc)
   - explain what branch mapping policy determined
 * convert tags to git
+* octopus merge explode re-implode
 
 FETCH
 ===========
@@ -24,9 +24,11 @@
 * only try to import non-mapped commits
 * tag conversion
 * save git metadata (committers, unless it's the same) as extra info
+* octopus merge explode
 
 SPEED/EFFICIENCY
 ================
+* switch object mapping to hg->git since the many to one is that direction
 * don't send blobs/trees already on server
 
 MILESTONES