dotsync 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c060e4f84252048c1b038e350efcf900bc5b62b6bab5285dc9b1a2a9d0d0da0f
-  data.tar.gz: 5bef34fde923690c3ffaf68b3d5ed77d2195006d91d8b4f2c59853533c285339
+  metadata.gz: 710780a2db7e818a04b5eca4d4546b3fb6f085fc4b0eaba11df1bcab6bfc0ebd
+  data.tar.gz: 4e41f76afbbce3996c723e681d9af06d6babd2e69533b6b67ac687fe15e06864
 SHA512:
-  metadata.gz: 7049966bedd67e25b008ad9a7bae1697f54d189dc7f666bd42495a242af68b8c9494ead4c3e5310e500ce516db47270d5ae0f0382035b50df5d09543a631192f
-  data.tar.gz: 7abedab0ed8d49946e5b832ad38390968f17c6a7e32da3a3d774a47117767f1eec9dc3cbefd20a2f815eed5b091dcab73c4e9612b21d67fb1b7f85a0b8499ed1
+  metadata.gz: 57e5da2e7b69b306a01709a5d6ebcc2e2d7cfd7fdd767bae7ab2bbc9957034abbd6dca04a9d0d237b6cd442ae6ac570c57bce15761ebabe865dc2730b1fb3558
+  data.tar.gz: adf1fb97f5fa7ca956653617c2d574f556e9bb6c9ed7407384e480de7f6694bd770776eed99d8a0474d7b1399d8f0616948e8e4d12e4aab0f242681371c2ab9f

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [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:**

data/Gemfile.lock

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

data/README.md

@@ -19,6 +19,7 @@ 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
@@ -35,6 +36,7 @@ Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles acro
     - [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)
@@ -579,6 +581,52 @@ 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:
@@ -853,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
 ```
@@ -993,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/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/version.rb

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

data/lib/dotsync.rb

@@ -31,6 +31,7 @@ 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"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dotsync
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - David Sáenz
@@ -334,6 +334,7 @@ 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