Metadata-Version: 2.5
Name: dot-tools
Version: 1.12.0
Summary: Dot files automation
Project-URL: github, https://github.com/cybergrind/dot-tools
Author-email: cybergrind <cybergrind+pypi@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: fan-tools>=3.7.0
Requires-Dist: pyyaml>=6
Requires-Dist: tomlkit>=0.13
Description-Content-Type: text/markdown

# dot-tools

A grab bag of small scripts I use to keep my dotfiles and projects in shape.
Nothing fancy — just the stuff I got tired of rewriting.

Install it however you prefer (`pip install dot-tools`, `uv tool install dot-tools`, etc.)
and you'll get the commands below on your `PATH`.

## What's in the box

### `traefik_run`
Spins up a local Traefik via docker-compose. Pass extra args after `--`.

```bash
traefik_run              # up -d
traefik_run -- ps -a
traefik_run -- down
```

### `handle_envrc`
Keeps `.envrc` files synced across machines through a shared folder
(set `ENVRC_HOME`, defaults to `~/.keys/envrc`).
`handle_envrc migrate` moves storage from the old location (`--old`, defaults to
`~/Yandex.Disk/home/envrc`) to `ENVRC_HOME`, re-points all symlinks under `--root`
(default: `~/devel`) and re-approves them with `direnv allow`.
If the local `.envrc` isn't a symlink yet, it moves it into the shared dir
and replaces it with a link. If a shared one exists but the link is missing, it restores it.

```bash
handle_envrc
```

### `add_dot_files`
Drops common project boilerplate into the current directory:
`.editorconfig`, `pyproject.toml`, `.pre-commit-config.yaml`, `.yamllint`, `.projectile`.
With `--install` it also runs `pre-commit install` (via `uv run` when available),
because the config alone does nothing until the hook exists.

```bash
add_dot_files
add_dot_files --install
```

Generated files carry a first-line stamp naming the template version they came from.
`--update` three-way merges newer template versions into files that already exist,
so project-specific edits survive. Template changes that collide with a project edit keep
the project version by default and are printed, so nothing disappears silently.
Files created before stamps existed get their base version detected by similarity.
For `pyproject.toml` structural rules run on top of the line merge: dev dependency
floors the template raised are raised, dev dependencies and keys new in the template are added.
The result is validated before writing (TOML parses, YAML parses, pre-commit hooks stay under
the right repo); a file whose merge fails validation, that carries unresolved conflict markers,
or that does not look generated from the template at all is left untouched and reported.

```bash
add_dot_files --update --dry-run        # show what would change
add_dot_files --update                  # apply, conflicts keep the project version
add_dot_files --update --conflicts markers   # leave diff3 markers to resolve by hand
```

Maintainers: `add_dot_files --dump-history` materialises every committed template version
under `dot_tools/templates/history` (a pre-commit hook in this repo keeps it current).

### `cpuniq`
Copy (or move) files into a directory without clobbering. If the name is taken
and the content differs, it appends a short uuid suffix.

```bash
cpuniq photo.jpg ~/pictures/
cpuniq -m mv *.log ~/archive/
```

### `release.py`
Bumps the version, tags, builds and uploads. Mostly for this repo's own release flow.

```bash
release.py master
release.py -v 1.2.3 master
```

## License

MIT.
