mirrorfile 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b29787fe3ec7d699137a8bc8f02dbfafd0ac95693dece15bf7199c977d3aa0e
-  data.tar.gz: df9541b78b01255029986e18f3144294f4e60b436b8d928c7e8ff8937177cadc
+  metadata.gz: de77b25cb4e899eb5e29e28c56864a7f592a917721333e7846f27143ce4e7fd1
+  data.tar.gz: e67318033257885299216cb91234ca51f53204224e6fd2a17d7e3cb86170b832
 SHA512:
-  metadata.gz: b3fd0d4747c159d0cf957012a7ba997b0dfc062278ef5d3b0b0bd823e23e96df11d78ebd863a1dbfe91beabac0a8e1a207e84cdbca662c0d2fa70a2ef5706172
-  data.tar.gz: b0fea1083d5ec020119d35d775d19545662223110306e0ac6ce87598c80bc190a952dcb4113ed7f056845b0074651097b17add026c7743f90cbdc23ac1b1895c
+  metadata.gz: 9f78685072b0bc631479c96d980a78a52f45e00d8ed9109937f9ead3a2de2e0fc1a48e5f85556630c7e7a22b5e160e1949b70c42d0513cbc91320c4626a33e16
+  data.tar.gz: f0c17c1fe5cfa8ac281bf61c0b0b7e0f1f9c518476444a49184087845ea355664f5f7f0613176710698455e34751212b3d6fc210fa84fd00dce9df74fba499e3

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,12 @@ 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 migrate-to-v1 help].freeze
+
+    # Deprecation warning shown on every command except migrate-to-v1
+    DEPRECATION_WARNING = <<~WARN.freeze
+      [mirrorfile] WARNING: v#{VERSION} is deprecated. Run `mirror migrate-to-v1` to upgrade to v1.0.
+    WARN
 
     # Creates a new CLI instance.
     #
@@ -48,15 +53,18 @@ module Mirrorfile
     def call(args)
       command = args.first
 
+      @stderr.puts DEPRECATION_WARNING unless command == 'migrate-to-v1'
+
       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 'migrate-to-v1'  then migrate_to_v1
+      when 'help'           then help
+      when '-h', '--help'   then help
+      when '-v', '--version' then version
+      else usage
       end
 
       0
@@ -65,7 +73,7 @@ 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
 
@@ -84,9 +92,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 +102,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 +114,15 @@ 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 the migrate-to-v1 command.
+    #
+    # @return [void]
+    # @api private
+    def migrate_to_v1
+      Mirror.new.migrate_to_v1
     end
 
     # Displays help information.
@@ -120,12 +136,13 @@ module Mirrorfile
         Usage: mirror <command>
 
         Commands:
-          init      Initialize project with Mirrorfile, .gitignore entry,
-                    and Zeitwerk initializer for Rails projects
-          install   Clone repositories that don't exist locally
-          update    Pull latest changes for existing repositories
-          list      Show all defined mirrors
-          help      Show this help message
+          init           Initialize project with Mirrorfile, .gitignore entry,
+                         and Zeitwerk initializer for Rails projects
+          install        Clone repositories that don't exist locally
+          update         Pull latest changes for existing repositories
+          list           Show all defined mirrors
+          migrate-to-v1  Upgrade to mirrorfile v1.0
+          help           Show this help message
 
         Options:
           -h, --help     Show this help message
@@ -155,7 +172,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,11 +184,12 @@ module Mirrorfile
         Usage: mirror <command>
 
         Commands:
-          init      Create Mirrorfile, .gitignore entry, and Zeitwerk initializer
-          install   Clone repositories that don't exist locally
-          update    Pull latest changes for existing repositories
-          list      Show all defined mirrors
-          help      Show detailed help
+          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
+          migrate-to-v1  Upgrade to mirrorfile v1.0
+          help           Show detailed help
 
         Run 'mirror help' for more information.
       USAGE

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
 
