README

   1 osc -- opensuse-commander with svn like handling
   2
   3
   4 Patches can be submitted via
   5  * mail to opensuse-buildservice@opensuse.org
   6  * Bugzilla: https://bugzilla.novell.com/enter_bug.cgi?product=openSUSE.org&component=BuildService
   7  * or the official Git repository on Gitorious:
   8    http://gitorious.org/opensuse/osc
   9
  10
  11 INSTALLATION:
  12
  13 RPM packages are here (rpm-md repository):
  14 http://download.opensuse.org/repositories/openSUSE:/Tools/
  15
  16 To install from svn, do
  17
  18         python setup.py build
  19         python setup.py install
  20         # create a symlink 'osc' in your path pointing to osc.py.
  21         ln -s osc-wrapper.py /usr/bin/osc
  22
  23 Alternatively, you can directly use osc-wrapper.py from the source dir
  24 (which is easier if you develop on osc).
  25
  26
  27 The program needs the cElementTree python module installed. On SUSE, the
  28 respective package is called python-elementtree (before 10.2: python-xml).
  29 For local building, you will need python-urlgrabber in addition. Those are
  30 standard package on SUSE Linux since a while. If your version is too old, you
  31 can find python-elementtree and python-urlgrabber here:
  32 http://download.opensuse.org/repositories/devel:/languages:/python/
  33
  34
  35
  36 CONFIGURATION:
  37
  38 When you use it for the first time, it will ask you for your username and
  39 password, and store it in ~/.oscrc.
  40
  41
  42 CONFIGURATION MIGRATION (only affects versions >= 0.114):
  43
  44 Version 0.114 got some cleanups for the configfile handling and therefore some
  45 options are now deprecated, namely:
  46 * apisrv
  47 * scheme
  48
  49 One new option was added:
  50 * apiurl = <protocol>://<somehost> # use this as the default apiurl. If this
  51 option isn't specified the default (https://api.opensuse.org) is used.
  52
  53 So far osc still has some backward compatibility for these options but it might
  54 get removed in the future that's why it issues a deprecation warning in case
  55 one of those options is still in use.
  56
  57 The new configuration scheme looks like the following:
  58  # entry for an apiurl
  59  [<protocol>://<apiurl>]
  60  user = <username>
  61  password = <password>
  62  ...
  63
  64 '''Before starting the migration please save your ~/.oscrc file!'''
  65
  66 If the migration doesn't work for whatever reason feel free to send me an email
  67 or ask on the opensuse-buildservice mailinglist or in the #opensuse-buildservice
  68 irc channel.
  69
  70 === Migration case I (apisrv only) ===
  71 The apisrv option is used to specify the default apihost. If apisrv isn't
  72 specified at all the default ("api.opensuse.org") is used.
  73 The current [general] section looks like this:
  74  [general]
  75  ...
  76  apisrv = <somehost>
  77  # or
  78  apisrv = <protocol>://<somehost>
  79
  80 apisrv got superseded by the new apiurl option which looks like this:
  81  [general]
  82  ...
  83  apiurl = <protocol>://<somehost>
  84
  85 If apisrv has no "<protocol>" https is used. Make sure all apiurl sections have
  86 the new format which is described above. Afterwards apisrv can be removed.
  87
  88 === Migration case II (scheme only) ===
  89 The current [general] section looks like this:
  90  [general]
  91  ...
  92  scheme = <protocol>
  93
  94 This means every apiurl section which don't have the new format which is
  95 described above for instance
  96  [<somehost>]
  97  user = <username>
  98  password = <password>
  99  ...
 100
 101 has to be converted to
 102  [<protocol>://<somehost>]
 103  user = <username>
 104  password = <password>
 105  ...
 106
 107 Afterwards the scheme option can be removed from the [general] section (it
 108 might be the case that some sections already have the correct format).
 109
 110 === Migration case III (apisrv and scheme) ===
 111 The current [general] section looks like this:
 112  [general]
 113  ...
 114  apisrv = <somehost>
 115  scheme = <protocol>
 116
 117 Both options can be removed if all apiurl sections have the new format which is
 118 described above. So basically just adjust all apiurl sections (it might be the
 119 case that some sections already have the correct format).
 120
 121
 122 KEYRING USAGE
 123
 124 Osc now can store passwords in keyrings instead of ~/.oscrc. To use it,
 125 you need python-keyring and either python-keyring-kde or -gnome.
 126
 127 If you want to switch to using a keyring you need to delete apiurl section
 128 from ~/.oscrc and you will be asked for credentials again, which will be then
 129 stored in the keyring application.
 130
 131
 132 WORKING COPY INCONSISTENT (only affects version >= 0.130)
 133
 134 osc's working copy handling was rewritten in 0.130. Thus some
 135 consistency checks were added. As a result osc might complain
 136 that some old working copies are in an inconsistent state:
 137  Your working copy '.' is in an inconsistent state.
 138  Please run 'osc repairwc .' (Note this might _remove_
 139  files from the .osc/ dir). Please check the state
 140  of the working copy afterwards (via 'osc status .')
 141 To fix this simply run "osc repairwc ." as suggested in the
 142 error message. Note that "osc repairwc ." might need to contact
 143 the api in order to fetch some missing files. Also it might remove
 144 some files from the storedir (.osc/) but it won't touch any locally
 145 modified files.
 146 If it DOES NOT fix the problem please create a bug report and attach
 147 your working copy to the bug (if possible).
 148
 149
 150 USAGE EXAMPLES:
 151 (online at http://en.opensuse.org/openSUSE:OSC )
 152
 153 To list existing content on the server
 154  osc ls                                # list projects
 155  osc ls Apache                         # list packages in a project
 156  osc ls Apache subversion              # list files of package of a project
 157
 158 Check out content
 159  osc co Apache                         # entire project
 160  osc co Apache subversion              # a package
 161  osc co Apache subversion foo          # single file
 162
 163 Update a working copy
 164  osc up
 165  osc up [pac_dir]                      # update a single package by its path
 166  osc up *                              # from within a project dir, update all packages
 167  osc up                                # from within a project dir, update all packages
 168                                        #   AND check out all newly added packages
 169
 170 If an update can't be merged automatically, a file is in 'C' (conflict)
 171 state, and conflicts are marked with special <<<<<<< and >>>>>>> lines.
 172 After manually resolving the problem, use
 173  osc resolved foo
 174
 175 Upload change content
 176  osc ci                                # current dir
 177  osc ci <dir>
 178  osc ci file1 file2 ...
 179
 180 Show the status (which files have been changed locally)
 181  osc st
 182  osc st <directory>
 183  osc st file1 file2 ...
 184
 185 Mark files to be added or removed on the next 'checkin'
 186  osc add file1 file2 ...
 187  osc rm file1 file2 ...
 188
 189 Adds all new files in local copy and removes all disappeared files.
 190  osc addremove
 191
 192 Generates a diff, to view the changes
 193  osc diff                              # current dir
 194  osc diff file1 file2 ...
 195
 196 Shows the build results of the package
 197  osc results
 198  osc results [repository]
 199
 200 Shows the log file of a package (you need to be inside a package directory)
 201  osc log <repository> <arch>
 202
 203 Shows the URLs of .repo files which are packages sources for Yum/YaST/smart
 204  osc repourls [dir]
 205
 206 Triggers a package rebuild for all repositories/architectures of a package
 207  osc rebuildpac [dir]
 208
 209 Shows available repository/build targets
 210  osc repository
 211
 212 Shows the configured repository/build targets of a project
 213  osc repository <project>
 214
 215 Shows meta information
 216  osc meta Apache
 217  osc meta Apache subversion
 218  osc id username
 219
 220 Edit meta information
 221 (Creates new package/project if it doesn't exist)
 222  osc editmeta Apache
 223  osc editmeta Apache subversion
 224
 225 Update package meta data with metadata taken from spec file
 226  osc updatepacmetafromspec <dir>
 227
 228
 229 There are other commands, which you may not need (they may be useful in scripts):
 230  osc repos
 231  osc buildconfig
 232  osc buildinfo
 233
 234
 235 Locally build a package (see 'osc help build' for more info):
 236  osc build <repo> <arch> specfile [--clean|--noinit]
 237
 238
 239 Update a package to a different sources (directory foo_package_source):
 240  cp -a foo_package_source foo; cd foo; osc init <prj> <pac>; osc addremove; osc ci; cd $OLDPWD; rm -r foo
 241
 242
 243
 244 HINT FOR W3M USERS
 245
 246 Putting the following in the file ~/.w3m/passwd will make
 247 w3m know the credentials for the buildservice servers:
 248
 249 """
 250 host api.opensuse.org
 251   port 80
 252   realm Authentication required
 253   login foo
 254   password bar
 255
 256 host build.opensuse.org
 257   port 80
 258   realm openSUSE Build Service
 259   login foo
 260   password bar
 261 """
 262
 263 chmod 0600 ~/.w3m/passwd
 264
 265
 266 NOTES about the testsuite
 267
 268 A new test suite has been created and should run via doing
 269 # cd tests
 270 # python suite.py
 271