dotsync 0.1.25 → 0.1.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 793ae0a7e00707a97255d631304eddae60e6ce6224d8c4d85c9550f54cbd59bd
-  data.tar.gz: 34fdbefc7f9b27a2f7fedd8dcbac9748ae59c99fb7cb15a970ebc67605e5ebe1
+  metadata.gz: 6d2cef06dff635c8202f87424d1532d0db5cfdf7e26e1c0c98daee44acdd12e4
+  data.tar.gz: 38484cab4e99854a8b54259e222ace225834000c9d9a6df8005dff8b1baa228c
 SHA512:
-  metadata.gz: 50471dd7fca75246adb01dd946b17dc217b590cc0df359253f608f4868ae190c08aeb5ce5c9302dafa2533f368c69f35b1f9b3f70143ed36066745729904030b
-  data.tar.gz: 2061b3db4dfb07aaec4750efba675091797ce8ebcb9979ce37ffca5e1b838f20d2ebec181925c45d5a0a6c52d4681d05f989953f4022540c0a6705dc8fc6dd76
+  metadata.gz: 22d5fe759b17a723377363c22f05f77cedf57fd6ac41b4c8d379c2f2b2bf4fb42022a0c92707083356a096385fe51b1175c9865fb1f78fde58ba41b94be9fa17
+  data.tar.gz: 3fb40ad4ac4835cf0c3a45e8bb3d872197dc60bb79d04b8a6ff09d5626d6b92f63865b035d5eb7cc923f12319b4651e08ffe36e808296d002f88712e5bc54730

data/.github/workflows/{gem-push.yml → ci.yml}

@@ -1,4 +1,4 @@
-name: Ruby Gem
+name: CI
 
 on:
   push:

data/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Get version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Extract changelog for version
+        id: changelog
+        run: |
+          # Extract the section for this version from CHANGELOG.md
+          # Matches from "## [X.Y.Z]" until the next "## [" or end of file
+          VERSION="${{ steps.version.outputs.version }}"
+          CHANGELOG=$(awk -v ver="$VERSION" '
+            /^## \[/ {
+              if (found) exit
+              if ($0 ~ "\\[" ver "\\]") found=1
+            }
+            found { print }
+          ' CHANGELOG.md | tail -n +2)
+
+          # Use heredoc for multiline output
+          echo "content<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGELOG" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: v${{ steps.version.outputs.version }}
+          body: ${{ steps.changelog.outputs.content }}
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.gitignore

@@ -9,3 +9,5 @@
 
 # rspec failure tracking
 .rspec_status
+
+.claude/

data/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: local
+    hooks:
+      - id: rubocop
+        name: rubocop
+        entry: bundle exec rubocop --autocorrect --force-exclusion
+        language: system
+        types: [ruby]
+        pass_filenames: true

data/CHANGELOG.md

@@ -1,4 +1,36 @@
-# 0.1.25
+## [0.1.26] - 2025-01-11
+
+**Breaking Changes:**
+- The explicit sync mapping syntax has changed from `[[sync]]` to `[[sync.mappings]]`
+  - Old: `[[sync]]` with `local`/`remote` keys
+  - New: `[[sync.mappings]]` with `local`/`remote` keys
+  - This allows combining explicit mappings with XDG shorthands in the same config
+  - See README for migration examples
+
+**New Features:**
+- Add bidirectional `[[sync.mappings]]` DSL for two-way synchronization
+  - Simplified syntax replaces separate push/pull mappings
+  - Automatic expansion to bidirectional mappings (local ↔ remote)
+  - Supports all existing options: `force`, `only`, `ignore`
+- Add XDG shorthand DSL for sync mappings
+  - `[[sync.home]]` - syncs $HOME ↔ $HOME_MIRROR
+  - `[[sync.xdg_config]]` - syncs $XDG_CONFIG_HOME ↔ $XDG_CONFIG_HOME_MIRROR
+  - `[[sync.xdg_data]]` - syncs $XDG_DATA_HOME ↔ $XDG_DATA_HOME_MIRROR
+  - `[[sync.xdg_cache]]` - syncs $XDG_CACHE_HOME ↔ $XDG_CACHE_HOME_MIRROR
+  - `[[sync.xdg_bin]]` - syncs $XDG_BIN_HOME ↔ $XDG_BIN_HOME_MIRROR (new)
+  - Use `path` for specific subdirectories or `only` for multiple paths
+- Fix custom config path (`-c` flag) not being applied to Runner
+
+**Documentation:**
+- Document bidirectional sync mappings with examples
+- Document XDG shorthand DSL with usage examples
+- Update README with new configuration options and supported shorthands table
+
+**Infrastructure:**
+- Rename GitHub workflow to ci.yml
+- Add sync_mappings concern to push and pull loaders
+
+## [0.1.25]
 
 **Features:**
 - Add support for file-specific paths in 'only' configuration option

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dotsync (0.1.25)
+    dotsync (0.1.27)
       fileutils (~> 1.7.3)
       find (~> 0.2.0)
       listen (~> 3.9.0)

