dotsync 0.1.23 → 0.1.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63f80ee3b4145da856a0750344202adb55eb1d2b8bf2e1da5b8885176aba7eef
-  data.tar.gz: ee4e30168d290f6f75d682fee94755b9f34d8e17975f1bd2f6d15936f3f9bd4b
+  metadata.gz: 793ae0a7e00707a97255d631304eddae60e6ce6224d8c4d85c9550f54cbd59bd
+  data.tar.gz: 34fdbefc7f9b27a2f7fedd8dcbac9748ae59c99fb7cb15a970ebc67605e5ebe1
 SHA512:
-  metadata.gz: 30d151ca07b1be8b116ebcb7d27f440f9822cfe127b07cf0c13e8c034b23c0a8526d34f87587d208e83082dccf8bc463df3c2a3eaf0965ae949e3d90a974e086
-  data.tar.gz: 8be2548a3144cc24765ee59666370d1267d2c96fd0ddb21187da03cf678846085e19d5ef7f1252c2b979e44d9bade730b4fc7d92bfbc04d4e7052df592cd4ca2
+  metadata.gz: 50471dd7fca75246adb01dd946b17dc217b590cc0df359253f608f4868ae190c08aeb5ce5c9302dafa2533f368c69f35b1f9b3f70143ed36066745729904030b
+  data.tar.gz: 2061b3db4dfb07aaec4750efba675091797ce8ebcb9979ce37ffca5e1b838f20d2ebec181925c45d5a0a6c52d4681d05f989953f4022540c0a6705dc8fc6dd76

data/CHANGELOG.md

@@ -1,3 +1,51 @@
+# 0.1.25
+
+**Features:**
+- Add support for file-specific paths in 'only' configuration option
+  - Enable specifying individual files within directories: `only = ["bundle/config", "ghc/ghci.conf"]`
+  - Parent directories are automatically created as needed
+  - Sibling files in the same directory remain unaffected
+  - Works with deeply nested paths: `only = ["nvim/lua/plugins/init.lua"]`
+  - Fix DirectoryDiffer to use bidirectional_include? for proper file traversal
+
+**Documentation:**
+- Completely rewrite 'force', 'only', and 'ignore' options section in README
+- Add 4 detailed examples showing different use cases
+- Add warnings and notes about combining options
+- Document important behaviors and edge cases
+
+**Testing:**
+- Add comprehensive test coverage for file-specific paths in 'only' option
+- Add tests for FileTransfer with nested file paths
+- Add tests for DirectoryDiffer with file-specific only paths
+- Add tests with force mode enabled
+- All 396 tests pass with 96.61% line coverage
+
+# 0.1.24
+
+**Performance Optimizations:**
+- Implement lazy loading to defer library loading until after argument parsing
+  - Reduces `--version` and `--help` startup time from ~900ms to ~380ms (2.4x faster)
+  - Full library only loaded when executing actual commands
+- Add action-specific loaders to reduce memory footprint
+  - Each command loads only its required dependencies
+  - Push/pull skip loading 'listen' gem (only needed for watch)
+  - Watch skips terminal-table and diff logic
+  - Setup uses minimal dependencies for near-instant execution
+- Add config caching with XDG_DATA_HOME integration
+  - Caches parsed TOML as Marshal binary (~180x faster to load)
+  - Automatic cache invalidation based on mtime, size, and version
+  - Graceful fallback to TOML parsing on errors
+  - Disable with `DOTSYNC_NO_CACHE=1` environment variable
+  - Saves ~14ms per invocation on typical configs
+
+**Combined Performance Impact:**
+- `--version`: 900ms → 380ms (2.4x faster)
+- `--help`: 900ms → 380ms (2.4x faster)
+- Setup: Near-instant with minimal loading
+- Push/pull: ~15% faster with cached config
+- Watch: ~40% faster without unnecessary dependencies
+
 # 0.1.23
 
 **Critical Bug Fix:**

data/Gemfile.lock

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

data/README.md

@@ -264,16 +264,107 @@ dest = "$DOTFILES_DIR/config/alacritty"
 
 Each mapping entry supports the following options:
 
