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