squared 0.4.19 → 0.5.0

data/README.ruby.md

@@ -0,0 +1,722 @@
+# squared 0.5
+
+* [source](https://github.com/anpham6/squared)
+* [docs](https://squared.readthedocs.io)
+
+## Version Compatibility
+
+| Date       | squared |    Min |    Max |
+| :--------: | ------: | -----: | -----: |
+| 2024-12-07 |   0.1.0 |  2.4.0 |  3.3.6 |
+| 2025-01-07 |   0.2.0 |        |  3.4.0 |
+| 2025-02-07 |   0.3.0 |        |  3.4.1 |
+| 2025-03-06 |   0.4.0 |        |  3.4.2 |
+| 2025-06-16 |   0.5.0 |  2.5.0 |  3.4.3 |
+
+The range chart indicates the latest Ruby tested against at the time of release.
+
+## Installation
+
+```sh
+gem install squared
+```
+
+### Optional
+
+* [Repo](https://source.android.com/docs/setup/reference/repo)
+* https://github.com/anpham6/squared-repo
+* Python 3.6
+* Not compatible with Windows
+
+```sh
+mkdir -p ~/.bin
+PATH="${HOME}/.bin:${PATH}"
+curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
+chmod a+rx ~/.bin/repo
+```
+
+## Example - Rakefile
+
+Projects from any accessible folder can be added relative to the parent directory (e.g. *REPO_ROOT*) or absolutely. The same Rakefile can also manage other similarly cloned `Repo` repositories remotely by setting the `REPO_ROOT` environment variable to the location. Missing projects will simply be excluded from the task runner.
+
+```ruby
+require "squared"
+
+require "squared/workspace"
+require "squared/workspace/repo"                     # Optional
+require "squared/workspace/project/node"             #
+require "squared/workspace/project/python"           #
+require "squared/workspace/project/ruby"             #
+require "squared/workspace/project/docker"           #
+# OR
+require "squared/app"                                # All workspace related modules
+
+# NODE_ENV  = production
+
+# REPO_ROOT = /workspaces                            |
+# REPO_HOME = /workspaces/squared                    | Dir.pwd
+# rake      = /workspaces/squared/Rakefile           | main?
+# OR
+# REPO_ROOT = /workspaces                            | Dir.pwd
+# rake      = /workspaces/Rakefile                   |
+# REPO_HOME = /workspaces/squared                    | main: "squared"
+
+# pathname  = /workspaces/pathname
+# optparse  = /workspaces/optparse
+# log       = /workspaces/logger
+# emc       = /workspaces/e-mc
+# pir       = /workspaces/pi-r
+# squared   = /workspaces/squared
+# cli       = /workspaces/squared/publish/sqd-cli
+# sqd-serve = /workspaces/squared/publish/sqd-serve
+# sqd       = /workspaces/squared/sqd
+
+Workspace::Application
+  .new(Dir.pwd, main: "squared") # Dir.pwd? (main? is implicitly basename)
+  .banner("group", "project", styles: ["yellow", "black"], border: "bold") # name | project | path | ref | group? | parent? | version?
+  .repo("https://github.com/anpham6/squared-repo", "nightly", script: ["build:dev", "build:prod"], ref: :node) # Repo (optional)
+  .run("rake install", ref: :ruby)
+  .depend(false, group: "default")
+  .clean("rake clean", group: "default")
+  .clean(["build/"], group: "app")
+  .log({ file: "tmp/%Y-%m-%d.log", level: "debug" }, group: "app")
+  .add("pathname", run: "rake compile", copy: "rake install", test: "rake test", group: "default", env: { # Ruby (with C extensions)
+    "CFLAGS" => "-fPIC -O1"
+  })
+  .add("optparse", doc: "rake rdoc", group: "default") # Uses bundler/gem_tasks (without C extensions)
+  .add("logger", copy: { from: "lib", glob: "**/*.rb", into: "~/.rvm/gems/ruby-3.4.0/gems/logger-1.6.1" }, clean: ["tmp/"]) # autodetect: true | "rvm" | "rbenv" | "asdf" | "bundler"
+  .add("e-mc", "emc", copy: { from: "publish", scope: "@e-mc", also: [:pir, "squared-express/"] }, ref: :node) # Node
+  .add("pi-r", "pir", copy: { from: "publish", scope: "@pi-r" }, clean: ["publish/**/*.js", "tmp/"]) # Trailing slash required for directories
+  .add("squared", script: ["build:stage1", "build:stage2"], group: "app") do # Copy target (main)
+    # Repo (global)
+    as(:run, "build:dev", "dev")                                             # npm run build:dev -> npm run dev
+    as(:run, { "build:dev": "dev", "build:prod": "prod" })
+
+    add("publish/sqd-cli", "cli", exclude: [:git])                           # rake cli:build
+    add("publish/sqd-serve")                                                 # rake sqd-serve:build
+    add("publish/sqd-admin", group: "sqd", exclude: [:base])
+    # OR
+    with(exclude: [:base]) { add("publish/*", "packages") }                  # rake packages:sqd-serve:build
+    # OR
+    add(["publish/sqd-cli", "publish/sqd-serve"], true, exclude: [:base])    # rake squared:sqd-serve:build
+
+    # Git
+    revbuild(include: %w[src/ framework/ types/])                            # Synchronous is recommended
+  end
+  .add("squared/sqd", exclude: :git, pass: [:node, "checkout", "bump"]) do   # Skip initialize(:node) + squared:checkout:* + squared:bump:*
+    variable_set :script, "build:sqd"                                        # Override detection
+    variable_set :depend, false
+    variable_set :clean, ["build/sqd/"]
+  end
+  .with(:docker, pass: ["unpack"]) do
+    .add("squared", "docker", file: "Dockerfile", context: ".", tag: "latest", registry: "localhost:5000", username: "squared",
+                              args: "--ssh=default",
+                              secrets: ["id=github,env=GITHUB_TOKEN"],
+                              mounts: ["src=.,dst=/project,ro,bind-propagation=rshared"]) do # Docker
+      series(:clean) do                                                                      # run | depend | doc | lint | test | copy | clean
+        File.read(basepath("docker-bake.hcl"))
+            .scan(/\btags\s+=\s+\["([^"]+)"\]/)
+            .each { |val| image(:rm, tag: val.first) }
+      end
+    end
+  end
+  .pass("pull", group: "default") { test? || doc? } # rake pathname:pull | rake optparse:pull
+  .style("banner", 255.255) # 256 colors (fg | fg.bg | -0.bg)
+  .build(default: "build", parallel: ["pull", "fetch", "rebase", "archive", "clean", /^outdated:/], pass: ["publish"]) do |workspace|
+    workspace
+      .enable_aixterm
+      .style({
+        banner: ["bright_cyan", "bold", "bright_black!"],
+        border: "bright_white"
+      })
+  end
+
+# default   = /workspaces/ruby/*
+# pathname  = /workspaces/ruby/pathname
+# optparse  = /workspaces/ruby/optparse
+# logger    = /workspaces/ruby/logger
+# android   = /workspaces/android-docs
+# chrome    = /workspaces/chrome-docs
+
+Workspace::Application
+  .new(ENV["SQUARED_HOME"], prefix: "rb", common: false) # Local styles
+  .group("ruby", "default", run: "rake build", copy: "rake install", clean: "rake clean", ref: :ruby, override: {
+    pathname: {
+      run: "rake compile"                                # rake rb:pathname:build
+    }
+  })
+  .with(:python, editable: false) do                     # ref=Symbol | group=String
+    banner([:name, ": ", :version], "path")              # chrome-docs: 0.1.0 | /workspaces/chrome-docs
+    doc("make html")                                     # rake rb:doc:python
+    run(false)                                           # rake rb:build:python (disabled)
+    exclude(%i[base git])                                # Project::Git.ref (superclass)
+    add("android-docs", "android")                       # rake rb:android:doc
+    add("chrome-docs", "chrome")                         # rake rb:chrome:doc
+  end
+  .style("inline", "bold")
+  .build
+```
+
+**NOTE**: The use of "**ref**" (class name) is only necessary when initializing an empty directory (e.g. *rake repo:init*).
+
+### Archive
+
+```ruby
+# HEADERS={"Authorization":"Bearer RANDOM-TOKEN"} | hash/json
+# ZIP_DEPTH=0                                     | default=1
+# TAR_DEPTH=0                                     | TAR_DEPTH_SQUARED
+# UNPACK_FORCE=1                                  | Remove target directory
+
+Workspace::Application
+  .new(main: "squared")
+  .with(:python) do
+    add("android-docs", "android", archive: "https://github.com/anpham6/android-docs/archive/refs/tags/v0.3.0.zip")
+    add("chrome-docs", "chrome", archive: {
+      uri: "https://github.com/anpham6/chrome-docs/archive/refs/tags/v0.5.0.tar.gz",  # URI.open (required)
+      digest: "e3d55d2004d4770dd663254c9272dc3baad0d57a5bd14ca767de6546cdf14680",     # SHA1 | SHA256 | SHA384 | SHA512 | MD5
+      digest: "rmd160:47b7790a511eed675fec1a3e742845fef058799b",                      # RMD160
+      ext: "tar.gz",                                                                  # zip | tar | tar.gz | tgz | tar.xz | txz | 7z
+      depth: 1,                                                                       # nested directories (e.g. --strip-components)
+      headers: {                                                                      # URI.open
+        "Authorization" => "Bearer RANDOM-TOKEN"
+      }
+    })
+  end
+  .add("squared", release: "https://github.com/anpham6/squared/archive/refs/tags/??") # squared:unpack:zip[v5.4.0,/tmp/squared]
+end
+```
+
+### Clone
+
+The task is only active when the project directory is empty or does not exist.
+
+```ruby
+Workspace::Application
+  .new(main: "squared")
+  .git(
+    "emc": "https://github.com/anpham6/e-mc",                   # rake emc:clone
+    "pir": {                                                    # rake pir:clone
+      uri: "https://github.com/anpham6/pi-r",                   #
+      options: {                                                #
+        "origin": "github",                                     # --origin=github
+        "recurse-submodules": false,                            # --no-recurse-submodules
+        "shallow-exclude": ["v0.0.1", "v0.0.2"]                 # --shallow-exclude=v0.0.1 --shallow-exclude=v0.0.2
+      }
+    }
+  )
+  .git("squared", "/path/to/squared", options: { local: true }) # Relative paths resolve from workspace root
+  .git(
+    {
+      emc: { uri: "e-mc", options: { "depth": 2 } },            # https://github.com/anpham6/e-mc
+      pir: "pi-r"                                               # Maps task alias to repository folder
+    },
+    base: "https://github.com/anpham6",                         # Required
+    repo: ["squared", "android-docs", "chrome-docs"],           # https://github.com/anpham6/squared
+    options: {                                                  # Only "repo"
+      "depth": 1,
+      "quiet": true
+    }
+  )
+  .with(:node) do                                               # rake clone:node
+    add("e-mc", "emc")                                          # https://github.com/anpham6/e-mc
+    add("pi-r", "pir")                                          # https://github.com/anpham6/pi-r
+    add("squared")                                              # https://github.com/anpham6/squared
+  end
+  .with(:python) do                                             # rake clone:python
+    add("android-docs")
+    add("chrome-docs") do
+      revbuild(include: "source/", exclude: ["source/conf.py"]) # Limit files being watched
+    end
+  end
+  .git("https://github.com/anpham6", ["emc", "pir"])            # Targets any defined project
+  .git("https://github.com/anpham6", cache: true)               # Uses already defined root projects + revbuild
+  .revbuild                                                     # Enables task revbuild (squared.revb)
+  .revbuild(file: "../build.json")                              # $ROOT/build.json
+  .build(parallel: ["clone"])                                   # rake clone + rake clone:sync
+```
+
+### Build
+
+#### Chain
+
+There has to be at least one project which uses the ``step`` attribute. Other placement attributes are ignored.
+
+**NOTE**: Projects can only reference non-global namespaced tasks. (e.g. with ":")
+
+```ruby
+Workspace::Application
+  .new
+  .with(:node) do
+    add("e-mc", "emc") do
+      chain "all", "clean", step: 1                                        # Required
+      chain "all", "build", step: 2
+    end
+    add("pi-r", "pir") do
+      chain "all", "build", after: "emc:build"                             # step: 3
+    end
+    add("pi-r2", "pir2") do
+      chain "all", "build", before: "squared"                              # step: 3
+    end
+    add("squared-express", "express") do
+      chain "all", "clean", with: "emc"                                    # step: 1
+      chain "all", "build", with: "pir"                                    # step: 3
+    end
+    add("squared") do
+      revbuild(include: %w[src/ framework/ types/])                        # Git revision build command (optional)
+      chain "all", "revbuild", after: "express:build"                      # step: 4
+      chain "publish", "bump:patch", "publish:latest", step: 0, sync: true # rake publish
+    end
+  end
+  .with(:python) do
+    doc("make html")
+    add("android-docs") do
+      chain "all", "doc", with: "squared", after: "squared"                # step: 4
+    end
+    add("chrome-docs") do
+      chain "all", "doc", with: "squared", before: "squared:revbuild"      # Same
+    end
+  end
+  .chain("all", "status", with: "squared", after: "android-docs")          # Global tasks (e.g. without ":")
+  .build
+```
+
+```sh
+rake all                # all[1-3-4]
+rake all:print
+```
+
+Threaded is the default when there are two or more tasks. Using ``with`` and either **before** or **after** will create a synchronous group.
+
+* Step 1: emc:clean + express:clean (thread)
+* Step 2: emc:build (sync)
+* Step 3: pir:build + express:build + pir2:build (thread)
+* Step 4: chrome-docs:doc + squared:revbuild + android-docs:doc + status (sync)
+
+#### Graph
+
+```ruby
+Workspace::Application
+  .new(main: "squared")
+  .graph(["depend"], ref: :git)                                                # Optional
+  .with(:python) do
+    doc(windows? ? ".\make.bat html" : "make html")                            # rake android-docs:doc | rake doc:python
+    add("android-docs", "android", venv: "/home/user/.venv")                   # rake android-docs:depend
+    add("chrome-docs", "chrome", graph: "android", venv: %w[.venv --clear]) do # /workspaces/chrome-docs/.venv
+      variable_set :dependindex, 1                                             # Use Poetry for dependencies (optional)
+    end
+  end
+  .with(:node) do
+    graph(["build", "copy"], on: {                                             # Overrides "git"
+      first: proc { puts "1" },
+      last: proc { puts "2" }
+    })
+    script("build:dev")                                                        # npm run build:dev
+    # OR
+    run([nil, "build:dev", { "PATH" => "~/.bin" }, "--workspace", "--silent"]) # PATH="~/.bin" npm run build:dev --workspace -- --silent
+    # OR
+    run({                                                                      # Same
+      script: "build:dev",                                                     #
+      env: { "PATH" => "~/.bin" },                                             #
+      opts: "--workspace",                                                     #
+      args: "--silent"                                                         #
+    })
+
+    add("e-mc", "emc") do
+      first("build", "emc:clean", "emc:depend")                                # rake emc:clean && rake emc:depend && rake emc:build && echo "123"
+      last("build", out: "123") { |out: nil| puts out }                        #
+      error("build") { |err: nil| log.debug err }                              #
+    end
+    add("pi-r", "pir", graph: "emc", first: {
+      build: proc { puts self.name }                                           # puts "pir"
+    })
+    add("squared-express", "express", graph: "pir")
+    add("squared", graph: ["chrome", "express"]) do
+      first("git:ls-files") { puts "1" }                                       # skipped
+      first("git:ls-files", override: true) { puts "2" }                       # puts "2"
+      last("git:ls-files") { puts workspace.root }                             # puts "/workspaces"
+    end
+  end
+  .with(:ruby) do
+    run("gem build")                                                           # gem build
+    # OR
+    run("gem build", on: { first: -> { p "2" }, last: -> { p "4" } }) do       # run | depend | graph | clean | doc | lint | test
+      p "1"
+    end
+    # OR
+    run(on: { first: -> { p "pass" }, last: -> { p "pass" } }) do
+      p "1"
+    end
+    # OR
+    run(["gem build", "--force", { "RUBY_VERSION" => "3.4.0" }])               # RUBY_VERSION="3.4.0" gem build --force
+    # OR
+    run({                                                                      #
+      command: "gem build",                                                    # RUBY_VERSION="3.4.0" gem build --silent --force
+      opts: "--force",                                                         # composable
+      env: { "PATH" => "~/.bin" },                                             #
+      args: { silent: true }                                                   #
+    })
+    # OR
+    run(["gem pristine", ["gem build", "gem cleanup"], nil, "--debug"])        # gem pristine --debug && gem build --debug && gem cleanup --debug
+    #
+    # All commands are either Array or Hash
+    #
+    run([                                                                      # PATH="~/.bin" GEM_HOME="~/.gems/ruby-3.4.0" (merged)
+      ["gem pristine", "--all", { "PATH" => "~/.bin" }, "--silent"],           # gem pristine --silent --all
+      ["gem build", { strict: true }, { "GEM_HOME" => "~/.gems/ruby-3.4.0" }]  # gem build --strict
+    ])                                                                         #
+    # OR
+    run([                                                                      # Same
+      {                                                                        #
+        env: { "PATH" => "~/.bin" },                                           #
+        command: "gem pristine",                                               #
+        opts: "--all", args: "--silent"                                        #
+      },                                                                       #
+      {                                                                        #
+        env: { "GEM_HOME" => "~/.gems/ruby-3.4.0" },                           #
+        command: "gem build",                                                  #
+        opts: { strict: true }                                                 #
+      }                                                                        #
+    ])
+
+    add("pathname", test: ["rake test", { jobs: ENV["RAKE_JOBS"] }])           # rake test --jobs 4
+    add("fileutils", graph: "pathname")
+    add("optparse", run: "gem build", env: { "PATH" => "~/.bin" }, opts: "-v") # PATH="~/.bin" gem build -v
+    add("rake", graph: ["fileutils", "optparse"])
+    banner(command: false)                                                     # Always hide banner
+  end
+  .build
+```
+
+```sh
+rake pir:graph      # emc + pir
+rake express:graph  # emc + pir + express
+rake chrome:graph   # android + chrome
+rake graph:python   # same
+rake squared:graph  # android + chrome + emc + pir + express + squared
+rake graph:node     # same
+rake rake:graph     # pathname + fileutils + optparse + rake
+rake graph:ruby     # same
+rake graph          # graph:node + graph:ruby
+
+rake squared:graph:run[express,pir]  # emc + pir + express + squared
+rake squared:graph:run[node,-emc]    # pir + express + squared
+```
+
+### Tasks
+
+```ruby
+Workspace::Series.batch(:ruby, :node, {
+  stage: %i[graph test],
+  reset: %i[stash pull]
+})
+
+Workspace::Series.rename("depend", "install")
+```
+
+## Usage
+
+```sh
+rake -T               # List tasks
+rake                  # rake status (usually "build")
+
+# GIT_OPTIONS=rebase
+rake pull             # All except "default" + "app"
+rake pull:ruby        # pathname + optparse + logger
+rake pull:default     # pathname + optparse
+rake pull:app         # squared
+rake pull:node        # emc + pir + squared
+
+rake build            # All except "android"
+rake doc              # optparse + android
+rake depend           # All except "default"
+
+rake build:ruby       # rake compile + rake install + rake install
+
+rake clean            # All except "default" + "app"
+rake clean:ruby       # rake clean + rake clean + ["tmp/"]
+rake clean:default    # rake clean + rake clean + skip
+rake clean:app        # none + skip + ["build/"]
+rake clean:node       # none + ["publish/**/*.js", "tmp/"] + ["build/"]
+
+rake squared:run[#]   # List scripts (node)
+rake squared:rake[#]  # List tasks (ruby)
+```
+
+```sh
+rake build:app                   # squared + cli + sqd-serve
+rake squared:build:workspace     # cli + sqd-serve
+rake pull:sqd                    # sqd-admin
+rake squared:pull:workspace      # sqd-serve + sqd-admin
+rake squared:outdated:workspace  # cli + sqd-serve + sqd-admin
+```
+
+## Methods
+
+Task:
+
+* run
+* script
+* depend
+* archive
+* graph
+* doc
+* lint
+* test
+* clean
+
+Non-task:
+
+* log
+* exclude
+
+## Styles
+
+* banner
+* border
+* header
+* active
+* inline
+* subject
+* border
+* warn
+* caution
+* current
+* latest
+* extra
+* major
+* red
+* yellow
+* green
+
+## Git
+
+Most project classes will inherit from `Git` which enables these tasks:
+
+| Task       | Git              |  Command                                      |
+| :--------- | :--------------- | :-------------------------------------------- |
+| branch     | branch           | create set delete move copy list edit current |
+| checkout   | checkout         | commit branch track detach path               |
+| commit     | commit           | add all amend amend-orig fixup                |
+| diff       | diff             | head cached branch files between contain      |
+| fetch      | fetch            | origin remote                                 |
+| files      | ls-files         | cached modified deleted others                |
+| git        |                  | add clean mv rm revert                        |
+| merge      | merge            | commit no-commit send                         |
+| pull       | pull             | origin remote                                 |
+| rebase     | rebase           | branch onto send                              |
+| refs       | ls-remote --refs | heads tags remote                             |
+| reset      | reset            | commit index patch mode                       |
+| restore    | restore          | staged worktree                               |
+| rev        | rev              | commit output                                 |
+| show       | show             | format oneline                                |
+| stash      | stash            | push pop apply drop list                      |
+| switch     | switch           | create detach merge                           |
+| tag        | tag              | add sign delete list                          |
+
+You can disable all of them at once using the `exclude` property.
+
+```ruby
+Workspace::Application.exclude('autostash', 'rebase')
+
+Workspace::Application
+  .new
+  .add("squared", exclude: :git)
+```
+
+You can disable one or more of them using the `pass` property as a *string*.
+
+```ruby
+Workspace::Application
+  .new
+  .add("squared", pass: ["pull"], ref: :node)
+  .pass("pull", ref: :node) { read_packagemanager(:private) }
+```
+
+### Commit Hash
+
+Commands which use commit hashes are parsed using a ":" prefix as to not be confused for an option.
+
+```sh
+rake squared:log:view[:af012345]                   # git log af012345
+rake squared:log:view[H1,HEAD^5,all,lib,./H12345]  # git log --all @~1 @^5 -- 'lib' 'H12345'
+```
+
+## Environment
+
+### Path
+
+All project binary programs can have their executable path set to a non-global alias.
+
+```ruby
+Common::PATH.update({
+  GIT: "/usr/bin/git",                         # PATH_GIT=/usr/bin/git
+  TAR: "/opt/archivers/tar",                   # PATH_TAR=/opt/archivers/tar
+  UNZIP: "/opt/archivers/unzip",
+  GEM: "~/.rvm/gems/ruby-3.4.0/bin/gem",
+  BUNDLE: "~/.rvm/gems/ruby-3.4.0/bin/bundle",
+  RAKE: "~/.rvm/gems/ruby-3.4.0/bin/rake",
+  NPM: "/opt/node/v22.0.0/bin/npm",
+  PYTHON: "#{ENV["PYTHONPATH"]}/bin/python"
+})
+```
+
+### Build
+
+```ruby
+Workspace::Application
+  .new
+  .add("squared", run: "gcc a.c -o a.o", opts: { __debug__: { g: true, O2: true, c: nil }, c: true, j: 4 }) # gcc a.c -o a.o -c -j4
+```
+
+```sh
+BUILD_TYPE                   # global
+${PROG}_COLOR=0              # --no-color (e.g. GIT_COLOR)
+
+# :env                                         :run           :args :opts :type
+# LD_LIBRARY_PATH="path/to/lib" CFLAGS="-Wall" gcc a.c -o a.o       -g    -O2
+BUILD_${NAME}                # gcc a.c -o a.o
+BUILD_${NAME}_OPTS           # -g
+BUILD_${NAME}_ENV            # {"LD_LIBRARY_PATH":"path/to/lib","CFLAGS":"-Wall"} (hash/json)
+BUILD_${NAME}_TYPE           # debug
+
+# :env                                       :script   :opts                                  :args
+# NODE_ENV="production" NO_COLOR="1" npm run build:dev --loglevel=error --workspaces=false -- --quiet
+BUILD_${NAME}                # build:dev
+BUILD_${NAME}_OPTS           # --loglevel=error --workspaces=false
+BUILD_${NAME}_ENV            # {"NODE_ENV":"production","NO_COLOR":"1"} (hash/json)
+BUILD_${NAME}_DEV            # pattern,0,1 (:dev)
+BUILD_${NAME}_PROD           # pattern,0,1 (:prod)
+${REF}_${NAME}_OPTS          # --quiet (e.g. NODE_SQUARED_OPTS)
+
+BUILD_${NAME}=0              # skip project
+BUILD_${NAME}_VERSION=0.1.0  # publish + detection
+
+BANNER=0                     # hide banner
+BANNER_${NAME}=0             #
+
+REVBUILD_FORCE=1             # Rebuild all targets
+REVBUILD_FORCE_${NAME}=1     # Rebuild project
+
+PREREQS_${NAME}=build,copy   # Class method name to invoke
+PREREQS_${REF}=depend        # e.g. Node
+```
+
+### Graph
+
+```sh
+GRAPH_${NAME}                # depend,build => squared:depend + squared:build
+GRAPH_${NAME}_PASS           # -emc,pir,express => pir + express
+```
+
+### Logger
+
+These global options also can target the project suffix `${NAME}`. (e.g. LOG_FILE_EMC)
+
+```sh
+LOG_FILE                     # %Y-%m-%d.log
+# OR
+LOG_AUTO                     # year,y,month,m,day,d,1
+# Optional
+LOG_DIR                      # exist?
+LOG_LEVEL                    # See gem "logger"
+```
+
+### Git
+
+```sh
+GIT_OPTIONS=q,strategy=ort  # all
+GIT_OPTIONS_${NAME}=v,ff    # project only
+GIT_AUTOSTASH=1             # rebase (all)
+GIT_AUTOSTASH_${NAME}=0     # rebase (project only)
+```
+
+| Command    | Flag              |  ENV                                                                  |
+| :--------- | :---------------- | :-------------------------------------------------------------------- |
+| branch     | create            | TRACK=0,1,s FORCE                                                     |
+| branch     | move copy         | FORCE                                                                 |
+| branch     | set delete        | COUNT=n                                                               |
+| branch     | global            | SYNC                                                                  |
+| checkout   | branch            | DETACH TRACK=s COUNT=n                                                |
+| checkout   | detach            | REFLOG=1                                                              |
+| checkout   | track             | COUNT=n                                                               |
+| checkout   | global path       | HEAD=s PATHSPEC=s                                                     |
+| checkout   | *                 | FORCE MERGE                                                           |
+| clone      | *                 | DEPTH=n ORIGIN=s BRANCH=s REVISION=s LOCAL=0,1                        |
+| commit     | *                 | UPSTREAM=s DRY_RUN EDIT=0 M|MESSAGE=s                                 |
+| diff       | -between -contain | MERGE_BASE                                                            |
+| diff       | head branch       | INDEX=n                                                               |
+| diff       | *                 | PATHSPEC=s                                                            |
+| fetch      | -remote           | ALL                                                                   |
+| fetch      | remote            | REFSPEC=s                                                             |
+| fetch      | *                 | FORCE RECURSE_SUBMODULES=0,1,s                                        |
+| git        | rm                | PATHSPEC=s                                                            |
+| log        | *                 | PATHSPEC=s                                                            |
+| pull       | rebase            | AUTOSTASH                                                             |
+| pull       | remote            | REFSPEC=s                                                             |
+| pull       | -remote           | ALL                                                                   |
+| pull       | *                 | REBASE=0,1 FORCE RECURSE_SUBMODULES=0,1,s                             |
+| rebase     | branch            | HEAD=s                                                                |
+| rebase     | onto              | INTERACTIVE I HEAD=s                                                  |
+| reset      | mode (mixed)      | N REFRESH=0                                                           |
+| reset      | index             | PATHSPEC=s                                                            |
+| reset      | commit            | COUNT=n REFLOG=1                                                      |
+| reset      | -commit           | HEAD=s                                                                |
+| restore    | *                 | PATHSPEC=s                                                            |
+| revbuild   | global            | UNTRACKED_FILES=s IGNORE_SUBMODULES=s IGNORED=s (status)              |
+| stash      | push              | PATHSPEC=s                                                            |
+| stash      | global            | ALL=0,1 KEEP_INDEX=0,1 INCLUDE_UNTRACKED=0,1 STAGED=0,1 M|MESSAGE=s   |
+| status     | global            | BRANCH LONG IGNORE_SUBMODULES=s,0-3 PATHSPEC=s                        |
+| switch     | detach            | REFLOG=1                                                              |
+| switch     | -detach           | HEAD=s                                                                |
+| switch     | *                 | FORCE                                                                 |
+| tag        | add               | SIGN FORCE HEAD=s M|MESSAGE=s                                         |
+| tag        | sign              | FORCE HEAD=s M|MESSAGE=s                                              |
+| tag        | delete            | COUNT=n                                                               |
+| rev        | commit branch     | HEAD=s                                                                |
+
+### Docker
+
+```sh
+DOCKER_OPTIONS=q,no-cache                # all
+DOCKER_OPTIONS_${NAME}=v,no-cache=false  # project only (override)
+DOCKER_TAG=latest                        # all
+DOCKER_TAG_${NAME}=v0.1.0                # project only (override)
+DOCKER_ALL=1                             # list every image/container
+DOCKER_Y=1                               # confirm all
+
+BUILD_SQUARED_OPTS="NODE_TAG=24 RUBY_VERSION=3.4.0" DOCKER_SQUARED_OPTS="--no-cache --label=v1" rake squared:build
+docker build --no-cache --label=v1 --build-arg='NODE_TAG=24' --build-arg='RUBY_VERSION=3.4.0' .
+```
+
+| Command    | Flag              |  ENV                                            |
+| :--------- | :---------------- | :---------------------------------------------- |
+| buildx     | build             | TAG=s                                           |
+| buildx     | bake              | SERVICE=s                                       |
+| compose    | build             | TARGET=s                                        |
+| container  | commit            | REGISTRY=s PLATFORM=s DISABLE_CONTENT_TRUST=0,1 |
+| image      | rm                | Y=0,1                                           |
+| image      | push              | TAG=s REGISTRY=s                                |
+
+### Repo
+
+These global options also can target the application main suffix `${NAME}`. (e.g. REPO_ROOT_SQUARED)
+
+```sh
+REPO_ROOT            # parent dir
+REPO_HOME            # project dir (main)
+REPO_BUILD           # run,script
+REPO_GROUP           # string
+REPO_REF             # e.g. ruby,node
+REPO_DEV             # pattern,0,1
+REPO_PROD            # pattern,0,1
+REPO_WARN            # 0,1
+REPO_SYNC            # 0,1
+REPO_URL             # manifest repository
+REPO_MANIFEST        # e.g. latest,nightly,prod
+REPO_DRYRUN          # 0,1,2
+REPO_TIMEOUT         # confirm dialog (seconds)
+```
+
+## LICENSE
+
+BSD 3-Clause