git_tree 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbe9b3cc4ea586c939cc994ddf433fe11a3ae801ebb4d414d26203969272e35e
-  data.tar.gz: a73a4c53e64d9cf8c3a9ac9f82cca966a469585a39c8d2df19f62d99d5d6bc9b
+  metadata.gz: 4f2b29b124bbe5716b420d6a24042e6082d611d5e4fbadcc4668881e6ca58919
+  data.tar.gz: 07ad131942b0d6192ad3adba9d25779747f6687a1d65dc6a6066f898d8ad8be7
 SHA512:
-  metadata.gz: 28bffd85905de74df607377f3db64588d1697ef7acbaace6ddc5ca410d6ba71aca2aaa293f1620fac87d9175618f2068ccd759080e4a803fc56ff57aa798c8d4
-  data.tar.gz: 963acbcdac77069745e6cc009b653fdb779e6f97e192d5bd937efb0c6bb9e4dfbb34d8796a00c48108e655239b41322baaa5f4751652f0f228cde1aec939cf76
+  metadata.gz: 1aa0222f18b6346b0634c0bf5f6415801e278905c492b7be4b1820844e19edbb036189e60e7bdbb94235153f98f2af9262b5e0c02e6141b0d4bc6135db8256e4
+  data.tar.gz: cf9d7a7b7b7fded9402dfffd33f263327d29dcf190248af9d4e5b9ca75bf0be6f67df148b87770323149eccc318328b7d17e4b00b619ab9f5cc676f609733aa0

data/.rubocop.yml

@@ -1,4 +1,4 @@
-require:
+plugins:
   - rubocop-md
   - rubocop-performance
   - rubocop-rake
@@ -29,6 +29,9 @@ Layout/HashAlignment:
 Layout/InitialIndentation:
   Exclude:
     - README.md
+    - CHANGELOG.md
+    - Gemfile*
+    - git_tree.gemspec
 
 Layout/LineLength:
   Max: 150
@@ -40,6 +43,9 @@ Lint/RedundantCopDisableDirective:
   Exclude:
     - git_tree.gemspec
 
+Lint/RedundantDirGlobSort:
+  Enabled: false
+
 Metrics/AbcSize:
   Max: 45
 
@@ -47,6 +53,7 @@ Metrics/BlockLength:
   Exclude:
     - git_tree.gemspec
     - spec/**/*
+  Max: 35
 
 Metrics/ClassLength:
   Exclude:
@@ -64,16 +71,26 @@ Metrics/PerceivedComplexity:
 Naming/FileName:
   Exclude:
     - Rakefile
