1WSTOOL(1) wstool WSTOOL(1)
2
6 wstool - wstool Documentation
7 Using wstool you can update several folders using a variety of SCMs
9 (SVN, Mercurial, git, Bazaar) with just one command.
10 That way you can more effectively manage source code workspaces.
12 The wstool package provides a Python API for interacting with a source
14 code workspace as well as a group of command line tools. Rosinstall
15 leverages the vcstools package for source control and stores its state
16 in .rosinstall files.
17
19 wstool allows manipulation of a set of version-controlled folders as
20 specified in a workspace definition file.
21 Contents
23 • wstool: A tool for managing source code workspaces
24 • Usage
26 • init
28 • set
30 • merge
32 • update
34 • info
36 • status
38 • diff
40 Usage
42 wstool is a command to manipulate multiple version controlled folders.
43 Official usage:
45 wstool CMD [ARGS] [OPTIONS]
46 wstool will try to infer install path from context
48 Type 'wstool help' for usage.
50 Options:
51 help provide help for commands
52 init set up a directory as workspace
53 set add or changes one entry from your workspace config
54 merge merges your workspace with another config set
55 remove (rm) remove an entry from your workspace config, without deleting files
56 update (up) update or check out some of your config elements
57 info Overview of some entries
58 status (st) print the change status of files in some SCM controlled entries
59 diff (di) print a diff over some SCM controlled entries
60 init
62 set up a directory as workspace
63 wstool init does the following:
65 1. Reads folder/file/web-uri SOURCE_PATH looking for a rosinstall
67 yaml
68 2. Creates new .rosinstall file at TARGET-PATH configured
70 SOURCE_PATH can e.g. be a folder like /opt/ros/electric If PATH is not
72 given, uses current folder.
73 Usage: wstool init [TARGET_PATH [SOURCE_PATH]]?
75 Options::
77 -h, --help show this help message and exit
79 --continue-on-error Continue despite checkout errors
80 -j JOBS, --parallel=JOBS
81 How many parallel threads to use for installing
82 Examples:
84 $ wstool init ~/jade /opt/ros/jade
86 set
88 add or changes one entry from your workspace config The command will
89 infer whether you want to add or modify an entry. If you modify, it
90 will only change the details you provide, keeping those you did not
91 provide. if you only provide a uri, will use the basename of it as lo‐
92 calname unless such an element already exists.
93 The command only changes the configuration, to checkout or update the
95 element, run wstool update afterwards.
96 Usage: wstool set [localname] [SCM-URI]? [--(detached|svn|hg|git|bzr)] [--version=VERSION]]
98 Options:
100 -h, --help show this help message and exit
101 --detached make an entry unmanaged (default for new element)
102 -v VERSION, --version-new=VERSION
103 point SCM to this version
104 --git make an entry a git entry
105 --svn make an entry a subversion entry
106 --hg make an entry a mercurial entry
107 --bzr make an entry a bazaar entry
108 -y, --confirm Do not ask for confirmation
109 -u, --update update repository after set
110 -t WORKSPACE, --target-workspace=WORKSPACE
111 which workspace to use
112 Examples:
114 $ wstool set robot_model --hg https://kforge.ros.org/robotmodel/robot_model
116 $ wstool set robot_model --version robot_model-1.7.1
117 $ wstool set robot_model --detached
118 merge
120 The command merges config with given other rosinstall element sets,
121 from files or web uris.
122 The default workspace will be inferred from context, you can specify
124 one using -t.
125 By default, when an element in an additional URI has the same lo‐
127 cal-name as an existing element, the existing element will be replaced.
128 In order to ensure the ordering of elements is as provided in the URI,
129 use the option --merge-kill-append.
130 Usage: wstool merge [URI] [OPTIONS]
132 Options:
134 -h, --help show this help message and exit
135 -a, --merge-kill-append
136 merge by deleting given entry and appending new one
137 -k, --merge-keep (default) merge by keeping existing entry and
138 discarding new one
139 -r, --merge-replace merge by replacing given entry with new one
140 maintaining ordering
141 -y, --confirm-all do not ask for confirmation unless strictly necessary
142 -t WORKSPACE, --target-workspace=WORKSPACE
143 which workspace to use
144 Examples:
146 $ wstool merge someother.rosinstall
148 You can use '-' to pipe in input, as an example:
150 $ roslocate info robot_mode | wstool merge -
152 update
154 update or check out some of your config elements
155 This command calls the SCM provider to pull changes from remote to your
157 local filesystem. In case the url has changed, the command will ask
158 whether to delete or backup the folder.
159 Usage: wstool update [localname]*
161 Options:
163 -h, --help show this help message and exit
164 --delete-changed-uris
165 Delete the local copy of a directory before changing
166 uri.
167 --abort-changed-uris Abort if changed uri detected
168 --continue-on-error Continue despite checkout errors
169 --backup-changed-uris=BACKUP_CHANGED
170 backup the local copy of a directory before changing
171 uri to this directory.
172 -j JOBS, --parallel=JOBS
173 How many parallel threads to use for installing
174 -v, --verbose Whether to print out more information
175 -t WORKSPACE, --target-workspace=WORKSPACE
176 which workspace to use
177 Examples:
179 $ wstool update -t ~/jade
181 $ wstool update robot_model geometry
182 info
184 Overview of some entries
185 The Status (S) column shows
187 x for missing L for uncommited (local) changes V for differ‐
188 ence in version and/or remote URI C for difference in local and
189 remote versions
190 The 'Version-Spec' column shows what tag, branch or revision was given
192 in the .rosinstall file. The 'UID' column shows the unique ID of the
193 current (and specified) version. The 'URI' column shows the configured
194 URL of the repo.
195 If status is V, the difference between what was specified and what is
197 real is shown in the respective column. For SVN entries, the url is
198 split up according to standard layout (trunk/tags/branches). The
199 ROS_PACKAGE_PATH follows the order of the table, earlier entries over‐
200 lay later entries.
201 When given one localname, just show the data of one element in list
203 form. This also has the generic properties element which is usually
204 empty.
205 The --only option accepts keywords: ['path', 'localname', 'version',
207 'revision', 'cur_revision', 'uri', 'cur_uri', 'scmtype']
208 Usage: wstool info [localname]* [OPTIONS]
210 Options:
213 -h, --help show this help message and exit
214 --root Show workspace root path
215 --data-only Does not provide explanations
216 --only=ONLY Shows comma-separated lists of only given comma-
217 separated attribute(s).
218 --yaml Shows only version of single entry. Intended for
219 scripting.
220 --fetch When used, retrieves version information from remote
221 (takes longer).
222 -u, --untracked Also show untracked files as modifications
223 -t WORKSPACE, --target-workspace=WORKSPACE
224 which workspace to use
225 -m, --managed-only only show managed elements
226 Examples:
228 $ wstool info -t ~/ros/jade
230 $ wstool info robot_model
231 $ wstool info --yaml
232 $ wstool info --only=path,cur_uri,cur_revision robot_model geometry
233 status
235 print the change status of files in some SCM controlled entries. The
236 status columns meanings are as the respective SCM defines them.
237 Usage: wstool status [localname]*
239 Options:
241 -h, --help show this help message and exit
242 -u, --untracked Also shows untracked files
243 -t WORKSPACE, --target-workspace=WORKSPACE
244 which workspace to use
245 diff
247 print a diff over some SCM controlled entries
248 Usage: wstool diff [localname]*
250 Options:
252 -h, --help show this help message and exit
253 -t WORKSPACE, --target-workspace=WORKSPACE
254 which workspace to use
255
257 On Ubuntu the recommended way to install rosinstall is to use apt.
258 sudo apt-get install python-wstool
260
262 On other platforms rosinstall is available on pypi and can be installed
263 via pip
264 pip install -U wstool
266 or easy_install:
268 easy_install -U wstool vcstools
270
272 Format
273 The rosinstall file format is a yaml document. It is a list of top
274 level dictionaries. Each top level dictionary is expected to have one
275 of the vcs type keys and no other keys.
276 Inside every top level dictionary there is one required key, local-name
278 this represents the path where to install files. It will support both
279 workspace relative paths as well as absolute paths.
280 Each of the vcs type keys requires a uri key, and optionally takes a
282 version key.
283 Top Level Keys
285 The valid keys are svn, hg, git, bzr.
286 Each key represents a form of version control system to use. These are
288 supported from the vcstools module.
289 Example rosinstall syntax:
291 Below is an example rosinstall syntax with examples of most of the pos‐
292 sible permutations:
293 - svn: {local-name: some/local/path2, uri: /some/local/uri}
295 - hg: {local-name: some/local/path3, uri: http://some/uri, version: 123}
296 - git: {local-name: /some/local/aboslute/path, uri: http://some/uri, version: 123}
297 - bzr: {local-name: some/local/path4, uri: http://some/uri, version: 123}
298 Things to note are:
300 • version is optional though recommended.
302 • Absolute or relative paths are valid for local-name
304 • uri can be a local file path to a repository.
306
308 Changelog
309 Changelog
310 0.1.18
311 • fix warnings by replacing yaml.load() with safe_load()
312 • Re-add snapshot command called 'export' (#117, #120)
314 • fix '-t' option not working for wstool remove
316 • upgrade vcstools library version to 0.1.41, with new fixes:
318 • fix git submodule errors
320 • fix export_upstream for git submodules
322 • fix python3 incompatibility
324 • fix git fast-forward failures
326 • fix get_affected_files
328 0.1.17
330 • Reverted the snapshot command since it was breaking rosws until it
331 can be fixed.
332 0.1.16
334 • Fixed some issues with new requirements.txt usage during the release
335 process.
336 0.1.15
338 • Fixed an issue with the conditional dependency on ordereddict in the
339 setup.py file.
340 0.1.14
342 • Fixed an issue which caused a traceback with invalid command line op‐
343 tions.
344 • Added a feature to "snapshot" the current commit hashes in the
346 workspace as a rosinstall file.
347 • Fixed option handling and documentation of the --untracked option.
349 • Added --shallow option to wstool init for shallow checkouts with git.
351 • Contributors: @cbandera, @rsinnet, @amiller27, @jayvdb, @at-wat
353 0.1.13
355 • Fix to avoid errors due to installing man pages with OS X's 10.11's
356 new SIP settings.
357 • Added option to show a simplified version info table.
359 • Added the -m (timeout), -v (verbose), and -j (parallel jobs) options
361 to each command.
362 • Contributors: @NikolausDemmel, @wkentaro
364 0.1.12
366 • Fix command line arguments of wstool scrape.
367 0.1.11
369 • Changed the way .bak files are created when overwriting existing con‐
370 figurations.
371 • Added the Scrape command.
373 • Added default git branch and status to wstool fetch --info.
375 • Added versioned dependency on vcstools 0.1.38 to make use of new API
377 features.
378 0.1.10
380 • Fix regression which broke the -j option.
381 • Enable pretty printing of the .rosinstall file's YAML.
383 0.1.9
385 • Fix for zsh completion.
386 • Fixed version dependency on vcstools for debian.
388 0.1.8
390 • Fix for installation issue.
391 0.1.7
393 • Added installation of generated man pages.
394 • Added installation of shell completion for wstool.
396 • Improved output of wstool info with the new get_current_version_label
398 in vcstools.
399 • Added a foreach command.
401 • Added a --root option to wstool info.
403 • Enhanced the --update option for wstool set.
405 • Now uses multiple threads for network operations by default.
407 • Some other minor fixes and improvements and docs.
409 0.1.5
411 • Releasing to allow changes for new platform vivid.
412 • Fix svn diff for change in output with svn 1.7.9.
414 • info command shows information about unmanaged paths.
416 0.1.4
418 • Fix detection of path conflicts #24 (‐
419 https://github.com/vcstools/wstool/pull/24).
420 0.0.3
422 • not using ROS_WORKSPACE anymore
423 • fix to "wstool cmd --help"
425 0.0.2
427 • fix #2 creating "wstool2 file instaed of ".rosinstall"
428 0.0.1
430 • Initial creation based on functions inrosinstall
431 Bug reports and feature requests
433 • Submit a bug report
434 Developer Setup
436 The wstool source can be downloaded using Mercurial:
437 $ git clone https://github.com/vcstools/wstool.git
439 You will also need vcstools, which you can either install using pip or
441 download using:
442 $ git clone https://github.com/vcstools/vcstools.git
444 $ cd vcstools
445 $ python develop
446 wstool uses setuptools, which you will need to download and install in
448 order to run the packaging. We use setuptools instead of distutils in
449 order to be able use setup() keys like install_requires.
450 Configure your environment:
452 $ cd wstool $ python develop
453 Testing
455 Install test dependencies
456 $ pip install nose
458 $ pip install mock
459 wstool uses Python nose for testing, which is a fairly simple and
461 straightforward test framework. The wstool mainly use unittest to con‐
462 struct test fixtures, but with nose you can also just write a function
463 that starts with the name test and use normal assert statements.
464 wstool also uses mock to create mocks for testing.
466 You can run the tests, including coverage, as follows:
468 $ cd wstool
470 $ make test
471 Documentation
473 Sphinx is used to provide API documentation for wstool. The documents
474 are stored in the doc sub-directory.
475 You can build the docs as follows:
477 $ cd wstool/doc
479 $ make html
480 • genindex
482 • modindex
484 • search
486
488 Tully Foote, Thibault Kruse, Ken Conley, Brian Gerkey
489
491 2022, Willow Garage
4920.1.18 Jan 21, 2022 WSTOOL(1)