Re: [StGit PATCH 5/6] Refresh the main stg man page

On 2008-10-06 22:14:05 +0100, Catalin Marinas wrote:

2008/10/5 Karl Hasselström [off-list ref]:

quoted

--- a/Documentation/stg.txt
+++ b/Documentation/stg.txt

[...]

quoted

+  * After making changes to the worktree, you can incorporate the
+    changes into an existing patch; this is called 'refreshing'. You
+    may refresh any patch, not just the topmost one.

I wouldn't advertise the refreshing of "any" patch as it doesn't
always work (it actually fails in a lot of cases). Or at least we
could mention that there are some restrictions.

Well, when it does fail, it fails in a controlled way, and lets the
user manually sort out the conflicts or undo. But I guess we could say
that.

When I wrote this, I didn't yet have a "Conflicts" chapter to point
to. :-)

quoted

+  * You can easily 'rebase' your patch stack on top of any other Git
+    branch.

It might be better with something like "on top of a different Git
commit". The first thought when reading the above is that you can
move the patch stack to a different Git branch easily, which is not
the case (you need to cherry-pick the patches).

Right, that makes sense. (We might want to mention "remote branch"
explicitly, though, since that's by far the most common case.)

quoted

+  * The patch stack is just some extra metadata attached to regular
+    Git commits, so you can continue to use Git tools along with
+    StGit.

Again, this is with some restrictions (or there aren't any with the
new infrastructure?).

Well, "stg undo" can repair any havoc the git tools can make. And by
"havoc" I mean merge or rebase.

This should probably grow a short disclaimer, and point to the "git
interoperability" chapter.

quoted

+  Tracking changes from a remote branch, while maintaining local
+  modifications against that branch, possibly with the intent of
+  sending some patches upstream. You can modify your patch stack as
+  much as you want, and when your patches are finally accepted
+  upstream, the permanent recorded Git history will contain just the
+  final sequence of patches, and not the messy sequence of edits that
+  produced them.

Maybe we could mention that the local history is also clean, not
only the upstream tree (though you mention it later in a different
hunk).

Hmm, yes. Though I can't immediately think of any wording that doesn't
make that paragraph a lot more complicated. Suggestions welcome.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle