1WSTOOL(1)                           wstool                           WSTOOL(1)
2
3
4

NAME

6       wstool - wstool Documentation
7
8       Using  wstool  you  can  update several folders using a variety of SCMs
9       (SVN, Mercurial, git, Bazaar) with just one command.
10
11       That way you can more effectively manage source code workspaces.
12
13       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

WSTOOL: A TOOL FOR MANAGING SOURCE CODE WORKSPACES

19       wstool  allows  manipulation  of a set of version-controlled folders as
20       specified in a workspace definition file.
21
22   Contents
23wstool: A tool for managing source code workspaces
24
25Usage
26
27init
28
29set
30
31merge
32
33update
34
35info
36
37status
38
39diff
40
41   Usage
42          wstool is a command to manipulate multiple version controlled folders.
43
44          Official usage:
45            wstool CMD [ARGS] [OPTIONS]
46
47          wstool will try to infer install path from context
48
49          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
61   init
62       set up a directory as workspace
63
64       wstool init does the following:
65
66          1. Reads folder/file/web-uri SOURCE_PATH looking  for  a  rosinstall
67             yaml
68
69          2. Creates new .rosinstall file at TARGET-PATH configured
70
71       SOURCE_PATH  can e.g. be a folder like /opt/ros/electric If PATH is not
72       given, uses current folder.
73
74          Usage: wstool init [TARGET_PATH [SOURCE_PATH]]?
75
76          Options::
77
78            -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
83       Examples:
84
85          $ wstool init ~/jade /opt/ros/jade
86
87   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
94       The command only changes the configuration, to checkout or  update  the
95       element, run wstool update afterwards.
96
97          Usage: wstool set [localname] [SCM-URI]?  [--(detached|svn|hg|git|bzr)] [--version=VERSION]]
98
99          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
113       Examples:
114
115          $ 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
119   merge
120       The  command  merges  config  with given other rosinstall element sets,
121       from files or web uris.
122
123       The default workspace will be inferred from context,  you  can  specify
124       one using -t.
125
126       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
131          Usage: wstool merge [URI] [OPTIONS]
132
133          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
145       Examples:
146
147          $ wstool merge someother.rosinstall
148
149       You can use '-' to pipe in input, as an example:
150
151          $ roslocate info robot_mode | wstool merge -
152
153   update
154       update or check out some of your config elements
155
156       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
160          Usage: wstool update [localname]*
161
162          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
178       Examples:
179
180          $ wstool update -t ~/jade
181          $ wstool update robot_model geometry
182
183   info
184       Overview of some entries
185
186       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
191       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
196       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
202       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
206       The  --only  option  accepts keywords: ['path', 'localname', 'version',
207       'revision', 'cur_revision', 'uri', 'cur_uri', 'scmtype']
208
209          Usage: wstool info [localname]* [OPTIONS]
210
211
212          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
227       Examples:
228
229          $ 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
234   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
238          Usage: wstool status [localname]*
239
240          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
246   diff
247       print a diff over some SCM controlled entries
248
249          Usage: wstool diff [localname]*
250
251          Options:
252            -h, --help            show this help message and exit
253            -t WORKSPACE, --target-workspace=WORKSPACE
254                                which workspace to use
255

UBUNTU

257       On Ubuntu the recommended way to install rosinstall is to use apt.
258
259          sudo apt-get install python-wstool
260

OTHER PLATFORMS

262       On other platforms rosinstall is available on pypi and can be installed
263       via pip
264
265          pip install -U wstool
266
267       or easy_install:
268
269          easy_install -U wstool vcstools
270

ROSINSTALL FILE FORMAT

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
277       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
281       Each of the vcs type keys requires a uri key, and  optionally  takes  a
282       version key.
283
284   Top Level Keys
285       The valid keys are svn, hg, git, bzr.
286
287       Each key represents a form of version control system to use.  These are
288       supported from the vcstools module.
289
290   Example rosinstall syntax:
291       Below is an example rosinstall syntax with examples of most of the pos‐
292       sible permutations:
293
294          - 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
299       Things to note are:
300
301version is optional though recommended.
302
303          • Absolute or relative paths are valid for local-name
304
305uri can be a local file path to a repository.
306

DEVELOPER'S GUIDE