-- **`force`**: A boolean (true/false) value. When set to `true`, it forces deletion of the destination folder before transferring files from the source. This is particularly useful when you need to ensure that the destination is clean before a transfer.
-- **`only`**: An array of files or folders. This option ensures that only the specified files or folders from the `src` directory are transferred to the `dest` directory. Example:
-  ```toml
-  [[push.mappings]]
-  src = "$XDG_CONFIG_HOME"
-  dest = "$DOTFILES_DIR/config"
-  only = ["config.yml", "themes"]
+##### `force` Option
 
-  ```
-- **`ignore`**: An array of patterns or file names to exclude during the transfer. This allows you to specify files or folders that should not be copied from the source to the destination.
+A boolean (true/false) value. When set to `true`, it forces deletion of files in the destination directory that don't exist in the source. This is particularly useful when you need to ensure the destination stays synchronized with the source.
+
+**Example:**
+```toml
+[[pull.mappings]]
+src = "$XDG_CONFIG_HOME_MIRROR/nvim"
+dest = "$XDG_CONFIG_HOME/nvim"
+force = true
+ignore = ["lazy-lock.json"]
+```
+
+> [!WARNING]
+> When using `force = true` with the `only` option, only files matching the `only` filter will be managed. Other files in the destination remain untouched.
+
+##### `only` Option
+
+An array of relative paths (files or directories) to selectively transfer from the source. This option provides precise control over which files get synchronized.
+
+**How it works:**
+- Paths are relative to the `src` directory
+- You can specify entire directories or individual files
+- Parent directories are automatically created as needed
+- Other files in the source are ignored
+- With `force = true`, only files matching the `only` filter are cleaned up in the destination
+
+**Example 1: Selecting specific directories**
+```toml
+[[push.mappings]]
+src = "$XDG_CONFIG_HOME"
+dest = "$DOTFILES_DIR/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"
+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"
+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  
+- `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"
+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.
+
+**Important behaviors:**
+- **File-specific paths**: When specifying individual files (e.g., `"bundle/config"`), only that file is managed. Sibling files in the same directory are not affected, even with `force = true`.
+- **Directory paths**: When specifying directories (e.g., `"nvim"`), all contents of that directory are managed, including subdirectories.
+- **Combining with `force`**: With `force = true` and directory paths, files in the destination directory that don't exist in the source are removed. With file-specific paths, only that specific file is managed.
+
+##### `ignore` Option
+
+An array of relative paths or patterns to exclude during transfer. This allows you to skip certain files or folders.
+
+**Example:**
+```toml
+[[pull.mappings]]
+src = "$XDG_CONFIG_HOME_MIRROR/nvim"
+dest = "$XDG_CONFIG_HOME/nvim"
+ignore = ["lazy-lock.json", "plugin/packer_compiled.lua"]
+```
+
+**Combining options:**
+```toml
+[[push.mappings]]
+src = "$XDG_CONFIG_HOME/nvim"
+dest = "$DOTFILES_DIR/config/nvim"
+only = ["lua", "init.lua"]
+ignore = ["lua/plugin/packer_compiled.lua"]
+force = true
+```
+This configuration:
+1. Transfers only the `lua/` directory and `init.lua` file (`only`)
+2. Excludes `lua/plugin/packer_compiled.lua` even though it's in the `lua/` directory (`ignore`)
+3. Removes files in the destination that don't exist in the source (`force`)
+
+> [!NOTE]
+> When `ignore` and `only` both match a path, `ignore` takes precedence.
 
 These options apply when the source is a directory and are relevant for both `push` and `pull` operations.
 

data/exe/dotsync

@@ -1,11 +1,15 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative "../lib/dotsync"
 require "optparse"
+require_relative "../lib/dotsync/version"
 
 options = { apply: false, config_path: nil }
 
+# Initialize logger early for consistent error handling
+require_relative "../lib/dotsync/core"
+logger = Dotsync::Logger.new
+
 opt_parser = OptionParser.new do |opts|
   opts.banner = <<~BANNER
     dotsync #{Dotsync::VERSION}
@@ -30,6 +34,7 @@ opt_parser = OptionParser.new do |opts|
       dotsync diff                       # Show what would change
       dotsync watch                      # Monitor and sync continuously
       dotsync -c ~/custom.toml push      # Use custom config file
