gitorious.org Git - opensuse:osc.git/blob

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.