+    - CHANGELOG.md
+    - README.md
+    - Gemfile*
+    - exe/*
 
 RSpec/ExampleLength:
   Max: 20
 
-RSpec/FilePath:
-  Enabled: false
-
 RSpec/MultipleExpectations:
   Max: 15
 
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  IgnoreMethods: true
+
+RSpec/SubjectStub:
+  Enabled: false
+
 Style/CommandLiteral:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,8 +1,14 @@
 # Change Log
 
-## 0.3.1 (in progress)
 
-* Added spec.platform to `.gemspec` because `RubyGems.org` now requires it
+## 1.0.0 / 2025-10-03
+
+* Made the file search breadth-first instead of depth-first,
+  greatly increasing performance.
+* Added `git-update` and `git-commitAll` commands.
+* Renamed `git-tree-replicate`, `git-tree-evars` and `git-tree-exec` to
+  `git-replicate`, `git-evars` and `git-exec`.
+* Added spec.platform to `.gemspec` because `RubyGems.org` now requires it.
 
 
 ## 0.3.0 / 2023-06-01

data/README.md

@@ -1,71 +1,161 @@
 # `Git_tree` [![Gem Version](https://badge.fury.io/rb/git_tree.svg)](https://badge.fury.io/rb/git_tree)
 
-This Ruby gem installs 3 commands that scan a git directory tree;
-2 of the commands write out scripts and the third executes an arbitrary bash command for each repository.
+This Ruby gem installs commands that walk a git directory tree and act on each repository.
 Directories containing a file called `.ignore` are ignored.
+Ignoring a directory means all subdirectories are also ignored.
+Multiple threads are used to dramatically boost performance.
 
-- The `git-tree-replicate` command writes a script that clones the repos in the tree,
-  and adds any defined remotes.
-  - Any git repos that have already been cloned into the target directory tree are skipped.
-    This means you can rerun `git-tree-replicate` as many times as you want, without ill effects.
-  - All remotes in each repo are replicated.
+- The `git-commitAll` command commits and pushes all changes to each repository in the tree.
+  Repositories in a detached `HEAD` state are skipped.
 
-- The `git-tree-evars` command writes a script that defines environment variables pointing to git repos.
+- The `git-evars` command writes a script that defines environment variables pointing to each git repository.
 
-- The `git-tree-exec` command executes an arbitrary bash command for each repository.
+- The `git-exec` command executes an arbitrary bash command for each repository.
 
+- The `git-replicate` command writes a script that clones the repos in the tree,
+  and adds any defined remotes.
 
-## Usage
-
-All commands require one environment variable reference to be passed to them.
-Enclose the name of the environment variable within single quotes,
-which will prevent the shell from expanding it before invoking the command.
+  - Any git repos that have already been cloned into the target directory tree are skipped.
+    This means you can rerun `git-replicate` as many times as you want, without ill effects.
 
+  - All remotes in each repo are replicated.
 
-## `git-tree-replicate` Usage
+- The `git-update` command updates each repository in the tree.
 
-The following creates a script in the current directory called `work.sh`,
-that replicates the desired portions of the directory tree of git repos pointed to by `$work`:
+You can list them by using the `gem specification` command, like this:
 
 ```shell
-$ git-tree-replicate '$work' > work.sh
+$ gem specification git_tree executables
+---
+- git-commitAll
+- git-evars
+- git-exec
+- git-replicate
+- git-update
 ```
 
-The generated environment variables will all be relative to the
-path pointed to by the expanded environment variable that you provided.
-You will understand what this means once you look at the generated script.
+## Installation
 
-When `git-tree-replicate` completes,
-edit the generated script to suit, then
-copy it to the target machine and run it.
-The following example copies the script to `machine2` and runs it:
+Type the following at a shell prompt on the machine you are copying the git tree from,
+and on the machine that you are copying the git tree to:
 
 ```shell
-$ scp work.sh machine2:
+$ yes | sudo apt install cmake libgit2-dev libssh2-1-dev pkg-config
 
-$ ssh machine2 work.sh
+$ gem install git_tree
 ```
 
+To register the new commands, either log out and log back in, or open a new console.
 
-### Generated Script from `git-tree-replicate`
+## Use Cases
 
-Following is a sample of one section, which is repeated for every git repo that is processed:
-You can edit them to suit.
+### Dependent Gem Maintenance
+
+One of my directory trees holds Jekyll plugins, packaged as 25 gems.
+They depend on one another, and must be built in a particular order.
+Sometimes an operation must be performed on all of the plugins, and then rebuild them all.
+
+Most operations do not require that the projects be processed in any particular order, however
+the build process must be invoked on the dependencies first.
+It is quite tedious to do this 25 times, over and over.
+
+Several years ago I wrote a bash script to perform this task, but as its requirements became more complex,
+the bash script proved difficult to maintain. This use case is now fulfilled by the `git-exec` command
+provided by the `git_tree` gem.
+See below for further details.
+
+### Replicating Trees of Git Repositories
+
+Whenever I set up an operating system for a new development computer,
+one of the tedious tasks that must be performed is to replicate
+the directory trees of Git repositories.
+
+It is a bad idea to attempt to copy an entire Git repository between computers,
+because the `.git` directories within them can quite large.
+So large, in fact, that it might much more time to copy than re-cloning.
+
+The reason is that copying the entire Git repository actually means copying the same information twice:
+first the `.git` hidden directory, complete with all the history for the project,
+and then again for the files in the currently checked out branch.
+Git repos store the entire development history of the project in their `.git` directories,
+so as they accumulate history they eventually become much larger than the
+code that is checked out at any given time.
+
+One morning I found myself facing the boring task of doing this manually once again.
+Instead, I wrote a bash script that scanned a Git directory tree and
+wrote out another bash script that clones the repos in the tree.
+Any additional remote references are replicated.
+
+Two years later, I decided to add new features to the script.
+Bash is great for short scripts,
+but it is not conducive to debugging or structured programming.
+I rewrote the bash script in Ruby, using the `rugged` gem.
+Much better!
+
+Two years after that I used Google Gemini Code Assist to rewrite it again in Ruby,
+this time as a multithreaded program.
+Performance is now lightning-fast for most use cases.
+I was also able to use the same core logic for several of the individual
+Git-related scripts I had written over the years.
+The result is this Ruby gem.
+
+This use case is fulfilled by the
+`git-replicate`
+and `git-evars` commands
+provided by this gem.
+
+
+## Usage
+
+### Single- And Multi-Threading
+
+All of these commands are inherently multi-threaded.
+They consume up to 75% of the threads that your CPU can provide.
+You may notice that your computer's fan gets louder when your run these commands on large numbers of Git repositories.
+
+For builds and other sequential tasks, however, parallelism is inappropriate.
+Instead, it is necessary to build components in the proper order.
+Doing all the work on a single thread is a straightforward way of ensuring proper task ordering.
+
+Use the `-s/--serial` option when the order that Git projects are processed matters.
+All of the commands support this option.
+Execution will take much longer that without the option,
+because performing most tasks take longer to perform in sequence than performing them in parallel.
+Exceptions include old sayings like “Nine women cannot have a baby in one month.”
+For those exceptions, use the `-s/--serial` option.
+
+### `git-commitAll`
+
+```text
+git-commitAll - Recursively commits and pushes changes in all git repositories under the specified DIRECTORY roots.
+If no directories are given, uses default environment variables ('sites', 'sitesUbuntu', 'work') as roots.
+Skips directories containing a .ignore file.
+Repositories in a detached HEAD state are skipped.
+
+Options:
+  -h, --help                Show this help message and exit.
+  -m, --message MESSAGE     Use the given string as the commit message.
+                            (default: "-")
+  -q, --quiet               Suppress normal output, only show errors.
+  -s, --serial              Run tasks serially in a single thread in the order specified.
+  -v, --verbose             Increase verbosity. Can be used multiple times (e.g., -v, -vv).
+```
 
 ```shell
-if [ ! -d "sinatra/sinatras-skeleton/.git" ]; then
-  mkdir -p 'sinatra'
-  pushd 'sinatra' > /dev/null
-  git clone git@github.com:mslinn/sinatras-skeleton.git
-  git remote add upstream 'https://github.com/simonneutert/sinatras-skeleton.git'
-  popd > /dev/null
-fi
+$ git commitAll
+Processing $sites $sitesUbuntu $work
+Initializing 18 worker threads...
+
+All work is complete.
 ```
 
-## `git-tree-evars` Usage
 
-The `git-tree-evars` command should be run on the target computer.
-The command requires only one parameter:
+### `git-evars`
+
+The `git-evars` command writes a script that defines environment variables pointing to each git repository.
+This command should be run on the target computer.
+
+Only one parameter is required:
 an environment variable reference, pointing to the top-level directory to replicate.
 The environment variable reference must be contained within single quotes to prevent expansion by the shell.
 
@@ -73,24 +163,34 @@ The following appends to any script in the `$work` directory called `.evars`.
 The script defines environment variables that point to each git repos pointed to by `$work`:
 
 ```shell
-$ git-tree-evars '$work' >> $work/.evars
+$ git-evars '$work' >> $work/.evars
 ```
 
 
-### Generated Script from `git-tree-evars`
+#### Generated Script from `git-evars`
 
 Following is a sample of environment variable definitions.
-You are expected to edit it to suit.
+The `-z`/`--zowee` option generates intermediate environment variable definitions,
+making them much easier to work with.
 
 ```shell
-export work=/mnt/c/work
-export ancientWarmth=$work/ancientWarmth/ancientWarmth
-export ancientWarmthBackend=$work/ancientWarmth/ancientWarmthBackend
-export braintreeTutorial=$work/ancientWarmth/braintreeTutorial
-export survey_analytics=$work/ancientWarmth/survey-analytics
-export survey_creator=$work/ancientWarmth/survey-creator
-export django=$work/django/django
-export frobshop=$work/django/frobshop
+$ git-evars -z '$sites'
+export mnt=/mnt
+export c=$mnt/c
+export _6of26=$sites/6of26
+export computers=$sites/computers.mslinn.com
+export ebooks=$sites/ebooks
+export expert=$sites/expert
+export fonts=$sites/fonts
+export intranet=$sites/intranet.ancientwarmth.com
+export intranet_mslinn=$sites/intranet.mslinn.com
+export jekyllTemplate=$sites/jekyllTemplate
+export lyrics=$sites/lyrics
+export metamusic=$sites/metamusic
+export music=$sites/music.mslinn.com
+export photos=$sites/photos
+export supportingLiterature=$sites/supportingLiterature
+export www=$sites/www.scalacourses.com
 ```
 
 The environment variable definitions are meant to be saved into a file that is `source`d upon boot.
@@ -112,26 +212,29 @@ $ cd $my_project
 ```
 
 
-## `git-tree-exec` Usage
+### `git-exec` Usage
 
-The `git-tree-exec` command can be run on any computer.
+The `git-exec` command can be run on any computer.
 The command requires two parameters.
 The first parameter indicates the directory or directories to process.
 3 forms are accepted:
 
   1. A directory name, which may be relative or absolute.
+
   2. An environment variable reference,
      which must be contained within single quotes to prevent expansion by the shell.
+
   3. A list of directory names, which may be relative or absolute, and may contain environment variables.
 
-### Example 1
+
+#### Example 1
 
 For all subdirectories of current directory,
 update `Gemfile.lock` and install a local copy of the gem:
 
 ```shell
-$ git-tree-exec '
-  $jekyll_plugin_logger
+$ git-exec \
+  '$jekyll_plugin_logger
   $jekyll_draft
   $jekyll_plugin_support
   $jekyll_all_collections
@@ -142,16 +245,16 @@ $ git-tree-exec '
   $jekyll_outline
   $jekyll_plugin_template
   $jekyll_pre
-  $jekyll_quote
-' 'bundle && bundle update && rake install'
+  $jekyll_quote'
+  'bundle && bundle update && rake install'
 ```
 
-### Example 2
+#### Example 2
 
 This example shows how to display the version of projects that
 create gems under the directory pointed to by `$my_plugins`.
 
-An executable script is required on the `PATH`, so `git-tree-exec`
+An executable script is required on the `PATH`, so `git-exec`
 can invoke it as it loops through the subdirectories.
 I call this script `version`, and it is written in `bash`,
 although the language used is not significant:
@@ -161,12 +264,12 @@ although the language used is not significant:
 
 x="$( ls lib/**/version.rb 2> /dev/null )"
 if [ -f "$x" ]; then