+      dotsync push --trace               # Show full error backtraces
 
     Options:
       -a, --apply           Apply changes (push or pull)
@@ -46,6 +51,7 @@ opt_parser = OptionParser.new do |opts|
       --only-config         Show only the config section
       --only-mappings       Show only the mappings section
       -v, --verbose         Force showing all available information
+      --trace               Show full error backtraces (for debugging)
       --version             Show version number
       -h, --help            Show this help message
   BANNER
@@ -106,6 +112,10 @@ opt_parser = OptionParser.new do |opts|
     options[:verbose] = true
   end
 
+  opts.on("--trace", "Show full error backtraces (for debugging)") do
+    options[:trace] = true
+  end
+
   opts.on("--version", "Show version number") do
     puts "dotsync #{Dotsync::VERSION}"
     exit
@@ -117,20 +127,43 @@ opt_parser = OptionParser.new do |opts|
   end
 end
 
-opt_parser.parse!
+begin
+  opt_parser.parse!
+rescue OptionParser::InvalidOption, OptionParser::InvalidArgument => e
+  # Extract just the problematic option from the error message
+  option_match = e.message.match(/invalid (?:option|argument): (.+)/)
+  problem = option_match ? option_match[1] : e.message
+
+  logger.error("Invalid option: #{problem}")
+  logger.info("See 'dotsync --help' for available options")
+
+  if options[:trace]
+    logger.log("\nFull backtrace:", color: 240)
+    e.backtrace.each { |line| logger.log("  #{line}", color: 240) }
+  end
+
+  exit 1
+end
 
 command = ARGV.shift
 
-case command
+# Load only the dependencies needed for the specific command
+begin
+  case command
 when "push"
+  require_relative "../lib/dotsync/loaders/push_loader"
   Dotsync::Runner.new(config_path: options[:config_path]).run(:push, options)
 when "pull"
+  require_relative "../lib/dotsync/loaders/pull_loader"
   Dotsync::Runner.new(config_path: options[:config_path]).run(:pull, options)
 when "watch"
+  require_relative "../lib/dotsync/loaders/watch_loader"
   Dotsync::Runner.new(config_path: options[:config_path]).run(:watch, options)
 when "setup", "init"
+  require_relative "../lib/dotsync/loaders/setup_loader"
   Dotsync::Runner.new(config_path: options[:config_path]).run(:setup)
 when "status"
+  require_relative "../lib/dotsync/loaders/push_loader"
   # Show config and mappings without executing any action
   # Use push action with only-config and only-mappings to display info
   status_options = options.merge(
@@ -141,14 +174,28 @@ when "status"
   )
   Dotsync::Runner.new(config_path: options[:config_path]).run(:push, status_options)
 when "diff"
+  require_relative "../lib/dotsync/loaders/push_loader"
   # Alias for push in preview mode (default behavior)
   diff_options = options.merge(apply: false)
   Dotsync::Runner.new(config_path: options[:config_path]).run(:push, diff_options)
 else
   if command
-    puts "dotsync: no such command '#{command}'"
+    logger.error("Unknown command: '#{command}'")
+    logger.info("See 'dotsync --help' for available commands")
   else
     puts opt_parser.banner
   end
   exit 1
+  end
+rescue => e
+  logger.error("Unexpected error: #{e.message}")
+
+  if options[:trace]
+    logger.log("\nFull backtrace:", color: 240)
+    e.backtrace.each { |line| logger.log("  #{line}", color: 240) }
+  else
+    logger.info("Run with --trace to see full error details")
+  end
+
+  exit 1
 end

data/lib/dotsync/config/base_config.rb

@@ -8,6 +8,7 @@ module Dotsync
 
     # Initialize the BaseConfig with the provided path.
     # Loads the TOML configuration file and validates it.
+    # Uses ConfigCache for improved performance.
     #
     # @param [String] path The file path to the configuration file.
     def initialize(path = Dotsync.config_path)
@@ -20,7 +21,7 @@ module Dotsync
           "  dotsync setup"
       end
 
-      @config = TomlRB.load_file(absolute_path)
+      @config = load_config(absolute_path)
       validate!
     end
 
@@ -29,6 +30,15 @@ module Dotsync
     end
 
     private
