Pending merges, non-integer revision numbers,...: documentation?

[Gonzalo HIGUERA DÍAZ]

Hello,

New to using bzr (hello everybody), I have stumbled across a couple of
things I don't understand, namely pending merges and revisions with
non-integer revid (which I call "subrevisions"). For some background:

Wondering about a way to manage a few $HOME configuration files across
several computers, I thought of storing a repository without working
branches on a USB flash drive and modifying/synching it through
checkouts present on each machine. Given that I might not always have
the USB drive with me, the workflow would involve local commits which
would be pushed to the master upon availability.

After doing a couple of local commits I have a pending change and the
USB drive handy, so I commit the changes and it results in three new
revisions, which I find fine. Later, after two other local commits I
have again the USB drive with me but no pending changes. How can I
commit them right now? A no-argument commit advises me to do an
update.

The result of the update surprises me: the local branch is changed to
the revision than's in the master (which seems logical given that it
might have changed) and converts the two local commits into pending
merges, a concept which I didn't know about. "bzr status" shows under
"pending merges" the two local commits are still differentiated, but
"bzr help commit" doesn't mention "pending merges". Shouldn't it?
Where is the concept of a "pending merge" explained?

At this stage, a "bzr commit" can check in it the two changes as
"subrevisions", Given the documentation on "bzr help commit" and that
a committing a new revision would have resulted in separate revisions
(at least if the master branch hadn't been updated), it feels wrong
for the sequence "bzr update; bzr commit" to group by default two
possibly unrelated changes under one revision. What would be the
alternative procedure which would have taken me to that point? Would
there be a better way to revert than to "bzr diff" between
subrevisions, uncommit, and then patch and commit each change?

After the commit, "bzr status" shows "subrevisions" as having their
own revid (revision id). However, "bzr help revisionspec" says a revid
is an integer, while there "subrevisions" seem to have the format
x.y.z (and maybe x.y and x.y.z.w are also possibilities), which makes
me wonder whether they have any important differences to integer
revids.

At this point, the concept of "subrevisions" seems interesting, but
brings many questions to mind: What is the proper way to call them?
How can they be created and converted back to regular revisions?
What's the recommend way to use them? What are the differences between
them and regular revisions and how might it affect the workflow (e.g.
how to uncommit a "subrevision" --which might simply not be a sensible
thing to do--)?

So much confusion in my head makes me wondering how thick headed I am
being (please excuse me for it), and whether I am confused becase
"subrevision"/"pending merges" add a degree of complexity which right
now to me seems wrong. Hopefully, all this is much easier than it
looks to me right now, so If I missed some documentation that will
help me out (I just skimmed through
<http://doc.bazaar-vcs.org/latest/> and didn't look much into the
Wiki), I would be glad to be pointed to it. Thank you.

-- 
Gonzalo HIGUERA DÍAZ <gonhidi at gmail.com>