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