dotsync 0.1.25 → 0.1.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 793ae0a7e00707a97255d631304eddae60e6ce6224d8c4d85c9550f54cbd59bd
-  data.tar.gz: 34fdbefc7f9b27a2f7fedd8dcbac9748ae59c99fb7cb15a970ebc67605e5ebe1
+  metadata.gz: 89c25a6529e3557dc1383f3facf677f0775053d7db53863b7cc61a5b44d13b11
+  data.tar.gz: 1cfadbe1c539923fb6bf9c27eafde24beeab527feeaadf2b88d997d762f972b4
 SHA512:
-  metadata.gz: 50471dd7fca75246adb01dd946b17dc217b590cc0df359253f608f4868ae190c08aeb5ce5c9302dafa2533f368c69f35b1f9b3f70143ed36066745729904030b
-  data.tar.gz: 2061b3db4dfb07aaec4750efba675091797ce8ebcb9979ce37ffca5e1b838f20d2ebec181925c45d5a0a6c52d4681d05f989953f4022540c0a6705dc8fc6dd76
+  metadata.gz: 2b7012240c48cd7b9d84cf8e20d54efa913fd08324720b08d270db0c39e46f87a1f63f124e6d562d06ab2bef7f0fd017bb686e666b40866fc89eceae831de1bf
+  data.tar.gz: 87f03124b8dc8cad8c3588d3391858414ac0a577416c7a227465702a081c8de9fa36648e5eb5c642ba9b6beae81c19043259c25b536a634cd3bfcd3b83a7cfc9

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.26)
       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

data/Rakefile

@@ -15,23 +15,137 @@ end
 task default: :spec
 
 namespace :release do
