Make 'trust always' more verbose, so that a user learns how to undo its effect.
[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
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 USAGE EXAMPLES:
133 (online at http://en.opensuse.org/Build_Service/CLI )
134
135 To list existing content on the server
136  osc ls                                # list projects
137  osc ls Apache                         # list packages in a project
138  osc ls Apache subversion              # list files of package of a project
139
140 Check out content
141  osc co Apache                         # entire project
142  osc co Apache subversion              # a package
143  osc co Apache subversion foo          # single file
144
145 Update a working copy
146  osc up
147  osc up [pac_dir]                      # update a single package by its path
148  osc up *                              # from within a project dir, update all packages
149  osc up                                # from within a project dir, update all packages
150                                        #   AND check out all newly added packages
151
152 If an update can't be merged automatically, a file is in 'C' (conflict)
153 state, and conflicts are marked with special <<<<<<< and >>>>>>> lines.
154 After manually resolving the problem, use
155  osc resolved foo
156
157 Upload change content
158  osc ci                                # current dir
159  osc ci <dir>
160  osc ci file1 file2 ...
161
162 Show the status (which files have been changed locally)
163  osc st
164  osc st <directory>
165  osc st file1 file2 ...
166
167 Mark files to be added or removed on the next 'checkin'
168  osc add file1 file2 ...
169  osc rm file1 file2 ...
170
171 Adds all new files in local copy and removes all disappeared files.
172  osc addremove
173
174 Generates a diff, to view the changes
175  osc diff                              # current dir
176  osc diff file1 file2 ...
177
178 Shows the build results of the package
179  osc results
180  osc results [repository]
181
182 Shows the log file of a package (you need to be inside a package directory)
183  osc log <repository> <arch>
184
185 Shows the URLs of .repo files which are packages sources for Yum/YaST/smart
186  osc repourls [dir]
187
188 Triggers a package rebuild for all repositories/architectures of a package
189  osc rebuildpac [dir]
190
191 Shows available repository/build targets
192  osc repository
193
194 Shows the configured repository/build targets of a project
195  osc repository <project>
196
197 Shows meta information
198  osc meta Apache
199  osc meta Apache subversion
200  osc id username
201
202 Edit meta information
203 (Creates new package/project if it doesn't exist)
204  osc editmeta Apache
205  osc editmeta Apache subversion
206
207 Update package meta data with metadata taken from spec file
208  osc updatepacmetafromspec <dir>
209
210
211 There are other commands, which you may not need (they may be useful in scripts):
212  osc repos
213  osc buildconfig
214  osc buildinfo
215
216
217 Locally build a package (see 'osc help build' for more info):
218  osc build <repo> <arch> specfile [--clean|--noinit]
219
220
221 Update a package to a different sources (directory foo_package_source):
222  cp -a foo_package_source foo; cd foo; osc init <prj> <pac>; osc addremove; osc ci; cd $OLDPWD; rm -r foo
223
224
225
226 HINT FOR W3M USERS
227
228 Putting the following in the file ~/.w3m/passwd will make
229 w3m know the credentials for the buildservice servers:
230
231 """
232 host api.opensuse.org
233   port 80
234   realm Authentication required
235   login foo
236   password bar
237
238 host build.opensuse.org
239   port 80
240   realm openSUSE Build Service
241   login foo
242   password bar
243 """
244
245 chmod 0600 ~/.w3m/passwd
246
247
248 NOTES about the testsuite
249
250 It requires editing tests.py, for a user account / project to work with.
251 I use my own project (home:poeml) for testing.
252 Tests can be run as ./tests.py
253 or, more powerful, with nosetests:
254   nosetests --exe
255 To run a single test, you can use:
256   nosetests --exe tests:TestOsc.testCmdOptVersion