jbrechtel
97e129a855
- Look for config at $XDG_CONFIG_HOME/converge/config.yaml by default - --config still overrides to an explicit path - Falls back to single-repo --repo mode if no config file found - New defaultConfigPath and configFileExists helpers in Converge module
85 lines
2.4 KiB
Markdown
85 lines
2.4 KiB
Markdown
# Converge
|
|
|
|
Auto-sync one or more git repositories by watching for file changes, automatically committing them, and pulling from a remote.
|
|
|
|
Converge notifies the user via libnotify / `notify-send` whenever a merge conflict occurs during automatic pulling.
|
|
|
|
## Usage
|
|
|
|
### Configuration
|
|
|
|
Converge looks for its config file at `$XDG_CONFIG_HOME/converge/config.yaml` (typically `~/.config/converge/config.yaml`). If found, it uses that file automatically.
|
|
|
|
```bash
|
|
# Run with the default XDG config file
|
|
./scripts/run
|
|
```
|
|
|
|
You can also specify a config file explicitly:
|
|
|
|
```bash
|
|
./scripts/run -- --config /path/to/converge.yaml
|
|
```
|
|
|
|
### Single repository (no config file)
|
|
|
|
If no config file exists, converge falls back to watching a single repository:
|
|
|
|
```bash
|
|
# Watch the current directory
|
|
./scripts/run
|
|
|
|
# Watch a specific repo with options
|
|
./scripts/run -- --repo /path/to/repo --branch master --debounce 10000
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `-c`, `--config FILE` | `$XDG_CONFIG_HOME/converge/config.yaml` | Path to YAML config file listing repositories |
|
|
| `-r`, `--repo PATH` | `.` (cwd) | Path to a single git repository (single-repo fallback mode) |
|
|
| `-d`, `--debounce MS` | `5000` | Debounce window in milliseconds (overrides config file) |
|
|
| `--remote NAME` | `origin` | Remote name (single-repo fallback mode) |
|
|
| `-b`, `--branch NAME` | `main` | Branch to pull (single-repo fallback mode) |
|
|
|
|
### Config file format
|
|
|
|
```yaml
|
|
# ~/.config/converge/config.yaml (XDG default)
|
|
repos:
|
|
- path: /absolute/or/relative/path
|
|
remote: origin # optional, defaults to "origin"
|
|
branch: main # optional, defaults to "main"
|
|
- path: /another/repo
|
|
|
|
debounce_ms: 5000 # optional, defaults to 5000
|
|
```
|
|
|
|
## Development
|
|
|
|
All development tools run inside Docker via the `hs` wrapper script.
|
|
|
|
```bash
|
|
# Build (format + compile)
|
|
./scripts/build
|
|
|
|
# Run tests
|
|
./scripts/test
|
|
|
|
# Run the tool
|
|
./scripts/run
|
|
|
|
# Install to ~/.local/bin
|
|
./scripts/install
|
|
```
|
|
|
|
## Design
|
|
|
|
- **Language**: Haskell (GHC 9.10.3 via lts-24.38)
|
|
- **File watching**: [fsnotify](https://hackage.haskell.org/package/fsnotify)
|
|
- **Concurrency**: one watcher thread per repository via `async`
|
|
- **Notifications**: shell out to `notify-send` (libnotify)
|
|
- **Configuration**: YAML config file at XDG config path for multi-repo, CLI flags for single-repo fallback
|
|
- **Daemonization**: TBD (likely systemd service)
|