dotsync 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0da622d8ef82d600401b7464c4ad28be7872fa942c252d00273378bcbdab2788
-  data.tar.gz: db97edbc75bb40ddd8353d97d2b3d255da9caa298dde368a58963e1f000bbc2d
+  metadata.gz: 710780a2db7e818a04b5eca4d4546b3fb6f085fc4b0eaba11df1bcab6bfc0ebd
+  data.tar.gz: 4e41f76afbbce3996c723e681d9af06d6babd2e69533b6b67ac687fe15e06864
 SHA512:
-  metadata.gz: f1f7fd2a2bb4d39df4c8a4286fb4ce750b55f5e3d4b0fb1a1bfa6a7902f5e6106919bb4dd1981057c583931fd4bf6534c64dc8161175caf38159bcb9dd5f93d5
-  data.tar.gz: a79078d32865500b76f5a27959bc426523a73ea31ec966aee7085b4786e024f9b7716dce1cb014323848228c64706618b91a9dfcd1a8ff5913817f165996c426
+  metadata.gz: 57e5da2e7b69b306a01709a5d6ebcc2e2d7cfd7fdd767bae7ab2bbc9957034abbd6dca04a9d0d237b6cd442ae6ac570c57bce15761ebabe865dc2730b1fb3558
+  data.tar.gz: adf1fb97f5fa7ca956653617c2d574f556e9bb6c9ed7407384e480de7f6694bd770776eed99d8a0474d7b1399d8f0616948e8e4d12e4aab0f242681371c2ab9f

data/CHANGELOG.md

@@ -1,3 +1,58 @@
+## [0.3.0] - 2026-02-14
+
+**New Features:**
+- Add `include` directive for config file composition
+  - Base config holds shared content; machine overlays contain only the delta
+  - `include = "base.toml"` — resolves path relative to the config file's directory
+  - Deep merge semantics: arrays concatenate, hashes merge recursively, scalars overlay wins
+  - Chained includes are rejected to keep behavior predictable
+  - Cache invalidation tracks included file's mtime and size alongside overlay file
+  - Zero downstream changes — `BaseConfig`, `PullActionConfig`, `PushActionConfig`, `SyncMappings` all see a plain merged hash
+
+**New Files:**
+- `lib/dotsync/utils/config_merger.rb` — ConfigMerger utility with resolve, deep merge, and include validation
+- `spec/dotsync/utils/config_merger_spec.rb` — Comprehensive tests for ConfigMerger
+
+**Documentation:**
+- Add "Config Includes" section to README with usage examples and merge semantics
+- Update "Per-Machine Configuration Files" section with include-based example
+
+**Testing:**
+- Add ConfigMerger specs: no-include passthrough, array concatenation, hash deep merge, scalar override, include key consumption, relative path resolution, missing file error, chained include rejection, non-string include error, base/overlay key preservation, empty overlay, include_path accessor
+- Add include-aware ConfigCache specs: mtime/size invalidation, deleted include, metadata contains include stats, no-cache mode with includes
+- Add end-to-end BaseConfig spec: base.toml + overlay.toml with include → to_h returns merged result
+
+## [0.2.3] - 2026-02-08
+
+**New Features:**
+- Add per-mapping post-sync hooks that run commands after files are transferred
+  - `post_sync` — runs after sync in both directions (`[[sync]]` mappings)
+  - `post_push` — runs only after push (`[[sync]]` and `[[push]]` mappings)
+  - `post_pull` — runs only after pull (`[[sync]]` and `[[pull]]` mappings)
+  - Template variables: `{files}` (shell-quoted changed dest paths), `{src}`, `{dest}`
+  - Hooks only execute when files actually changed and only with `--apply`
+  - Hook failures log errors but do not abort remaining hooks or mappings
+  - Preview mode shows what commands would run without executing
+- Add `HookError` error class for hook-related errors
+- Add hook icon (󰜎) to mappings legend with custom icon support
+
+**New Files:**
+- `lib/dotsync/utils/hook_runner.rb` — HookRunner utility with execute, preview, and template expansion
+- `spec/dotsync/utils/hook_runner_spec.rb` — Comprehensive tests for HookRunner
+
+**Documentation:**
+- Add "Post-Sync Hooks" section to README with hook types, examples, template variables, and real-world use cases
+- Add post-sync hooks to Key Features and Table of Contents
+
+**Testing:**
+- Add 35 new test examples covering hooks across all layers
+  - HookRunner: template expansion, multiple commands, failure handling, shell-escaped paths, preview mode
+  - Mapping: hooks attribute, has_hooks?, hook icon display
+  - SyncMappings: direction resolution, array concatenation, shorthand hooks, validation of invalid keys
+  - PushActionConfig/PullActionConfig: hook extraction, validation of unidirectional constraints
+  - PushAction/PullAction: hook execution with changes, skipped without changes, skipped in dry-run
+- Total: 467 examples, 0 failures | Line: 96.45% | Branch: 82.86%
+
 ## [0.2.2] - 2025-02-07
 
 **New Features:**