308   Changelog
309   Changelog
310   0.1.18
311       • fix warnings by replacing yaml.load() with safe_load()
312
313       • Re-add snapshot command called 'export' (#117, #120)
314
315       • fix '-t' option not working for wstool remove
316
317       • upgrade vcstools library version to 0.1.41, with new fixes:
318
319         • fix git submodule errors
320
321         • fix export_upstream for git submodules
322
323         • fix python3 incompatibility
324
325         • fix git fast-forward failures
326
327         • fix get_affected_files
328
329   0.1.17
330       • Reverted  the  snapshot  command since it was breaking rosws until it
331         can be fixed.
332
333   0.1.16
334       • Fixed some issues with new requirements.txt usage during the  release
335         process.
336
337   0.1.15
338       • Fixed  an issue with the conditional dependency on ordereddict in the
339         setup.py file.
340
341   0.1.14
342       • Fixed an issue which caused a traceback with invalid command line op‐
343         tions.
344
345       • Added  a  feature  to  "snapshot"  the  current  commit hashes in the
346         workspace as a rosinstall file.
347
348       • Fixed option handling and documentation of the --untracked option.
349
350       • Added --shallow option to wstool init for shallow checkouts with git.
351
352       • Contributors: @cbandera, @rsinnet, @amiller27, @jayvdb, @at-wat
353
354   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
358       • Added option to show a simplified version info table.
359
360       • Added  the -m (timeout), -v (verbose), and -j (parallel jobs) options
361         to each command.
362
363       • Contributors: @NikolausDemmel, @wkentaro
364
365   0.1.12
366       • Fix command line arguments of wstool scrape.
367
368   0.1.11
369       • Changed the way .bak files are created when overwriting existing con‐
370         figurations.
371
372       • Added the Scrape command.
373
374       • Added default git branch and status to wstool fetch --info.
375
376       • Added  versioned dependency on vcstools 0.1.38 to make use of new API
377         features.
378
379   0.1.10
380       • Fix regression which broke the -j option.
381
382       • Enable pretty printing of the .rosinstall file's YAML.
383
384   0.1.9
385       • Fix for zsh completion.
386
387       • Fixed version dependency on vcstools for debian.
388
389   0.1.8
390       • Fix for installation issue.
391
392   0.1.7
393       • Added installation of generated man pages.
394
395       • Added installation of shell completion for wstool.
396
397       • Improved output of wstool info with the new get_current_version_label
398         in vcstools.
399
400       • Added a foreach command.
401
402       • Added a --root option to wstool info.
403
404       • Enhanced the --update option for wstool set.
405
406       • Now uses multiple threads for network operations by default.
407
408       • Some other minor fixes and improvements and docs.
409
410   0.1.5
411       • Releasing to allow changes for new platform vivid.
412
413       • Fix svn diff for change in output with svn 1.7.9.
414
415       • info command shows information about unmanaged paths.
416
417   0.1.4
418       • Fix       detection      of      path      conflicts      #24      (‐
419         https://github.com/vcstools/wstool/pull/24).
420
421   0.0.3
422       • not using ROS_WORKSPACE anymore
423
424       • fix to "wstool cmd --help"
425
426   0.0.2
427       • fix #2 creating "wstool2 file instaed of ".rosinstall"
428
429   0.0.1
430       • Initial creation based on functions inrosinstall
431
432   Bug reports and feature requests
433Submit a bug report
434
435   Developer Setup
436       The wstool source can be downloaded using Mercurial:
437
438          $ git clone https://github.com/vcstools/wstool.git
439
440       You will also need vcstools, which you can either install using pip  or
441       download using:
442
443          $ git clone https://github.com/vcstools/vcstools.git
444          $ cd vcstools
445          $ python develop
446
447       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
451       Configure your environment:
452          $ cd wstool $ python develop
453
454   Testing
455       Install test dependencies
456
457          $ pip install nose
458          $ pip install mock
459
460       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
465       wstool also uses mock to create mocks for testing.
466
467       You can run the tests, including coverage, as follows:
468
469          $ cd wstool
470          $ make test
471
472   Documentation
473       Sphinx is used to provide API documentation for wstool.  The  documents
474       are stored in the doc sub-directory.
475
476       You can build the docs as follows:
477
478          $ cd wstool/doc
479          $ make html
480
481       • genindex
482
483       • modindex
484
485       • search
486

AUTHOR

488       Tully Foote, Thibault Kruse, Ken Conley, Brian Gerkey
489
491       2022, Willow Garage
492
493
494
495
4960.1.18                           Jan 21, 2022                        WSTOOL(1)
Impressum