mirrorfile 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b29787fe3ec7d699137a8bc8f02dbfafd0ac95693dece15bf7199c977d3aa0e
-  data.tar.gz: df9541b78b01255029986e18f3144294f4e60b436b8d928c7e8ff8937177cadc
+  metadata.gz: 513175ce2e6de6e4e0a0a810d844ce5a280fd3e899cf490b289249054a8c37f9
+  data.tar.gz: 9a8ca82bdd368ef020c97fbf156aba1e5d3cad6860e5eef4e02226165c167277
 SHA512:
-  metadata.gz: b3fd0d4747c159d0cf957012a7ba997b0dfc062278ef5d3b0b0bd823e23e96df11d78ebd863a1dbfe91beabac0a8e1a207e84cdbca662c0d2fa70a2ef5706172
-  data.tar.gz: b0fea1083d5ec020119d35d775d19545662223110306e0ac6ce87598c80bc190a952dcb4113ed7f056845b0074651097b17add026c7743f90cbdc23ac1b1895c
+  metadata.gz: 0046b1bde5286137d682244bf597e8f72a0d43a206c6013b4dc470b08b9dead8ebbe0d7aa390c63437330b9ccf15c93dbefc99ca8e5a0bd346606166232f38b9
+  data.tar.gz: fa70c541f5cdaa6e17c2a654bf07a094cb2037a405409a9fda00fe8f7d725331cb6b66737915fe1df8b39a2f7c8bdbe4bcd887a1a536fd7c1420fa8bcbbdd971

data/.envrc

@@ -0,0 +1 @@
+use flake

data/README.md

