X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=topgit.git;a=blobdiff_plain;f=README;h=b99b03680fb7fced0e1dc2f0e699f73b141745f5;hp=89899041088cf0b3303d168eb9178b1fb9133ee3;hb=d33fe8bccb78adca51fa87626cd80bd064676d1f;hpb=5996feaf0ff31de1350906aec3b60ed646be6bca

diff --git a/README b/README
index 8989904..b99b036 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,10 +272,26 @@ tg patch
 	TODO: tg patch -i to base at index instead of branch,
 		-w for working tree
 
+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.
+
+	It takes a mandatory remote name argument, and optional
+	'--populate' switch - use that for your origin-style remote,
+	it will seed the local topic branch system based on the
+	remote topic branches. '--populate' will also make 'tg remote'
+	automatically fetch the remote and 'tg update' to look at
+	branches of this remote for updates by default.
+
 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,
 	'!' marks that it has missing dependencies (even recursively),
 	'B' marks that it is out-of-date wrt. its base).
@@ -336,21 +374,37 @@ 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
-	it depends on. This is made in two phases - first,
+	it depends on and remote branches.
+	This is performed in two phases - first,
 	changes within the dependencies are merged to the base,
-	then the base is merged into the topic branch. The output
-	will guide you in case of conflicts.
+	then the base is merged into the topic branch.
+	The output will guide you in case of conflicts.
 
 	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
 
@@ -434,7 +488,8 @@ self-contained topic system in the remote repository, and increased conceptual
 simplicity.
 
 Thus, we choose to instantiate all the topic branches of given remote locally;
-tg update will also check if a branch can be updated from its corresponding
+this is performed by 'tg remote --populate'.
+'tg update' will also check if a branch can be updated from its corresponding
 remote branch. The logic is somewhat involved if we should DTRT.
 First, we update the base, handling the remote branch as if it was the first
 dependency; thus, conflict resolutions made in the remote branch will be
@@ -442,3 +497,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.