Bound branch implementation

[Nathaniel McCallum]

On Sun, 2005-11-13 at 13:24 +0100, Erik Bågfors wrote:
> I find this syntax more complicated.  Now you have shadows, updates
> (what are they?) syncs (what's the difference?) merge to and from
> (while the current merge command is consistent an simple (just <from>
> <to>, where <to> defaults to cwd).
> 
> You can have multiple shadows, which will make things complicated,
> what do you do if the commit works on one of them but not the other,
> then you need to "fail" the first commit.  Uhh...?
> 
> pull, push, merge and bind is all I need to care about, it's simple
> and easy to explain.  For example, everyone should understand what
> "bzr pull path" means almost without explanation, "bzr merge path"
> should also be simple to understand. But to understand that "bzr merge
> -f path" is very different from "bzr merge path" is hard. I would
> think that -f == force and that it overrides local changes, if I was
> not to read the documentation.
> 
> merge and pull and push should not be under the same command (merge)
> since they do different things.  Also, merge requires a commit after,
> pull and push doesn't.  So you have to use them differently.

I'm trying to have the commands reflect conceptually what is happening
with branches.  Doing x to branch a is an "action".  Actions can affect
only the local branch (ie. commit) or they can involve other branches
(ie. push or pull).  Actions that affect other branches and are done
repeatedly define "relationships" (ie. "pull without push" ==
"parent/child").  So, actions become relationships when done
consistently and repeatedly.

There are only a few meta-actions (for any values of A and B):
   A  -> B | A <-  B (uni-directional)
   A <-> B           (bi-directional)

The way this is currently handled is this:
* A  -> B
  if exists(B):
     bzr pull and/or bzr merge
  else:
     bzr branch A B
* A <-> B
  There are lots of ways to do this that we are trying to solve:
      - branch ; <hack> ; commit ; pull ; merge ; commit ; push
      - bound branches


I think the branch mechanism is really good.  It could be expanded to
take any writeable vfs as the destination.  ie. bzr branch /foo bzr
+sftp://server/path

However, can we make merge function more conceptually like branch?
Thus, in the meta-action scenario above:

* A  -> B
  if exists(B):
     bzr merge A B
  else:
     bzr branch A B
* A <-> B
  if exists(A) and exists(B):
     bzr sync A B     # Using "sync"' here rather than "merge --sync"
  else:
     error()

Because of these three types of meta-actions...
   A  -> B | A <-  B (uni-directional)
   A <-> B           (bi-directional)
... there are three types of relationships:
   A  -> B: (pushed) mirror
   A <-  B: (pulled) parent
   A <-> B: synchronized peer (aka a bound branch)

This is what I was trying to accomplish with shadows.  Though, perhaps
they would be better split up into various commands (ie. mirrors --add,
parent --add, etc).  I'm not sold either way.

The most important time to think about relationships is at commit time
(when changes are actually being made to a branch).

For instance this
  $ bzr bind
  <hack>
  $ bzr commit
  $ bzr unbind
  <hack>
  $ bzr commit
  $ bzr bind  # sync?
... is far less clear to me than this:
  <hack>
  $ bzr commit -s # sync
  <hack>
  $ bzr commit    # no sync
  $ bzr peers -s  # sync


Anyway, I'm not caught up on a particular implementation, just wondering
how we can think about branches, their actions and their relationships
and model our UI against it.

This is particularly useful when thinking at the GUI level.  Look at
bzrk.  Why not have a graphical utility that shows the state of all
registered branches?  Here are some use cases and implementation ideas:
 ACTIONS
   * "I want to put the contents of a into b"
     - drag <a> and drop it onto <b>
   * "I want the contents of a and b to be the same, just this once" 
     - click "sync", drag <a> onto <b>
 RELATIONSHIPS
   * "I want branch b to always be identical to branch a"
     - click "shadow", drag <a> onto <b>
   * "I want a to get b's changes and vice versa"
     - click "shadow", click "sync", drag <a> onto <b>
   * "I want to know what the static relationships are between branches"
     - click "shadow", the relationships are depicted using arrows

Again, just brain storming.  Thanks for listening.

Nathaniel