https://github.com/asherikov/wshandler
Workspace utility (an alternative to wstool and vcstool)
https://github.com/asherikov/wshandler
catkin-workspace gitman ros-workspace vcs2l vcstool vcstools version-control wstool
Last synced: 5 months ago
JSON representation
Workspace utility (an alternative to wstool and vcstool)
- Host: GitHub
- URL: https://github.com/asherikov/wshandler
- Owner: asherikov
- License: apache-2.0
- Created: 2023-04-01T21:02:31.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2026-01-14T22:53:31.000Z (5 months ago)
- Last Synced: 2026-01-15T04:44:38.110Z (5 months ago)
- Topics: catkin-workspace, gitman, ros-workspace, vcs2l, vcstool, vcstools, version-control, wstool
- Language: Shell
- Homepage:
- Size: 113 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Introduction
============
`wshandler` is a workspace management utility similar to
(now
),
, and discontinued
. It is also conceptually similar to
, which comes from a different
(non-ROS) background.
A workspace is a directory containing a set of packages (typically git
repositories), see
or for more information.
Key features:
- `wshandler` mimics `wstool`'s 'stateful' workflow dropped in `vcstool`, i.e.,
it is easy to keep track of your local changes with respect to the upstream;
- `wshandler` is implemented in `bash` and relies on either `gojq`
or `yq`
for yaml processing;
- currently supported package sources: `git`;
- supported repository list formats: `repos` (default) and `rosinstall`
();
- custom repository list extensions:
- repository entries can be tagged for selective updates and status
information, e.g., `wshandler: {tags: [mytag]}`, see `./tests/tags/` for
examples;
- experimental sparse checkouts for entries that contain `wshandler:
{sparse: []}`, see `./tests/sparse` for examples.
Installation
============
`wshandler` is a bash script that can be placed anywhere, e.g., your
`${HOME}/bin`. It requires `bash`, `git` and either `gojq` (default) or `yq` to
work. `gojq` is available via binary packages on many modern systems, but has
certain limitations, e.g., it always sorts entries and does not preserve
comments. `yq` is not available via debian packages on Ubuntu, but can be
installed using `snap`. You can also find an AppImage bundle including
`wshandler` and `yq` at
(`git` and `bash` must be present on the host system).
Usage
=====
```
Usage (default values are shown in curly braces):
wshandler [] []
Notation:
{DEFAULT VALUE}
[OPTIONAL ARGUMENT]
(VALID OPTIONS IN A LIST)
Common arguments:
-y|--yaml_tool auto|gojq|yq {auto} # Use gojq or yq, auto prefers gojq
-Y|--yaml_binary {yq|gojq} # Override yaml tool (yq/gojq) path
-r|--root {./} # Parent of --list if it is a path
-c|--cache {} # Temporary files created here
-t|--type rosinstall|repos {repos} # Repository list format
-i|--indent 1|2|3... {4} # Default indentation in yaml repository list
-k|--keep-going {false} # Do not stop on errors
-l|--list {.rosinstall|.repos} # Default depends on --type,
#can be specified multiple times,
#mutually exclusive with -L
-L|--list-discover # Automatically discover lists in the root,
#recursively searches for *. files,
#mutually exclusive with -l,
#should be set after -r and -t.
-T|--tag {} # Filter repositories by tags
#can be specified multiple times
-q|--quiet # Suppress most of the output
Repository list commands:
Information:
[-u|--unsorted] status # show workspace status
is_source_space # check if a directory is a workspace
Initialization:
Common arguments:
[-p|--policy ({default}|shallow|nolfs)]
default # plain clone
shallow # shallow clone
nolfs # disable git LFS
clone git [] # clone workspace from a given repository
init [git ...] # initialize new workspace
Modification:
[-p|--policy {ask}|add|show|clean] scrape }> # process unmanaged repositories
ask # interactive mode
add # automaticaly add repositories
show # show unmanaged repositories
clean # remove unmanaged repositories
add git # add a repository
set_version_by_url # set repository version
set_version_by_name # set repository version
set_version_to_hash # set all repository versions to hash
pin # alias for set_version_to_hash
[-p|--policy ({active})] set_version_to_branch # change to the given branch
active # switch if the given branch is checked out
remove ... # remove repository from a list
remove_by_url [] # remove repository from a list
[-p|--policy {keep}|replace] merge # merge repository list
keep # keep original entries when there is a collision
replace # replace entries when there is a collision
Repository commands:
Selective commands ( may be a pattern):
Common arguments:
[-j|--jobs {1}] # use multiple jobs if possible
[-U|--unmanaged] # work on unmanaged repository directories: directory names must
#be given instead of package names, at least one is required,
#ignores --jobs
clean [ ...] # remove repository
prune [ ...] # git prune
push [ ...] # git push
unshallow [ ...] # git unshallow
feature_branches [ ...] # list git feature branches
[-p|--policy ({default}|shallow|nolfs|rebase)] update [ ...] # git pull
default # plain clone
shallow # shallow clone
nolfs # disable git LFS
rebase # do git pull with rebase
unmodified # only unmodified repos
nosubmodules # do not checkout submodules
Generic commands:
[-j|--jobs {1}] foreach git '' # execute command in each repository
Branching commands:
branch show [''] # show matching branches
branch new # create a new branch in modified repositories
branch allnew # create a new branch in all repositories
branch delete # delete branch from all repositories
branch merge # merge brach
commit '' # commit to modified repositories
wshandler installation commands:
install_test_deps # install test dependeincies
[-p|--policy {skip_yaml_tool}|snap|download|apt] install # install wshandler
skip_yaml_tool # do not install yaml tool
snap # install yaml tool (jq) using snap
download # download yaml tool (jq)
apt # install yaml tool (gojq) using apt
upgrade # upgrade wshandler
upgrade_appimage # upgrade wshandler AppImage
```
Examples
========
- `wshandler status`
```
>>> wshandler status: git sources ---
Flags: H - version hash mismatch, M - uncommited changes
name version actual version HM repository
---- ------- -------------- -- ----------
ariles pkg_ws_2 tags/ws-2.3.1-0-ge2748ad4 https://github.com/asherikov/ariles.git
intrometry main tags/0.1.0-0-ga033cd5-dirty M https://github.com/asherikov/intrometry.git
thread_supervisor master tags/1.1.0-0-gbbf8a09 https://github.com/asherikov/thread_supervisor.git
<<< wshandler status: git sources ---
```