Commits

Augie Fackler  committed 255b65b

Adding a pile of docs I just wrote. Hopefully this encourages people to contribute.

  • Participants
  • Parent commits 3f649e4

Comments (0)

Files changed (3)

+== Design ==
+This is a 20k feet view of the code right now. This may improve with time, or the clarity of the code may improve to a point where such things are less necessary.
+
+=== Subcommands ===
+Subcommands are created by using the {{{util.register_subcommand}}} decorator to add the function to the lookup table used in {{{svncommand}}}. The docstring is the help text that will be displayed by {{{hg svn help}}}.
+
+==== demandimport ====
+{{{demandimport}}} is used by Mercurial to reduce startup time. This has the slight problem for hgsubversion that subcommands in files other than svncommand.py won't be found (because the decorator will not execute) until too late. The fix is code like this at the top of {{{svncommand.py}}}:
+{{{
+#!python
+# dirty trick to force demandimport to run my decorator anyway.
+from utility_commands import print_wc_url
+}}}
+What happens here is that demandimport evaluates the {{{utility_commands}}} module during import of {{{svncommand}}}. This causes the decorator to run at the correct time, preventing missing commands.
+
+=== hg_delta_editor ===
+This is where a special editor subclass lives. This is the editor that is driven by libsvn_ra when replay is used. If the server does not support replay, this code is still used in some places, which is probably a good candidate for a refactor at some point in the future.
+
+=== svnwrap ===
+A lot of the magic happens here. hgsubversion actually started out as an experiment playing around, and early versions were actually just this wrapper around the lower-level Subversion APIs. The goal is for this package to transparently work on both the ctypes bindings for Subversion (not merged to trunk as of this writing) and the SWIG bindings.
+This is the package with the best automated test coverage, provided by {{{test_svnwrap.py}}}.
+
+=== Tests ===
+Lots more could be used. Real automated tests of the actual conversion would be a great way to help the project. At present, the best way to test major changes are to use a local {{{svnsync}}}ed mirror of a repository to convert from, and the {{{verify_all_revisions}}} command to double-check the results. Note that you can force hgsubversion to pretend there is no replay support by passing the {{{--stupid}}} flag to {{{svnclone}}} and {{{pull}}, which allows testing of non-replay changes even locally.
 == Welcome ==
 
-Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it.
+Welcome to the hgsubversion project. The goal of the hgsubversion project is to create a fully-featured Subversion client that works as an extension to Mercurial suitable for distribution in the stock Mercurial distribution.
 
-=== Wiki features ===
+=== Hacking ===
 
-This wiki uses the [[http://www.wikicreole.org/|Creole]] syntax, and is fully compatible with the 1.0 specification.
+See [[Design]] for some thoughts on the design of hgsubversion.
 
-The wiki itself is actually a hg repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.
 
-Go ahead and try:
-
-{{{
-$ hg clone http://bitbucket.org/durin42/hgsubversion/wiki/
-}}}
-
-Wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.
-
-=== Syntax highlighting ===
-
-You can also highlight snippets of text, we use the excellent [[http://www.pygments.org/|Pygments]] library.
-
-Here's an example of some Python code:
-
-{{{
-#!python
-
-def wiki_rocks(text):
-	formatter = lambda t: "funky"+t
-	return formatter(text)
-}}}
-
-You can check out the source of this page to see how that's done, and make sure to bookmark [[http://pygments.org/docs/lexers/|the vast library of Pygment lexers]], we accept the 'short name' or the 'mimetype' of anything in there.
-
-Have fun!
+=== Use ===
+See [[Use]] for some basic examples of use.
+== Use ==
+The original goal was to have as many of the commands as possible live as subcommands of the svn subcommand. The only (current) exception to this is the {{{svnclone}}} command because svnclone is special in that it does not require a repository to work.
+
+
+=== Cloning a repository ===
+Right now, you can only clone repositories that use a more-or-less standard Subversion layout. That is, the default location where work is done is called {{{trunk}}}, branches are located in a sibling of that directory called {{{branches}}}. Tags are expected to be another sibling of {{{trunk}}} called {{{tags}}}, but that is configurable.
+
+To get a clone of [[http://code.google.com/p/python-nose/|Nose]], start with
+{{{
+$ hg svnclone http://python-nose.googlecode.com/svn nose-hg
+}}}
+The last argument, {{{nose-hg}} is not strictly required, but because of how Google Code lays out projects, the default target would be named {{{svn-hg}}} which is not very helpful.
+
+=== Pulling New Updates ===
+This will replay all the revisions from the Subversion repository into a new Mercurial repository. If {{{nose-hg}}} already exists, it will try to use that as a repository previously created with the same command.
+
+To pull new revisions from the remote repo, use {{{hg svn pull}}} while in the repository. This is analogous to {{{hg pull}}} except that it will pull from the Subversion server instead of from a Mercurial one.
+
+
+=== Other Stuff ===
+You can use the usual Mercurial commands to work with this repository. If you have a series of commits on a given branch, and want to move them to the tip of that branch, use the {{{hg svn rebase}}} command while on the tip of your work, and those changesets will automatically be rebased over top of the new upstream work.
+
+You can see what changes need to be sent back to the server using the {{{hg svn outgoing}}} command.