-  v="$(
+  v="$( \
     cat "$x" | \
     grep '=' | \
     sed -e s/.freeze// | \
-    tr -d 'VERSION =\"' | \
-    tr -d \'
+    tr -d 'VERSION ="' | \
+    tr -d \
   )"
   echo "$(basename $PWD) v$v"
 fi
@@ -175,7 +278,7 @@ fi
 Call it like this:
 
 ```shell
-$ git-tree-exec '$my_plugins' version
+$ git-exec '$my_plugins' version
 jekyll_all_collections v0.3.3
 jekyll_archive_create v1.0.2
 jekyll_archive_display v1.0.1
@@ -207,13 +310,13 @@ jekyll_sort_natural v1.0.0
 jekyll_time_since v0.1.3
 ```
 
-### Example 3
+#### Example 3
 
 List the projects under the directory pointed to by `$my_plugins`
 that have a `demo/` subdirectory:
 
 ```shell
-$ git-tree-exec '$my_plugins' \
+$ git-exec '$my_plugins' \
   'if [ -d demo ]; then realpath demo; fi'
 /mnt/c/work/jekyll/my_plugins/jekyll-hello/demo
 /mnt/c/work/jekyll/my_plugins/jekyll_all_collections/demo
@@ -234,25 +337,57 @@ $ git-tree-exec '$my_plugins' \
 /mnt/c/work/jekyll/my_plugins/jekyll_time_since/demo
 ```
 