@@ -17,7 +72,6 @@
 - Add integration tests for glob patterns in FileTransfer (including force mode)
 - Add integration tests for glob patterns in DirectoryDiffer
 - All 432 tests pass with 96.29% line coverage
-
 ## [0.2.1] - 2025-02-06
 
 **Performance Optimizations:**

data/Gemfile.lock

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

data/README.md

@@ -19,6 +19,8 @@ Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles acro
 - **Smart Filtering**: Use `force`, `only`, and `ignore` options to precisely control what gets synced
 - **Automatic Backups**: Pull operations create timestamped backups for easy recovery
 - **Live Watching**: Continuously monitor and sync changes in real-time with `watch` command
+- **Config Includes**: Compose configs from a shared base + machine-specific overlays with `include`
+- **Post-Sync Hooks**: Run commands automatically after files change (e.g., codesigning, chmod, service reload)
 - **Customizable Output**: Control verbosity and customize icons to match your preferences
 - **Auto-Updates**: Get notified when new versions are available
 
@@ -33,6 +35,8 @@ Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles acro
     - [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)
+    - [Post-Sync Hooks](#post-sync-hooks)
+    - [Config Includes](#config-includes)
   - [Safety Features](#safety-features)
   - [Customizing Icons](#customizing-icons)
   - [Automatic Update Checks](#automatic-update-checks)
@@ -499,6 +503,130 @@ This configuration:
 
 These options apply when the source is a directory and are relevant for both `push` and `pull` operations.
 
+#### Post-Sync Hooks
+
+Hooks let you run commands automatically after a mapping's files are transferred. Hooks only execute when files actually changed, and only when using `--apply`.
+
+##### Hook Types
+
+| Hook | Description | Valid in |
+|------|-------------|----------|
+| `post_sync` | Runs after sync in both directions | `[[sync]]` mappings |
+| `post_push` | Runs only after push | `[[sync]]` and `[[push]]` mappings |
+| `post_pull` | Runs only after pull | `[[sync]]` and `[[pull]]` mappings |
+
+For sync mappings, hooks are resolved by direction:
+- **Push**: `post_sync` + `post_push` commands
+- **Pull**: `post_sync` + `post_pull` commands
+
+##### Examples
+
+**Single command (shorthand mapping):**
+```toml
+[[sync.xdg_bin]]
+force = true
+
+[sync.xdg_bin.hooks]
+post_sync = "codesign -s - {files}"
+```
+
+**Multiple commands (explicit sync):**
+```toml
+[[sync.mappings]]
+local  = "$XDG_CONFIG_HOME/scripts"
+remote = "$XDG_CONFIG_HOME_MIRROR/scripts"
+
+[sync.mappings.hooks]
+post_sync = ["codesign -s - {files}", "chmod 700 {files}"]
+post_pull = "launchctl kickstart -k gui/$(id -u)/com.example.service"
+```
+
+**Unidirectional mapping:**
+```toml
+[[pull.mappings]]
+src = "$DOTFILES_DIR/scripts"
+dest = "$HOME/Scripts"
+
+[pull.mappings.hooks]
+post_pull = ["codesign -s - {files}", "chmod 700 {files}"]
+```
+
+##### Template Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{files}` | Shell-quoted paths of changed destination files |
+| `{src}` | The mapping's source path |
+| `{dest}` | The mapping's destination path |
+
+##### Real-World Examples
+
+```toml
+# Codesign scripts after pulling (macOS Ventura+ requirement for LaunchAgents)
+[[sync.xdg_bin]]
+force = true
+
+[sync.xdg_bin.hooks]
+post_pull = "codesign -s - {files}"
+
+# Reload a LaunchAgent after pulling config changes
+[[pull.mappings]]
+src = "$DOTFILES_DIR/LaunchAgents/com.example.plist"
+dest = "$HOME/Library/LaunchAgents/com.example.plist"
+
+[pull.mappings.hooks]
+post_pull = "launchctl kickstart -k gui/$(id -u)/com.example"
+```
+
+> [!NOTE]
+> In preview mode (without `--apply`), hooks are displayed as a preview showing what commands would run. Hook failures log errors but do not abort remaining hooks or mappings.
+
+#### Config Includes
+
+Use `include` to compose a config from a shared base file and a machine-specific overlay. This eliminates duplication when multiple machines share most of the same mappings.
+
+```toml
+# dotsync.mbp_personal.toml (overlay — only the delta)
+include = "dotsync.base.toml"
+
+# Machine-specific mappings appended to base
+[[sync.xdg_config]]
+path = "claude"
+only = ["settings.json", "instructions", "commands"]
+
+[[sync.mappings]]
+local  = "$XDG_CONFIG_HOME/opencode/opencode.jsonc"
+remote = "$XDG_CONFIG_HOME_MIRROR/opencode/opencode.mbp_personal.jsonc"
+```
+
+```toml
+# dotsync.base.toml (shared across all machines)
+[[sync.home]]
+path = ".zshenv"
+
+[[sync.xdg_config]]
+only = ["alacritty", "brewfile", "git", "nvim", "zsh"]
+force = true
+
+[watch]
+src = "~/.config"
+paths = ["~/.config/nvim/", "~/.config/zsh/"]
+```
+
+**Merge semantics:**
+
+| Type | Behavior | Example |
+|------|----------|---------|
+| Arrays (`[[array-of-tables]]`) | Concatenate (base + overlay) | Base `[[sync.home]]` entries + overlay `[[sync.home]]` entries |
+| Hashes (`[tables]`) | Recursive deep merge (overlay wins on leaves) | Overlay `[watch].dest` overrides base `[watch].dest` |
+| Scalars | Overlay wins | Overlay `force = false` overrides base `force = true` |
+
+**Rules:**
+- The `include` path is resolved relative to the overlay file's directory
+- Chained includes (an included file that itself has `include`) are not supported
+- The `include` key is consumed and does not appear in the merged config
+- Cache invalidation tracks both the overlay and included file's mtime/size
+
 ### Safety Features
 
 Dotsync includes several safety mechanisms to prevent accidental data loss:
@@ -773,21 +901,30 @@ force = true
 
 ### Per-Machine Configuration Files
 
-Use different config files for different machines:
+Use `include` to share a base config across machines, with each machine adding only its delta:
+
+```
+dotfiles/xdg_config_home/dotsync/
+  dotsync.base.toml            # shared mappings, hooks, watch paths
+  dotsync.mbp_personal.toml    # include + personal-only mappings
+  dotsync.mbp_work.toml        # include + work-only mappings
+  dotsync.mac_mini.toml        # include + mac-mini-only mappings
+```
 
 ```toml
-# In dotsync.macbook.toml
-[[sync.mappings]]
-local  = "$XDG_CONFIG_HOME/dotsync.toml"
-remote = "$XDG_CONFIG_HOME_MIRROR/dotsync/dotsync.macbook.toml"
+# dotsync.mbp_personal.toml — slim overlay
+include = "dotsync.base.toml"
+
+[[sync.xdg_config]]
+path = "claude"
+only = ["settings.json", "instructions", "commands"]
 
-# In dotsync.work.toml
 [[sync.mappings]]
 local  = "$XDG_CONFIG_HOME/dotsync.toml"
-remote = "$XDG_CONFIG_HOME_MIRROR/dotsync/dotsync.work.toml"
+remote = "$XDG_CONFIG_HOME_MIRROR/dotsync/dotsync.mbp_personal.toml"
 ```
 
-Then use `-c` flag to select the appropriate config:
+Each machine's overlay self-references so `ds push` keeps it in sync with the repo. Use `-c` to select a config:
 ```shell
 dotsync -c ~/.config/dotsync/dotsync.macbook.toml push --apply
 ```
@@ -913,21 +1050,31 @@ dotsync -c ~/my-config.toml setup
 
 ### Releasing a new version
 
-1. Update the version number in `lib/dotsync/version.rb`
-2. Add entry to `CHANGELOG.md` documenting changes
-3. Commit all changes: `git add . && git commit -m "Release vX.Y.Z"`
-4. Create annotated tag with changelog extract:
-   ```shell
-   git tag -a vX.Y.Z -m "Release vX.Y.Z
+**Automated (recommended):**
 
-   <paste relevant CHANGELOG section here>"
-   ```
-5. Push commits and tags: `git push && git push --tags`
-6. Build and publish gem manually:
-   ```shell
-   gem build dotsync.gemspec
-   gem push dotsync-X.Y.Z.gem
-   ```
+```shell
+# 1. Update version in lib/dotsync/version.rb
+# 2. Commit all changes
+# 3. Run the full release workflow:
+rake release:publish
+```
+
+This generates a CHANGELOG entry from commits, opens it for review, commits, creates an annotated tag (with markdown stripped to plain text), and pushes everything.
+
+**Individual tasks:**
+
+```shell
+rake release:changelog        # Generate CHANGELOG entry from commits since last tag
+rake release:tag              # Create annotated tag from CHANGELOG (uses Dotsync::VERSION)
+rake release:tag[0.3.0]      # Create annotated tag for a specific version
+```
+
+**Publishing the gem:**
+
+```shell
+gem build dotsync.gemspec
+gem push dotsync-X.Y.Z.gem
+```
 
 The `release.yml` GitHub Action automatically creates a GitHub Release when a version tag is pushed, extracting release notes from CHANGELOG.md.
 

data/Rakefile

@@ -14,14 +14,30 @@ end
 
 task default: :spec
 
+# Strip markdown formatting for plain-text contexts (git tag messages)
+def strip_markdown(text)
+  text
+    .gsub(/\*\*(.+?)\*\*/, '\1')  # **bold** → bold
+    .gsub(/`([^`]+)`/, '\1')      # `code`  → code
+    .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') # [text](url) → text
+end
+
+# Load local version.rb, overriding any gem-installed constant
+def local_version
+  verbose = $VERBOSE
+  $VERBOSE = nil
+  load File.expand_path("lib/dotsync/version.rb", __dir__)
+  $VERBOSE = verbose
+  Dotsync::VERSION
+end
+
 namespace :release do
   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
+      version = local_version
     end
     version = version.sub(/^v/, "")
     today = Date.today.strftime("%Y-%m-%d")
@@ -87,8 +103,7 @@ namespace :release do
   task :tag, [:version] do |_t, args|
     version = args[:version]
     unless version
-      require_relative "./lib/dotsync/version"
-      version = Dotsync::VERSION
+      version = local_version
     end
     version = version.sub(/^v/, "")
     tag_name = "v#{version}"
@@ -109,11 +124,11 @@ namespace :release do
       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}"
+    content = strip_markdown(match[2].strip)
+    tag_message = "Release v#{version}\n\n#{content}"
 
     puts "Tagging commit as #{tag_name}..."
+    puts "\n--- Tag message ---\n#{tag_message}\n---\n\n"
     sh "git", "tag", "-a", tag_name, "-m", tag_message
     puts "Tag created. Push with: git push origin #{tag_name}"
   end
@@ -123,8 +138,7 @@ namespace :release do
   task :publish, [:version] do |_t, args|
     version = args[:version]
     unless version
-      require_relative "./lib/dotsync/version"
-      version = Dotsync::VERSION
+      version = local_version
     end
     version = version.sub(/^v/, "")
 

data/lib/dotsync/actions/concerns/mappings_transfer.rb

@@ -23,8 +23,9 @@ module Dotsync
 
     MAPPINGS_LEGEND = [
       [Icons.force, "The source will overwrite the destination"],
-      [Icons.only, "Paths designated explicitly as source only"],
-      [Icons.ignore, "Paths configured to be ignored in the destination"],
+      [Icons.only, "Filtered by 'only' whitelist"],
+      [Icons.ignore, "Filtered by 'ignore' blacklist"],
+      [Icons.hook, "Post-sync hooks configured"],
       [Icons.invalid, "Invalid paths detected in the source or destination"]
     ]
 
@@ -135,6 +136,42 @@ module Dotsync
       end
     end
 
+    def execute_hooks
+      valid_mappings.each_with_index do |mapping, idx|
+        next unless mapping.has_hooks?
+
+        differ = differs[idx]
+        changed_files = differ.additions + differ.modifications
+        next if changed_files.empty?
+
+        runner = Dotsync::HookRunner.new(mapping: mapping, changed_files: changed_files, logger: logger)
+        runner.execute
+      end
+    end
+
+    def show_hooks_preview
+      hooks_to_run = []
+
+      valid_mappings.each_with_index do |mapping, idx|
+        next unless mapping.has_hooks?
+
+        differ = differs[idx]
+        changed_files = differ.additions + differ.modifications
+        next if changed_files.empty?
+
+        runner = Dotsync::HookRunner.new(mapping: mapping, changed_files: changed_files, logger: logger)
+        hooks_to_run.concat(runner.preview)
+      end
+
+      return if hooks_to_run.empty?
+
+      info("Hooks to run:", icon: :hook)
+      hooks_to_run.each do |command|
+        logger.log("  #{command}")
+      end
+      logger.log("")
+    end
+
     private
       # Computes diffs for all valid mappings.
       #

data/lib/dotsync/actions/pull_action.rb

@@ -16,6 +16,7 @@ module Dotsync
       show_mappings if output_sections[:mappings]
       show_differences_legend if has_differences? && output_sections[:differences_legend]
       show_differences(diff_content: output_sections[:diff_content]) if output_sections[:differences]
+      show_hooks_preview if output_sections[:differences]
 
       return unless options[:apply]
 
@@ -32,6 +33,7 @@ module Dotsync
       end
 
       transfer_mappings
+      execute_hooks
       action("Mappings pulled", icon: :done)
     end
 

data/lib/dotsync/actions/push_action.rb

@@ -14,6 +14,7 @@ module Dotsync
       show_mappings if output_sections[:mappings]
       show_differences_legend if has_differences? && output_sections[:differences_legend]
       show_differences(diff_content: output_sections[:diff_content]) if output_sections[:differences]
+      show_hooks_preview if output_sections[:differences]
 
       return unless options[:apply]
 
@@ -23,6 +24,7 @@ module Dotsync
       end
 
       transfer_mappings
+      execute_hooks
       action("Mappings pushed", icon: :done)
     end
   end

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

@@ -96,6 +96,12 @@ module Dotsync
         base["ignore"] = mapping["ignore"] if mapping.key?("ignore")
         base["only"] = mapping["only"] if mapping.key?("only")
 
+        # Resolve hooks for direction
+        if mapping.key?("hooks")
+          resolved = resolve_hooks_for_direction(mapping["hooks"], direction)
+          base["hooks"] = resolved if resolved.any?
+        end
+
         base
       end
 
@@ -142,9 +148,41 @@ module Dotsync
         base["ignore"] = mapping["ignore"] if mapping.key?("ignore")
         base["only"] = only if only
 
+        # Resolve hooks for direction
+        if mapping.key?("hooks")
+          resolved = resolve_hooks_for_direction(mapping["hooks"], direction)
+          base["hooks"] = resolved if resolved.any?
+        end
+
         base
       end
 
+      def resolve_hooks_for_direction(raw_hooks, direction)
+        return [] unless raw_hooks.is_a?(Hash)
+
+        hooks = Array(raw_hooks["post_sync"])
+        case direction
+        when :push
+          hooks += Array(raw_hooks["post_push"])
+        when :pull
+          hooks += Array(raw_hooks["post_pull"])
+        end
+        hooks
+      end
+
+      def validate_hooks!(hooks, context)
+        return unless hooks.is_a?(Hash)
+
+        valid_keys = %w[post_sync post_push post_pull]
+        invalid_keys = hooks.keys - valid_keys
+        return if invalid_keys.empty?
+
+        raise Dotsync::ConfigError,
+          "Configuration error in #{context}: " \
+          "Invalid hook key(s): #{invalid_keys.join(", ")}. " \
+          "Valid keys are: #{valid_keys.join(", ")}"
+      end
+
       def build_path(base, path)
         path ? File.join(base, path) : base
       end
@@ -171,6 +209,8 @@ module Dotsync
               "Configuration error in sync.mappings ##{index + 1}: " \
               "Each mapping must have 'local' and 'remote' keys."
           end
+
+          validate_hooks!(mapping["hooks"], "sync.mappings ##{index + 1}") if mapping.key?("hooks")
         end
       end
 
@@ -184,6 +224,8 @@ module Dotsync
                 "Configuration error in sync.#{shorthand_type} ##{index + 1}: " \
                 "Each mapping must be a table."
             end
+
+            validate_hooks!(mapping["hooks"], "sync.#{shorthand_type} ##{index + 1}") if mapping.is_a?(Hash) && mapping.key?("hooks")
           end
         end
       end

data/lib/dotsync/config/pull_action_config.rb

@@ -22,7 +22,15 @@ module Dotsync
 
       def section_mappings
         return [] unless section && section["mappings"]
-        Array(section["mappings"]).map { |mapping| Dotsync::Mapping.new(mapping) }
+        Array(section["mappings"]).map do |mapping|
+          attrs = mapping.dup
+          if attrs.key?("hooks") && attrs["hooks"].is_a?(Hash)
+            resolved = Array(attrs["hooks"]["post_pull"])
+            attrs["hooks"] = resolved.any? ? resolved : nil
+            attrs.delete("hooks") unless attrs["hooks"]
+          end
+          Dotsync::Mapping.new(attrs)
+        end
       end
 
       def validate!
@@ -46,6 +54,16 @@ module Dotsync
           unless mapping.is_a?(Hash) && mapping.key?("src") && mapping.key?("dest")
             raise "Configuration error in pull mapping ##{index + 1}: Each mapping must have 'src' and 'dest' keys."
           end
+
+          if mapping.is_a?(Hash) && mapping.key?("hooks") && mapping["hooks"].is_a?(Hash)
+            invalid_keys = mapping["hooks"].keys - ["post_pull"]
+            if invalid_keys.any?
+              raise Dotsync::ConfigError,
+                "Configuration error in pull mapping ##{index + 1}: " \
+                "Only 'post_pull' hooks are allowed in [pull] mappings. " \
+                "Invalid key(s): #{invalid_keys.join(", ")}"
+            end
+          end
         end
       end
   end

data/lib/dotsync/config/push_action_config.rb

@@ -17,7 +17,15 @@ module Dotsync
 
       def section_mappings
         return [] unless section && section["mappings"]
-        Array(section["mappings"]).map { |mapping| Dotsync::Mapping.new(mapping) }
+        Array(section["mappings"]).map do |mapping|
+          attrs = mapping.dup
+          if attrs.key?("hooks") && attrs["hooks"].is_a?(Hash)
+            resolved = Array(attrs["hooks"]["post_push"])
+            attrs["hooks"] = resolved.any? ? resolved : nil
+            attrs.delete("hooks") unless attrs["hooks"]
+          end
+          Dotsync::Mapping.new(attrs)
+        end
       end
 
       def validate!
@@ -41,6 +49,16 @@ module Dotsync
           unless mapping.is_a?(Hash) && mapping.key?("src") && mapping.key?("dest")
             raise "Configuration error in push mapping ##{index + 1}: Each mapping must have 'src' and 'dest' keys."
           end
+
+          if mapping.is_a?(Hash) && mapping.key?("hooks") && mapping["hooks"].is_a?(Hash)
+            invalid_keys = mapping["hooks"].keys - ["post_push"]
+            if invalid_keys.any?
+              raise Dotsync::ConfigError,
+                "Configuration error in push mapping ##{index + 1}: " \
+                "Only 'post_push' hooks are allowed in [push] mappings. " \
+                "Invalid key(s): #{invalid_keys.join(", ")}"
+            end
+          end
         end
       end
   end

data/lib/dotsync/errors.rb

@@ -8,4 +8,5 @@ module Dotsync
   class DiskFullError < FileTransferError; end
   class SymlinkError < FileTransferError; end
   class TypeConflictError < FileTransferError; end
+  class HookError < Error; end
 end

data/lib/dotsync/icons.rb

@@ -18,6 +18,7 @@ module Dotsync
     DEFAULT_ONLY = " "
     DEFAULT_IGNORE = "󰈉 "
     DEFAULT_INVALID = "󱏏 "
+    DEFAULT_HOOK = "󰜎 "
 
     # Default Mappings Differences icons
     DEFAULT_DIFF_CREATED = " "
@@ -50,6 +51,7 @@ module Dotsync
         only: config.dig("icons", "only") || DEFAULT_ONLY,
         ignore: config.dig("icons", "ignore") || DEFAULT_IGNORE,
         invalid: config.dig("icons", "invalid") || DEFAULT_INVALID,
+        hook: config.dig("icons", "hook") || DEFAULT_HOOK,
         # Differences Legend
         diff_created: config.dig("icons", "diff_created") || DEFAULT_DIFF_CREATED,
         diff_updated: config.dig("icons", "diff_updated") || DEFAULT_DIFF_UPDATED,
@@ -75,6 +77,10 @@ module Dotsync
       @custom_icons[:invalid] || DEFAULT_INVALID
     end
 
+    def self.hook
+      @custom_icons[:hook] || DEFAULT_HOOK
+    end
+
     # Differences Legend methods
 
     def self.diff_created
@@ -100,6 +106,7 @@ module Dotsync
       diff: DIFF,
       force: -> { force },
       ignore: -> { ignore },
+      hook: DEFAULT_HOOK,
       pull: PULL,
       push: PUSH,
       watch: WATCH,

data/lib/dotsync/loaders/pull_loader.rb

@@ -13,6 +13,7 @@ require_relative "../utils/directory_differ"
 require_relative "../utils/config_cache"
 require_relative "../utils/content_diff"
 require_relative "../utils/parallel"
+require_relative "../utils/hook_runner"
 
 # Models
 require_relative "../models/mapping"

data/lib/dotsync/loaders/push_loader.rb

@@ -13,6 +13,7 @@ require_relative "../utils/directory_differ"
 require_relative "../utils/config_cache"
 require_relative "../utils/content_diff"
 require_relative "../utils/parallel"
+require_relative "../utils/hook_runner"
 
 # Models
 require_relative "../models/mapping"

data/lib/dotsync/models/mapping.rb

@@ -29,6 +29,7 @@ module Dotsync
       @original_ignores = Array(attributes["ignore"])
       @original_only = Array(attributes["only"])
       @force = attributes["force"] || false
+      @hooks = Array(attributes["hooks"])
 
       @sanitized_src, @sanitized_dest, @sanitized_ignores, @sanitized_only = process_paths(
         @original_src,
@@ -58,6 +59,12 @@ module Dotsync
       @force
     end
 
+    attr_reader :hooks
+
+    def has_hooks?
+      @hooks.any?
+    end
+
     def directories?
       File.directory?(src) && File.directory?(dest)
     end
@@ -103,6 +110,7 @@ module Dotsync
       msg << Icons.force if force?
       msg << Icons.only if has_inclusions?
       msg << Icons.ignore if has_ignores?
+      msg << Icons.hook if has_hooks?
       msg << Icons.invalid unless valid?
       msg.join
     end

data/lib/dotsync/utils/config_cache.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "digest"
+require_relative "config_merger"
 
 module Dotsync
   class ConfigCache
@@ -19,7 +20,7 @@ module Dotsync
 
     def load
       # Skip cache if disabled via environment variable
-      return parse_toml if ENV["DOTSYNC_NO_CACHE"]
+      return resolve_config if ENV["DOTSYNC_NO_CACHE"]
 
       return parse_and_cache unless valid_cache?
 
@@ -47,6 +48,15 @@ module Dotsync
         cache_age_days = (Time.now.to_f - meta["cached_at"]) / 86400
         return false if cache_age_days > 7
 
+        # Check include file validity if present
+        if meta["include_path"]
+          return false unless File.exist?(meta["include_path"])
+
+          include_stat = File.stat(meta["include_path"])
+          return false if include_stat.mtime.to_f != meta["include_mtime"]
+          return false if include_stat.size != meta["include_size"]
+        end
+
         true
       rescue StandardError
         # Any error in validation means invalid cache
@@ -54,7 +64,7 @@ module Dotsync
       end
 
       def parse_and_cache
-        config = parse_toml
+        config = resolve_config
 
         # Write cache files
         FileUtils.mkdir_p(@cache_dir)
@@ -67,6 +77,12 @@ module Dotsync
         config
       end
 
+      def resolve_config
+        raw = parse_toml
+        @merger = ConfigMerger.new(raw, @config_path)
+        @merger.resolve
+      end
+
       def parse_toml
         require "toml-rb"
         TomlRB.load_file(@config_path)
@@ -74,13 +90,22 @@ module Dotsync
 
       def build_metadata
         source_stat = File.stat(@config_path)
-        {
+        meta = {
           source_path: @config_path,
           source_size: source_stat.size,
           source_mtime: source_stat.mtime.to_f,
           cached_at: Time.now.to_f,
           dotsync_version: Dotsync::VERSION
         }
+
+        if @merger&.include_path
+          include_stat = File.stat(@merger.include_path)
+          meta[:include_path] = @merger.include_path
+          meta[:include_mtime] = include_stat.mtime.to_f
+          meta[:include_size] = include_stat.size
+        end
+
+        meta
       end
   end
 end

data/lib/dotsync/utils/config_merger.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "toml-rb"
+
+module Dotsync
+  class ConfigMerger
+    attr_reader :include_path
+
+    def self.resolve(config_hash, config_path)
+      new(config_hash, config_path).resolve
+    end
+
+    def initialize(config_hash, config_path)
+      @config = config_hash
+      @config_path = config_path
+      @include_path = nil
+    end
+
+    def resolve
+      return @config unless @config.key?("include")
+
+      validate_include_value!
+      @include_path = resolve_include_path
+      validate_include_exists!
+
+      base_config = load_base_config
+      validate_no_chained_includes!(base_config)
+
+      merged = deep_merge(base_config, overlay)
+      merged
+    end
+
+    private
+      def validate_include_value!
+        unless @config["include"].is_a?(String)
+          raise ConfigError, "Config Error: 'include' must be a string path, got #{@config["include"].class}"
+        end
+      end
+
+      def resolve_include_path
+        include_value = @config["include"]
+        config_dir = File.dirname(@config_path)
+        File.expand_path(include_value, config_dir)
+      end
+
+      def validate_include_exists!
+        unless File.exist?(@include_path)
+          raise ConfigError, "Config Error: Included file not found: #{@include_path}"
+        end
+      end
+
+      def load_base_config
+        TomlRB.load_file(@include_path)
+      end
+
+      def validate_no_chained_includes!(base_config)
+        if base_config.key?("include")
+          raise ConfigError, "Config Error: Chained includes are not supported (found 'include' in #{@include_path})"
+        end
+      end
+
+      def overlay
+        @config.reject { |key, _| key == "include" }
+      end
+
+      def deep_merge(base, overlay)
+        base.merge(overlay) do |_key, base_val, overlay_val|
+          if base_val.is_a?(Hash) && overlay_val.is_a?(Hash)
+            deep_merge(base_val, overlay_val)
+          elsif base_val.is_a?(Array) && overlay_val.is_a?(Array)
+            base_val + overlay_val
+          else
+            overlay_val
+          end
+        end
+      end
+  end
+end

data/lib/dotsync/utils/hook_runner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+
+module Dotsync
+  class HookRunner
+    def initialize(mapping:, changed_files:, logger:)
+      @mapping = mapping
+      @changed_files = changed_files
+      @logger = logger
+    end
+
+    def execute
+      @mapping.hooks.map do |command|
+        expanded = expand_template(command)
+        run_command(expanded)
+      end
+    end
+
+    def preview
+      @mapping.hooks.map { |command| expand_template(command) }
+    end
+
+    private
+      def expand_template(command)
+        files_str = @changed_files.map { |f| Shellwords.escape(f) }.join(" ")
+
+        command
+          .gsub("{files}", files_str)
+          .gsub("{src}", @mapping.src)
+          .gsub("{dest}", @mapping.dest)
+      end
+
+      def run_command(command)
+        stdout, stderr, status = Open3.capture3(command)
+
+        if status.success?
+          @logger.info("Hook succeeded: #{command}", icon: :hook)
+        else
+          @logger.error("Hook failed: #{command}")
+          @logger.error("  #{stderr.strip}") unless stderr.strip.empty?
+        end
+
+        { command: command, stdout: stdout, stderr: stderr, success: status.success? }
+      end
+  end
+end

data/lib/dotsync/version.rb

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

data/lib/dotsync.rb

@@ -31,7 +31,9 @@ require_relative "dotsync/utils/file_transfer"
 require_relative "dotsync/utils/directory_differ"
 require_relative "dotsync/utils/version_checker"
 require_relative "dotsync/utils/config_cache"
+require_relative "dotsync/utils/config_merger"
 require_relative "dotsync/utils/parallel"
+require_relative "dotsync/utils/hook_runner"
 
 # Models
 require_relative "dotsync/models/mapping"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dotsync
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - David Sáenz
@@ -334,9 +334,11 @@ files:
 - lib/dotsync/runner.rb
 - lib/dotsync/tasks/actions.rake
 - lib/dotsync/utils/config_cache.rb
+- lib/dotsync/utils/config_merger.rb
 - lib/dotsync/utils/content_diff.rb
 - lib/dotsync/utils/directory_differ.rb
 - lib/dotsync/utils/file_transfer.rb
+- lib/dotsync/utils/hook_runner.rb
 - lib/dotsync/utils/logger.rb
 - lib/dotsync/utils/parallel.rb
 - lib/dotsync/utils/path_utils.rb