bzr for documents

[Stephen J. Turnbull]

Rustom Mody writes:

 > So some (specific) questions:
 > -- Am I required to keep the .bzr directories in each directory where
 > versioned files reside? Or can I have one repo for all versioned files?

AFAIK bzr looks in ancestor directories for the repo.  So you can keep
all the versioned files in a single (sub)tree of your work area
(however you define that).  So for example you could put the repo in
$HOME.  The problem you run into is that unversionable cruft will be
in your status output and may get dragged into adds, etc.  If there's
not much of it, or you have a naming convention for cruft that can be
put into a regexp, you can put that regexp in an ignore file.  You can
ignore whole directories this way too (that is, by name; bzr's ignore
functionality doesn't know about directories except as reflected in
the name regexps in the ignore file).

However, if your home directory is "messy" in the sense that ignoring
the cruft name by name would be painful, then you would prefer to
organize your files in a few repos with high concentrations of
versioned files.

I also suppose that you could put the repo in $HOME but have bzr
ignore *everything* by default.  The cost of this would be that you
would have to use a "force" flag when adding a file to the versioned
set.  Pretty low cost for the scenario you describe, IMO, but YMMV.

 > -- How do I disentangle the histories of different (unrelated) that simply
 > happen to be in the same directory.

Give the file's name as an argument to the command.  If you only want
to see logs of commits that touched wd/file.txt, "bzr log wd/file.txt"
will do that.

 > More general questions:
 > -- I grew up on rcs (about 15 years ago). Is there not an 'rcs-workflow' ie
 > a file oriented rather than directory oriented one?

First, bzr is not directory-oriented.  It's tree-oriented; it will
recurse into subdirectories.

As for emulating RCS, just put file names in all your commands like
you did with RCS.  (Syntax may vary in a few cases where the file name
would for some reason mean something else to bzr, but mostly just
append the file name as above.)

 > -- Should not the user guide have a 'document management workflow' along
 > with the others? Or my question(s) are a little stupid :-)

To Unix folk, "document management" generally means systems like TeX
or HTML which provide an appropriate include-by-reference facility,
and are generally built from source, rather than pulling objects into
the document's file.  So there's no real difference between the
workflow for "programs" and the workflow for "documents".

OTOH, if you work like this:

- edit file1.txt
- "bzr commit -m 'what I did to file 1'"
- edit file2.txt
- "bzr commit -m 'what I did to file 2'"
- edit file3.txt
- "bzr commit -m 'what I did to file 3'"
- edit file1.txt
- "bzr commit -m 'what I did next to file 1'"
- edit file3.txt
- "bzr commit -m 'what I did next to file 3'"
- "bzr log file2.txt"

you can generally omit the file name.  bzr will figure out that only
one file was changed and commit only that file.  (file1.txt,
file2.txt, file3.txt, and file4.txt are assumed to exist in the repo
already.  Commands in "" are verbatim bzr commands and would work.
You might want to give better log messages, though. ;-)

In fact, you can do this:

- edit file1.txt
- edit file2.txt
- edit file3.txt
- edit file1.txt
- edit file3.txt
- "bzr commit -m 'what I've done recently'"
- "bzr log file2.txt"

and as long as you describe what you've done to file 2 accurately,
you'll get a reasonable result.  OTOH, the changes to file 1 will be
mashed together in the log (which may or may not be what you want).
And

- "bzr diff -r date:yesterday file2.txt"

will report all the changes to file 2 (only!) since yesterday.
Finally,

- "bzr log file4.txt"
- "bzr diff -r date:yesterday file4.txt"

will not report any of the above changes (in either scenario, the
commit each edit version or the commit whole session at once
scenario).

HTH