+      # Loads configuration from file, using cache when possible
+      #
+      # @param [String] path The file path to the configuration file.
+      # @return [Hash] The parsed configuration
+      def load_config(path)
+        require_relative "../utils/config_cache"
+        ConfigCache.new(path).load
+      end
+
       # Validates the configuration file.
       #
       # @raise [NotImplementedError] if not implemented by a subclass.

data/lib/dotsync/core.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Core dependencies needed by all actions
+require "fileutils"
+require "logger"
+require "forwardable"
+require "ostruct"
+require "find"
+
+# Base classes and utilities
+require_relative "errors"
+require_relative "icons"
+require_relative "colors"
+require_relative "version"
+
+# Config Concerns (loaded early as they're used by other modules)
+require_relative "config/concerns/xdg_base_directory"
+
+# Utils (common utilities)
+require_relative "utils/path_utils"
+require_relative "utils/logger"
+require_relative "utils/version_checker"
+
+# Runner
+require_relative "runner"
+
+module Dotsync
+  class << self
+    attr_writer :config_path
+
+    def config_path
+      @config_path ||= ENV["DOTSYNC_CONFIG"] || "~/.config/dotsync.toml"
+    end
+  end
+end

data/lib/dotsync/loaders/pull_loader.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Load core dependencies
+require_relative "../core"
+
+# Gems needed for pull
+require "toml-rb"
+require "terminal-table"
+
+# Utils needed for pull
+require_relative "../utils/file_transfer"
+require_relative "../utils/directory_differ"
+require_relative "../utils/config_cache"
+
+# Models
+require_relative "../models/mapping"
+require_relative "../models/diff"
+
+# Config
+require_relative "../config/base_config"
+require_relative "../config/pull_action_config"
+
+# Actions Concerns
+require_relative "../actions/concerns/mappings_transfer"
+require_relative "../actions/concerns/output_sections"
+
+# Actions
+require_relative "../actions/base_action"
+require_relative "../actions/pull_action"

data/lib/dotsync/loaders/push_loader.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Load core dependencies
+require_relative "../core"
+
+# Gems needed for push
+require "toml-rb"
+require "terminal-table"
+
+# Utils needed for push
+require_relative "../utils/file_transfer"
+require_relative "../utils/directory_differ"
+require_relative "../utils/config_cache"
+
+# Models
+require_relative "../models/mapping"
+require_relative "../models/diff"
+
+# Config
+require_relative "../config/base_config"
+require_relative "../config/push_action_config"
+
+# Actions Concerns
+require_relative "../actions/concerns/mappings_transfer"
+require_relative "../actions/concerns/output_sections"
+
+# Actions
+require_relative "../actions/base_action"
+require_relative "../actions/push_action"

data/lib/dotsync/loaders/setup_loader.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Setup only needs minimal dependencies
+require "toml-rb"
+require "fileutils"
+
+# Load only what's needed
+require_relative "../version"
+require_relative "../utils/logger"
+require_relative "../runner"
+
+module Dotsync
+  class << self
+    attr_writer :config_path
+
+    def config_path
+      @config_path ||= ENV["DOTSYNC_CONFIG"] || "~/.config/dotsync.toml"
+    end
+  end
+end

data/lib/dotsync/loaders/watch_loader.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Load core dependencies
+require_relative "../core"
+
+# Gems needed for watch (includes listen)
+require "listen"
+require "toml-rb"
+
+# Utils needed for watch
+require_relative "../utils/file_transfer"
+require_relative "../utils/config_cache"
+
+# Models
+require_relative "../models/mapping"
+
+# Config
+require_relative "../config/base_config"
+require_relative "../config/watch_action_config"
+
+# Actions Concerns
+require_relative "../actions/concerns/mappings_transfer"
+
+# Actions
+require_relative "../actions/base_action"
+require_relative "../actions/watch_action"