+### `git-replicate` Usage
 
-## Installation
+This command generates a shell script to replicate a tree of git repositories.
+ROOTS can be directory names or environment variable references (e.g., '$work').
+Multiple roots can be specified in a single quoted string.
 
-Type the following at a shell prompt on the machine you are copying the git tree from,
-and on the machine that you are copying the git tree to:
+```shell
+$ git-replicate '$work' > work.sh                # Replicate repos under $work
+$ git-replicate '$work $sites' > replicate.sh    # Replicate repos under $work and $sites
+```
+
+The generated environment variables will all be relative to the
+path pointed to by the expanded environment variable that you provided.
+You will understand what this means once you look at the generated script.
+
+When `git-replicate` completes,
+edit the generated script to suit, then
+copy it to the target machine and run it.
+The following example copies the script to `machine2` and runs it:
 
 ```shell
-$ yes | sudo apt install cmake libgit2-dev libssh2-1-dev pkg-config
+$ scp work.sh machine2:
 
-$ gem install git_tree
+$ ssh machine2 work.sh
 ```
 
-To register the new commands, either log out and log back in, or open a new console.
+
+#### Generated Script from `git-replicate`
+
+Following is a sample of one section, which is repeated for every git repo that is processed:
+You can edit them to suit.
+
+```shell
+if [ ! -d "sinatra/sinatras-skeleton/.git" ]; then
+  mkdir -p 'sinatra'
+  pushd 'sinatra' > /dev/null
+  git clone git@github.com:mslinn/sinatras-skeleton.git
+  git remote add upstream 'https://github.com/simonneutert/sinatras-skeleton.git'
+  popd > /dev/null
+fi
+```
+
+### `git-update`
+
+The `git-update` command updates each repository in the tree.
 
 
 ## Additional Information
 
 More information is available on
