<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>rosws: A tool for managing source code workspaces — rosinstall 0.6 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/print.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/theme_extras.js"></script>
<link rel="top" title="rosinstall 0.6 documentation" href="index.html" />
<link rel="next" title="roslocate: locate source-control repositories" href="roslocate.html" />
<link rel="prev" title="rosinstall: source-based install tool" href="rosinstall_usage.html" />
</head>
<body>
<div class="header"><h1 class="heading"><a href="index.html">
<span>rosinstall 0.6 documentation</span></a></h1>
<h2 class="heading"><span>rosws: A tool for managing source code workspaces</span></h2>
</div>
<div class="topnav">
<p>
«  <a href="rosinstall_usage.html">rosinstall: source-based install tool</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="roslocate.html">roslocate: locate source-control repositories</a>  »
</p>
</div>
<div class="content">
<div class="section" id="rosws-a-tool-for-managing-source-code-workspaces">
<h1><a class="toc-backref" href="#id2">rosws: A tool for managing source code workspaces</a><a class="headerlink" href="#rosws-a-tool-for-managing-source-code-workspaces" title="Permalink to this headline">¶</a></h1>
<p>rosws can do anything that rosinstall can do, and more. Most commands
will just do a small subset of a single rosinstall invocation, so
users can more easily understand and control the tool actions.</p>
<p>The main difference to rosinstall is that rosws uses an SCM like
syntax of command keywords.</p>
<p>The motivation for rosws was that many users were overwhelmed with the
number of things rosinstall does with just one command, and ended up
not using it at all. rosws does much less and informs the user more
about what it will do, so that users should feel safer and also should
more easily understand what the tool is doing.</p>
<p>The single most important feature that is different to rosinstall is
the info command. The second most is the set command.</p>
<p>The general design philosophy for rosws wa that each command should
just perform a single task, not multiple tasks.</p>
<p>The command was introduced with <a class="reference internal" href="#rep110">[REP110]</a>.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#rosws-a-tool-for-managing-source-code-workspaces" id="id2">rosws: A tool for managing source code workspaces</a><ul>
<li><a class="reference internal" href="#wishlist" id="id3">Wishlist</a></li>
<li><a class="reference internal" href="#usage" id="id4">Usage</a><ul>
<li><a class="reference internal" href="#init" id="id5">init</a></li>
<li><a class="reference internal" href="#set" id="id6">set</a></li>
<li><a class="reference internal" href="#merge" id="id7">merge</a></li>
<li><a class="reference internal" href="#update" id="id8">update</a></li>
<li><a class="reference internal" href="#info" id="id9">info</a></li>
<li><a class="reference internal" href="#status" id="id10">status</a></li>
<li><a class="reference internal" href="#diff" id="id11">diff</a></li>
<li><a class="reference internal" href="#regenerate" id="id12">regenerate</a></li>
</ul>
</li>
<li><a class="reference internal" href="#see-also" id="id13">See also</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="wishlist">
<h2><a class="toc-backref" href="#id3">Wishlist</a><a class="headerlink" href="#wishlist" title="Permalink to this headline">¶</a></h2>
<p>Thanks to its scm like syntax the rosws tool has a lot of room to
grow. Possible changes that have been discussed are:</p>
<ul class="simple">
<li>declare fixed positions for entries</li>
<li>maintain environment parameters like PATH, PYTHONPATH, LD_LIBRARY_PATH in .rosinstall</li>
<li>ability to deactivate entries but still keep their data in the file</li>
<li>manage labeled configurations for individual entries (and whole workspace)</li>
<li>manage nested or included workspaces</li>
<li>maintain workspace meta-information (rosinstall version, workspace relationships)</li>
<li>use an improved yaml syntax that also allows for all of the above</li>
<li>rosws as shell command to switch workspaces (prototype in contrib/rosws.shell)</li>
<li>recognize SCM folders as such when adding them</li>
<li>provide tags and branches of distributed SCMs in tab-completion and info</li>
<li>show whether updates are available on remote</li>
<li>colorize outputs</li>
<li>a command to reorder elements</li>
<li>an option for <tt class="docutils literal"><span class="pre">set</span></tt> to change element position</li>
<li>split out ROS agnostic tool for multi-vcs shell-project management</li>
<li>ability to store personal tool preferences in a .rc file</li>
<li>rosgui plugin</li>
</ul>
<p>At the time of this writing the rosws command is very new, so
it was decided to only provide a small set of commands and see
how users accept those before adding functionality.</p>
</div>
<div class="section" id="usage">
<h2><a class="toc-backref" href="#id4">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><pre>rosws is a command to manipulate ROS workspaces. rosws replaces its predecessor rosinstall.
Official usage:
rosws CMD [ARGS] [OPTIONS]
rosws will try to infer install path from context
Type 'rosws 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
regenerate create ROS workspace specific setup files</pre>
</div>
<div class="section" id="init">
<h3><a class="toc-backref" href="#id5">init</a><a class="headerlink" href="#init" title="Permalink to this headline">¶</a></h3>
<p>set up a directory as workspace</p>
<p>rosws init does the following:</p>
<blockquote>
<div><ol class="arabic simple">
<li>Reads folder/file/web-uri SOURCE_PATH looking for a rosinstall yaml</li>
<li>Creates new .rosinstall file at TARGET-PATH configured</li>
<li>Generates ROS setup files</li>
</ol>
</div></blockquote>
<p>SOURCE_PATH can e.g. be a folder like /opt/ros/electric
If PATH is not given, uses current folder.</p>
<div class="highlight-python"><pre>Usage: rosws init [TARGET_PATH [SOURCE_PATH]]?
Options::
-h, --help show this help message and exit
-c, --catkin Declare this is a catkin build.
--cmake-prefix-path=CATKINPP
Where to set the CMAKE_PREFIX_PATH
--continue-on-error Continue despite checkout errors
-j JOBS, --parallel=JOBS
How many parallel threads to use for installing</pre>
</div>
<p>Examples:</p>
<div class="highlight-python"><pre>$ rosws init ~/fuerte /opt/ros/fuerte</pre>
</div>
</div>
<div class="section" id="set">
<h3><a class="toc-backref" href="#id6">set</a><a class="headerlink" href="#set" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>The command only changes the configuration, to checkout or update
the element, run rosws update afterwards.</p>
<div class="highlight-python"><pre>Usage: rosws 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
-t WORKSPACE, --target-workspace=WORKSPACE
which workspace to use</pre>
</div>
<p>Examples:</p>
<div class="highlight-python"><pre>$ rosws set robot_model --hg https://kforge.ros.org/robotmodel/robot_model
$ rosws set robot_model --version robot_model-1.7.1
$ rosws set robot_model --detached</pre>
</div>
</div>
<div class="section" id="merge">
<h3><a class="toc-backref" href="#id7">merge</a><a class="headerlink" href="#merge" title="Permalink to this headline">¶</a></h3>
<p>The command merges config with given other rosinstall element sets, from files
or web uris.</p>
<p>The default workspace will be inferred from context, you can specify one using
-t.</p>
<p>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 <tt class="docutils literal"><span class="pre">--merge-kill-append</span></tt>.</p>
<div class="highlight-python"><pre>Usage: rosws 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</pre>
</div>
<p>Examples:</p>
<div class="highlight-python"><pre>$ rosws merge someother.rosinstall</pre>
</div>
<p>You can use ‘-‘ to pipe in input, as an example:</p>
<div class="highlight-python"><pre>$ roslocate info robot_mode | rosws merge -</pre>
</div>
</div>
<div class="section" id="update">
<h3><a class="toc-backref" href="#id8">update</a><a class="headerlink" href="#update" title="Permalink to this headline">¶</a></h3>
<p>update or check out some of your config elements</p>
<p>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.</p>
<div class="highlight-python"><pre>Usage: rosws 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</pre>
</div>
<p>Examples:</p>
<div class="highlight-python"><pre>$ rosws update -t ~/fuerte
$ rosws update robot_model geometry</pre>
</div>
</div>
<div class="section" id="info">
<h3><a class="toc-backref" href="#id9">info</a><a class="headerlink" href="#info" title="Permalink to this headline">¶</a></h3>
<p>Overview of some entries</p>
<dl class="docutils">
<dt>The Status (S) column shows</dt>
<dd>x for missing
L for uncommited (local) changes
V for difference in version and/or remote URI</dd>
</dl>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>The <tt class="docutils literal"><span class="pre">--only</span></tt> option accepts keywords: [‘path’, ‘localname’, ‘version’,
‘revision’, ‘cur_revision’, ‘uri’, ‘cur_uri’, ‘scmtype’]</p>
<div class="highlight-python"><pre>Usage: rosws info [localname]* [OPTIONS]
Options:
-h, --help show this help message and exit
--data-only Does not provide explanations
--no-pkg-path Suppress ROS_PACKAGE_PATH.
--pkg-path-only Shows only ROS_PACKAGE_PATH separated by ':'.
Supercedes all other options.
--only=ONLY Shows comma-separated lists of only given comma-
separated attribute(s).
--yaml Shows only version of single entry. Intended for
scripting.
-t WORKSPACE, --target-workspace=WORKSPACE
which workspace to use</pre>
</div>
<p>Examples:</p>
<div class="highlight-python"><pre>$ rosws info -t ~/ros/fuerte
$ rosws info robot_model
$ rosws info --yaml
$ rosws info --only=path,cur_uri,cur_revision robot_model geometry</pre>
</div>
</div>
<div class="section" id="status">
<h3><a class="toc-backref" href="#id10">status</a><a class="headerlink" href="#status" title="Permalink to this headline">¶</a></h3>
<p>print the change status of files in some SCM controlled entries. The status
columns meanings are as the respective SCM defines them.</p>
<div class="highlight-python"><pre>Usage: rosws 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</pre>
</div>
</div>
<div class="section" id="diff">
<h3><a class="toc-backref" href="#id11">diff</a><a class="headerlink" href="#diff" title="Permalink to this headline">¶</a></h3>
<p>print a diff over some SCM controlled entries</p>
<div class="highlight-python"><pre>Usage: rosws 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</pre>
</div>
</div>
<div class="section" id="regenerate">
<h3><a class="toc-backref" href="#id12">regenerate</a><a class="headerlink" href="#regenerate" title="Permalink to this headline">¶</a></h3>
<p>remove an entry from your workspace config, without deleting files</p>
<p>this command without options generates files setup.sh, setup.bash and
setup.zsh. Note that doing this is unnecessary in general, as these
files do not change anymore, unless you change from one ROS distro to
another (which you should never do like this, create a separate new
workspace instead), or you deleted or modified any of those files
accidentally.</p>
<div class="highlight-python"><pre>Usage: rosws regenerate
Options:
-h, --help show this help message and exit
-c, --catkin Declare this is a catkin build.
--cmake-prefix-path=CATKINPP
Where to set the CMAKE_PREFIX_PATH</pre>
</div>
</div>
</div>
<div class="section" id="see-also">
<h2><a class="toc-backref" href="#id13">See also</a><a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<table class="docutils citation" frame="void" id="rep110" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[REP110]</a></td><td>SCM-like rosinstall command structure
(<a class="reference external" href="http://www.ros.org/reps/rep-0110.html">http://www.ros.org/reps/rep-0110.html</a>)</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="bottomnav">
<p>
«  <a href="rosinstall_usage.html">rosinstall: source-based install tool</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="roslocate.html">roslocate: locate source-control repositories</a>  »
</p>
</div>
<div class="footer">
© Copyright 2011, Willow Garage.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
