Remove list of formats from bzr init and bzr init-repo

[Andrew Cowie]

Given the existence of `bzr help current-formats` and `bzr help other-formats` which, respectively, quite helpfully say:

Current Storage Formats

pack-0.92:
    (native) (default) New in 0.92: Pack-based format with data
    compatible with dirstate-tags format repositories. Interoperates
    with bzr repositories before 0.92 but cannot be read by bzr <
    0.92. Previously called knitpack-experimental. For more
    information, see http://doc.bazaar-
    vcs.org/latest/developers/packrepo.html.

rich-root-pack:
    (native) New in 1.0: A variant of pack-0.92 that supports rich-
    root data (needed for bzr-svn).

1.6:
    (native) A format that allows a branch to indicate that there is
    another (stacked) repository that should be used to access data
    that is not present locally.

1.6.1-rich-root:
    (native) A variant of 1.6 that supports rich-root data (needed for
    bzr-svn).

1.9:
    (native) A repository format using B+tree indexes. These indexes
    are smaller in size, have smarter caching and provide faster
    performance for most operations.

1.9-rich-root:
    (native) A variant of 1.9 that supports rich-root data (needed for
    bzr-svn).

and

Other Storage Formats

Experimental formats are shown below.

development-wt5:
    (native) A working-tree format that supports views and content
    filtering.

development-wt5-rich-root:
    (native) A variant of development-wt5 that supports rich-root data
    (needed for bzr-svn).

development:
    (native) Current development format. Can convert data to and from
    pack-0.92 (and anything compatible with pack-0.92) format
    repositories. Repositories and branches in this format can only be
    read by bzr.dev. Please read http://doc.bazaar-
    vcs.org/latest/developers/development-repo.html before use.

development-subtree:
    (native) Current development format, subtree variant. Can convert
    data to and from pack-0.92-subtree (and anything compatible with
    pack-0.92-subtree) format repositories. Repositories and branches
    in this format can only be read by bzr.dev. Please read http://doc
    .bazaar-vcs.org/latest/developers/development-repo.html before
    use.

Deprecated formats are shown below.

weave:
    (native) Pre-0.8 format. Slower than knit and does not support
    checkouts or shared repositories.

metaweave:
    (native) Transitional format in 0.8. Slower than knit.

knit:
    (native) Format using knits. Recommended for interoperation with
    bzr <= 0.14.

dirstate:
    (native) New in 0.15: Fast local operations. Compatible with bzr
    0.8 and above when accessed over the network.

dirstate-tags:
    (native) New in 0.15: Fast local operations and improved scaling
    for network operations. Additionally adds support for tags.
    Incompatible with bzr < 0.15.

rich-root:
    (native) New in 1.0. Better handling of tree roots. Incompatible
    with bzr < 1.0.

there is no need whatsoever for the very first thing that a new user of Bazaar sees to be a list of this information.

$ bzr init --help
...
  Branch Format:
    --format=ARG Specify a format for this branch. See "help formats".
    --1.6 A format that allows a branch to indicate that there
                        is another (stacked) repository that should be used to
                        access data that is not present locally.
    --1.6.1-rich-root A variant of 1.6 that supports rich-root data (needed
                        for bzr-svn).
    --1.9 A repository format using B+tree indexes. These
                        indexes are smaller in size, have smarter caching and
                        provide faster performance for most operations.
    --1.9-rich-root A variant of 1.9 that supports rich-root data (needed
                        for bzr-svn).
    --default New in 0.92: Pack-based format with data compatible
                        with dirstate-tags format repositories. Interoperates
                        with bzr repositories before 0.92 but cannot be read
                        by bzr < 0.92. Previously called knitpack-
                        experimental. For more information, see http://doc
                        .bazaar-vcs.org/latest/developers/packrepo.html.
    --development Current development format. Can convert data to and
                        from pack-0.92 (and anything compatible with
                        pack-0.92) format repositories. Repositories and
                        branches in this format can only be read by bzr.dev.
                        Please read http://doc.bazaar-
                        vcs.org/latest/developers/development-repo.html before
                        use.
    --development-subtree
                        Current development format, subtree variant. Can
                        convert data to and from pack-0.92-subtree (and
                        anything compatible with pack-0.92-subtree) format
                        repositories. Repositories and branches in this format
                        can only be read by bzr.dev. Please read http://doc
                        .bazaar-vcs.org/latest/developers/development-
                        repo.html before use.
    --development-wt5 A working-tree format that supports views and content
                        filtering.
    --development-wt5-rich-root
                        A variant of development-wt5 that supports rich-root
                        data (needed for bzr-svn).
    --dirstate New in 0.15: Fast local operations. Compatible with
                        bzr 0.8 and above when accessed over the network.
    --dirstate-tags New in 0.15: Fast local operations and improved
                        scaling for network operations. Additionally adds
                        support for tags. Incompatible with bzr < 0.15.
    --knit Format using knits. Recommended for interoperation
                        with bzr <= 0.14.
    --metaweave Transitional format in 0.8. Slower than knit.
    --pack-0.92 New in 0.92: Pack-based format with data compatible
                        with dirstate-tags format repositories. Interoperates
                        with bzr repositories before 0.92 but cannot be read
                        by bzr < 0.92. Previously called knitpack-
                        experimental. For more information, see http://doc
                        .bazaar-vcs.org/latest/developers/packrepo.html.
    --rich-root New in 1.0. Better handling of tree roots.
                        Incompatible with bzr < 1.0.
    --rich-root-pack New in 1.0: A variant of pack-0.92 that supports rich-
                        root data (needed for bzr-svn).
    --weave Pre-0.8 format. Slower than knit and does not support
                        checkouts or shared repositories.

...

I therefore recommend that ALL of that be removed from the help for `bzr init` and `bzr init-repo` because it is horribly confusing for new users, especially in the face of "... otherwise the default is fine".

AfC

[Wesley J. Landaker (wjl)]

One thing to keep in mind if this is changed or removed is that the user still needs to know that they can do "bzr init --1.9" as opposed to "bzr init --format=1.9". The help pages on formats don't tell you that.

[Martin Pool (mbp)]

  tags help ui easy
  status confirmed
  importance medium

--
Martin

[Martin Pool (mbp)]

I just hit this myself looking at bug 249908, it certainly shows way too many.

[Robert Collins (lifeless)]

On Thu, 2009-03-19 at 04:17 +0000, Martin Pool wrote:
> I just hit this myself looking at bug 249908, it certainly shows way too
> many.

I agree; note that help formats now *doesn't* show everything, so
removing it from init --help etc will make it undiscoverable if no
further actions are taken.

-Rob

[Martin Pool (mbp)]

I propose to do this by

 * removing the expansion of formats into options so that you have to say --format 1.9.

 * making sure there's a link to 'help formats' from --format