data/README.md

@@ -13,7 +13,8 @@
 Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles across machines. Whether you're setting up a new development environment or keeping configurations in sync, Dotsync makes it effortless.
 
 **Key Features:**
-- **Bidirectional Sync**: Push local dotfiles to your repository or pull from repository to local machine
+- **Bidirectional Sync Mappings**: Define once, sync both ways — eliminates config duplication with `[[sync.mappings]]` syntax
+- **XDG Shorthand DSL**: Concise `[[sync.home]]`, `[[sync.xdg_config]]`, `[[sync.xdg_data]]`, `[[sync.xdg_bin]]` syntax for common directory patterns
 - **Preview Mode**: See what changes would be made before applying them (dry-run by default)
 - **Smart Filtering**: Use `force`, `only`, and `ignore` options to precisely control what gets synced
 - **Automatic Backups**: Pull operations create timestamped backups for easy recovery
@@ -29,6 +30,9 @@ Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles acro
 - [Usage](#usage)
   - [Executable Commands](#executable-commands)
   - [Configuration](#configuration)
+    - [Bidirectional Sync Mappings (Recommended)](#bidirectional-sync-mappings-recommended)
+    - [Alternative: Unidirectional Mappings](#alternative-unidirectional-mappings)
+    - [Mapping Options (force, only, ignore)](#force-only-and-ignore-options-in-mappings)
   - [Safety Features](#safety-features)
   - [Customizing Icons](#customizing-icons)
   - [Automatic Update Checks](#automatic-update-checks)
@@ -76,22 +80,29 @@ Get started with Dotsync in just a few steps:
    ```
    This creates `~/.config/dotsync.toml` with example mappings.
 
-3. **Edit the configuration** (`~/.config/dotsync.toml`) to define your dotfile mappings:
+3. **Edit the configuration** (`~/.config/dotsync.toml`) to define your dotfile mappings using bidirectional sync:
    ```toml
-   [[pull.mappings]]
-   src = "$HOME/dotfiles/config"
-   dest = "$HOME/.config"
+   # Sync your shell config
+   [[sync.home]]
+   path = ".zshenv"
+
+   # Sync XDG config directories
+   [[sync.xdg_config]]
+   only = ["nvim", "alacritty", "zsh", "git"]
+   force = true
    ```
 
 4. **Preview your changes** (dry-run mode):
    ```shell
-   dotsync pull
+   dotsync pull   # Preview pulling from repo to local
+   dotsync push   # Preview pushing from local to repo
    ```
    This shows what would be changed without modifying any files.
 
 5. **Apply changes** when you're ready:
    ```shell
-   dotsync pull --apply
+   dotsync pull --apply   # Apply repo → local
+   dotsync push --apply   # Apply local → repo
    ```
 
 ## Usage
@@ -127,7 +138,7 @@ Dotsync provides the following commands to manage your dotfiles:
   ```shell
   dotsync watch [OPTIONS]
   ```
-  
+
   The watch command supports the same output control options as push and pull (e.g., `--quiet`, `--no-legend`, `--no-mappings`).
 
 - **Setup** (alias: **init**): Generate a default configuration file at `~/.config/dotsync.toml` with example mappings for `pull`, `push`, and `watch`.
@@ -212,53 +223,162 @@ dotsync watch --quiet              # Watch with minimal output
 
 ### Configuration
 
-The configuration file uses a `mappings` structure to define the source and destination of your dotfiles. Here is an example:
+Dotsync uses TOML configuration files to define mappings between your local machine and your dotfiles repository. The recommended approach is **bidirectional sync mappings**, which eliminate duplication and keep your config clean.
+
+> [!TIP]
+> Set up mirror environment variables for cleaner configuration:
+> ```bash
+> # Add to your ~/.zshrc or ~/.bashrc
+> export DOTFILES_DIR="$HOME/Code/dotfiles"
+> export XDG_CONFIG_HOME_MIRROR="$DOTFILES_DIR/xdg_config_home"
+> export XDG_DATA_HOME_MIRROR="$DOTFILES_DIR/xdg_data_home"
+> export HOME_MIRROR="$DOTFILES_DIR/home"
+> ```
+
+#### Bidirectional Sync Mappings (Recommended)
+
+Use `[[sync]]` mappings to define paths that sync in both directions. This is the **preferred approach** as it eliminates duplication between push and pull configurations.
+
+##### XDG Shorthand Syntax
+
+The most concise way to define mappings for standard XDG directories:
 
 ```toml
-[[pull.mappings]]
-src = "$XDG_CONFIG_HOME_MIRROR"
-dest = "$XDG_CONFIG_HOME"
-ignore = ["nvim"]
+# Sync home directory files
+[[sync.home]]
+path = ".zshenv"
 
-[[pull.mappings]]
-src  = "$XDG_CONFIG_HOME_MIRROR/nvim"
-dest = "$XDG_CONFIG_HOME/nvim"
-# FEATURE: forces the deletion of destination folder
+# Sync multiple configs from XDG_CONFIG_HOME
+[[sync.xdg_config]]
+only = ["alacritty", "git", "zsh", "starship.toml"]
+force = true
+
+# Sync specific config with custom options
+[[sync.xdg_config]]
+path = "nvim"
 force = true
-# FEATURE: use relative paths to "dest" to ignore files and folders
 ignore = ["lazy-lock.json"]
 
-[[pull.mappings]]
-src = "$HOME_MIRROR/.zshenv"
-dest = "$HOME"
+# Sync XDG data directories
+[[sync.xdg_data]]
+path = "git"
+force = true
+```
 
+**Supported shorthands:**
 
-[[push.mappings]]
-src = "$HOME/.zshenv"
-dest = "$HOME_MIRROR/.zshenv"
+| Shorthand | Local | Remote |
+|-----------|-------|--------|
+| `sync.home` | `$HOME` | `$HOME_MIRROR` |
+| `sync.xdg_config` | `$XDG_CONFIG_HOME` | `$XDG_CONFIG_HOME_MIRROR` |
+| `sync.xdg_data` | `$XDG_DATA_HOME` | `$XDG_DATA_HOME_MIRROR` |
+| `sync.xdg_cache` | `$XDG_CACHE_HOME` | `$XDG_CACHE_HOME_MIRROR` |
+| `sync.xdg_bin` | `$XDG_BIN_HOME` | `$XDG_BIN_HOME_MIRROR` |
 
-[[push.mappings]]
-src = "$XDG_CONFIG_HOME/alacritty"
-dest = "$DOTFILES_DIR/config/alacritty"
-# FEATURE: transfer only relative paths of files and folders passed here
-only = ["alacritty.toml", "rose-pine.toml"]
+**Options:**
+- `path` (optional): Relative path within the directory. If omitted, syncs the entire directory.
+- `force`, `ignore`, `only`: All standard mapping options are supported.
 
+##### Explicit Sync Syntax
 
-[[watch.mappings]]
-src = "$HOME/.zshenv"
-dest = "$HOME_MIRROR/.zshenv"
+For custom paths that don't follow XDG conventions, use explicit `[[sync.mappings]]` entries:
+
+```toml
+[[sync.mappings]]
+local  = "$XDG_CONFIG_HOME/nvim"
+remote = "$XDG_CONFIG_HOME_MIRROR/nvim"
+force  = true
+ignore = ["lazy-lock.json"]
+
+[[sync.mappings]]
+local  = "$HOME/.zshenv"
+remote = "$HOME_MIRROR/.zshenv"
+
+# Sync config file to a different location in repo
+[[sync.mappings]]
+local  = "$XDG_CONFIG_HOME/dotsync.toml"
+remote = "$XDG_CONFIG_HOME_MIRROR/dotsync/dotsync.macbook.toml"
+```
+
+**How it works:**
+- `local` is your local machine path (e.g., `~/.config/nvim`)
+- `remote` is your dotfiles repository path (e.g., `~/dotfiles/config/nvim`)
+- For **push** operations: `local` → `remote`
+- For **pull** operations: `remote` → `local`
+- All standard options (`force`, `ignore`, `only`) are supported
+
+##### Complete Example
+
+Here's a real-world configuration using bidirectional sync:
+
+```toml
+## BIDIRECTIONAL SYNC CONFIGURATION
+
+# Home directory files
+[[sync.home]]
+path = ".zshenv"
+
+# Bulk sync multiple configs
+[[sync.xdg_config]]
+only = [
+  "alacritty",
+  "brewfile",
+  "git",
+  "lazygit",
+  "tmux",
+  "zellij",
+  "starship.toml"
+]
+force = true
+
+# Zsh with ignored files
+[[sync.xdg_config]]
+path = "zsh"
+ignore = [".zsh_sessions", ".zsh_history", ".zcompdump"]
+
+# Neovim with force sync
+[[sync.xdg_config]]
+path = "nvim"
+force = true
+ignore = ["lazy-lock.json"]
+
+# Git templates in data directory
+[[sync.xdg_data]]
+path = "git"
+force = true
+
+# This config file itself
+[[sync.mappings]]
+local  = "$XDG_CONFIG_HOME/dotsync.toml"
+remote = "$XDG_CONFIG_HOME_MIRROR/dotsync/dotsync.macbook.toml"
+```
+
+#### Alternative: Unidirectional Mappings
+
+For asymmetric sync scenarios where push and pull need different configurations, you can use separate `[[push.mappings]]` and `[[pull.mappings]]` sections:
 
+```toml
+# Pull from repo to local (repo → local)
+[[pull.mappings]]
+src  = "$XDG_CONFIG_HOME_MIRROR/nvim"
+dest = "$XDG_CONFIG_HOME/nvim"
+force = true
+ignore = ["lazy-lock.json"]
+
+# Push from local to repo (local → repo)
+[[push.mappings]]
+src  = "$XDG_CONFIG_HOME/alacritty"
+dest = "$XDG_CONFIG_HOME_MIRROR/alacritty"
+only = ["alacritty.toml", "themes"]
+
+# Watch for live syncing
 [[watch.mappings]]
-src = "$XDG_CONFIG_HOME/alacritty"
-dest = "$DOTFILES_DIR/config/alacritty"
+src = "$XDG_CONFIG_HOME/nvim"
+dest = "$XDG_CONFIG_HOME_MIRROR/nvim"
 ```
 
-> [!TIP]
-> I use mirror environment variables to cleaner configuration
->
->  ```bash
->  export XDG_CONFIG_HOME_MIRROR="$HOME/Code/dotfiles/xdg_config_home"
->  ```
+> [!NOTE]
+> You can mix `[[sync.mappings]]`, XDG shorthands (`[[sync.home]]`, `[[sync.xdg_config]]`, etc.), and `[[push.mappings]]`/`[[pull.mappings]]` in the same config file. Use bidirectional sync for symmetric mappings and unidirectional for special cases.
 
 #### `force`, `only`, and `ignore` Options in Mappings
 
@@ -270,9 +390,8 @@ A boolean (true/false) value. When set to `true`, it forces deletion of files in
 
 **Example:**
 ```toml
-[[pull.mappings]]
-src = "$XDG_CONFIG_HOME_MIRROR/nvim"
-dest = "$XDG_CONFIG_HOME/nvim"
+[[sync.xdg_config]]
+path = "nvim"
 force = true
 ignore = ["lazy-lock.json"]
 ```
@@ -293,41 +412,34 @@ An array of relative paths (files or directories) to selectively transfer from t
 
 **Example 1: Selecting specific directories**
 ```toml
-[[push.mappings]]
-src = "$XDG_CONFIG_HOME"
-dest = "$DOTFILES_DIR/config"
+[[sync.xdg_config]]
 only = ["nvim", "alacritty", "zsh"]
 ```
 This transfers only the `nvim/`, `alacritty/`, and `zsh/` directories.
 
 **Example 2: Selecting specific files**
 ```toml
-[[push.mappings]]
-src = "$XDG_CONFIG_HOME/alacritty"
-dest = "$DOTFILES_DIR/config/alacritty"
+[[sync.xdg_config]]
+path = "alacritty"
 only = ["alacritty.toml", "rose-pine.toml"]
 ```
 This transfers only two specific TOML files from the alacritty config directory.
 
 **Example 3: Selecting files inside nested directories**
 ```toml
-[[push.mappings]]
-src = "$HOME/.config"
-dest = "$DOTFILES_DIR/config"
+[[sync.xdg_config]]
 only = ["bundle/config", "ghc/ghci.conf", "cabal/config"]
 ```
 This transfers only specific configuration files from different subdirectories:
 - `bundle/config` file from the `bundle/` directory
-- `ghc/ghci.conf` file from the `ghc/` directory  
+- `ghc/ghci.conf` file from the `ghc/` directory
 - `cabal/config` file from the `cabal/` directory
 
 The parent directories (`bundle/`, `ghc/`, `cabal/`) are created automatically in the destination, but other files in those directories are not transferred.
 
 **Example 4: Deeply nested paths**
 ```toml
-[[push.mappings]]
-src = "$XDG_CONFIG_HOME"
-dest = "$DOTFILES_DIR/config"
+[[sync.xdg_config]]
 only = ["nvim/lua/plugins/init.lua", "nvim/lua/config/settings.lua"]
 ```
 This transfers only specific Lua files from deeply nested paths within the nvim configuration.
@@ -343,17 +455,15 @@ An array of relative paths or patterns to exclude during transfer. This allows y
 
 **Example:**
 ```toml
-[[pull.mappings]]
-src = "$XDG_CONFIG_HOME_MIRROR/nvim"
-dest = "$XDG_CONFIG_HOME/nvim"
+[[sync.xdg_config]]
+path = "nvim"
 ignore = ["lazy-lock.json", "plugin/packer_compiled.lua"]
 ```
 
 **Combining options:**
 ```toml
-[[push.mappings]]
-src = "$XDG_CONFIG_HOME/nvim"
-dest = "$DOTFILES_DIR/config/nvim"
+[[sync.xdg_config]]
+path = "nvim"
 only = ["lua", "init.lua"]
 ignore = ["lua/plugin/packer_compiled.lua"]
 force = true
@@ -426,7 +536,7 @@ By default, all `push` and `pull` commands run in preview mode:
 
 Dotsync provides clear, actionable error messages for common issues:
 
-- **Permission Errors**: 
+- **Permission Errors**:
   ```
   Permission denied: /path/to/file
   Try: chmod +w <path> or check file permissions
@@ -496,10 +606,8 @@ diff_created = "✨"    # New files created
 diff_updated = "📝"    # Files modified
 diff_removed = "🗑️ "    # Files deleted
 
-# Example mappings section
-[[pull.mappings]]
-src = "$XDG_CONFIG_HOME_MIRROR"
-dest = "$XDG_CONFIG_HOME"
+# Example sync mapping
+[[sync.xdg_config]]
 ignore = ["cache"]
 ```
 
@@ -550,10 +658,10 @@ The check runs after your command completes and uses a cached timestamp to avoid
   ```bash
   # Work dotfiles
   dotsync -c ~/work-dotfiles.toml push --apply
-  
+
   # Personal dotfiles
   dotsync -c ~/.config/personal.toml pull --apply
-  
+
   # Server configs
   dotsync --config ~/server.toml push --apply
   ```
@@ -562,7 +670,7 @@ The check runs after your command completes and uses a cached timestamp to avoid
   ```shell
   # In a script or CI/CD pipeline
   dotsync pull --apply --yes --quiet
-  
+
   # Shorthand
   dotsync push -ayq
   ```
@@ -604,14 +712,13 @@ The check runs after your command completes and uses a cached timestamp to avoid
 
 ## Common Use Cases
 
-Here are some practical examples of how to use Dotsync for popular configuration files:
+Here are practical examples using bidirectional sync for popular configuration files:
 
 ### Syncing Neovim Configuration
 
 ```toml
-[[pull.mappings]]
-src = "$HOME/dotfiles/config/nvim"
-dest = "$HOME/.config/nvim"
+[[sync.xdg_config]]
+path = "nvim"
 force = true
 ignore = ["lazy-lock.json", ".luarc.json"]
 ```
@@ -619,31 +726,49 @@ ignore = ["lazy-lock.json", ".luarc.json"]
 ### Syncing Terminal Emulator (Alacritty)
 
 ```toml
-[[push.mappings]]
-src = "$HOME/.config/alacritty"
-dest = "$HOME/dotfiles/config/alacritty"
+[[sync.xdg_config]]
+path = "alacritty"
 only = ["alacritty.toml", "themes"]
 ```
 
 ### Syncing Shell Configuration
 
 ```toml
-[[pull.mappings]]
-src = "$HOME/dotfiles/shell/.zshrc"
-dest = "$HOME"
+[[sync.home]]
+path = ".zshenv"
 
-[[pull.mappings]]
-src = "$HOME/dotfiles/shell/.zshenv"
-dest = "$HOME"
+[[sync.xdg_config]]
+path = "zsh"
+ignore = [".zsh_sessions", ".zsh_history", ".zcompdump"]
 ```
 
 ### Syncing Multiple Config Directories
 
 ```toml
-[[pull.mappings]]
-src = "$HOME/dotfiles/config"
-dest = "$HOME/.config"
-ignore = ["nvim", "cache", "*.log"]
+[[sync.xdg_config]]
+only = ["nvim", "alacritty", "git", "zsh", "tmux", "starship.toml"]
+force = true
+```
+
+### Per-Machine Configuration Files
+
+Use different config files for different machines:
+
+```toml
+# In dotsync.macbook.toml
+[[sync.mappings]]
+local  = "$XDG_CONFIG_HOME/dotsync.toml"
+remote = "$XDG_CONFIG_HOME_MIRROR/dotsync/dotsync.macbook.toml"
+
+# In dotsync.work.toml
+[[sync.mappings]]
+local  = "$XDG_CONFIG_HOME/dotsync.toml"
+remote = "$XDG_CONFIG_HOME_MIRROR/dotsync/dotsync.work.toml"
+```
+
+Then use `-c` flag to select the appropriate config:
+```shell
+dotsync -c ~/.config/dotsync/dotsync.macbook.toml push --apply
 ```
 
 ## Troubleshooting
@@ -652,7 +777,7 @@ ignore = ["nvim", "cache", "*.log"]
 
 **Problem**: Icons appear as boxes, question marks, or strange characters.
 
-**Solution**: 
+**Solution**:
 - Install a [Nerd Font](https://www.nerdfonts.com/) and configure your terminal to use it
 - Or customize icons in `~/.config/dotsync.toml` using UTF-8 emojis or regular characters:
   ```toml