@@ -22,7 +22,7 @@ gem install mirrorfile
 
 ## Usage
 ```bash
-mirror init      # creates Mirrorfile, .gitignore entry, zeitwerk initializer
+mirror init      # creates Mirrorfile, .gitignore entry, zeitwerk initializer (Rails only)
 mirror install   # clones missing repos
 mirror update    # pulls existing repos
 mirror list      # shows defined mirrors

data/flake.lock

@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1772773019,
+        "narHash": "sha256-E1bxHxNKfDoQUuvriG71+f+s/NT0qWkImXsYZNFFfCs=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "aca4d95fce4914b3892661bcb80b8087293536c6",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/flake.nix

@@ -0,0 +1,34 @@
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+
+    flake-utils.url = "github:numtide/flake-utils";
+    flake-utils.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          packages = with pkgs; [
+            ruby_3_4
+            bundler
+          ];
+
+          shellHook = ''
+            export BUNDLE_PATH=".bundler"
+            export GEM_PATH=".bundler/ruby/3.4.0"
+
+            export PATH="$PWD/bin:$PATH"
+            export PATH=".bundler/ruby/3.4.0/bin:$PATH"
+          '';
+
+        };
+
+        packages.default = pkgs.hello;
+      }
+    );
+}

data/lib/mirrorfile/cli.rb

@@ -21,7 +21,7 @@ module Mirrorfile
   class CLI
     # Available CLI commands
     # @return [Array<String>] list of valid commands
-    COMMANDS = %w[init install update list help].freeze
+    COMMANDS = %w[init install update list git help].freeze
 
     # Creates a new CLI instance.
     #
@@ -48,15 +48,33 @@ module Mirrorfile
     def call(args)
       command = args.first
 
+      if legacy_command?(command) && Mirror.new.legacy?
+        return CLILegacy.new(stdout: @stdout, stderr: @stderr).call(args)
+      end
+
+      dispatch(args)
+    end
+
+    # Dispatches args to the appropriate command method.
+    #
+    # Separated from {#call} so that {CLILegacy} can dispatch
+    # without re-checking legacy state.
+    #
+    # @param args [Array<String>] command-line arguments
+    # @return [Integer] exit status code
+    def dispatch(args)
+      command = args.first
+
       case command
-      when "init"    then init
-      when "install" then install
-      when "update"  then update
-      when "list"    then list
-      when "help"    then help
-      when "-h", "--help" then help
-      when "-v", "--version" then version
-      else                usage
+      when 'init'    then init
+      when 'install' then install
+      when 'update'  then update
+      when 'list'    then list
+      when 'git'     then git(args.drop(1))
+      when 'help'    then help
+      when '-h', '--help' then help
+      when '-v', '--version' then version
+      else usage
       end
 
       0
@@ -65,12 +83,25 @@ module Mirrorfile
       1
     rescue StandardError => e
       @stderr.puts "Error: #{e.message}"
-      @stderr.puts e.backtrace.first(5).map { "  #{_1}" } if ENV["DEBUG"]
+      @stderr.puts(e.backtrace.first(5).map { "  #{_1}" }) if ENV['DEBUG']
       1
     end
 
     private
 
+    # Returns whether the given command should use legacy mode
+    # when legacy mirrors are detected.
+    #
+    # Commands like init, help, and version flags are not affected
+    # by legacy state and always use the standard CLI.
+    #
+    # @param command [String, nil] the command name
+    # @return [Boolean]
+    # @api private
+    def legacy_command?(command)
+      %w[install update list git].include?(command)
+    end
+
     # Executes the init command.
     #
     # @return [void]
@@ -84,9 +115,9 @@ module Mirrorfile
     # @return [void]
     # @api private
     def install
-      @stdout.puts "Installing mirrors..."
+      @stdout.puts 'Installing mirrors...'
       Mirror.new.install
-      @stdout.puts "Done."
+      @stdout.puts 'Done.'
     end
 
     # Executes the update command.
@@ -94,9 +125,9 @@ module Mirrorfile
     # @return [void]
     # @api private
     def update
-      @stdout.puts "Updating mirrors..."
+      @stdout.puts 'Updating mirrors...'
       Mirror.new.update
-      @stdout.puts "Done."
+      @stdout.puts 'Done.'
     end
 
     # Executes the list command.
@@ -106,7 +137,19 @@ module Mirrorfile
     def list
       entries = Mirror.new.list
 
-      entries.empty? ? @stdout.puts("No mirrors defined.") : entries.each { @stdout.puts _1 }
+      entries.empty? ? @stdout.puts('No mirrors defined.') : entries.each { @stdout.puts _1 }
+    end
+
+    # Executes a git command against a .git.mirror directory.
+    #
+    # Runs git with --git-dir=.git.mirror in the current working
+    # directory, passing through all additional arguments.
+    #
+    # @param args [Array<String>] arguments to pass to git
+    # @return [void]
+    # @api private
+    def git(args)
+      system('git', '--git-dir=.git.mirror', *args)
     end
 
     # Displays help information.
@@ -125,6 +168,7 @@ module Mirrorfile
           install   Clone repositories that don't exist locally
           update    Pull latest changes for existing repositories
           list      Show all defined mirrors
+          git       Run git commands against a .git.mirror directory
           help      Show this help message
 
         Options:
@@ -135,6 +179,7 @@ module Mirrorfile
           $ mirror init
           $ mirror install
           $ mirror update
+          $ cd mirrors/rails && mirror git log --oneline
 
         Mirrorfile syntax:
           source "https://github.com"
@@ -155,7 +200,7 @@ module Mirrorfile
     # @return [void]
     # @api private
     def version
-      @stdout.puts "mirrorfile #{Mirrorfile::VERSION}"
+      @stdout.puts "mirrorfile #{::Mirrorfile::VERSION}"
     end
 
     # Displays usage information for unknown commands.
@@ -167,10 +212,11 @@ module Mirrorfile
         Usage: mirror <command>
 
         Commands:
-          init      Create Mirrorfile, .gitignore entry, and Zeitwerk initializer
+          init      Create Mirrorfile, .gitignore entry, and Zeitwerk initializer (Rails only)
           install   Clone repositories that don't exist locally
           update    Pull latest changes for existing repositories
           list      Show all defined mirrors
+          git       Run git commands against a .git.mirror directory
           help      Show detailed help
 
         Run 'mirror help' for more information.

data/lib/mirrorfile/cli_legacy.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Mirrorfile
+  # Legacy CLI for projects with old-style .git directories.
+  #
+  # This CLI is used automatically when mirrorfile detects that the
+  # mirrors directory contains repositories with .git instead of
+  # .git.mirror. It prints a deprecation warning and operates using
+  # the legacy .git directory name.
+  #
+  # @see CLI
+  # @since 1.0.0
+  class CLILegacy < CLI
+    LEGACY_WARNING = <<~WARN
+      [mirrorfile] WARNING: Your mirrors use legacy .git directories.
+      Upgrade with mirrorfile v0.1.1 (`mirror migrate-to-v1`), or remove
+      the mirrors/ directory and re-run `mirror install`.
+    WARN
+
+    # Overrides CLI#call to skip legacy detection and dispatch directly.
+    #
+    # @param args [Array<String>] command-line arguments
+    # @return [Integer] exit status code
+    def call(args)
+      dispatch(args)
+    end
+
+    private
+
+    # Executes the install command in legacy mode.
+    #
+    # @return [void]
+    # @api private
+    def install
+      @stderr.puts LEGACY_WARNING
+      @stdout.puts 'Installing mirrors (legacy mode)...'
+      Mirror.new.install(legacy: true)
+      @stdout.puts 'Done.'
+    end
+
+    # Executes the update command in legacy mode.
+    #
+    # @return [void]
+    # @api private
+    def update
+      @stderr.puts LEGACY_WARNING
+      @stdout.puts 'Updating mirrors (legacy mode)...'
+      Mirror.new.update(legacy: true)
+      @stdout.puts 'Done.'
+    end
+
+    # Executes the list command with a legacy warning.
+    #
+    # @return [void]
+    # @api private
+    def list
+      @stderr.puts LEGACY_WARNING
+      super
+    end
+
+    # Executes a git command using the default .git directory.
+    #
+    # In legacy mode, mirrors have .git (not .git.mirror), so
+    # no --git-dir flag is needed.
+    #
+    # @param args [Array<String>] arguments to pass to git
+    # @return [void]
+    # @api private
+    def git(args)
+      @stderr.puts LEGACY_WARNING
+      system('git', *args)
+    end
+  end
+end

data/lib/mirrorfile/entry.rb

@@ -41,7 +41,13 @@ module Mirrorfile
     # clone the repository once. If the local directory already exists,
     # no action is taken.
     #
+    # After cloning, the .git directory is renamed to the configured
+    # git_dir name (default: .git.mirror) so that the host project's
+    # git does not treat it as a nested repository.
+    #
     # @param base_dir [Pathname] the base directory to clone into
+    # @param git_dir [String] the git directory name to use
+    #   (default: ".git.mirror", use ".git" for legacy mode)
     # @return [Boolean, nil] true if clone succeeded, false if failed,
     #   nil if already exists
     #
@@ -49,9 +55,15 @@ module Mirrorfile
     #   entry.install(Pathname.new("mirrors"))
     #
     # @see #update
-    def install(base_dir)
+    def install(base_dir, git_dir: '.git.mirror')
       dir = local_path(base_dir)
-      system("git", "clone", url, dir.to_s) unless dir.exist?
+      return if dir.exist?
+
+      return unless system('git', 'clone', url, dir.to_s)
+
+      return unless git_dir != '.git'
+
+      File.rename(dir.join('.git').to_s, dir.join(git_dir).to_s)
     end
 
     # Updates an existing repository by pulling the latest changes.
@@ -60,6 +72,8 @@ module Mirrorfile
     # If the local directory doesn't exist, no action is taken.
     #
     # @param base_dir [Pathname] the base directory containing the clone
+    # @param git_dir [String] the git directory name to use
+    #   (default: ".git.mirror", use ".git" for legacy mode)
     # @return [Boolean, nil] true if pull succeeded, false if failed,
     #   nil if directory doesn't exist
     #
@@ -67,9 +81,12 @@ module Mirrorfile
     #   entry.update(Pathname.new("mirrors"))
     #
     # @see #install
-    def update(base_dir)
+    def update(base_dir, git_dir: '.git.mirror')
       dir = local_path(base_dir)
-      system("git", "-C", dir.to_s, "pull", "--ff-only") if dir.exist?
+      return unless dir.exist?
+
+      system('git', '--git-dir', dir.join(git_dir).to_s,
+             '--work-tree', dir.to_s, 'pull', '--ff-only')
     end
 
     # Returns a human-readable representation of the entry.

data/lib/mirrorfile/mirror.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+
 module Mirrorfile
   # Orchestrates mirror operations: init, install, and update.
   #
@@ -46,10 +48,10 @@ module Mirrorfile
     #   mirror = Mirrorfile::Mirror.new(root: "/path/to/project")
     def initialize(root: Dir.pwd)
       @root = Pathname.new(root)
-      @mirrors_dir = @root.join("mirrors")
-      @gitignore_path = @root.join(".gitignore")
-      @mirrorfile_path = @root.join("Mirrorfile")
-      @initializer_path = @root.join("config/initializers/mirrors.rb")
+      @mirrors_dir = @root.join('mirrors')
+      @gitignore_path = @root.join('.gitignore')
+      @mirrorfile_path = @root.join('Mirrorfile')
+      @initializer_path = @root.join('config/initializers/mirrors.rb')
       @mirrorfile = load_mirrorfile if @mirrorfile_path.exist?
     end
 
@@ -66,10 +68,11 @@ module Mirrorfile
     #   mirror.install
     #
     # @see Entry#install
-    def install
+    def install(legacy: false)
       ensure_mirrorfile!
       mirrors_dir.mkpath
-      @mirrorfile.entries.each { _1.install(mirrors_dir) }
+      git_dir = legacy ? '.git' : '.git.mirror'
+      @mirrorfile.entries.each { _1.install(mirrors_dir, git_dir: git_dir) }
     end
 
     # Updates all existing local repositories.
@@ -86,9 +89,10 @@ module Mirrorfile
     #   mirror.update
     #
     # @see Entry#update
-    def update
+    def update(legacy: false)
       ensure_mirrorfile!
-      @mirrorfile.entries.each { _1.update(mirrors_dir) }
+      git_dir = legacy ? '.git' : '.git.mirror'
+      @mirrorfile.entries.each { _1.update(mirrors_dir, git_dir: git_dir) }
     end
 
     # Initializes a new project with mirror support.
@@ -98,7 +102,7 @@ module Mirrorfile
     #
     # - Creates a Mirrorfile with example syntax
     # - Adds /mirrors to .gitignore (creates file if needed)
-    # - Creates a Rails initializer for Zeitwerk autoloading
+    # - Creates a Rails initializer for Zeitwerk autoloading (Rails projects only)
     #
     # Existing files are not overwritten.
     #
@@ -115,6 +119,7 @@ module Mirrorfile
     def init
       create_mirrorfile
       setup_gitignore
+      setup_templates
       setup_zeitwerk
       puts "Initialized mirrors in #{root}"
     end
@@ -131,6 +136,20 @@ module Mirrorfile
       @mirrorfile.entries.to_a
     end
 
+    # Returns whether any mirrors use legacy .git directories.
+    #
+    # A project is considered legacy if any subdirectory of mirrors/
+    # contains a .git directory without a .git.mirror sibling.
+    #
+    # @return [Boolean] true if legacy mirrors are detected
+    def legacy?
+      return false unless mirrors_dir.exist?
+
+      mirrors_dir.children.select(&:directory?).any? do |path|
+        path.join('.git').exist? && !path.join('.git.mirror').exist?
+      end
+    end
+
     private
 
     # Loads and parses the Mirrorfile.
@@ -195,10 +214,10 @@ module Mirrorfile
     # @return [Integer, nil] bytes written or nil if already ignored
     # @api private
     def setup_gitignore
-      gitignore_path.exist? || gitignore_path.write("")
+      gitignore_path.exist? || gitignore_path.write('')
 
       lines = gitignore_path.readlines.map(&:chomp)
-      lines.include?("/mirrors") || gitignore_path.write([*lines, "/mirrors"].join("\n") + "\n")
+      lines.include?('/mirrors') || gitignore_path.write([*lines, '/mirrors'].join("\n") + "\n")
     end
 
     # Creates a Rails initializer for Zeitwerk autoloading.
@@ -211,6 +230,8 @@ module Mirrorfile
     # @return [Integer, nil] bytes written or nil if file exists
     # @api private
     def setup_zeitwerk
+      return unless rails_project?
+
       initializer_path.dirname.mkpath
       initializer_path.exist? || initializer_path.write(<<~RUBY)
         # frozen_string_literal: true
@@ -231,5 +252,34 @@ module Mirrorfile
         end
       RUBY
     end
+
+    # Copies template files into the mirrors directory.
+    #
+    # Creates the mirrors directory if it doesn't exist, then copies
+    # envrc.template and README.md.template from the gem's
+    # templates directory. Existing files are not overwritten.
+    #
+    # @return [void]
+    # @api private
+    def setup_templates
+      mirrors_dir.mkpath
+
+      templates_dir = Pathname.new(__dir__).join('../../templates')
+
+      envrc_dest = mirrors_dir.join('.envrc')
+      envrc_dest.exist? || FileUtils.cp(templates_dir.join('envrc.template'), envrc_dest)
+
+      readme_dest = mirrors_dir.join('README.md')
+      readme_dest.exist? || FileUtils.cp(templates_dir.join('README.md.template'), readme_dest)
+    end
+
+    # Determines if the current project is a Rails application by checking
+    # for the standard Rails application entrypoint.
+    #
+    # @return [Boolean] true if Rails project structure is detected
+    # @api private
+    def rails_project?
+      root.join('config/application.rb').exist?
+    end
   end
 end

data/lib/mirrorfile/version.rb

@@ -3,5 +3,5 @@
 module Mirrorfile
   # Current version of the Mirrorfile gem
   # @return [String] the semantic version string
-  VERSION = "0.1.0"
+  VERSION = '1.0.0'
 end

data/lib/mirrorfile.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require "pathname"
+require 'pathname'
 
-require_relative "mirrorfile/version"
-require_relative "mirrorfile/entry"
-require_relative "mirrorfile/mirrorfile"
-require_relative "mirrorfile/mirror"
-require_relative "mirrorfile/cli"
+require_relative 'mirrorfile/version'
+require_relative 'mirrorfile/entry'
+require_relative 'mirrorfile/mirrorfile'
+require_relative 'mirrorfile/mirror'
+require_relative 'mirrorfile/cli'
+require_relative 'mirrorfile/cli_legacy'
 
 # Mirrorfile is a gem for managing local mirrors of git repositories.
 #
@@ -49,14 +50,14 @@ module Mirrorfile
     #
     # @return [Pathname] path to the mirrors directory
     def mirrors_dir
-      root.join("mirrors")
+      root.join('mirrors')
     end
 
     # Returns the path to the Mirrorfile
     #
     # @return [Pathname] path to the Mirrorfile
     def mirrorfile_path
-      root.join("Mirrorfile")
+      root.join('Mirrorfile')
     end
   end
 end

data/templates/README.md.template

@@ -0,0 +1,21 @@
+# Mirrors
+
+This directory contains mirrored git repositories managed by mirrorfile.
+
+## Working with git in mirrored repos
+
+The `.git` directory in each mirrored repository is renamed to `.git.mirror`
+to prevent the parent project from detecting them as submodules.
+
+To run git commands within a mirror, use:
+
+    mirror git <command>
+
+For example:
+
+    mirror git status
+    mirror git log --oneline
+
+Alternatively, if you have [direnv](https://direnv.net/) installed, `cd` into
+a mirror directory and the `.envrc` file will automatically set
+`GIT_DIR=.git.mirror`, allowing you to use `git` commands directly.

data/templates/envrc.template

@@ -0,0 +1,24 @@
+# vim: set filetype=bash :
+#
+# This file can be utilised if `direnv` is installed.
+# Alternatively, run the following helper:
+#
+#   $ mirror git <any-git-command>
+#
+#   $ mirror git status
+#   $ mirror git add .
+#   $ mirror git commit -m "example commit message"
+#
+# Direnv related resources:
+#   Docs - https://direnv.net/
+#   Packages - https://github.com/direnv
+#   Git - https://github.com/direnv/direnv
+#
+# This is needed because mirrorfile renames the `.git` directory to `.git.mirror`.
+# This is essential to avoid issues with nested git repos that .gitignore can't solve.
+# An example would be wanting to run `git add --force ./mirrors/example-project/flake.nix`.
+# Unfortunately this doesn't work without removing the directory from .gitignore, which then means
+# you have a submodule in your repo.
+# By renaming the `.git` directory you avoid the parent repo detecting the folder as a submodule.
+
+export GIT_DIR=.git.mirror

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mirrorfile
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Nathan Kidd
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -77,19 +77,25 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".envrc"
 - ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - exe/mirror
+- flake.lock
+- flake.nix
 - lib/mirrorfile.rb
 - lib/mirrorfile/cli.rb
+- lib/mirrorfile/cli_legacy.rb
 - lib/mirrorfile/entry.rb
 - lib/mirrorfile/mirror.rb
 - lib/mirrorfile/mirrorfile.rb
 - lib/mirrorfile/version.rb
 - mirrorfile.gemspec
+- templates/README.md.template
+- templates/envrc.template
 homepage: https://github.com/n-at-han-k/mirrorfile
 licenses:
 - MIT
@@ -113,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Manage local mirrors of git repositories
 test_files: []