dotsync 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 918c52bf2da4cb3e03aa03725cc037bf6d3a5c6ede78c6c4f30b8bc6b74d8a55
-  data.tar.gz: 53ee0db3a70dd65effc25cc83717fe4c3c98e193f9a389efdd82a2922d4eccba
+  metadata.gz: 3b49b79875a41ac8a64361efc61108dc18ee203b08804daf40e709e18972ed88
+  data.tar.gz: f3eaf2a153a9757d98018900245ac7020596aab2844dbf1841d99e5e7ae055c3
 SHA512:
-  metadata.gz: 2ff87f445e42c1216a5d4e4b362d5023dabe0f9264dc926ec8be41a0890693d497b5152fdc9c9b2835989227e0a97ee94d25b27f4ddd9e8d361a7c64fbe7ec35
-  data.tar.gz: d965b970d2324afa4eb95662ef18cbce918439ee9d783b3c48d159f271c5e6a6cfbf3e262c067ba72dbbdd5c4f7eb0839885160a1106e2da5b9b947085840ca9
+  metadata.gz: 3315fa7273357e2a61c494e1fa3abdd31ba2e43089888f8dc5174e8bc70ce69fe4bbf553a3db2d647d437b9dae81811056dcc43f7d31bef56736346628ef76b1
+  data.tar.gz: fa0bdc870da7374523db60c823d527e0ec8c1da8809548b3f4aeaaec03872cf3f96e08bff0c27d73524c80677ef6e765725416d74b57f83d66f57f86cfb31772

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.4.0] - 2026-03-01
+
+### Added
+
+- Add manifest-based orphan cleanup for non-force sync mappings (#32)
+- Add `source` directive for config file indirection (#29) (#30)
+
+### Changed
+
+- CHANGELOG: remove manual version
+- Decouple Terminal::Table from domain logic via TableRenderer (#28)
+
 ## [0.3.3] - 2026-02-16
 
 ### Added
@@ -461,6 +473,7 @@ Add gem executables
 
 Initial version
 
+[0.4.0]: https://github.com/dsaenztagarro/dotsync/compare/v0.3.3...v0.4.0
 [0.3.3]: https://github.com/dsaenztagarro/dotsync/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/dsaenztagarro/dotsync/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/dsaenztagarro/dotsync/compare/v0.3.0...v0.3.1

data/Gemfile.lock

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

data/README.md

@@ -20,6 +20,7 @@ Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles acro
 - **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`
+- **Config Source**: Point local config to your dotfiles repo with `source` — changes are visible immediately without syncing
 - **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
@@ -37,6 +38,7 @@ Dotsync is a powerful Ruby gem for managing and synchronizing your dotfiles acro
     - [Mapping Options (force, only, ignore)](#force-only-and-ignore-options-in-mappings)
     - [Post-Sync Hooks](#post-sync-hooks)
     - [Config Includes](#config-includes)
+    - [Config Source](#config-source)
   - [Safety Features](#safety-features)
   - [Customizing Icons](#customizing-icons)
   - [Automatic Update Checks](#automatic-update-checks)
@@ -627,6 +629,54 @@ paths = ["~/.config/nvim/", "~/.config/zsh/"]
 - 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
 
+#### Config Source
+
+Use `source` to point your local config at the authoritative copy in your dotfiles repository. Instead of syncing config files back and forth, dotsync reads the config directly from the repo. Changes are visible immediately — no pull needed.
+
+**The problem it solves:** When config files change in your dotfiles repo, you normally need to `ds pull` to update local copies, then run `ds pull` again so the new config takes effect. With `source`, dotsync reads from the repo directly, eliminating this two-pass problem.
+
+**Setup:**
+
+```toml
+# ~/.config/dotsync.toml (one-time setup — never changes)
+source = "$XDG_CONFIG_HOME_MIRROR/dotsync/dotsync.mbp_personal.toml"
+```
+
+```toml
+# ~/Code/dotfiles/xdg_config_home/dotsync/dotsync.mbp_personal.toml (the real config)
+include = "dotsync.base.toml"
+
+[[sync.xdg_config]]
+path = "zsh"
+ignore = [".zsh_sessions", ".zsh_history", ".zcompdump"]
+
+[[sync.xdg_config]]
+path = "nvim"
+force = true
+ignore = ["lazy-lock.json"]
+```
+
+The local file is a thin pointer that never changes. The real config (and its `include` base) live in the repo and are read directly.
+
+**Rules:**
+- `source` must be the **only** key in the pointer file — no other config keys allowed
+- The source file can use `include` to compose with a base config (resolved relative to the source file)
+- Chained sources (a source file pointing to another source) are not supported
+- Environment variables are expanded in the `source` path (e.g., `$XDG_CONFIG_HOME_MIRROR`)
+- Cache invalidation tracks the pointer file, the source file, and any included file
+
+**Per-machine setup:**
+
+```
+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
+```
+
+Each machine's `~/.config/dotsync.toml` is a one-line pointer to its overlay. Edit the repo files and changes take effect immediately — no syncing, no two-pass.
+
 ### Safety Features
 
 Dotsync includes several safety mechanisms to prevent accidental data loss:

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

@@ -48,15 +48,13 @@ module Dotsync
       info("Environment variables:", icon: :env_vars)
 
       rows = env_vars.map { |env_var| [env_var, ENV[env_var]] }.sort_by(&:first)
-      table = Terminal::Table.new(rows: rows)
-      logger.log(table)
+      logger.log(Dotsync::TableRenderer.new(rows: rows).render)
       logger.log("")
     end
 
     def show_mappings_legend
       info("Mappings Legend:", icon: :legend)
-      table = Terminal::Table.new(rows: MAPPINGS_LEGEND)
-      logger.log(table)
+      logger.log(Dotsync::TableRenderer.new(rows: MAPPINGS_LEGEND).render)
       logger.log("")
     end
 
@@ -70,15 +68,13 @@ module Dotsync
           colorize_env_vars(mapping.original_dest)
         ]
       end
-      table = Terminal::Table.new(headings: ["Flags", "Source", "Destination"], rows: rows)
-      logger.log(table)
+      logger.log(Dotsync::TableRenderer.new(headings: ["Flags", "Source", "Destination"], rows: rows).render)
       logger.log("")
     end
 
     def show_differences_legend
       info("Differences Legend:", icon: :legend)
-      table = Terminal::Table.new(rows: DIFFERENCES_LEGEND)
-      logger.log(table)
+      logger.log(Dotsync::TableRenderer.new(rows: DIFFERENCES_LEGEND).render)
       logger.log("")
     end
 
@@ -97,6 +93,8 @@ module Dotsync
       logger.log("")
 
       show_content_diffs if diff_content && has_modifications?
+
+      show_orphan_preview if respond_to?(:manifests_xdg_data_home, true)
     end
 
     def show_content_diffs
@@ -138,6 +136,28 @@ module Dotsync
       end
     end
 
+    def cleanup_orphans
+      valid_mappings.each do |mapping|
+        next unless mapping.has_inclusions? && !mapping.force? && mapping.manifest_key
+
+        current_files = dest_files_matching_inclusions(mapping)
+        manifest = Dotsync::Manifest.new(
+          dest_dir: mapping.dest,
+          key: mapping.manifest_key,
+          xdg_data_home: manifests_xdg_data_home
+        )
+
+        manifest.orphans(current_files).each do |orphan_path|
+          next unless File.exist?(orphan_path)
+
+          FileUtils.rm(orphan_path)
+          logger.log("#{Icons.diff_removed}#{orphan_path}", color: Colors.diff_removals)
+        end
+
+        manifest.write(current_files)
+      end
+    end
+
     def execute_hooks(force: false)
       valid_mappings.each_with_index do |mapping, idx|
         next unless mapping.has_hooks?
@@ -230,6 +250,43 @@ module Dotsync
         mappings.select(&:valid?)
       end
 
+      def show_orphan_preview
+        orphans = []
+        valid_mappings.each do |mapping|
+          next unless mapping.has_inclusions? && !mapping.force? && mapping.manifest_key
+
+          current_files = dest_files_matching_inclusions(mapping)
+          manifest = Dotsync::Manifest.new(
+            dest_dir: mapping.dest,
+            key: mapping.manifest_key,
+            xdg_data_home: manifests_xdg_data_home
+          )
+          orphans.concat(manifest.orphans(current_files).select { |p| File.exist?(p) })
+        end
+
+        return if orphans.empty?
+
+        info("Orphans to remove:", icon: :diff)
+        orphans.sort.each do |path|
+          logger.log("#{Icons.diff_removed}#{path}", color: Colors.diff_removals)
+        end
+        logger.log("")
+      end
+
+      def dest_files_matching_inclusions(mapping)
+        return [] unless File.directory?(mapping.dest)
+
+        files = []
+        Find.find(mapping.dest) do |path|
+          next if path == mapping.dest
+          next if File.directory?(path)
+          next unless mapping.include?(path)
+
+          files << Pathname.new(path).relative_path_from(Pathname.new(mapping.dest)).to_s
+        end
+        files
+      end
+
       def all_dest_files(mapping)
         if File.directory?(mapping.dest)
           files = []

data/lib/dotsync/actions/pull_action.rb

@@ -6,6 +6,7 @@ module Dotsync
     include OutputSections
 
     def_delegator :@config, :backups_root
+    def_delegator :@config, :manifests_xdg_data_home
 
     def execute(options = {})
       output_sections = compute_output_sections(options)
@@ -33,6 +34,7 @@ module Dotsync
       end
 
       transfer_mappings
+      cleanup_orphans
       execute_hooks(force: options[:force_hooks])
       action("Mappings pulled", icon: :done)
     end

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

@@ -147,6 +147,7 @@ module Dotsync
         base["force"] = mapping["force"] if mapping.key?("force")
         base["ignore"] = mapping["ignore"] if mapping.key?("ignore")
         base["only"] = only if only
+        base["sync_type"] = shorthand_type
 
         # Resolve hooks for direction
         if mapping.key?("hooks")

data/lib/dotsync/config/pull_action_config.rb

@@ -13,6 +13,10 @@ module Dotsync
       File.join(xdg_data_home, "dotsync", "backups")
     end
 
+    def manifests_xdg_data_home
+      xdg_data_home
+    end
+
     private
       SECTION_NAME = "pull"
 

data/lib/dotsync/loaders/pull_loader.rb

@@ -5,7 +5,7 @@ require_relative "../core"
 
 # Gems needed for pull
 require "toml-rb"
-require "terminal-table"
+require_relative "../utils/table_renderer"
 
 # Utils needed for pull
 require_relative "../utils/file_transfer"
@@ -14,6 +14,7 @@ require_relative "../utils/config_cache"
 require_relative "../utils/content_diff"
 require_relative "../utils/parallel"
 require_relative "../utils/hook_runner"
+require_relative "../utils/manifest"
 
 # Models
 require_relative "../models/mapping"

data/lib/dotsync/loaders/push_loader.rb

@@ -5,7 +5,7 @@ require_relative "../core"
 
 # Gems needed for push
 require "toml-rb"
-require "terminal-table"
+require_relative "../utils/table_renderer"
 
 # Utils needed for push
 require_relative "../utils/file_transfer"

data/lib/dotsync/models/mapping.rb

@@ -21,7 +21,7 @@ module Dotsync
   class Mapping
     include Dotsync::PathUtils
 
-    attr_reader :original_src, :original_dest, :original_ignores, :original_only
+    attr_reader :original_src, :original_dest, :original_ignores, :original_only, :sync_type
 
     def initialize(attributes)
       @original_src = attributes["src"]
@@ -30,6 +30,7 @@ module Dotsync
       @original_only = Array(attributes["only"])
       @force = attributes["force"] || false
       @hooks = Array(attributes["hooks"])
+      @sync_type = attributes["sync_type"]
 
       @sanitized_src, @sanitized_dest, @sanitized_ignores, @sanitized_only = process_paths(
         @original_src,
@@ -65,6 +66,27 @@ module Dotsync
       @hooks.any?
     end
 
+    def has_inclusions?
+      @original_only.any?
+    end
+
+    def manifest_key
+      return nil unless @sync_type
+
+      shorthand_base = SyncMappings::SHORTHANDS.dig(@sync_type, :local)
+      return @sync_type unless shorthand_base
+
+      expanded_base = sanitize_path(shorthand_base)
+      if dest == expanded_base
+        @sync_type
+      elsif dest.start_with?("#{expanded_base}/")
+        subpath = dest.delete_prefix("#{expanded_base}/")
+        "#{@sync_type}--#{subpath}"
+      else
+        @sync_type
+      end
+    end
+
     def directories?
       File.directory?(src) && File.directory?(dest)
     end
@@ -211,10 +233,6 @@ module Dotsync
         @original_ignores.any?
       end
 
-      def has_inclusions?
-        @original_only.any?
-      end
-
       def process_paths(raw_src, raw_dest, raw_ignores, raw_only)
         sanitized_src = sanitize_path(raw_src)
         sanitized_dest = sanitize_path(raw_dest)

data/lib/dotsync/utils/config_cache.rb

@@ -7,6 +7,7 @@ require_relative "config_merger"
 module Dotsync
   class ConfigCache
     include Dotsync::XDGBaseDirectory
+    include Dotsync::PathUtils
 
     def initialize(config_path)
       @config_path = File.expand_path(config_path)
@@ -50,6 +51,15 @@ module Dotsync
         cache_age_days = (Time.now.to_f - meta["cached_at"]) / 86400
         return false if cache_age_days > 7
 
+        # Check source file validity if present
+        if meta["source_file_path"]
+          return false unless File.exist?(meta["source_file_path"])
+
+          source_file_stat = File.stat(meta["source_file_path"])
+          return false if source_file_stat.mtime.to_f != meta["source_file_mtime"]
+          return false if source_file_stat.size != meta["source_file_size"]
+        end
+
         # Check include file validity if present
         if meta["include_path"]
           return false unless File.exist?(meta["include_path"])
@@ -82,13 +92,62 @@ module Dotsync
 
       def resolve_config
         raw = parse_toml
-        @merger = ConfigMerger.new(raw, @config_path)
+        if raw.key?("source")
+          resolve_source(raw)
+        else
+          @merger = ConfigMerger.new(raw, @config_path)
+          @merger.resolve
+        end
+      end
+
+      def resolve_source(raw)
+        validate_source!(raw)
+        @source_path = resolve_source_path(raw["source"])
+        validate_source_exists!
+
+        source_raw = parse_toml_file(@source_path)
+        validate_no_chained_source!(source_raw)
+
+        @merger = ConfigMerger.new(source_raw, @source_path)
         @merger.resolve
       end
 
+      def validate_source!(raw)
+        unless raw["source"].is_a?(String)
+          raise ConfigError, "Config Error: 'source' must be a string path, got #{raw["source"].class}"
+        end
+
+        if raw.keys.any? { |k| k != "source" }
+          raise ConfigError,
+            "Config Error: 'source' cannot be combined with other keys. " \
+            "The source file should contain the full configuration."
+        end
+      end
+
+      def resolve_source_path(source_value)
+        expanded = expand_env_vars(source_value)
+        File.expand_path(expanded)
+      end
+
+      def validate_source_exists!
+        unless File.exist?(@source_path)
+          raise ConfigError, "Config Error: Source file not found: #{@source_path}"
+        end
+      end
+
+      def validate_no_chained_source!(config)
+        if config.key?("source")
+          raise ConfigError, "Config Error: Chained sources are not supported (found 'source' in #{@source_path})"
+        end
+      end
+
       def parse_toml
+        parse_toml_file(@config_path)
+      end
+
+      def parse_toml_file(path)
         require "toml-rb"
-        TomlRB.load_file(@config_path)
+        TomlRB.load_file(path)
       end
 
       def build_metadata
@@ -101,6 +160,13 @@ module Dotsync
           dotsync_version: Dotsync::VERSION
         }
 
+        if @source_path
+          source_file_stat = File.stat(@source_path)
+          meta[:source_file_path] = @source_path
+          meta[:source_file_mtime] = source_file_stat.mtime.to_f
+          meta[:source_file_size] = source_file_stat.size
+        end
+
         if @merger&.include_path
           include_stat = File.stat(@merger.include_path)
           meta[:include_path] = @merger.include_path

data/lib/dotsync/utils/manifest.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Dotsync
+  class Manifest
+    MANIFESTS_DIR = "dotsync/manifests"
+
+    # @param dest_dir [String] the mapping's destination directory (absolute)
+    # @param key [String] manifest filename key (e.g., "xdg_bin")
+    # @param xdg_data_home [String] base path for manifest storage
+    def initialize(dest_dir:, key:, xdg_data_home:)
+      @dest_dir = dest_dir
+      @key = key
+      @manifest_path = File.join(xdg_data_home, MANIFESTS_DIR, "#{key}.json")
+    end
+
+    # Returns array of relative file paths from stored manifest
+    # @return [Array<String>]
+    def read
+      return [] unless File.exist?(@manifest_path)
+
+      data = JSON.parse(File.read(@manifest_path))
+      Array(data["files"])
+    rescue JSON::ParserError
+      []
+    end
+
+    # Writes current file list to manifest
+    # @param files [Array<String>] relative file paths
+    def write(files)
+      FileUtils.mkdir_p(File.dirname(@manifest_path))
+      File.write(@manifest_path, JSON.pretty_generate({ "files" => files.sort }))
+    end
+
+    # Returns orphan absolute paths: files in old manifest but not in current_files
+    # @param current_files [Array<String>] relative file paths currently synced
+    # @return [Array<String>] absolute paths ready for deletion
+    def orphans(current_files)
+      previous = read
+      orphaned = previous - current_files
+      orphaned.map { |file| File.join(@dest_dir, file) }
+    end
+  end
+end

data/lib/dotsync/utils/table_renderer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "terminal-table"
+
+module Dotsync
+  class TableRenderer
+    attr_reader :rows
+
+    def initialize(rows:, headings: nil)
+      @rows = rows
+      @headings = headings
+    end
+
+    def render
+      options = { rows: @rows }
+      options[:headings] = @headings if @headings
+      Terminal::Table.new(**options).to_s
+    end
+  end
+end

data/lib/dotsync/version.rb

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

data/lib/dotsync.rb

@@ -11,7 +11,7 @@ require "logger"
 require "forwardable" # Ruby standard library
 require "ostruct"
 require "find"
-require "terminal-table"
+require_relative "dotsync/utils/table_renderer"
 
 # Base classes
 require_relative "dotsync/errors"
@@ -34,6 +34,7 @@ require_relative "dotsync/utils/config_cache"
 require_relative "dotsync/utils/config_merger"
 require_relative "dotsync/utils/parallel"
 require_relative "dotsync/utils/hook_runner"
+require_relative "dotsync/utils/manifest"
 
 # Models
 require_relative "dotsync/models/mapping"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dotsync
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - David Sáenz
@@ -340,8 +340,10 @@ files:
 - lib/dotsync/utils/file_transfer.rb
 - lib/dotsync/utils/hook_runner.rb
 - lib/dotsync/utils/logger.rb
+- lib/dotsync/utils/manifest.rb
 - lib/dotsync/utils/parallel.rb
 - lib/dotsync/utils/path_utils.rb
+- lib/dotsync/utils/table_renderer.rb
 - lib/dotsync/utils/version_checker.rb
 - lib/dotsync/version.rb
 homepage: https://github.com/dsaenztagarro/dotsync