wstool (1) - Linux Manuals

wstool: wstool Documentation

NAME

wstool - wstool Documentation

Using wstool you can update several folders using a variety of SCMs (SVN, Mercurial, git, Bazaar) with just one command.

That way you can more effectively manage source code workspaces.

The wstool package provides a Python API for interacting with a source code workspace as well as a group of command line tools. Rosinstall leverages the vcstools package for source control and stores its state in .rosinstall files.

WSTOOL: A TOOL FOR MANAGING SOURCE CODE WORKSPACES

wstool allows manipulation of a set of version-controlled folders as specified in a workspace definition file.

Contents

•
wstool: A tool for managing source code workspaces
•
Usage
•
init
•
set
•
merge
•
update
•
info
•
status
•
diff

Usage

wstool is a command to manipulate multiple version controlled folders.

Official usage:
  wstool CMD [ARGS] [OPTIONS]

wstool will try to infer install path from context

Type 'wstool help' for usage.
Options:
  help            provide help for commands
  init            set up a directory as workspace
  set             add or changes one entry from your workspace config
  merge           merges your workspace with another config set
  remove (rm)     remove an entry from your workspace config, without deleting files
  update (up)     update or check out some of your config elements
  info            Overview of some entries
  status (st)     print the change status of files in some SCM controlled entries
  diff (di)       print a diff over some SCM controlled entries

init

set up a directory as workspace

wstool init does the following:

1.
Reads folder/file/web-uri SOURCE_PATH looking for a rosinstall yaml
2.
Creates new .rosinstall file at TARGET-PATH configured

SOURCE_PATH can e.g. be a folder like /opt/ros/electric If PATH is not given, uses current folder. 

Usage: wstool init [TARGET_PATH [SOURCE_PATH]]?

Options::

  -h, --help            show this help message and exit
  --continue-on-error   Continue despite checkout errors
  -j JOBS, --parallel=JOBS
                        How many parallel threads to use for installing

Examples: 

$ wstool init ~/jade /opt/ros/jade

set

add or changes one entry from your workspace config The command will infer whether you want to add or modify an entry. If you modify, it will only change the details you provide, keeping those you did not provide. if you only provide a uri, will use the basename of it as localname unless such an element already exists.

The command only changes the configuration, to checkout or update the element, run wstool update afterwards. 

Usage: wstool set [localname] [SCM-URI]?  [--(detached|svn|hg|git|bzr)] [--version=VERSION]]

Options:
  -h, --help            show this help message and exit
  --detached            make an entry unmanaged (default for new element)
  -v VERSION, --version-new=VERSION
                        point SCM to this version
  --git                 make an entry a git entry
  --svn                 make an entry a subversion entry
  --hg                  make an entry a mercurial entry
  --bzr                 make an entry a bazaar entry
  -y, --confirm         Do not ask for confirmation
  -u, --update          update repository after set
  -t WORKSPACE, --target-workspace=WORKSPACE
                        which workspace to use

Examples: 

$ wstool set robot_model --hg https://kforge.ros.org/robotmodel/robot_model
$ wstool set robot_model --version robot_model-1.7.1
$ wstool set robot_model --detached

merge

The command merges config with given other rosinstall element sets, from files or web uris.

The default workspace will be inferred from context, you can specify one using -t.

By default, when an element in an additional URI has the same local-name as an existing element, the existing element will be replaced. In order to ensure the ordering of elements is as provided in the URI, use the option --merge-kill-append. 

Usage: wstool merge [URI] [OPTIONS]

Options:
  -h, --help            show this help message and exit
  -a, --merge-kill-append
                        merge by deleting given entry and appending new one
  -k, --merge-keep      (default) merge by keeping existing entry and
                        discarding new one
  -r, --merge-replace   merge by replacing given entry with new one
                        maintaining ordering
  -y, --confirm-all     do not ask for confirmation unless strictly necessary
  -t WORKSPACE, --target-workspace=WORKSPACE
                        which workspace to use

Examples: 

$ wstool merge someother.rosinstall

You can use '-' to pipe in input, as an example: 

$ roslocate info robot_mode | wstool merge -

update

update or check out some of your config elements

This command calls the SCM provider to pull changes from remote to your local filesystem. In case the url has changed, the command will ask whether to delete or backup the folder. 

Usage: wstool update [localname]*

Options:
  -h, --help            show this help message and exit
  --delete-changed-uris
                        Delete the local copy of a directory before changing
                        uri.
  --abort-changed-uris  Abort if changed uri detected
  --continue-on-error   Continue despite checkout errors
  --backup-changed-uris=BACKUP_CHANGED
                        backup the local copy of a directory before changing
                        uri to this directory.
  -j JOBS, --parallel=JOBS
                        How many parallel threads to use for installing
  -v, --verbose         Whether to print out more information
  -t WORKSPACE, --target-workspace=WORKSPACE
                        which workspace to use

Examples: 

$ wstool update -t ~/jade
$ wstool update robot_model geometry

info

Overview of some entries

The Status (S) column shows
x for missing L for uncommited (local) changes V for difference in version and/or remote URI C for difference in local and remote versions

The 'Version-Spec' column shows what tag, branch or revision was given in the .rosinstall file. The 'UID' column shows the unique ID of the current (and specified) version. The 'URI' column shows the configured URL of the repo.

If status is V, the difference between what was specified and what is real is shown in the respective column. For SVN entries, the url is split up according to standard layout (trunk/tags/branches). The ROS_PACKAGE_PATH follows the order of the table, earlier entries overlay later entries.

When given one localname, just show the data of one element in list form. This also has the generic properties element which is usually empty.