-  desc "Tag git with the current Dotsync::VERSION"
-  task :tag do
-    require_relative "./lib/dotsync/version"
-    version = Dotsync::VERSION
+  desc "Generate CHANGELOG entry for a new version"
+  # Usage: rake release:changelog[0.2.1]
+  task :changelog, [:version] do |_t, args|
+    version = args[:version]
+    unless version
+      require_relative "./lib/dotsync/version"
+      version = Dotsync::VERSION
+    end
+    version = version.sub(/^v/, "")
+    today = Date.today.strftime("%Y-%m-%d")
+
+    latest_tag = `git describe --tags --abbrev=0 2>/dev/null`.strip
+    commits = if latest_tag.empty?
+      `git log --oneline --no-decorate`.strip.split("\n")
+    else
+      `git log #{latest_tag}..HEAD --oneline --no-decorate`.strip.split("\n")
+    end
+
+    if commits.empty?
+      abort "No commits since #{latest_tag}. Nothing to release."
+    end
+
+    categories = { "Added" => [], "Changed" => [], "Fixed" => [], "Removed" => [], "Security" => [], "Dependencies" => [] }
+
+    commits.each do |commit|
+      message = commit.sub(/^[a-f0-9]+\s+/, "")
+      case message.downcase
+      when /^add|^feat|^implement|^create|^new|^support/i then categories["Added"] << message
+      when /^fix|^bugfix|^hotfix|^resolve|^correct/i then categories["Fixed"] << message
+      when /^remove|^delete|^drop/i then categories["Removed"] << message
+      when /^security|^vuln|^cve/i then categories["Security"] << message
+      when /^bump|^upgrade|^update.*dependency|^dep/i then categories["Dependencies"] << message
+      else categories["Changed"] << message
+      end
+    end
+
+    changelog_entry = "## [#{version}] - #{today}\n"
+    categories.each do |category, items|
+      next if items.empty?
+      changelog_entry += "\n### #{category}\n\n"
+      items.each { |item| changelog_entry += "- #{item}\n" }
+    end
+
+    changelog_path = "CHANGELOG.md"
+    abort "CHANGELOG.md not found." unless File.exist?(changelog_path)
+
+    changelog = File.read(changelog_path)
+    abort "Version #{version} already exists in CHANGELOG.md" if changelog.include?("[#{version}]")
+
+    match = changelog.match(/^## \[/m)
+    new_changelog = match ? changelog.sub(/^## \[/m, "#{changelog_entry}\n## [") : changelog.rstrip + "\n\n#{changelog_entry}"
+
+    repo_url = `git remote get-url origin`.strip.sub(/\.git$/, "").sub(/^git@github\.com:/, "https://github.com/")
+    previous_version = latest_tag.empty? ? "v0.0.0" : latest_tag
+    link_entry = "[#{version}]: #{repo_url}/compare/#{previous_version}...v#{version}"
+
+    new_changelog = if new_changelog.match?(/^\[[\d.]+\]:.*compare/m)
+      new_changelog.sub(/^(\[[\d.]+\]:.*compare)/m, "#{link_entry}\n\\1")
+    else
+      new_changelog.rstrip + "\n\n#{link_entry}\n"
+    end
+
+    File.write(changelog_path, new_changelog)
+    puts "Updated CHANGELOG.md with version #{version}"
+    puts "\n#{changelog_entry}"
+  end
+
+  desc "Create annotated git tag from CHANGELOG"
+  # Usage: rake release:tag[0.2.1] or just rake release:tag (uses Dotsync::VERSION)
+  task :tag, [:version] do |_t, args|
+    version = args[:version]
+    unless version
+      require_relative "./lib/dotsync/version"
+      version = Dotsync::VERSION
+    end
+    version = version.sub(/^v/, "")
     tag_name = "v#{version}"
 
-    # Check if tag already exists
     if `git tag --list`.split.include?(tag_name)
       puts "Tag #{tag_name} already exists."
       exit(1)
     end
 
+    changelog_path = "CHANGELOG.md"
+    abort "CHANGELOG.md not found." unless File.exist?(changelog_path)
+
+    changelog = File.read(changelog_path)
+    version_regex = /^## \[#{Regexp.escape(version)}\] - (\d{4}-\d{2}-\d{2})\n(.*?)(?=^## \[|\z)/m
+    match = changelog.match(version_regex)
+
+    unless match
+      abort "Version #{version} not found in CHANGELOG.md\nRun 'rake release:changelog[#{version}]' first."
+    end
+
+    date = match[1]
+    content = match[2].strip
+    tag_message = "#{version} - #{date}\n\n#{content}"
+
     puts "Tagging commit as #{tag_name}..."
-    sh "git tag -a #{tag_name} -m 'Release #{tag_name}'"
-    puts "Pushing tag #{tag_name} to origin..."
-    sh "git push origin #{tag_name}"
-    puts "Done!"
+    sh "git", "tag", "-a", tag_name, "-m", tag_message
+    puts "Tag created. Push with: git push origin #{tag_name}"
+  end
+
+  desc "Full release: update changelog, commit, tag, and push"
+  # Usage: rake release:publish[0.2.1] or rake release:publish (uses Dotsync::VERSION)
+  task :publish, [:version] do |_t, args|
+    version = args[:version]
+    unless version
+      require_relative "./lib/dotsync/version"
+      version = Dotsync::VERSION
+    end
+    version = version.sub(/^v/, "")
+
+    status = `git status --porcelain`.strip
+    uncommitted = status.split("\n").reject { |line| line.end_with?("CHANGELOG.md") }
+    abort "Uncommitted changes:\n#{uncommitted.join("\n")}" unless uncommitted.empty?
+
+    Rake::Task["release:changelog"].invoke(version)
+    puts "\nReview CHANGELOG.md, then press Enter to continue..."
+    $stdin.gets
+
+    sh "git", "add", "CHANGELOG.md"
+    sh "git", "commit", "-m", "Update CHANGELOG for v#{version}\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+
+    Rake::Task["release:tag"].reenable
+    Rake::Task["release:tag"].invoke(version)
+
+    branch = `git rev-parse --abbrev-ref HEAD`.strip
+    sh "git", "push", "origin", branch
+    sh "git", "push", "origin", "v#{version}"
+    puts "\n✅ Released v#{version}"
   end
 end
 

data/lib/dotsync/config/concerns/sync_mappings.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Dotsync
+  # SyncMappings provides bidirectional mapping support.
+  # It reads [sync] section mappings and converts them to push or pull format.
+  #
+  # The [sync] section supports multiple sub-types:
+  #
+  # 1. Explicit mappings with [[sync.mappings]]:
+  #    [[sync.mappings]]
+  #    local  = "$XDG_CONFIG_HOME/nvim"
+  #    remote = "$XDG_CONFIG_HOME_MIRROR/nvim"
+  #    force  = true
+  #    ignore = ["lazy-lock.json"]
+  #
+  # 2. XDG shorthand mappings that auto-expand environment variables:
+  #    [[sync.xdg_config]]
+  #    path = "nvim"
+  #    force = true
+  #    # Expands to: local=$XDG_CONFIG_HOME/nvim, remote=$XDG_CONFIG_HOME_MIRROR/nvim
+  #
+  # Supported shorthands:
+  #   - 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
+  #   - sync.mappings:   explicit local/remote mappings
+  #
+  # For push: local → remote (src=local, dest=remote)
+  # For pull: remote → local (src=remote, dest=local)
+  module SyncMappings
+    SYNC_SECTION = "sync"
+    MAPPINGS_KEY = "mappings"
+
+    # Shorthand type definitions mapping to local/remote base paths
+    SHORTHANDS = {
+      "home"       => { local: "$HOME",            remote: "$HOME_MIRROR" },
+      "xdg_config" => { local: "$XDG_CONFIG_HOME", remote: "$XDG_CONFIG_HOME_MIRROR" },
+      "xdg_data"   => { local: "$XDG_DATA_HOME",   remote: "$XDG_DATA_HOME_MIRROR" },
+      "xdg_cache"  => { local: "$XDG_CACHE_HOME",  remote: "$XDG_CACHE_HOME_MIRROR" },
+      "xdg_bin"    => { local: "$XDG_BIN_HOME",    remote: "$XDG_BIN_HOME_MIRROR" }
+    }.freeze
+
+    def sync_mappings_for_push
+      all_sync_mappings(:push)
+    end
+
+    def sync_mappings_for_pull
+      all_sync_mappings(:pull)
+    end
+
+    def has_sync_mappings?
+      return false unless sync_section.is_a?(Hash)
+
+      explicit_mappings_raw.any? || shorthand_mappings_raw.any?
+    end
+
+    private
+      def all_sync_mappings(direction)
+        convert_explicit_mappings(direction: direction) + convert_shorthand_mappings(direction: direction)
+      end
+
+      def sync_section
+        @config[SYNC_SECTION]
+      end
+
+      # Explicit [[sync.mappings]] with local/remote keys
+      def explicit_mappings_raw
+        return [] unless sync_section.is_a?(Hash)
+        return [] unless sync_section.key?(MAPPINGS_KEY)
+
+        Array(sync_section[MAPPINGS_KEY])
+      end
+
+      def convert_explicit_mappings(direction:)
+        explicit_mappings_raw.map do |mapping|
+          converted = convert_explicit_mapping(mapping, direction)
+          Dotsync::Mapping.new(converted)
+        end
+      end
+
+      def convert_explicit_mapping(mapping, direction)
+        local = mapping["local"]
+        remote = mapping["remote"]
+
+        base = case direction
+               when :push
+                 { "src" => local, "dest" => remote }
+               when :pull
+                 { "src" => remote, "dest" => local }
+        end
+
+        # Preserve other options
+        base["force"] = mapping["force"] if mapping.key?("force")
+        base["ignore"] = mapping["ignore"] if mapping.key?("ignore")
+        base["only"] = mapping["only"] if mapping.key?("only")
+
+        base
+      end
+
+      # Shorthand mappings: [[sync.home]], [[sync.xdg_config]], etc.
+      def shorthand_mappings_raw
+        return [] unless sync_section.is_a?(Hash)
+
+        mappings = []
+        SHORTHANDS.each_key do |shorthand_type|
+          next unless sync_section.key?(shorthand_type)
+          Array(sync_section[shorthand_type]).each do |mapping|
+            mappings << { type: shorthand_type, mapping: mapping }
+          end
+        end
+        mappings
+      end
+
+      def convert_shorthand_mappings(direction:)
+        shorthand_mappings_raw.map do |entry|
+          converted = convert_shorthand_mapping(entry[:type], entry[:mapping], direction)
+          Dotsync::Mapping.new(converted)
+        end
+      end
+
+      def convert_shorthand_mapping(shorthand_type, mapping, direction)
+        shorthand_def = SHORTHANDS[shorthand_type]
+
+        # Support both 'path' for single paths and 'only' for multiple paths
+        path = mapping["path"]
+        only = mapping["only"]
+
+        local = build_path(shorthand_def[:local], path)
+        remote = build_path(shorthand_def[:remote], path)
+
+        base = case direction
+               when :push
+                 { "src" => local, "dest" => remote }
+               when :pull
+                 { "src" => remote, "dest" => local }
+        end
+
+        # Preserve other options
+        base["force"] = mapping["force"] if mapping.key?("force")
+        base["ignore"] = mapping["ignore"] if mapping.key?("ignore")
+        base["only"] = only if only
+
+        base
+      end
+
+      def build_path(base, path)
+        path ? File.join(base, path) : base
+      end
+
+      def validate_sync_mappings!
+        return unless sync_section
+
+        unless sync_section.is_a?(Hash)
+          raise Dotsync::ConfigError,
+            "Configuration error: [sync] must be a table, not an array. " \
+            "Use [[sync.mappings]] for explicit mappings."
+        end
+
+        validate_explicit_mappings!
+        validate_shorthand_mappings!
+      end
+
+      def validate_explicit_mappings!
+        return unless sync_section.key?(MAPPINGS_KEY)
+
+        explicit_mappings_raw.each_with_index do |mapping, index|
+          unless mapping.is_a?(Hash) && mapping.key?("local") && mapping.key?("remote")
+            raise Dotsync::ConfigError,
+              "Configuration error in sync.mappings ##{index + 1}: " \
+              "Each mapping must have 'local' and 'remote' keys."
+          end
+        end
+      end
+
+      def validate_shorthand_mappings!
+        SHORTHANDS.each_key do |shorthand_type|
+          next unless sync_section.key?(shorthand_type)
+
+          Array(sync_section[shorthand_type]).each_with_index do |mapping, index|
+            unless mapping.is_a?(Hash)
+              raise Dotsync::ConfigError,
+                "Configuration error in sync.#{shorthand_type} ##{index + 1}: " \
+                "Each mapping must be a table."
+            end
+          end
+        end
+      end
+  end
+end

data/lib/dotsync/config/pull_action_config.rb

@@ -3,10 +3,10 @@
 module Dotsync
   class PullActionConfig < BaseConfig
     include XDGBaseDirectory
+    include SyncMappings
 
     def mappings
-      mappings_list = section["mappings"]
-      Array(mappings_list).map { |mapping| Dotsync::Mapping.new(mapping) }
+      section_mappings + sync_mappings_for_pull
     end
 
     def backups_root
@@ -20,13 +20,31 @@ module Dotsync
         SECTION_NAME
       end
 
+      def section_mappings
+        return [] unless section && section["mappings"]
+        Array(section["mappings"]).map { |mapping| Dotsync::Mapping.new(mapping) }
+      end
+
       def validate!
-        validate_section_present!
-        validate_key_present! "mappings"
+        validate_pull_or_sync_present!
+        validate_pull_mappings!
+        validate_sync_mappings!
+      end
+
+      def validate_pull_or_sync_present!
+        has_pull = @config.key?(section_name) && section["mappings"]&.any?
+
+        unless has_pull || has_sync_mappings?
+          raise_error "No [#{section_name}] mappings or [sync] mappings found in config file"
+        end
+      end
+
+      def validate_pull_mappings!
+        return unless section && section["mappings"]
 
         Array(section["mappings"]).each_with_index do |mapping, index|
           unless mapping.is_a?(Hash) && mapping.key?("src") && mapping.key?("dest")
-            raise "Configuration error in mapping ##{index + 1}: Each mapping must have 'src' and 'dest' keys."
+            raise "Configuration error in pull mapping ##{index + 1}: Each mapping must have 'src' and 'dest' keys."
           end
         end
       end

data/lib/dotsync/config/push_action_config.rb

@@ -2,9 +2,10 @@
 
 module Dotsync
   class PushActionConfig < BaseConfig
+    include SyncMappings
+
     def mappings
-      mappings_list = section["mappings"]
-      Array(mappings_list).map { |mapping| Dotsync::Mapping.new(mapping) }
+      section_mappings + sync_mappings_for_push
     end
 
     private
@@ -14,13 +15,31 @@ module Dotsync
         SECTION_NAME
       end
 
+      def section_mappings
+        return [] unless section && section["mappings"]
+        Array(section["mappings"]).map { |mapping| Dotsync::Mapping.new(mapping) }
+      end
+
       def validate!
-        validate_section_present!
-        validate_key_present! "mappings"
+        validate_push_or_sync_present!
+        validate_push_mappings!
+        validate_sync_mappings!
+      end
+
+      def validate_push_or_sync_present!
+        has_push = @config.key?(section_name) && section["mappings"]&.any?
+
+        unless has_push || has_sync_mappings?
+          raise_error "No [#{section_name}] mappings or [sync] mappings found in config file"
+        end
+      end
+
+      def validate_push_mappings!
+        return unless section && section["mappings"]
 
         Array(section["mappings"]).each_with_index do |mapping, index|
           unless mapping.is_a?(Hash) && mapping.key?("src") && mapping.key?("dest")
-            raise "Configuration error in mapping ##{index + 1}: Each mapping must have 'src' and 'dest' keys."
+            raise "Configuration error in push mapping ##{index + 1}: Each mapping must have 'src' and 'dest' keys."
           end
         end
       end

data/lib/dotsync/loaders/pull_loader.rb

@@ -16,6 +16,10 @@ require_relative "../utils/config_cache"
 require_relative "../models/mapping"
 require_relative "../models/diff"
 
+# Config Concerns
+require_relative "../config/concerns/xdg_base_directory"
+require_relative "../config/concerns/sync_mappings"
+
 # Config
 require_relative "../config/base_config"
 require_relative "../config/pull_action_config"

data/lib/dotsync/loaders/push_loader.rb

@@ -16,6 +16,9 @@ require_relative "../utils/config_cache"
 require_relative "../models/mapping"
 require_relative "../models/diff"
 
+# Config Concerns
+require_relative "../config/concerns/sync_mappings"
+
 # Config
 require_relative "../config/base_config"
 require_relative "../config/push_action_config"

data/lib/dotsync/runner.rb

@@ -5,6 +5,7 @@ module Dotsync
     def initialize(logger: nil, config_path: nil)
       @logger = logger || Dotsync::Logger.new
       @config_path = config_path
+      Dotsync.config_path = config_path if config_path
     end
 
     # action_name should be a symbol, e.g., :pull, :watch, :sync

data/lib/dotsync/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dotsync
-  VERSION = "0.1.25"
+  VERSION = "0.1.26"
 end

data/lib/dotsync.rb

@@ -22,6 +22,7 @@ require_relative "dotsync/version"
 
 # Config Concerns (loaded early as they're used by other modules)
 require_relative "dotsync/config/concerns/xdg_base_directory"
+require_relative "dotsync/config/concerns/sync_mappings"
 
 # Utils
 require_relative "dotsync/utils/path_utils"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dotsync
 version: !ruby/object:Gem::Version
-  version: 0.1.25
+  version: 0.1.26
 platform: ruby
 authors:
 - David Sáenz
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: toml-rb
@@ -285,9 +284,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
-- ".github/workflows/gem-push.yml"
-- ".github/workflows/gem-push.yml.bak"
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
+- ".pre-commit-config.yaml"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
@@ -317,6 +317,7 @@ files:
 - lib/dotsync/actions/watch_action.rb
 - lib/dotsync/colors.rb
 - lib/dotsync/config/base_config.rb
+- lib/dotsync/config/concerns/sync_mappings.rb
 - lib/dotsync/config/concerns/xdg_base_directory.rb
 - lib/dotsync/config/pull_action_config.rb
 - lib/dotsync/config/push_action_config.rb
@@ -346,7 +347,6 @@ metadata:
   homepage_uri: https://github.com/dsaenztagarro/dotsync
   source_code_uri: https://github.com/dsaenztagarro/dotsync
   changelog_uri: https://github.com/dsaenztagarro/dotsync/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -361,8 +361,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Manage dotfiles like a boss
 test_files: []

data/.github/workflows/gem-push.yml.bak

@@ -1,45 +0,0 @@
-jobs:
-  build:
-    name: Build + Publish
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Publish to GPR
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build *.gemspec
-        gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
-      env:
-        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
-        OWNER: ${{ github.repository_owner }}
-
-  publish:
-    needs: test
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/master' && matrix.ruby == '3.2'
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.2
-          bundler-cache: true
-
-      - name: Check if gem version has changed
-        id: gem_version_check
-        run: |
-          gem build *.gemspec
-          gem_name=$(ls *.gem | head -n 1)
-          gem info $gem_name --remote || echo "new_version" > version_changed
-        env:
-          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"