@@ -98,7 +100,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.
     #
@@ -131,6 +133,23 @@ module Mirrorfile
       @mirrorfile.entries.to_a
     end
 
+    # Migrates the project to mirrorfile v1.0.
+    #
+    # Performs the following steps:
+    # - Updates Gemfile version constraint to ~> 1.0 (if Gemfile exists)
+    # - Updates the system gem if installed
+    # - Installs template files (.envrc, README.md) into mirrors/
+    # - Renames .git directories to .git.mirror in existing mirrors
+    #
+    # @return [void]
+    def migrate_to_v1
+      update_gemfile
+      update_system_gem
+      install_templates
+      rename_git_dirs
+      puts 'Migration to v1.0 complete.'
+    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,97 @@ module Mirrorfile
         end
       RUBY
     end
+
+    # Updates the Gemfile to use mirrorfile ~> 1.0.
+    #
+    # Replaces any existing mirrorfile gem declaration with one
+    # constrained to ~> 1.0. Does nothing if Gemfile doesn't exist
+    # or doesn't reference mirrorfile.
+    #
+    # @return [void]
+    # @api private
+    def update_gemfile
+      gemfile = root.join('Gemfile')
+      return unless gemfile.exist?
+
+      content = gemfile.read
+      updated = content.gsub(/^(\s*gem\s+["']mirrorfile["']).*$/, '\1, "~> 1.0"')
+
+      return unless content != updated
+
+      gemfile.write(updated)
+      puts 'Updated Gemfile to mirrorfile ~> 1.0'
+    end
+
+    # Updates the system-installed mirrorfile gem.
+    #
+    # Checks if the gem is installed globally and runs gem update
+    # if so.
+    #
+    # @return [void]
+    # @api private
+    def update_system_gem
+      return if ENV['MIRRORFILE_SKIP_GEM_UPDATE']
+      return unless system('gem', 'list', '-i', 'mirrorfile', out: File::NULL, err: File::NULL)
+
+      puts 'Updating system gem...'
+      system('gem', 'update', 'mirrorfile')
+    end
+
+    # Copies template files into the mirrors directory.
+    #
+    # Creates the mirrors directory if needed, then copies
+    # envrc.template and README.md.template. Existing files
+    # are not overwritten.
+    #
+    # @return [void]
+    # @api private
+    def install_templates
+      mirrors_dir.mkpath
+
+      templates_dir = Pathname.new(__dir__).join('../../templates')
+
+      envrc_dest = mirrors_dir.join('.envrc')
+      unless envrc_dest.exist?
+        FileUtils.cp(templates_dir.join('envrc.template'), envrc_dest)
+        puts 'Created mirrors/.envrc'
+      end
+
+      readme_dest = mirrors_dir.join('README.md')
+      return if readme_dest.exist?
+
+      FileUtils.cp(templates_dir.join('README.md.template'), readme_dest)
+      puts 'Created mirrors/README.md'
+    end
+
+    # Renames .git directories to .git.mirror in existing mirrors.
+    #
+    # Scans all subdirectories of mirrors/ for .git directories
+    # and renames them. Skips entries that already have .git.mirror.
+    #
+    # @return [void]
+    # @api private
+    def rename_git_dirs
+      return unless mirrors_dir.exist?
+
+      mirrors_dir.children.select(&:directory?).each do |mirror_path|
+        git_dir = mirror_path.join('.git')
+        git_mirror_dir = mirror_path.join('.git.mirror')
+
+        if git_dir.exist? && !git_mirror_dir.exist?
+          File.rename(git_dir.to_s, git_mirror_dir.to_s)
+          puts "Renamed #{mirror_path.basename}/.git to .git.mirror"
+        end
+      end
+    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 = '0.1.1'
 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: 0.1.1
 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,12 +77,15 @@ 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/entry.rb
@@ -90,6 +93,8 @@ files:
 - 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 +118,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: []