Skip to content

Latest commit

 

History

History
191 lines (143 loc) · 5.44 KB

README.md

File metadata and controls

191 lines (143 loc) · 5.44 KB
Raw

Tests GitHub tag

ansible-stow

An Ansible module that interacts with GNU Stow packages.

Table of Contents

Compatibility

This ansible module is tested against the following versions:

Program Compatible versions
ansible 2.10.7, 3.4.0, 4.10.0, 5.10.0, 6.7.0, 7.7.0, 8.7.0, 9.7.0
python 3.6.x, 3.7.x, 3.8.x, 3.9.x, 3.10.x, 3.11.x, 3.12.x
stow 2.3.1, 2.4.0

For python < 3 (legacy systems that still uses 2.x), use the v0.1.3 of this module.

Development

For linting and other code verifications, python >= 3.10 is required.

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.2.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

License