- re-add but ignore deprecated option --skip-validation
[opensuse:osc.git] / PROJ_PACK.txt
1                 jw, Tue Oct 20 22:09:16 CEST 2009
2
3 This is a feature suggestion for easier osc commandline handling.
4 Many commands require specifying Project and/or Package names.
5
6 The current situation is not satisfying for the following reasons:
7  - inconsistent defaults. Some osc subcommands can take project
8    and/or package names from the current directory, if run inside a checkout
9    tree. If both project and package can use this default or only one, and if
10    one, which, depends on the command. Users have a hard time memorizing
11    which is which.
12      Examples as of osc version 0.123:
13        osc maintainer PRJ [PKG]
14          - does not look in the current directory.
15          - need at least PRJ.
16        osc list [PRJ [PKG]]
17          - Never looks at the current directory.
18          - lists all projects, if run without parameters.
19        osc checkout [PRJ] PKG
20        osc checkout PRJ
21          - takes project from current directory, if inside a checkout tree
22          - else operates on an entire project.
23        osc checkin [ARG]
24          - defaults to current project and package,
25          - if arg is a subdirectory, project is taken from current directory
26          - if arg is a file, both project and package are taken from current
27            directory.
28        osc results [PRJ PKG]
29          - takes either both or none from current directory.
30  - many commands do not look into the current directory,
31    they are cumbersome to use.
32  - sometimes PRJ/PKG can be used instead of PRJ PKG
33
34
35 Suggested solution
36 ------------------
37
38 Instead of tuning (maybe optional) positional parameters.
39 We suggest to deprecate this syntax over time and instead favour an alternate
40 syntax:
41   osc CMD ... [--prj PRJ] [--pkg PKG] ...
42   osc CMD ... [--proj PRJ] [--pack PKG] ...
43   osc CMD ... [--project PRJ] [--package PKG] ...
44
45 These six options are new to osc, currently no existing command uses
46 them.  Thus the new syntax is conflict free wit the old syntax, both can be
47 used in parallel.
48
49 --prj, --proj, --project are synonyms.
50 --pkg, --pack, --package are synonyms.
51
52 osc shall support aliases, to save typing. Some implicit aliases exist,
53 with well defined magic effects. Aliases substitution is literal.
54 They can replace options including their parameters, or just the option, or
55 just the parameters.
56  -        (a dash) expands to --prj openSUSE:Factory
57         (or --prj followed by any other project as defined in
58         ~/.oscrc:default_project )
59         --prj -         is synonymous to just -, for consistency.
60
61  .      (a dot) evaluates the current working directory, searching for
62         .osc/_apiurl, .osc/_project, and .osc/_package
63         Implicit --apiurl, --prj, or --pkg options are constructed as far
64         as available from the current directory and as far as not already
65         present in the command line.
66         If a dot is used as parameter to an option, it has a more
67         deterministic meaning.
68         --apiurl .        Substitute only the current apiurl,
69         --prj .                Substitute the current project name, and provides
70                         a default for --apiurl unless given.
71         --pkg .         Substitures current package name likewise.
72
73  ./.    expands to --prj . --pkg .
74  ./PKG  expands to --prj . --pkg PKG
75
76 Unless otherwise noted in the online help, magic aliases are only attempted onceper commandline, and will only apply to their respective options.
77 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
78 osc ci . -m - would do.
79
80 Additionally, user defined aliases can be added to ~/.oscrc
81 If an alias expansion has effect on the command line, the expanded line is
82 printed as debug output.
83
84 online help of osc commands shall refer to the above syntax like this:
85
86         osc CMD ... PROJ/PACK
87
88 An additional help entry
89
90         osc help 'PROJ/PACK'
91
92 shall explain the relevant details as presented herein.