X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=README;h=719b919d51adf85a5ddbd56410a458870e25c006;hb=2986273479a7303a5b21c238182e1df51be2b3eb;hp=9df3699d765e8242b4b5f24075aa6d500b3753f1;hpb=a8d65d218c971d013e294be03e123114093f4e74;p=topgit.git

diff --git a/README b/README
index 9df3699..719b919 100644
--- a/README
+++ b/README
@@ -184,6 +184,24 @@ SYNOPSIS
 	tg: Updating base with t/gitweb/nifty-links changes...
 	tg: Updating t/whatever against new base...
 
+	## Clone a TopGit-controlled repository
+	$ git clone URL repo
+	$ cd repo
+	$ tg remote --populate origin
+	...
+	$ git fetch
+	$ tg update
+
+	## Add a TopGit remote to a repository and push to it
+	$ git remote add foo URL
+	$ tg remote foo
+	$ git push foo
+
+	## Update from a non-default TopGit remote
+	$ git fetch foo
+	$ tg -r foo summary
+	$ tg -r foo update
+
 
 USAGE
 -----
@@ -215,6 +233,10 @@ tg create
 	it will detect that you are on a topic branch base ref and
 	resume the topic branch creation operation.
 
+	In an alternative use case, if '-r BRANCH' is given instead
+	of dependency list, the topic branch is created based on
+	the given remote branch.
+
 tg delete
 ~~~~~~~~~
 	Remove a TopGit-controlled topic branch of given name
@@ -250,11 +272,30 @@ tg patch
 	TODO: tg patch -i to base at index instead of branch,
 		-w for working tree
 
+tg mail
+~~~~~~~
+	Send a patch from the current or specified topic branch as
+	email.
+
+	Takes the patch given on the command line and emails it out.
+	Destination addresses such as To, Cc and Bcc are taken from the
+	patch header.
+
+	Since it actually boils down to `git send-email` please refer to
+	it's documentation for details on how to setup email for git.
+
+
+	TODO: tg mail patchfile  to mail an already exported patch
+	TODO: mailing patch series
+	TODO: specifying additional options and addresses on command
+	      line
+
 tg remote
 ~~~~~~~~~
 	Register given remote as TopGit-controlled. This will create
 	the namespace for the remote branch bases and teach 'git fetch'
-	and 'git push' to operate on them.
+	and 'git push' to operate on them. (Do NOT use 'git push --all'
+	for your pushes - plain 'git push' will do the right thing.)
 
 	It takes a mandatory remote name argument, and optional
 	'--populate' switch - use that for your origin-style remote,
@@ -266,7 +307,8 @@ tg remote
 tg summary
 ~~~~~~~~~~
 	Show overview of all TopGit-tracked topic branches and their
-	up-to-date status ('0' marks that it introduces no own changes,
+	up-to-date status ('>' marks the current topic branch,
+	'0' marks that it introduces no own changes,
 	'l'/'r' marks that it is local-only or has remote mate,
 	'L'/'R' marks that it is ahead/out-of-date wrt. its remote mate,
 	'D' marks that it is out-of-date wrt. its dependencies,
@@ -351,6 +393,16 @@ tg export
 	TODO: For quilt exporting, use a temporary branch and remove it when
 	      done - this would allow producing conflict-less series
 
+tg import
+~~~~~~~~~
+	Import commits within the given revision range into TopGit,
+	creating one topic branch per commit, the dependencies forming
+	a linear sequence starting on your current branch.
+
+	The branch names are auto-guessed from the commit messages
+	and prefixed by t/ by default; use '-p PREFIX' to specify
+	an alternative prefix (even an empty one).
+
 tg update
 ~~~~~~~~~
 	Update the current topic branch wrt. changes in the branches
@@ -363,10 +415,15 @@ tg update
 	In case your dependencies are not up-to-date, tg update
 	will first recurse into them and update these.
 
+	If a remote branch update brings dependencies on branches
+	not yet instantiated locally, you can either bring in all
+	the new branches from the remote using 'tg remote --populate'
+	or only pick out the missing ones using 'tg create -r'
+	('tg summary' will point out branches with incomplete
+	dependencies by showing an '!' near to them).
+
 	TODO: tg update -a for updating all topic branches
 
-TODO: Some infrastructure for sharing topic branches between
-	repositories easily
 TODO: tg depend for adding/removing dependencies smoothly
 TODO: tg rename
 
@@ -459,3 +516,8 @@ carried over to our local base automagically. Then, the base is merged into
 remote branch and the result is merged to local branch - again, to carry over
 remote conflict resolutions. In the future, this order might be adjustable
 per-update in case local changes are diverging more than the remote ones.
+
+All commands by default refer to the remote that 'tg remote --populate'
+was called on the last time ('topgit.remote' configuration variable). You can
+manually run any command with a different base remote by passing '-r REMOTE'
+_before_ the subcommand name.