178 lines
5.3 KiB
Markdown
178 lines
5.3 KiB
Markdown
# AutoYADM
|
|
|
|
<!--toc:start-->
|
|
|
|
- [AutoYADM](#autoyadm)
|
|
- [Features](#features)
|
|
- [Installation](#installation)
|
|
- [Usage](#usage)
|
|
- [Tracking](#tracking)
|
|
- [Ignoring Certain Files](#ignoring-certain-files)
|
|
- [Committing & Pushing](#committing-pushing)
|
|
- [Calling AutoYADM Automatically](#calling-autoyadm-automatically)
|
|
- [Contributing](#contributing)
|
|
|
|
<!--toc:end-->
|
|
|
|
> This is part of Daniel's [utility collection](https://sr.ht/~ficd/utils/).
|
|
|
|
AutoYADM is a small shell utility to automate the process of managing dotfiles
|
|
with [YADM](https://github.com/yadm-dev/yadm) by allowing the user to define a
|
|
list of files & directories to be automatically added, committed and pushed
|
|
whenever the script is run. **Most notably, AutoYADM accounts for newly created
|
|
files previously untracked by YADM.**
|
|
|
|
The benefits of this approach:
|
|
|
|
1. Robust version control thanks to YADM and Git.
|
|
2. You won't forget to commit new files in important folders.
|
|
3. Maintain control over paths to auto-commit, and paths to only manually
|
|
commit.
|
|
|
|
I have personally been using AutoYADM to sync my dotfiles between devices
|
|
without any problems since October 2024.
|
|
|
|
## Features
|
|
|
|
- Configure a list of files & directories to be automatically tracked by YADM.
|
|
- Tracked directories will also track any new files inside them!
|
|
- Automatically add, commit, and push tracked paths.
|
|
- `.ignore`/`.gitignore` support with `fd`.
|
|
|
|
## Installation
|
|
|
|
Simply clone the repository:
|
|
|
|
```Bash
|
|
git clone https://git.sr.ht/~ficd/autoyadm
|
|
```
|
|
|
|
You may consider adding aliases to your shell configuration:
|
|
|
|
```Bash
|
|
alias autoyadm="/path/to/autoyadm/autoyadm.sh"
|
|
alias yadmadd="/path/to/autoyadm/yadmadd.sh"
|
|
# To enable automatic pushing:
|
|
alias autoyadm="AUTOYADMPUSH=1 /path/to/autoyadm/autoyadm.sh"
|
|
```
|
|
|
|
**Dependencies**:
|
|
|
|
- [YADM](https://github.com/yadm-dev/yadm)
|
|
- `git`
|
|
- `fd` (optional, but recommended)
|
|
- fallback to `find` otherwise
|
|
- `openssh` (required for pushing)
|
|
|
|
## Usage
|
|
|
|
> Note: The following assumes you have created shell aliases to the two scripts.
|
|
> You may, of course, simply call them directly.
|
|
|
|
### Tracking
|
|
|
|
AutoYADM maintains a list of files and directories for automatic tracking.
|
|
_**All** children of tracked directories will be tracked, including newly
|
|
created, previously untracked files._ For example, if you add your Neovim
|
|
configuration at `~/.config/nvim` to tracking, then any new files you create
|
|
inside that folder will automatically be added and committed by AutoYADM.
|
|
|
|
The tracking file is stored in `~/.config/yadm/tracked`. `$XDG_CONFIG_HOME` is
|
|
respected. The file will be automatically created if it doesn't already exist.
|
|
You can even add it to tracking: `yadmadd ~/.config/yadm/tracked`
|
|
|
|
> **Important**: Symlinks are _**not**_ added; this is to avoid conflicts with
|
|
> `yadm alt`
|
|
|
|
The tracking file contains the paths to tracked files & directories **relative
|
|
to $HOME**. For example:
|
|
|
|
```
|
|
.bashrc
|
|
.config/nvim
|
|
```
|
|
|
|
To add paths to be tracked, you may use `yadmadd.sh`. Any valid absolute or
|
|
relative path should work.
|
|
|
|
```Bash
|
|
$ yadmadd ~/.bashrc
|
|
$ yadmadd /home/username/.bashrc
|
|
# Relative paths work too.
|
|
$ yadmadd ../../.bashrc
|
|
# You may supply any number of paths as arguments.
|
|
$ yadmadd .bashrc .zshrc .config/nvim
|
|
```
|
|
|
|
To remove a target from tracking, simply delete it from the `tracked` file.
|
|
|
|
### Ignoring Certain Files
|
|
|
|
It's possible to ignore certain patterns inside a folder you're otherwise
|
|
tracking with `yadmadd`. For example, suppose you've added `.config/foo`, but
|
|
you want to specifically ignore `.config/foo/bar.log`. You can use a
|
|
`.ignore`/`.gitignore` file for this:
|
|
|
|
```sh
|
|
echo "bar.log" > ~/.config/foo/.ignore
|
|
```
|
|
|
|
The `.ignore`/`.gitignore` file must be in the root of the directory you've
|
|
added with `yadmadd`. You also need `fd` available on your `$PATH` for ignoring
|
|
to work.
|
|
|
|
### Committing & Pushing
|
|
|
|
To automatically add and commit your tracking targets, use `autoyadm.sh`:
|
|
|
|
```Bash
|
|
$ autoyadm
|
|
```
|
|
|
|
By default, automatic pushing is disabled. You can enable it with an environment
|
|
variable:
|
|
|
|
```Bash
|
|
$ export AUTOYADMPUSH=1
|
|
$ autoyadm
|
|
# Or you can combine these into one line:
|
|
$ AUTOYADMPUSH=1 autoyadm
|
|
```
|
|
|
|
> Note: For auto push to work, ssh-agent must be enabled, and the environment
|
|
> file needs to exist inside `~/.ssh`. Furthermore, you must have SSH setup with
|
|
> your git host.
|
|
|
|
### Calling AutoYADM Automatically
|
|
|
|
By default, AutoYADM only runs when the user calls it explicitly. If you want to
|
|
automate this process, you are responsible for setting it up yourself. You may
|
|
consider configuring a cron job for this. The following example will run
|
|
AutoYADM every 15 minutes, with automatic push enabled, appending its output to
|
|
a log file:
|
|
|
|
```Bash
|
|
*/15 * * * * AUTOYADMPUSH=1 /path/to/autoyadm/audoyadm.sh >> /path/to/log/file.log
|
|
```
|
|
|
|
If you are on Arch Linux, you can follow these instructions to set up the cron
|
|
job:
|
|
|
|
```Bash
|
|
# Install a cron daemon if you
|
|
# don't already have one.
|
|
$ sudo pacman -S cronie
|
|
# This command will open your $EDITOR,
|
|
# you may paste the above cron job configuration here
|
|
# and save the file to apply your changes.
|
|
$ crontab -e
|
|
# Don't forget to enable cronie.service:
|
|
$ systemctl enable cronie
|
|
$ systemctl start cronie
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Please submit patches, questions, and discussion points to the
|
|
[~ficd/utils mailing list](https://lists.sr.ht/~ficd/utils), and consider
|
|
visiting the [public ticket tracker](https://todo.sr.ht/~ficd/utils).
|