Repository referencing in command lines (was Re: 08:16 < abentley> Better phrasing: [...])

[Matthew D. Fuller]

[ This mail developed along different directions than I'd originally
   intended.  My main ideas are all in the second half, but a few
   points along the way led to them.  I could spend an hour or two
   trying to edit it all into a more coherent missive, or I can just
   send it now.  I'm lazy. ]

On Thu, Feb 09, 2006 at 11:20:34PM +0100 I heard the voice of
Erik B?gfors, and lo! it spake thus:
> 
> I think we should support paths in the repos, just like svn for
> example, so you can have
> REPODIR/trunk
> REPODIR/branches/0.9
> etc....

Please, no.  That's high on the list of reasons I skipped SVN
altogether.


> * Creating a new standalone branch
> * Creating a new branch in a repo

To me, these are the same thing; in both cases, you're creating a
branch with nothing in it (until you add).  Where the branch is stored
is kinda a side issue.  You've them both as just slightly different
invocations to "bzr init"; I'd be tempted to make the repo-variant a
flag; something like "bzr init --repo=/foo/bar" instead.

Of course, in a standalone branch, you don't have to call it anything;
you can just `bzr nick` later if you want.  In a repository, you have
to declare what the branch will be called.  I'd be tempted to add an
arg and have "bzr init <location> <branch-name>"; maybe it's optional
for standalone to declare the name, but it would be required for repo.


As a side point, I'd also push heavily for a $BZR_REPO or such
environmental variable.  I have a dozen or so wrapper scripts for CVS
that call it with different $CVSROOT's for all the places I do work;
that's a lot nicer than writing it on command lines, or trying to
write wrapper scripts that substitute things in the middle of the
line.  So something like "env BZR_REPO=foo/bar bzr init --repo" should
work too.  See additional mentions below.


> * Creating a standalone branch based on another
> * Creating a branch based on another branch and store in repo

These, as well, are the same.  But these show more the need for syntax
in-line, rather than an argument.

I think this is the best question to tackle here.  The question needs
to be "How do we denominate a branch in a repository"?

SVN does this by the path names.  I really, really hate that, as far
as it's reflected in the actual structure of the repository.  Think of
the effects on revnos and `bzr log`.  As a UI abstraction, I just
single-really hate it.  So, I'd out that.

CVS has its little twitchiness with branches as symbolic revision
names, equivalent in most ways with tags.  As well, it has only repos
and only works on a single repo, so it doesn't have to deal with
multiples in a command-line (think of branching from one repo, and
storing the new branch in another).  So, that doesn't really work
either.


Some possibilities:

- Breaking into multiple args.  Example:
  "bzr branch FROMREPO FROMBRANCH TOREPO TOBRANCH"
  This is FULL of problems; it means wildly different meanings for the
  args based on whether FROM and TO are standalone or repos, for one
  thing.  It's a pain to type, and it takes a lot of work for the eye
  to parse.  For that reason, I discard this.


- URL-ish forms.  "bzr branch repo://foo/bar[...]"  This doesn't
  actually solve the "how do you denominate a branch within a repo"
  question, and also blows up when you want to access a repo over SFTP
  or bzr+ssh or such methods.  So that's a non-starter.


- Non-URL separated values.  "bzr branch repo:/foo/bar:mybranch"  This
  recalls the $CVSROOT constructions like :ext:me at some.server:/foo/bar
  in using the :'s to separate pieces of a single string.  This makes
  it pretty easy to reference repo or standalone branches with very
  similar syntax, and to declare branch names within the repo.
  
  This is the one I like.  Some proposed examples, using "branch"
  since you get to specify two branches at once in it:

  # Branch from bzr.dev [standalone] into my ~/repos/bzr repository
  # (will inherit "bzr.dev" as branch name since I don't specify one)
  % bzr branch http://bazaar-ng.org/bzr/bzr.dev repo:~/repos/bzr

  # Assume bzr.dev goes into a repo at b-ng.o/bzr.  Pull it into a
  # standalone branch in a dir called "bzr.dev" in my current dir
  # (i.e., what "bzr branch http://b-ng.o/bzr/bzr.dev" does now).
  # This is tricky, since we're embedding a URL (where :'s are common
  # and significant) inside a :-delimited string.  I'm going with
  # quoting the URL as the way to handle this.
  % bzr branch repo:"http://bazaar-ng.org/bzr":bzr.dev

  # Branch from the standalone branch at "./branches/mybranch" into a
  # branch called "mybranch" in a repo on my web server.  Use an env
  # variable to save typing.
  % env BZR_REPO="sftp://me@web/~/myrepo" \
            bzr branch branches/mybranch repo:

  # I'd actually wrap that in a script which set the env variable, so
  # the command-line I'd type would be more like:
  % mywebbzr branch branches/mybranch repo:

  # We want repository aliases, to save a lot of typing (this could be
  # extended to current push/pull/merge too, and should be).
  # Somewhere, somehow, I define "myweb" as a repository alias for the
  # repo listed above; maybe this is global, maybe per-branch, maybe
  # whatever.  Worry about those details later; for now, presume I
  # have that alias.
  # Do the same as above, except call the branch 'mynew' in the
  # repository.
  % bzr branch branches/mybranch repo-alias:myweb:mynew

  # Also, have "standalone:" be a tag for a standalone branch.  It's
  # not normally necessary, for simplicity and backward compatibility,
  # but we may want to use it occasionally if we have a standalone
  # branch called "repo" or something, for disambiguation.  Sorta like
  # "-r revno:5"
  % bzr branch standalone:repo repo:/foo/bar:mybranch



I think determining how we'll refer to a repository and a branch in
it, in such a way that it can be described inline without piling on a
bunch of --options, is the most necessary step in determining what
commands will do what how.  Piling up a --repo=/my/repo and
--branch-in-repo=mybranch is nasty, and it just gets double nasty in
commands like 'branch' where we need to specify TWO branches, either
of which can be repo/standalone.


-- 
Matthew Fuller     (MF4839)   |  fullermd at over-yonder.net
Systems/Network Administrator |  http://www.over-yonder.net/~fullermd/
           On the Internet, nobody can hear you scream.