data/lib/dotsync/utils/config_cache.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module Dotsync
+  class ConfigCache
+    include Dotsync::XDGBaseDirectory
+
+    def initialize(config_path)
+      @config_path = File.expand_path(config_path)
+      @cache_dir = File.join(xdg_data_home, "dotsync", "config_cache")
+
+      # Use hash of real path for cache filename to support multiple configs
+      cache_key = Digest::SHA256.hexdigest(File.realpath(@config_path))
+      @cache_file = File.join(@cache_dir, "#{cache_key}.cache")
+      @meta_file = File.join(@cache_dir, "#{cache_key}.meta")
+    end
+
+    def load
+      # Skip cache if disabled via environment variable
+      return parse_toml if ENV["DOTSYNC_NO_CACHE"]
+
+      return parse_and_cache unless valid_cache?
+
+      # Fast path: load from cache
+      Marshal.load(File.binread(@cache_file))
+    rescue StandardError
+      # Fallback: reparse if cache corrupted or any error
+      parse_and_cache
+    end
+
+    private
+      def valid_cache?
+        return false unless File.exist?(@cache_file)
+        return false unless File.exist?(@meta_file)
+
+        meta = JSON.parse(File.read(@meta_file))
+        source_stat = File.stat(@config_path)
+
+        # Quick validation checks
+        return false if source_stat.mtime.to_f != meta["source_mtime"]
+        return false if source_stat.size != meta["source_size"]
+        return false if Dotsync::VERSION != meta["dotsync_version"]
+
+        # Age check (invalidate cache older than 7 days for safety)
+        cache_age_days = (Time.now.to_f - meta["cached_at"]) / 86400
+        return false if cache_age_days > 7
+
+        true
+      rescue StandardError
+        # Any error in validation means invalid cache
+        false
+      end
+
+      def parse_and_cache
+        config = parse_toml
+
+        # Write cache files
+        FileUtils.mkdir_p(@cache_dir)
+        File.binwrite(@cache_file, Marshal.dump(config))
+        File.write(@meta_file, JSON.generate(build_metadata))
+
+        config
+      rescue StandardError
+        # If caching fails, still return the parsed config
+        config
+      end
+
+      def parse_toml
+        require "toml-rb"
+        TomlRB.load_file(@config_path)
+      end
+
+      def build_metadata
+        source_stat = File.stat(@config_path)
+        {
+          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
+        }
+      end
+  end
+end

data/lib/dotsync/utils/directory_differ.rb

@@ -36,7 +36,7 @@ module Dotsync
         Find.find(mapping_src) do |src_path|
           rel_path = src_path.sub(/^#{Regexp.escape(mapping_src)}\/?/, "")
 
-          unless @mapping.include?(src_path)
+          unless @mapping.bidirectional_include?(src_path)
             Find.prune
             next
           end

data/lib/dotsync/version.rb

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

data/lib/dotsync.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Full library load for backward compatibility
+# For optimized loading, use specific loaders in lib/dotsync/loaders/
+
 # Libs dependencies
 require "fileutils"
 require "listen"
@@ -26,6 +29,7 @@ require_relative "dotsync/utils/logger"
 require_relative "dotsync/utils/file_transfer"
 require_relative "dotsync/utils/directory_differ"
 require_relative "dotsync/utils/version_checker"
+require_relative "dotsync/utils/config_cache"
 
 # Models
 require_relative "dotsync/models/mapping"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dotsync
 version: !ruby/object:Gem::Version
-  version: 0.1.23
+  version: 0.1.25
 platform: ruby
 authors:
 - David Sáenz
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-15 00:00:00.000000000 Z
+date: 2025-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: toml-rb
@@ -321,12 +321,18 @@ files:
 - lib/dotsync/config/pull_action_config.rb
 - lib/dotsync/config/push_action_config.rb
 - lib/dotsync/config/watch_action_config.rb
+- lib/dotsync/core.rb
 - lib/dotsync/errors.rb
 - lib/dotsync/icons.rb
+- lib/dotsync/loaders/pull_loader.rb
+- lib/dotsync/loaders/push_loader.rb
+- lib/dotsync/loaders/setup_loader.rb
+- lib/dotsync/loaders/watch_loader.rb
 - lib/dotsync/models/diff.rb
 - lib/dotsync/models/mapping.rb
 - lib/dotsync/runner.rb
 - lib/dotsync/tasks/actions.rake
+- lib/dotsync/utils/config_cache.rb
 - lib/dotsync/utils/directory_differ.rb
 - lib/dotsync/utils/file_transfer.rb
 - lib/dotsync/utils/logger.rb