PROJ_PACK.txt

                jw, Tue Oct 20 22:09:16 CEST 2009

This is a feature suggestion for easier osc commandline handling.
Many commands require specifying Project and/or Package names.

The current situation is not satisfying for the following reasons:
 - inconsistent defaults. Some osc subcommands can take project
   and/or package names from the current directory, if run inside a checkout
   tree. If both project and package can use this default or only one, and if
   one, which, depends on the command. Users have a hard time memorizing
   which is which.
     Examples as of osc version 0.123:
       osc maintainer PRJ [PKG]
         - does not look in the current directory.
         - need at least PRJ.
       osc list [PRJ [PKG]]
         - Never looks at the current directory.
         - lists all projects, if run without parameters.
       osc checkout [PRJ] PKG
       osc checkout PRJ
         - takes project from current directory, if inside a checkout tree
         - else operates on an entire project.
       osc checkin [ARG]
         - defaults to current project and package,
         - if arg is a subdirectory, project is taken from current directory
         - if arg is a file, both project and package are taken from current
           directory.
       osc results [PRJ PKG]
         - takes either both or none from current directory.
 - many commands do not look into the current directory,
   they are cumbersome to use.
 - sometimes PRJ/PKG can be used instead of PRJ PKG


Suggested solution
------------------

Instead of tuning (maybe optional) positional parameters.
We suggest to deprecate this syntax over time and instead favour an alternate
syntax:
  osc CMD ... [--prj PRJ] [--pkg PKG] ...
  osc CMD ... [--proj PRJ] [--pack PKG] ...
  osc CMD ... [--project PRJ] [--package PKG] ...

These six options are new to osc, currently no existing command uses
them.  Thus the new syntax is conflict free wit the old syntax, both can be
used in parallel.

--prj, --proj, --project are synonyms.
--pkg, --pack, --package are synonyms.

osc shall support aliases, to save typing. Some implicit aliases exist,
with well defined magic effects. Aliases substitution is literal.
They can replace options including their parameters, or just the option, or
just the parameters.
 -        (a dash) expands to --prj openSUSE:Factory
        (or --prj followed by any other project as defined in
        ~/.oscrc:default_project )
        --prj -         is synonymous to just -, for consistency.

 .      (a dot) evaluates the current working directory, searching for
        .osc/_apiurl, .osc/_project, and .osc/_package
        Implicit --apiurl, --prj, or --pkg options are constructed as far
        as available from the current directory and as far as not already
        present in the command line.
        If a dot is used as parameter to an option, it has a more
        deterministic meaning.
        --apiurl .        Substitute only the current apiurl,
        --prj .                Substitute the current project name, and provides
                        a default for --apiurl unless given.
        --pkg .         Substitures current package name likewise.

 ./.    expands to --prj . --pkg .
 ./PKG  expands to --prj . --pkg PKG

Unless otherwise noted in the online help, magic aliases are only attempted onceper commandline, and will only apply to their respective options.
E.g. osc ci -m - will use a simple '-' as check in messages, and the absence of any project or package will default to the current project or package, just as
osc ci . -m - would do.

Additionally, user defined aliases can be added to ~/.oscrc
If an alias expansion has effect on the command line, the expanded line is
printed as debug output.

online help of osc commands shall refer to the above syntax like this:

        osc CMD ... PROJ/PACK

An additional help entry

        osc help 'PROJ/PACK'

shall explain the relevant details as presented herein.