ansible-stow
ansible-stow copied to clipboard
an ansible module that interacts with gnu stow packages
ansible-stow
An Ansible module that interacts with GNU Stow packages.
Table of Contents
- Compatibility
- Dependencies
- Installation
-
Usage
- Options
- Examples
- Caveats
- Acknowledgements
- License
Compatibility
This ansible module is tested against ansible 2.10.7 | 3.4.0 | 4.10.0 | 5.4.0
and python >= 3.6, < 4.0
. Note that
for ansible >= 4.10.0
, python >= 3.8
is required. For development (linting and other code verification) python >= 3.7.2
is required.
For python < 3
(legacy systems that still uses 2.x
), use the v0.1.3
of this module.
Dependencies
To use ansible-stow
, the managed node should have stow
installed.
GNU Stow is widely available in all major distributions and can be
installed with apt-get
, pacman
, yum
etc.
Installation
Download the module and move it into your global Ansible library or into the library directory alongside your top-level playbook. E.g.:
$ wget https://raw.githubusercontent.com/caian-org/ansible-stow/v1.1.1/stow
$ (sudo) mv stow /usr/share/ansible
Usage
Options
Parameter | Required | Choices / Defaults | Comments |
---|---|---|---|
package |
yes | Name of the Stow package | |
target |
no | Default: user's home directory | Path of target directory to perform |
dir |
yes | Path of the Stow directory | |
state |
yes |
Choices:
|
|
Examples
# stow package "zsh" of directory "/media/user/dots" to the home directory
- stow:
state: present
package: zsh
dir: /media/user/dots
target: '$HOME'
# remove package "tmux"
- stow:
state: absent
package: tmux
dir: /media/user/dots
# in case of conflict, overwrite the file with a symlink
- stow:
state: supress
package: vim
dir: /media/user/dots
# loop through list of packages
- stow:
state: latest
package: '{{ item }}'
dir: /media/user/dots
with_items:
- zsh
- tmux
- i3
Caveats
- If the package target already exists on the node filesystem as a file or a
symbolic link, the
supress
state will delete/unlink the target and then stow the package. - If the package target already exists and is a directory,
ansible-stow
will fail -- even using thesupress
state. This is an implementation decision. - Stow cannot handle the tilde expansion (
~
). Use the$HOME
environment variable instead or Ansible's template functionlookup
.
Acknowledgements
Original implementation by Ric da Silva.
License
To the extent possible under law, Caian Ertl has waived all copyright
and related or neighboring rights to this work. In the spirit of freedom of
information, I encourage you to fork, modify, change, share, or do whatever
you like with this project! ^C ^V