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