spuxy / ansible-stow

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: absent latest present supress	absent: unstow / delete the package. Equivalent to stow --delete. latest: first unstow a package, then stow again. Equivalent to stow --restow. present: stow a package. Equivalent to stow --stow. supress: stow a package and overwrite the file if any conflict is found. THIS CAN LEAD TO DATA LOSS! Use wisely.

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 the supress state. This is an implementation decision.
• Stow cannot handle the tilde expansion (~). Use the $HOME environment variable instead or Ansible's template function lookup.

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