Hi,
as a part of our Google Summer of Code Project to cleanup osc our
first task was to define a new commandline user interface for osc.
The current user interface is quite “inconsistent” (with regard to
the expected arguments for different commands) and has some other
“flaws”.
Here are some examples to show some flaws of the current user
interface:
* inconsistent ui:
– osc results project package –repo repo –arch arch
– osc rebuild project package repo arch
– osc build repo arch
– osc ls project package repo arch -b
– osc ls project package -r repo -a arch -b
– osc undelete project package_1 … package_N
– osc rdelete project package_1
* counterintuitive commands:
– osc abortbuild project package
– osc abortbuild project package repo arch
– osc abortbuild (in a package working copy)
– osc abortbuild –repo repo –arch arch (in a package working copy)
– osc abortbuild repo arch (in a package working copy)
=> treats “repo” “arch” as “project” “package”
* “duplicated” commands:
– diff, rdiff
– buildlog, remotebuildlog, localbuildlog
– delete, rdelete, rremove
Additionally we support lots of commands and the output of
“osc –help”is quite long. In order to tackle this problem we decided
to introduce “groups” with subcommands, for instance:
attribute list
attribute create…
attribute set…
…
As a result we get rid of “god commands” (commands which supported
lots of different options for different things (like osc meta)) and
the new commands are easier to use because they support less arguments
and/or options (note: this doesn’t mean we lose functionality – the
functionality is just moved to another command/command group).
The attached table is just a _proposal_ for a new commandline user
interface.
Some additional explanations:
The biggest change with regard to our current user interface is the
introduction of an url-like syntax:
For example:
osc ls api://project/package
instead of
osc ls project package
In this case “api” means that the request is issued to the default
apiurl (in most cases https://api.opensuse.org) which can be
configured in the ~/.oscrc.
To issue the “list” request to a different obs instance one can use:
osc ls https://api.somehost/project/package
or
osc ls alias://project/package
“alias” is an alias for this apiurl which can be configured in the
~/.oscrc.
If you see this url-like syntax for the first time you might think
that it makes things much more complicated (and even more to type)
but it is advantageous:
– in most cases it is obvious if a command is a remote command or
local working copy command
– this way we get rid of ambiguities:
Suppose we support the following command (“<foo>” indicate that
“foo” is an optional argument):
binaries get api://project/package <repo/arch>
binaries get <repo/arch> (if $PWD is a package working copy
the project and package arguments will be read from it)
Possible invocations are:
osc binaries get api://foo/bar standard/i586 # get all binaries
for this repo and arch
osc binaries get api://foo/bar # get all binaries for all repos
and all arches
# now suppose $PWD is a package working copy:
osc binaries get standard/i586 # get all binaries for this repo
and arch (project and package are read from the working copy)
osc binaries get api://foo/bar # gets all binaries for all repos
and all arches (project is “foo” and package is “bar”)
In the latter invocation we’re still in a package working copy
but ignore it and use the project and package arguments which
were specified.
Note: in this case a special (like the url-like) syntax is required
otherwise osc is unable to distinguish between a project/package and
repo/arch argument.
Once again this is just a _proposal_ – feedback is very welcome!
(please send the feedback to the opensuse-buildservice@opensuse.org mailinglist – thread)
Marcus
init, list, meta, attribute, request, submitrequest, review, link, copy, maintenance, branch, delete, undelete, diff, checkout, status, add, addremove, commit, update, resolved, distributions, results, buildlog, buildmeta, build, chroot, log, service, abortbuild, rebuild, binaries, search, my,
importsrcpkg, person, cat, less, repair, pull, signkey, vc, mv, config, revert, api, aggregate, mkpac, setlinkrev, linktobranch, detachbranch
setlinkrev, linktobranch and detachbranch might be grouped into group “other”.
Deleted commands:
| cmd | replacement | reason |
|---|---|---|
| deleterequest args | request create –delete args | |
| reqeuestmaintainership args | request create –role maintainer args | |
| changedevelrequest args | request create –changedevel args | |
| request approvenew project <package> | request –interactive-review could be used (but it’s no real replacement) | |
| request log id | request show id –log | |
| linkpac | link | |
| copypac | copy | |
| releaserequest | maintenance releaserequest | |
| createincident | maintenance createincident | |
| maintenancerequest | maintenance request | |
| mbranch | maintenance branch | |
| getpac | use branch | |
| rdelete | delete | |
| updatepacmetafromspec | ||
| rdiff | diff | |
| linkdiff | no replacement atm (current implementation partly broken); diff could support it | |
| repourls | isn’t needed IMHO | |
| prjresults | results | |
| remotebuildlog | buildlog | |
| localbuildlog | buildlog –local | |
| buildinfo | buildmeta info | |
| buildconfig | buildmeta config | |
| triggerreason | buildmeta triggerreason | |
| dependson | buildmeta dependson | |
| buildhistory | buildmeta history | |
| jobhistory | buildmeta jobhistory | |
| info | not needed anymore | |
| getbinaries | binaries get | |
| wipebinaries | binaries wipe | |
| list –binaries | binaries list | |
| search –binary | binaries search | |
| bugowner | no real replacement use person maintainer -b (if we support this) | |
| maintainer | person maintainer | |
| maintainer project –add user –role role | person add api://project role user | |
| maintainer project –delete user | person delete api://project user | |
| whois | person meta | |
| meta user | person meta | |
| cat/less http://api/source/project/package/file | not needed (IMHO) | |
| repairlink | repair link | |
| repairwc | repair wc | |
| signkey | signkey | it’s not context-sensitive anymore |
| rremove | do we really need this? | |
| aggregatepac | aggregate | |
| develproject | meta | meta should display the xml in a nice way so that it’s easy to see whether a develprj is defined or not |
| repositories | meta | meta should display the xml in a nice way so that all repos are displayed |
new commandline user interface
init
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| init | api://project | ||||
| init | api://project/package |
list
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| ls | x | list all remote packages for the wc project | |||
| ls | x | list all remote files for the wc package | |||
| ls | api:// | ||||
| ls | api://project | ||||
| ls | api://project/package | ||||
| ls | api://project/package/file | just for backward compatibility |
meta
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| meta | x | shows/edits project meta | |||
| meta | x | shows/edits package meta | |||
| meta | api://project | ||||
| meta | api://project/package | ||||
| meta | api://project/_prjconf |
attribute
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| attribute is not context sensitive | |||||
| attribute | list | api://project | show all attributes | ||
| attribute | list | api://project attribute | show specific attribute | ||
| attribute | set | api://project attribute newval | set attribute to newval | ||
| attribute | create | api://project attribute | create new attribute | ||
| attribute | delete | api://project attribute | delete attribute | ||
| attribute | list | api://project/package | show all attributes | ||
| attribute | list | api://project/package/binary | show all attributes – /binary works for all commands below, too | ||
| attribute | list | api://project/package attribute | show specific attribute | ||
| attribute | set | api://project/package attribute newval | set attribute to newval | ||
| attribute | create | api://project/package attribute | create new attribute | ||
| attribute | delete | api://project/package attribute | delete attribute | ||
request
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| request is not context sensitive | |||||
| request | create | –submit api://project/package api://tgt_projet/<package> | |||
| request | create | –submit api://project/package api://tgt_projet/<package> | |||
| request | create | –changedevel api://project/package api://tgt_projet/<package> | |||
| request | create | –role role user api://project/<package> | |||
| request | create | –grouprole role group api://project/<package> | |||
| request | create | –bugowner user api://project/<package> | alternatively we treat bugowner as a “role” and use –role bugowner… | ||
| request | create | –delete api://project/<package> | |||
| request | list | api://<project>/<package> | list all/project/package requests | ||
| in the following we support both: “api://id” and “id” (if the latter format is specified the default apiurl is used – regardless if the cmd is executed in a wc) | |||||
| request | show | api://id | apart from –brief also support –log which just shows the statehistory + current state | ||
| request | supersede | api://id api://supersede_id | |||
| request | accept | api://id | |||
| request | decline | api://id | |||
| request | revoke | api://id | |||
| request | reopen | api://id | |||
| request | wipe | api://id | |||
| request | checkout | (x) | api://id | if the package’s package belongs to the wc’s project the package will be added to this project (if it already exists an error will be printed) | |
submitrequest
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| submitrequest | x | semantic change: creates a sr for all local packages (instead of all remote) | |||
| submitrequest | x | wc has to be a source link | |||
| submitrequest | x | api://tgt_project/<tgt_package> | |||
| submitrequest | api://project/package api://tgt_project/<tgt_package> |
review
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| review | accept | api://id | |||
| review | decline | api://id | |||
| review | reopen | api://id | |||
| review | susersede | api://id api://supsersede_id | |||
| review | add | api://id –user user –group group –package package –project project | at least one option is required | ||
| review | list | api://<project>/<package> | just for convenience; “request list –state review” should lead to the same result |
link
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| link | api://link_project api://project | ||||
| link | api://link_project/link_package api://project/&tl;package> |
copy
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| copy | api://copy_project api://project | could be supported | |||
| copy | api://copy_project/copy_package api://project/&tl;package> |
maintenance
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| maintenance | releaserequest | x | |||
| maintenance | releaserequest | api://project | |||
| maintenance | createincident | <api://project> | |||
| maintenance | request | api://project <api://tgt_project> | |||
| maintenance | branch | package <tgt_project> | XXX: this voilates the url schema |
branch
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| branch | api://project/package <api://tgt_project/tgt_package> |
undelete
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| undelete | api://project/<package> |
delete
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| delete | api://project/<package> | multiple arguments can be specified | |||
| delete | /path/to/package | ||||
| delete | /path/to/file |
diff
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| diff | x | ||||
| diff | x | ||||
| diff | /path/to/file | multiple args are supported | |||
| diff | /path/to/package | ||||
| diff | /path/to/project | ||||
| diff | api://project/package | ||||
| diff | api://project/package api://original_project/original_package |
checkout
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| checkout | api://project/<package> | checking out a file is not supported anymore | |||
| checkout | x | package | adds the package to the wc | ||
| checkout | x | package | adds the package to the wc |
status
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| status | x | ||||
| status | x | ||||
| status | /path/to/project_or_package_or_file | multiple arguments are supported |
add
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| add | /path/to/dir_or_file | multiple arguments are supported | |||
| add | URL | create a _service file |
addremove
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| addremove | x | ||||
| addremove | x | ||||
| addremove | /path/to/package | multiple arguments are supported |
commit
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| commit | x | ||||
| commit | x | ||||
| commit | /path/to/project_or_package_or_file | multiple arguments are supported |
update
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| update | x | ||||
| update | x | ||||
| update | /path/to/project_or_package | multiple arguments are supported |
resolved
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| resolved | /path/to/file | multiple arguments are supported |
distributions
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| distributions | api:// |
results
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| results | x | ||||
| results | x | ||||
| results | api://project/<package> |
buildlog
if repo/arch is not specified the config values will be used (default_repo, default_arch)
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| buildlog | x | <repo/arch> | |||
| buildlog | x | <repo/arch> –local | |||
| buildlog | api://project/package <repo/arch> |
buildmeta
if repo/arch is not specified the config values will be used (default_repo, default_arch)
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| buildmeta | info | x | <repo/arch> <build_descr> | distingiush between repo/arch build_descr, /arch build_descr via the file extension of build_descr | |
| buildmeta | info | api://project/package <repo/arch> <build_descr> | distingiush between repo/arch build_descr, /arch build_descr via the file extension of build_descr | ||
| buildmeta | config | x | <repo/arch> <build_descr> | ||
| buildmeta | config | api://project/package <repo> | |||
| buildmeta | triggerreason | x | <repo/arch> | ||
| buildmeta | triggerreason | api://project/package <repo/arch> | |||
| buildmeta | dependson | x | <repo/arch> | ||
| buildmeta | dependson | api://project/package <repo/arch> | |||
| buildmeta | log | x | <repo/arch> | same as buildlog (just for consistency) | |
| buildmeta | log | x | <repo/arch> –local | same as buildlog (just for consistency) | |
| buildmeta | log | api://project/package <repo/arch> | same as buildlog (just for consistency) | ||
| buildmeta | history | x | <repo/arch> | ||
| buildmeta | history | api://project/package <repo/arch> | |||
| buildmeta | jobhistory | x | <repo/arch> | ||
| buildmeta | jobhistory | x | <repo/arch> | ||
| buildmeta | jobhistory | api://project/<package> <repo/arch> |
build
if repo/arch is not specified the config values will be used (default_repo, default_arch)
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| build | x | <repo/arch> <build_descr> |
chroot
if repo/arch is not specified the config values will be used (default_repo, default_arch)
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| chroot | x | <repo/arch> <build_descr> | build_descr is not needed for the command itself |
log
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| log | x | ||||
| log | x | ||||
| log | api://project/<package> |
service
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| service | run | x | <service_name> | ||
| service | disabledrun | x | |||
| service | remoterun | api://project/package |
abortbuild
if repo/arch is not specified the config values will be used (default_repo, default_arch)
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| abortbuild | x | <repo/arch> | to abort all builds specifiy –all | ||
| abortbuild | x | <repo/arch> | to abort all builds specifiy –all | ||
| abortbuild | api://project/<package> <repo/arch> | to abort all builds specifiy –all |
rebuild
if repo/arch is not specified the config values will be used (default_repo, default_arch)
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| rebuild | x | <repo/arch> | to rebuild all packages specifiy –all | ||
| rebuild | x | <repo/arch> | to rebuild all packages specifiy –all | ||
| rebuild | api://project/<package> <repo/arch> | to rebuild all packages specifiy –all |
rebuild
if repo/arch is not specified the config values will be used (default_repo, default_arch)
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| binaries | get | x | <repo/arch> | to get all binaries specifiy –all | |
| binaries | get | x | <repo/arch> | to get all binaries specifiy –all | |
| binaries | get | api://project/<package> <repo/arch> | to get all binaries specifiy –all | ||
| binaries | list | x | <repo/arch> | to list all binaries specifiy –all | |
| binaries | list | x | <repo/arch> | to list all binaries specifiy –all | |
| binaries | list | api://project/<package> <repo/arch> | to list all binaries specifiy –all | ||
| binaries | wipe | x | <repo/arch> | to wipe all binaries specifiy –all | |
| binaries | search | api://<project> search_term | |||
| binaries | wipe | api://project/<package> <repo/arch> | to wipe all binaries specifiy –all |
my
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| my | requests | ||||
| my | submitrequests | ||||
| my | projects | ||||
| my | packages |
search
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| search | search_term |
importsrcpkg
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| importsrcpkg | x | /path/to/srpm |
person
For groups we can add a new “group” command
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| person | meta | api://username <–edit> | |||
| person | maintainer | api://project/<package> | show maintainer of the project/package | ||
| person | maintainer | api://project/<package> | show maintainer of the project/package | ||
| person | add | api://project/<package> user role | |||
| person | delete | api://project/<package> user <role> |
cat
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| cat | api://project/package/file |
less
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| cat | api://project/package/file |
repair
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| repair | link | x | |||
| repair | link | api://project/package <api://into_project/<into_package>> | |||
| repair | wc | x | |||
| repair | wc | x |
pull
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| pull | x |
signkey
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| signkey | api://project |
vc
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| vc |
mv
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| mv | x | filename new_filename | should we support this for packages, too? |
config
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| config | section option | ||||
| config | section option value |
revert
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| revert | x | ||||
| revert | /path/to/file | multiple arguments are supported |
api
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| api | api://path/to/something |
aggregate
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| aggregate | api://project/package api://tgt_project/<tgt_packge> |
mkpac
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| mkpac | x | package_name |
setlinkrev
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| setlinkrev | x | ||||
| setlinkrev | api://project/<package> |
linktobranch
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| linktobranch | x | ||||
| linktobranch | api://project/package |
detachbranch
| cmd | subcmd | prj wc | pkg wc | params/opts | note |
|---|---|---|---|---|---|
| detachbranch | x | ||||
| detachbranch | api://project/package |
(please send the feedback to the opensuse-buildservice@opensuse.org mailinglist – thread)
Both comments and pings are currently closed.