The --only option accepts keywords: ['path', 'localname', 'version', 'revision', 'cur_revision', 'uri', 'cur_uri', 'scmtype'] 

Usage: wstool info [localname]* [OPTIONS]


Options:
  -h, --help            show this help message and exit
  --root                Show workspace root path
  --data-only           Does not provide explanations
  --only=ONLY           Shows comma-separated lists of only given comma-
                        separated attribute(s).
  --yaml                Shows only version of single entry. Intended for
                        scripting.
  --fetch               When used, retrieves version information from remote
                        (takes longer).
  -u, --untracked       Also show untracked files as modifications
  -t WORKSPACE, --target-workspace=WORKSPACE
                        which workspace to use
  -m, --managed-only    only show managed elements

Examples: 

$ wstool info -t ~/ros/jade
$ wstool info robot_model
$ wstool info --yaml
$ wstool info --only=path,cur_uri,cur_revision robot_model geometry

status

print the change status of files in some SCM controlled entries. The status columns meanings are as the respective SCM defines them. 

Usage: wstool status [localname]*

Options:
  -h, --help            show this help message and exit
  --untracked           Also shows untracked files
  -t WORKSPACE, --target-workspace=WORKSPACE
                        which workspace to use

diff

print a diff over some SCM controlled entries 

Usage: wstool diff [localname]*

Options:
  -h, --help            show this help message and exit
  --untracked           Also shows untracked files
  -t WORKSPACE, --target-workspace=WORKSPACE
                      which workspace to use

UBUNTU

On Ubuntu the recommended way to install rosinstall is to use apt. 

sudo apt-get install python-wstool

OTHER PLATFORMS

On other platforms rosinstall is available on pypi and can be installed via pip 

pip install -U wstool

or easy_install: 

easy_install -U wstool vcstools

ROSINSTALL FILE FORMAT

Format

The rosinstall file format is a yaml document. It is a list of top level dictionaries. Each top level dictionary is expected to have one of the vcs type keys and no other keys.

Inside every top level dictionary there is one required key, local-name this represents the path where to install files. It will support both workspace relative paths as well as absolute paths.

Each of the vcs type keys requires a uri key, and optionally takes a version key.

Top Level Keys

The valid keys are svn, hg, git, bzr.

Each key represents a form of version control system to use. These are supported from the vcstools module.

Example rosinstall syntax:

Below is an example rosinstall syntax with examples of most of the possible permutations: 

- svn: {local-name: some/local/path2, uri: /some/local/uri}
- hg: {local-name: some/local/path3, uri: http://some/uri, version: 123}
- git: {local-name: /some/local/aboslute/path, uri: http://some/uri, version: 123}
- bzr: {local-name: some/local/path4, uri: http://some/uri, version: 123}

Things to note are:

•
version is optional though recommended.
•
Absolute or relative paths are valid for local-name
•
uri can be a local file path to a repository.

DEVELOPER'S GUIDE

Changelog

0.1.12

•
Fix command line arguments of wstool scrape.

0.1.11

•
Changed the way .bak files are created when overwriting existing configurations.
•
Added the Scrape command.
•
Added default git branch and status to wstool fetch --info.
•
Added versioned dependency on vcstools 0.1.38 to make use of new API features.

0.1.10

•
Fix regression which broke the -j option.
•
Enable pretty printing of the .rosinstall file's YAML.

0.1.9

•
Fix for zsh completion.
•
Fixed version dependency on vcstools for debian.

0.1.8

•
Fix for installation issue.

0.1.7

•
Added installation of generated man pages.
•
Added installation of shell completion for wstool.
•
Improved output of wstool info with the new get_current_version_label in vcstools.
•
Added a foreach command.
•
Added a --root option to wstool info.
•
Enhanced the --update option for wstool set.
•
Now uses multiple threads for network operations by default.
•
Some other minor fixes and improvements and docs.

0.1.5

•
Releasing to allow changes for new platform vivid.
•
Fix svn diff for change in output with svn 1.7.9.
•
info command shows information about unmanaged paths.

0.1.4

•
Fix detection of path conflicts #24 (https://github.com/vcstools/wstool/pull/24).

0.0.3

•
not using ROS_WORKSPACE anymore
•
fix to "wstool cmd --help"

0.0.2

•
fix #2 creating "wstool2 file instaed of ".rosinstall"

0.0.1

•
Initial creation based on functions inrosinstall

Bug reports and feature requests

•
Submit a bug report

Developer Setup

The wstool source can be downloaded using Mercurial: 

$ git clone https://github.com/vcstools/wstool.git

You will also need vcstools, which you can either install using pip or download using: 

$ git clone https://github.com/vcstools/vcstools.git
$ cd vcstools
$ python develop

wstool uses setuptools, which you will need to download and install in order to run the packaging. We use setuptools instead of distutils in order to be able use setup() keys like install_requires.

Configure your environment: $ cd wstool $ python develop

Testing

Install test dependencies 

$ pip install nose
$ pip install mock

wstool uses Python nose for testing, which is a fairly simple and straightforward test framework. The wstool mainly use unittest to construct test fixtures, but with nose you can also just write a function that starts with the name test and use normal assert statements.

wstool also uses mock to create mocks for testing.

You can run the tests, including coverage, as follows: 

$ cd wstool
$ make test

Documentation

Sphinx is used to provide API documentation for wstool. The documents are stored in the doc sub-directory.

You can build the docs as follows: 

$ cd wstool/doc
$ make html
•
genindex
•
modindex
•
search

AUTHOR

Tully Foote, Thibault Kruse, Ken Conley, Brian Gerkey

COPYRIGHT

2011, Willow Garage

Pages related to wstool