Repository Reference Rollup (was Re: Repository referencing in command lines)

[Matthew D. Fuller]

On Sat, Feb 11, 2006 at 08:33:38AM -0600 I heard the voice of
Matthew D. Fuller, and lo! it spake thus:
> 
> Which is why I suggest the "repo:<repo_url>:<branch_name>" syntax in
> the first place    8-}

I've hopscotched around a lot in this thread, and skipped a lot of
steps; it's getting hard for even me to keep track of what I'm saying.
So, let me try to roll it all up in one email, showing all my work (as
it were) leading to my conclusions.


First assumption: When we tell bzr to do something, it should be
unambiguous; the program shouldn't have to guess.  I don't think
anybody would disagree on that.

Giving a URL to a standalone or repository branch is always
unambiguous.  It doesn't matter whether "http://foo.bar/baz/quux/nix"
refers to a standalone branch at "/baz/quux/nix", a branch called
"nix" in the repository "/baz/quux", or a branch called "quux/nix" in
the repository at "/baz"; the metafiles available at that location
will tell bzr everything it needs to know.  This is a "complete
reference" (to coin a term).

Similarly, "../../stor/baz/quux" is a complete reference, whether it
points at a standalone branch, or however much of the path is a repo
and however much a branch, as above.  It's not an absolute path, but
it IS a complete reference.  Following that path will lead you to
files that can tell bzr what they are and how to deal with them.


So far, so good; I think we all agree on all that.  It still sits a
little badly with me, but I'll accept that that's just my own little
weirdness.  And I can well believe that this time next year, I'll look
back and say "Yeah, they were all right; it's not really a problem."


Now, here we diverge.

Second assumption: There are times where it would be useful (almost
requisite, for human factors) to refer to a repository branch by its
branch name, without giving a full path to the repository.  I've
outlined a couple such use cases in previous mails, and more can be
imagined.  We can discuss "when/why would you do that?", but that's
another thread.

If you don't accept this assumption, of course, you might as well just
stop reading now; from here on, I'm going from that assumption and
trying to answer the question "How do we do so?".


By the first assumption, this has to be done in an unambiguous way.
And the URL reference, by itself, _can't_ provide this.  If I say to
get "bzr/dev", bzr can't unambiguously tell whether I'm talking about
a branch name in a repository, or a path from here.  It can guess (and
probably, would guess right much of the time), but we don't want it to
guess, because that way lies madness.

So, to make it unambiguous, the only way that occurs to me is to have
the repository path and branch name denoted separately somehow in the
command, so that it's obvious when one is omitted (but see 'Another
alternative' below).  There are roughly three ways to do that.

- An argument, like --repo=/foo/bar.  This is also roughly equivalent
  to doing it from env variable.  Both of these methods fare badly
  with bzr, because there are commands (like branch) where you need to
  refer to multiple branches, which could be in DIFFERENT
  repositories.  And having --repo1 and --repo2 is just nutty.  It's
  also not much fun to type...

- Have them be separate args.  "bzr get REPODIR BRANCH".  That's UI
  insanity as well, because then the args mean different things if
  it's a standalone branch, etc.  Also bad.

- Have some syntax in the arg to do it.  The simple way is
  repo:branch, so you'd get "bzr get /foo/bar:branch.name".  But this
  is still a bit ambiguous, since you could (if you were nutty) have a
  colon in a pathname.  And it's a bit more work to parse by eye.
  Still, it's the most promising of the three choices.

So, given after that, I extend it out to a 3-piece,
"repo:/repo/dir:branch.name".  The remaining potential trouble would
be if you had a path or standalone branch that started with "repo",
but I solve that by creating a "standalone:" tag that could be used if
you needed to do that.

This syntax allows omitting pieces, in such a way that it's obvious
what is missing.  The forms "repo:/repo/dir:" and "repo::" both omit
the branch name, which would just be a flat-out error; there's no case
where you'd need to specify a repo without a branch, that I can think
of offhand.

However, the form "repo::branch.name" allows specifying the branch
name, without the repo where it's stored.  bzr can then know that
you're specifying a branch with the given name, in a repo that it's
supposed to be able to get (see endnote [0] for a summary of the
suggested way to find the repo).  Of course, if bzr can't tell by one
of the defined ways where the repo is, it should just error.


Another alternative:

Of course, if you're specifying the full repo/branch combination, the
URL form is probably simpler and easier.  So maybe we don't want to
have a form that CAN specify the repo, just to be mostly used when you
DON'T want to specify the repo.  Maybe we want to have something like
"rbranch:branch.name" instead, and only use this special syntax when
we're specifying just the branch name, and expecting bzr to find the
repo.

Actually, maybe I like that better.




[0] One sketch of how to find the repository when omitted:
    - IF I'm currently in a checkout of a branch in a repository, use
      that repository.
    - ELSE if there's a specification in the bzr config for our dir
      (e.g., "when $CWD is in ~/work, repo is ~/workrepo") however we
      decide to represent that, use that.
    - ELSE if the env variable $BZR_REPO is set, use that.
    - ELSE smack the user for not telling us

    Variations or alterations in order may apply; there's not much
    point in digging through all those details right now.



-- 
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.