-[Mike Slinn’s website](https://www.mslinn.com/git/1100-git-tree.html)
+[Mike Slinn’s website](https://www.mslinn.com/git/1100-git-tree.html).
 
 
 ## Development
@@ -269,9 +404,7 @@ You can run `bin/console` for an interactive prompt that will allow you to exper
 
 ```shell
 $ bin/console
-irb(main):001:0> GitTree.command_replicate 'demo'
-
-irb(main):002:0> GitTree.command_evars 'demo'
+irb(main):001:0> GitTree::ReplicateCommand.new('$work').run
 ```
 
 
@@ -289,12 +422,14 @@ Examine the newly built gem:
 $ gem info git_tree
 
 *** LOCAL GEMS ***
-git_tree (0.2.0)
+
+git_tree (0.3.0)
     Author: Mike Slinn
-    Homepage:
-    https://github.com/mslinn/git_tree_replicate
+    Homepage: https://www.mslinn.com/git/1100-git-tree.html
     License: MIT
-    Installed at: /home/mslinn/.gems
+    Installed at: /home/mslinn/.rbenv/versions/3.4.6/lib/ruby/gems/3.4.0
+
+    Installs five commands that walk a git directory tree and perform tasks.
 ```
 
 
@@ -325,4 +460,10 @@ To release a new version:
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+## Additional Information
+
+More information is available on
+[Mike Slinn’s website](https://www.mslinn.com/git/1100-git-tree.html)

data/exe/git-commitAll

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/commands/git_commit_all'

data/exe/git-evars

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/commands/git_evars'

data/exe/git-exec

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/commands/git_exec'

data/exe/git-replicate

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/commands/git_replicate'

data/exe/git-update

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/commands/git_update'

data/git_tree.gemspec

@@ -4,22 +4,26 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   github = 'https://github.com/mslinn/git_tree'
 
   spec.authors     = ['Mike Slinn']
-  spec.bindir      = 'bindir'
+  spec.bindir      = 'exe'
   spec.description = <<~END_OF_DESC
-    Installs 3 commands that process a git directory tree.
+    Installs 5 commands that process a git directory tree.
     Directories containing a file called .ignore are ignored.
 
-    The git-tree-replicate command writes a script that clones the repos in the tree,
-    and adds any defined remotes.
+    The git-commitAll command commits all changes to each repository in the tree.
+
+    The git-evars command writes a script that defines environment variables pointing to git repos.
 
-    The git-tree-evars command writes a script that defines environment variables pointing to git repos.
+    The git-exec command executes a bash expression on children of a directory, or a list of directories.
+
+    The git-replicate command writes a script that clones the repos in the tree,
+    and adds any defined remotes.
 
-    The git-tree-exec command executes a bash expression on children of a directory, or a list of directories.
+    The git-update command updates each repository in the tree.
   END_OF_DESC
   spec.email       = ['mslinn@mslinn.com']
-  spec.executables = %w[git-tree-exec git-tree-evars git-tree-replicate]
+  spec.executables = %w[git-commitAll git-evars git-exec git-replicate git-update]
   spec.files = Dir[
-    '{bindir,lib}/**/*',
+    '{exe,lib}/**/*',
     '.rubocop.yml',
     'LICENSE.*',
     'Rakefile',
@@ -42,10 +46,11 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
     Thanks for installing #{spec.name}!
 
   END_MESSAGE
-  spec.required_ruby_version = '>= 2.6.0'
-  spec.summary               = 'Installs two commands that scan a git directory tree and write out scripts for replication.'
+  spec.required_ruby_version = '>= 3.2.0'
+  spec.summary               = 'Installs five commands that walk a git directory tree and perform tasks.'
   spec.version               = GitUrlsVersion::VERSION
 
+  spec.add_dependency 'gem_support'
   spec.add_dependency 'rainbow'
   spec.add_dependency 'rugged'
 end