> So in shuffling stuff around, the question of what to do with source
> repos comes up.
I must say, I'm strangely heartened by the lack of enthusiasm for git
8-}
So, based on feedback, my operative theory is that I will go ahead and
bzr-ify things. The long-term future isn't ultra rosy, and assuming
the status quo does tend to suggest we'll have to migrate away from it
at some point. But I'm confident enough that it won't be in the next
couple years.
At the same time, I'll also setup a regular mirror into git, and stick
it on github. On the one hand, that lets people use git to grab and
build things (though puts them in slightly worse position for
submitting changes bigger than a single patch). And on the other, it
means we have a conversion constantly ready and [theoretically]
already debugged if we need to jump out an escape hatch.
I've babbled out a little doc (attached) about how bzr will work
day-to-day, attached. This isn't really a complete -crash-course sort
of thing, but should let those who aren't used to bzr see how various
things will work a bit differently (including a couple little
screenshots of the GUI history view). The ref'd bzr branches are up
on LP, so you can grab and fiddle along. As mentioned in the doc,
they should definitely be considered throwaways, not the final
conversions, so at the moment mtn is still the authoritative place to
do any work. Though if you have outstanding branches (with more than
1 commit, anyway), we should probably arrange for them to be pushed
into the central repo or otherwise gotten to me so it can all get
convered together.
So, anyone interested, please take a run through it; if anything looks
showstoppery; then we can fix or reconsider before committing to it.
I've also tested and setup the git conversion, stuck up at
<https://github.com/fullermd/ctwm-bzr>. This is a conversion from the
bzr branches, not straight from the mtn, so it's the same process as
will be used in the final mirror-maintaining. Which also means that
git repo should be considered throwaway like the linked bzr branches,
as the final conversions will probably be somewhat redone.
--
Matthew Fuller (MF4839) | [email protected]
Systems/Network Administrator | http://www.over-yonder.net/~fullermd/
On the Internet, nobody can hear you scream.
(Given code locations are temporary. Conversions probably are too; I'll
probably make some tweaks before finalizing, so consider these
throwaway.)
INTRO
In mtn, the primary object that you clone/sync is the repository, with
whatever collection of branches it is. In bzr, the objects you talk
directly about are the individual branches. And bzr is built around a
branch-per-directory workflow; it's not the ONLY possible one, but it's
the one the tool makes obvious and easiest. So that's what I'll
describe.
As a consequence of this, the obvious natural usage will involve moving
around the full history for each branch. For ctwm, that's pretty small,
but it's still silly to have multiple copies of it around. So we'll add
a step at the start that creates what bzr calls a "Shared Repository",
which means the Repository (in bzr terms, the store that holds the
history) is shared among multiple Branches. It organizes this by pure
filesystem layout; it looks for the repo and .. and ../.. and ../../..
and so on.
SETUP
I presume this is all happening in ~/work/ctwm/bzr/. So the first step
is to set up that Shared Repository, so that it's there waiting when we
start transferring branches around.
% cd ~/work/ctwm/bzr
% bzr init-repo .
Shared repository with trees (format: 2a)
Location:
shared repository: .
That'll leave a .bzr/ directory there; the repo is inside. That should
be the last time you ever need to look at or think about the repo itself.
All the new branches we copy down or create under ~/work/ctwm/bzr/ will
automatically use that repo and not duplicate revs.
Next, we'll grab the two branches I pushed up to LP: the trunk which I
called ctwm (ex-free.lp.se:X.ctwm), and ctwm.rhialto.cleanup
(ex-free.lp.se:X.ctwm.rhialto.cleanup) which has some unmerged stuff.
% bzr branch lp:~fullermd/+junk/ctwm
Branched 243 revisions.
% bzr branch lp:~fullermd/+junk/ctwm.rhialto.cleanup
Branched 242 revisions.
That leaves you two directories in ~/work/ctwm/bzr (well, 3, if you count
the hidden .bzr holding the repository):
% ls
ctwm/ ctwm.rhialto.cleanup/
And in each dir is a working tree on that branch.
A FEW COMMANDS
Day to day working commands are pretty similar to most other VCSen.
There's "bzr ci" or "bzr commit" to checkin stuff, "bzr log" to look at
the history, "stat" and "diff" to look at changes, "add", "mv", "rm",
etc. "push" and "pull" are used to sync up copies of the branch in
various places; I'll recommend workflows involving "update" as well for
branches like trunk, but that's a story for another doc.
Revisions are assigned long UUID identifiers (visible in log with
--show-ids), but those are usually hidden and revisions are instead
identified via numbers. These are derived from where revs fall in the
shape of the history of the branch (so one rev might have different
numbers in different branches); details are way out of scope of this.
A notable thing bzr does differently from other major systems is to
preserve and give meaning to the social asymmetry of merges. While in a
technical sense merges are symmetric ("merge these two things together"),
socially they're generally not ("merge somebody's $THAT into my $THIS").
This has various effects, but the most obvious (and the one I bring it up
to talk about) is in log. By default, log shows only the merge commit,
but hides away the "other side" bits that were brought in. With stuff in
the history this means the log messages won't be too helpful (since mtn
auto-commits merges with an auto message), but will for the future (since
bzr doesn't; you commit it yourself after doing the merge, so can give a
good message about just what you're merging).
That's... probably not clear to anybody who doesn't already grok it.
Here's an example, from the current tree. I'm using log --short for
shortness. The last merge was back on rev 236:
-------------------------------------------
236 rhialto 2013-02-12 [merge]
propagate from branch 'free.lp.se:X.ctwm' (head b18c4bb7d183135b87e0d580ea
4b1531e3fbceb7)
to branch 'free.lp.se:X.ctwm.rhialto.cleanup' (head
e04b96f6cb79bca3c5f5c048ea7c3d02bd847e20)
235 rhialto 2013-02-12
Cleanup re: raising and warping to windows (previous location of pointer
in
windows), SaveWorkspaceFocus. A few extra NULL pointer checks.
-------------------------------------------
It shows the rev before it (r235, which was b18c4bb in mtn), but
it doesn't show the other rev (e04b96f6c). But it does list that [merge]
there on the first line, which tells you there are revs "off to the side"
there. To show them, you add the "-n0" arg to log:
-------------------------------------------
236 rhialto 2013-02-12 [merge]
propagate from branch 'free.lp.se:X.ctwm' (head b18c4bb7d183135b87e0d580ea
4b1531e3fbceb7)
to branch 'free.lp.se:X.ctwm.rhialto.cleanup' (head e04b96f6cb
79bca3c5f5c048ea7c3d02bd847e20)
208.4.1 rhialto 2007-03-29
Rename TwmWindow.list to iconmanagerlist, and various smaller cl
eanups.
235 rhialto 2013-02-12
Cleanup re: raising and warping to windows (previous location of pointer i
n
windows), SaveWorkspaceFocus. A few extra NULL pointer checks.
-------------------------------------------
Now it shows e04b96f6c, which gets the revno 208.4.1 (details of bzr's
derivation of these is still way out of scope, but basically integers are
down the "mainline" of left/first parents of the history, and dotted
numbers for the other paths. Or functionally, integers are what you
committed on this branch, and the dotted ones are the ones that you
merged in from elsewhere). It shows all the merged revs (in this case
only 1) there indented, before going back to the next mainline rev. A
bigger example is a bit farther back in history:
-------------------------------------------
220 Richard Levitte 2007-12-01 [merge]
propagate from branch 'free.lp.se:X.ctwm-3.8-fixes' (head
0bb87cb06f688c0e9af0959aa2f309a774184d46)
to branch 'free.lp.se:X.ctwm' (head
3d7aa71e56e415dbb3603d9633fc2d72537a078d)
208.1.31 Martin Blais 2007-12-01
Add the 'SaveWorkspaceFocus' feature.
208.1.30 Martin Blais 2007-12-01
Fix a bug in the warpring 'next' function. Submitted by Martin
Blais
208.1.29 Richard Levitte 2007-11-22 [merge]
merge of '1dfd5be037e9fb09f9aee3d938dcca2848aa7744'
and 'e4bdcfe0db22e2b61ca33b39a74dd8c6c440b808'
208.2.1 Richard Levitte 2007-06-05
There are bigger mice these days
208.1.28 fullermd 2007-11-22
Update CHANGES for the last few updates.
[... bunch of revs elided ...]
208.1.1 fullermd 2007-03-08
Fix apparent typo in d3f2af2a654ab0ce5003140e3704ebc924d555e2
which causes [de]iconfied status to not propogate across
workspaces correctly.
219 richard 2007-03-08
applied changes from d3f2af2a654ab0ce5003140e3704ebc924d555e2
through 4d3c304422e28c21b2c955e2f028dad19d08f046
-------------------------------------------
This one has multiple levels: r220 merged a bunch of revs, one of which
(r208.1.29) was itself a merge (of just one rev), so it steps in another
level to show that.
So, that's a different in reading and workflow from mtn. In mtn, it's
more like the individual change revs are important, and the merges are
ignorable; in bzr-land, it's more common that the merges are important
since they show when $FEATURE/$FIX/etc landed in the branch (and will
have it described in the log message), while the individual revs in the
merge are usually ignorable unless you need to delve into them. It's
still the same old individual-rev-DAG underneath, but merges serve
conceptually as a "roll-up".
GUI
The major GUI is from the 'qbzr' plugin, which gives (among others, but
this is the major one) a 'qlog' command. This gives a pretty familiar
GUI log view. You can have it show multiple branches at once for
comparison by passing two (or more) branches when invoking it
% bzr qlog ctwm ctwm.rhialto.cleanup
http://www.over-yonder.net/~fullermd/dl/qlog1.png
For revs in common on both branches it's all obvious. It gives dotted
numbers to the revs that are only in ctwm.rhialto.cleanup by giving them
the revs they'd have if they were merged right now into ctwm. You can
flip that the other way around by changing the order of the args.
% bzr qlog ctwm.rhialto.cleanup ctwm
http://www.over-yonder.net/~fullermd/dl/qlog2.png
INTER-BRANCH
Few quick notes on working between branches. Making a new branch happens
via the 'branch' command.
% cd ~/work/ctwm/bzr
% bzr branch ctwm my-work
Branched 243 revisions.
[Now have new branch in ~/work/ctwm/bzr/my-work/]
The 'missing' command lets you look at the differences between branches.
I like using the --line log style with it, since I mostly just want a
quick idea of the divergence:
-------------------------------------------
% cd ctwm
% bzr missing ../ctwm.rhialto.cleanup/
You have 3 extra revisions:
243: fullermd 2014-04-24 $DESTDIR shouldn't be included when defining where ...
242: fullermd 2014-01-15 -aux-info doesn't really add much utility, and blow...
241: fullermd 2014-01-15 Cast another size_t-derived result to unsigned long...
You are missing 2 revisions:
242: rhialto 2013-09-13 3 - Selected a number of cleanups from Stefan Monnier
241: rhialto 2013-06-23 Add an option (default off) to map and unmap workspa...
-------------------------------------------
And landing them happens via the 'merge' command.
-------------------------------------------
% cd ctwm
% bzr merge ../ctwm.rhialto.cleanup/
M CHANGES
M add_window.c
M add_window.h
[... lots of changes ...]
M workmgr.c
M workmgr.h
Text conflict in util.c
1 conflicts encountered.
[ manually resolve conflict ; standard <<<< ==== >>>> style conflict
markers, then use 'bzr resolve' to tell bzr ]
% bzr stat
modified:
CHANGES
add_window.c
[...]
workmgr.c
workmgr.h
pending merge tips: (use -v to see all merge revisions)
rhialto 2013-09-13 3 - Selected a number of cleanups from Stefan Monnier
% bzr ci -m 'merge ctwm.rhialto.cleanup'
Committing to: /home/fullermd/work/ctwm/bzr/ctwm/
modified CHANGES
modified add_window.c
[...]
modified workmgr.h
Committed revision 244.
-------------------------------------------
And now we have that new merge rev up top.
-------------------------------------------
% bzr log --short -n0
244 Matthew Fuller 2014-04-26 [merge]
merge ctwm.rhialto.cleanup
240.1.2 rhialto 2013-09-13
3 - Selected a number of cleanups from Stefan Monnier
[...]
240.1.1 rhialto 2013-06-23
Add an option (default off) to map and unmap workspaces in the "
[...]
243 fullermd 2014-04-24
$DESTDIR shouldn't be included when defining where paths will be at
runtime.
-------------------------------------------
When a branch is fully merged and no longer needed, rm -rf. Or mv or tar
it somewhere for archive purposes if you feel paranoid.
Well, that should be enough for a flavor.
