[RFC] [MERGE] Help first lines

Martin Pool mbp at sourcefrog.net
Thu Oct 18 02:55:02 BST 2007


On 10/18/07, Matthew Revell <matthew.revell at canonical.com> wrote:
> Hi,
>
> I've run through "bzr commands help" and clarified the one line
> summaries. I updated these in builtin.py - I assume that's the right
> place.

Thanks, that's a good idea.

> This merge directive also has my changes to the mini-tutorial. I tried
> to use bzr send -r last:1 and bzr send -r date:today and a couple of
> other combinations to give only my changes to builtin.py but with no
> luck.
>
> Some questions:
>
> bzr check: "This command checks various invariants..." Can you guys
> offer me an example of what an "invariant" is in this context?

It means "something that should always be true", like
http://foldoc.org/?invariant

But it's probably not the clearest word to use here.  Is it enough to
just say 'checks the branch and repository' or 'checks for problems
in'?

> bzr diff: "Show differences in the working tree or between revisions."
> I'm not really sure what the first part means. Differences in the
> working tree and the parent branch, or what?

Well, by default it shows the differences between the working tree and
the last revision on its branch.  With options you can show the
differences between other selected trees or revisions.

> bzr ignore: is this effectively the opposite of bzr add?

No, 'remove' is closer to being the opposite of add.  ignore means,
treat this file (or files matching this pattern) as ignored if they
are not versioned.

> bzr info: Can we be more specific about what information is shown?
> Otherwise, the help description is a bit redundant.

The main things it shows are the version and the paths of related
branches or repositories.  With -v, it gives you some more statistics
about the age of the branch, number of revisions and contributors, and
the size of the repository.  (Just try it!)

>
> bzr init-repository: Is this to create a shared, centralised
> repository? Or is it to create a single repository with many working
> trees? In both cases, I'm not sure I understand quite what the purpose
> is.

It makes a repository directory, underneath which you can make branch
directories (with bzr init).  You can either use those branches
directly as working trees, or you can make checkouts of them somewhere
else with bzr checkout.  It has nothing to do with whether one person
or many people will use them.

>
> bzr merge: "Perform a three way merge" - I don't understand how this
> is a three way merge. Isn't there a parent branch and a target branch?
> Where's the third part?

The 'three-way merge' is an implementation detail (and indeed not
always true); to the user this just merges one branch into another and
it should say so.

>
> bzr reconcile: Can we explain a little more about how this works? For
> example: is there a better chance of it working if you specify another
> branch?

> Purpose: Reconcile bzr metadata in a branch.

It might be better to say 'repair inconsistencies in a branch.'

By default it runs on the branch containing the working directory, or
another branch if one is specified.

  The branch *MUST* be on a listable system such as local disk or sftp.

I don't think that's a useful message.  All writable locations are
listable.  Let's just say you must be able to write to the branch.

>
> bzr register-branch: where is the help text for that? I couldn't find
> a launchpad.py or similar.

bzrlib/plugins/launchpad/__init__.py

Thank you.
-- 
Martin



More information about the bazaar mailing list