Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Make mage easier to browse: grouped task list, ls filter, cwd-aware alias (#83616)

bryan2b17f4d88772
diff --git a/bb.edn b/bb.edn
index 8be54cbaa91..6b3efd56564 100644
--- a/bb.edn
+++ b/bb.edn
@@ -15,6 +15,8 @@
table/table {:mvn/version "0.5.0"} ;; table printing
}
;; No :pods key on purpose: tasks lazily load only what they need.
+ ;; Every public task needs a :group naming its section in the `./bin/mage` listing. Use one of the
+ ;; names in `mage.util/task-groups`, or add a new name there; that vector sets the section order.
:tasks
{:requires [[mage.cli :as cli]
[mage.color :as c]]
@@ -26,7 +28,8 @@
(cons 'do body))))
alias
- {:doc "Installs 'mage' alias and autocomplete"
+ {:group "Mage"
+ :doc "Installs 'mage' alias and autocomplete"
:examples [["./bin/mage alias" "Prints instructions to install the 'mage' alias and autocomplete"]
["./bin/mage alias install fish" "Installs mage alias for fish shell"]
["./bin/mage alias print zsh" "Prints shell script to put into .zshrc for zsh users"]]
@@ -38,7 +41,8 @@
:task (task! (alias/instructions parsed))}
cljfmt-staged
- {:doc "Runs cljfmt on staged files"
+ {:group "Format & lint"
+ :doc "Runs cljfmt on staged files"
:requires [[mage.format :as format]]
:examples [["./bin/mage cljfmt-staged" "Format staged files"]
["./bin/mage cljfmt-staged -c" "Check staged files"]]
@@ -46,7 +50,8 @@
:task (task! (format/staged parsed))}
cljfmt-files
- {:doc "Runs cljfmt on the given files/directories"
+ {:group "Format & lint"
+ :doc "Runs cljfmt on the given files/directories"
:requires [[mage.format :as format]]
:examples [["./bin/mage cljfmt-files src/metabase/events.clj" "Format events.clj"]
["./bin/mage cljfmt-files src" "Format all files in src"]
@@ -57,14 +62,16 @@
:task (task! (format/files parsed))}
cljfmt-all
- {:doc "Runs cljfmt on all (clojure) files"
+ {:group "Format & lint"
+ :doc "Runs cljfmt on all (clojure) files"
:requires [[mage.format :as format]]
:examples [["./bin/mage cljfmt-all" "Format all files"]]
:options [["-c" "--force-check" "Check staged files"]]
:task (task! (format/all parsed))}
cljfmt-updated
- {:doc "Runs cljfmt on all (Clojure) files relative to a git ref (default HEAD)"
+ {:group "Format & lint"
+ :doc "Runs cljfmt on all (Clojure) files relative to a git ref (default HEAD)"
:requires [[mage.format :as format]]
:examples [["./bin/mage cljfmt-updated" "Format updated files relative to HEAD"]
["./bin/mage cljfmt-updated master" "Format updated files relative to master"]]
@@ -73,7 +80,8 @@
:task (task! (format/updated parsed))}
kondo
- {:doc "Runs Kondo against a file, directory, or everything we usually lint"
+ {:group "Format & lint"
+ :doc "Runs Kondo against a file, directory, or everything we usually lint"
:examples [["./bin/mage kondo" "run Kondo against everything we usually lint"]
["./bin/mage kondo src/metabase/db.clj" "run Kondo against a file"]
["./bin/mage kondo src/metabase/db.clj src/metabase/config.clj" "run Kondo against 2 files"]
@@ -82,14 +90,16 @@
:task (task! (kondo/kondo (:arguments parsed)))}
kondo-updated
- {:doc "Runs kondo against files changed compared to a git ref"
+ {:group "Format & lint"
+ :doc "Runs kondo against files changed compared to a git ref"
:examples [["./bin/mage kondo-updated" "run Kondo on files with changes relative to HEAD"]
["./bin/mage kondo-updated master" "run Kondo on files with changes relative to master"]]
:requires [[mage.kondo :as kondo]]
:task (task! (kondo/kondo-updated (:arguments parsed)))}
fix-unused-requires
- {:doc "Removes unused requires flagged by clj-kondo"
+ {:group "Format & lint"
+ :doc "Removes unused requires flagged by clj-kondo"
:examples [["./bin/mage fix-unused-requires src/metabase/utils/validate.cljc" "Fix unused requires in a specific file"]
["./bin/mage fix-unused-requires src" "Fix unused requires in all files in src"]]
:requires [[mage.fix-unused-requires :as fix]]
@@ -98,32 +108,37 @@
:task (task! (fix/fix-files parsed))}
load-namespaces
- {:doc "Checks that every shipped namespace loads without :dev dependencies (and finds circular dependencies)"
+ {:group "Tests & checks"
+ :doc "Checks that every shipped namespace loads without :dev dependencies (and finds circular dependencies)"
:examples [["./bin/mage load-namespaces"]]
:requires [[mage.load-namespaces]]
:arg-schema [:tuple]
:task (task! (mage.load-namespaces/load-namespaces))}
codespell
- {:doc "Check for misspellings in the source code."
+ {:group "Format & lint"
+ :doc "Check for misspellings in the source code."
:examples [["./bin/mage codespell"]]
:requires [[mage.codespell]]
:task (task! (mage.codespell/codespell (:arguments parsed)))}
codespell-interactive
- {:doc "Check for misspellings in the source code, and interactively prompt to fix them."
+ {:group "Format & lint"
+ :doc "Check for misspellings in the source code, and interactively prompt to fix them."
:examples [["./bin/mage codespell-interactive"]]
:requires [[mage.codespell]]
:task (task! (mage.codespell/codespell-interactive (:arguments parsed)))}
start-maildev
- {:doc "Start Maildev"
+ {:group "Local dev"
+ :doc "Start Maildev"
:examples [["./bin/mage start-maildev -h" "print help for start-maildev"]]
:requires [[mage.start-maildev :as start-maildev]]
:task (task! (start-maildev/start-maildev!))}
docs-preview
- {:doc "Preview the docs of a Metabase repo in your metabase-dot-com checkout, at http://localhost:4000/docs/latest/"
+ {:group "Local dev"
+ :doc "Preview the docs of a Metabase repo in your metabase-dot-com checkout, at http://localhost:4000/docs/latest/"
:examples [["./bin/mage docs-preview" "Preview the docs of this repo"]
["./bin/mage docs-preview .claude/worktrees/my-feature" "Preview the docs of a worktree (a relative path starts at this repo)"]
["./bin/mage docs-preview ~/code/other-metabase" "Preview the docs of another checkout"]
@@ -136,19 +151,22 @@
:task (task! (docs-preview/docs-preview! parsed))}
tail-d
- {:doc "Tail the #d debug log in real time (see dev.debug). Asks the running REPL for the exact path; falls back to DEV_DEBUG_LOG or /tmp/<dir>_debug.log."
+ {:group "Local dev"
+ :doc "Tail the #d debug log in real time (see dev.debug). Asks the running REPL for the exact path; falls back to DEV_DEBUG_LOG or /tmp/<dir>_debug.log."
:examples [["./bin/mage tail-d" "tail the #d log, with bat syntax highlighting if available"]]
:requires [[mage.tail-d :as tail-d]]
:task (task! (tail-d/tail-d! parsed))}
start-python-runner
- {:doc "Start python-runner container with internal Moto S3 server for Python transforms"
+ {:group "Local dev"
+ :doc "Start python-runner container with internal Moto S3 server for Python transforms"
:examples [["./bin/mage start-python-runner" "start python-runner with internal S3"]]
:requires [[mage.start-python-runner :as start-python-runner]]
:task (task! (start-python-runner/start-python-runner!))}
start-db
- {:doc "Start a db on a default port in docker"
+ {:group "Local dev"
+ :doc "Start a db on a default port in docker"
:examples [["./bin/mage start-db postgres latest" "start the latest postgres db we support"]
["./bin/mage start-db mysql oldest" "start the oldest mysql db we support"]
["./bin/mage start-db postgres latest --port 5555" "start postgres on a custom port"]]
@@ -172,7 +190,8 @@
(start-db/start-db (-> (current-task) :db-info db) db version (:options parsed))))}
nrepl
- {:doc "Starts the babashka nrepl: helpful for mage development"
+ {:group "Mage"
+ :doc "Starts the babashka nrepl: helpful for mage development"
:requires [[babashka.nrepl.server :as nrepl.server]
[mage.color :as c]]
:examples [["./bin/mage nrepl" "Starts the nrepl server"]
@@ -186,7 +205,8 @@
(deref (promise))))}
lint-migrations
- {:doc "Lint migrations files"
+ {:group "Migrations"
+ :doc "Lint migrations files"
:requires [[lint-migrations-file]
[babashka.process :as p]]
:examples [["./bin/mage lint-migrations" "Lint all migrations and print report"]]
@@ -195,7 +215,8 @@
(lint-migrations-file/-main))}
new-migration
- {:doc "Create a new version-less migration file in the current year's directory"
+ {:group "Migrations"
+ :doc "Create a new version-less migration file in the current year's directory"
:requires [[mage.new-migration :as new-migration]]
:examples [["./bin/mage new-migration mq_indexes" "Create resources/migrations/2026/20261012_mq_indexes.yaml with a random changeset id"]]
:arg-schema [:tuple
@@ -203,7 +224,8 @@
:task (task! (new-migration/new-migration parsed))}
jar-download
- {:doc "Download (and optionally run) jar for a metabase version or branch"
+ {:group "Local dev"
+ :doc "Download (and optionally run) jar for a metabase version or branch"
:examples [["./bin/mage jar-download 50" "Download the latest enterprise version of release 50 to ~/path/to/my/metabase/jars"]
["./bin/mage jar-download 1.45.2 -r" "Download and run metabase_1.45.2.jar"]
["./bin/mage jar-download 1.45.2 -d ~/path/to/my/jars" "Download metabase_1.45.2.jar to ~/path/to/my/jars, deleting if it exists"]
@@ -229,13 +251,15 @@
:task (task! (jar-download/jar-download parsed))}
setup-stats-repl
- {:doc "Connect to the stats repl"
+ {:group "Local dev"
+ :doc "Connect to the stats repl"
:examples [["./bin/mage connect-stats-repl" "Connects to the stats repl"]]
:requires [[mage.stats-repl :as stats-repl]]
:task (stats-repl/connect (cli/parse! (current-task)))}
notify
- {:doc "Send notification for a comment (that already exists)"
+ {:group "CI"
+ :doc "Send notification for a comment (that already exists)"
:requires [[mage.be-dev :refer [nrepl-eval]]]
:options [["-c" "--comment-id ID" "Notify about this comment id"]
["-p" "--port PORT" "Port to use for the task, defaults to value in .nrepl-port"]]
@@ -249,7 +273,8 @@
(nrepl-eval "metabase.comments.core" code)))}
run-tests
- {:doc "Quickly run tests locally. Pass dirs, files, namespaces, or single tests as arguments."
+ {:group "Tests & checks"
+ :doc "Quickly run tests locally. Pass dirs, files, namespaces, or single tests as arguments."
:examples [["./bin/mage run-tests" "launch interactive test picker"]
["./bin/mage run-tests test/metabase/db" "run tests in test/metabase/db"]
["./bin/mage run-tests test/metabase/logger test/metabase/api_keys" "run tests in test/metabase/logger and test/metabase/api_keys"]
@@ -267,7 +292,8 @@
:task (task! (qtr/go parsed))}
openapi-diff
- {:doc "Semantic diff of two OpenAPI specs, classified breaking-first, for the API changelog"
+ {:group "Tests & checks"
+ :doc "Semantic diff of two OpenAPI specs, classified breaking-first, for the API changelog"
:examples [["./bin/mage openapi-diff old.json new.json" "Full diff, breaking changes first"]
["./bin/mage openapi-diff old.json new.json --severity breaking" "Only what needs a changelog entry"]
["./bin/mage openapi-diff --refs release-x.63.x release-x.64.x --severity breaking" "Generate both specs from source, then diff"]
@@ -301,14 +327,16 @@
:task (task! (mage.openapi-diff/cli-diff parsed))}
openapi-staleness
- {:doc "Is the committed OpenAPI spec current relative to the API source? (a stale spec under-reports)"
+ {:group "Tests & checks"
+ :doc "Is the committed OpenAPI spec current relative to the API source? (a stale spec under-reports)"
:examples [["./bin/mage openapi-staleness"]]
:arg-schema [:tuple]
:requires [[mage.openapi-diff]]
:task (task! (mage.openapi-diff/cli-staleness parsed))}
affected-modules
- {:doc "Which backend modules have changes?"
+ {:group "Modules"
+ :doc "Which backend modules have changes?"
:examples [["./bin/mage affected-modules master" "prints changes compared to `master`"]
["./bin/mage affected-modules"]]
:arg-schema [:or [:tuple] [:tuple [:string {:name "git-ref"}]]]
@@ -316,7 +344,8 @@
:task (task! (mage.modules/cli-print-affected-modules (:arguments parsed)))}
update-codeowners
- {:doc "Rewrite the module-ownership block in .github/CODEOWNERS from the modules that set :codeowners"
+ {:group "Modules"
+ :doc "Rewrite the module-ownership block in .github/CODEOWNERS from the modules that set :codeowners"
:examples [["./bin/mage update-codeowners" "Rewrite the generated block in .github/CODEOWNERS"]
["./bin/mage update-codeowners --check" "Exit non-zero if the block is out of date (for CI)"]]
:options [[nil "--check" "Exit non-zero if CODEOWNERS is out of date instead of rewriting it"]]
@@ -324,7 +353,8 @@
:task (task! (mage.modules/cli-update-codeowners parsed))}
modules-tree
- {:doc "Print the module hierarchy, nesting enterprise extensions under their OSS module"
+ {:group "Modules"
+ :doc "Print the module hierarchy, nesting enterprise extensions under their OSS module"
:examples [["./bin/mage modules-tree" "Print the full tree; * marks a custom :ns-prefix"]
["./bin/mage modules-tree --nested-only" "Print only roots with nested modules"]
["./bin/mage modules-tree --prefixes" "Show custom prefixes instead of *"]
@@ -338,14 +368,16 @@
:task (task! (mage.modules/cli-print-module-tree parsed))}
can-skip-driver-tests
- {:doc "Can we skip driver tests for this branch?"
+ {:group "Tests & checks"
+ :doc "Can we skip driver tests for this branch?"
:examples [["./bin/mage can-skip-driver-tests master" "Returns zero (success) if we can skip driver tests based on changes related to `master`"]
["./bin/mage can-skip-driver-tests" "Returns zero (success) if we can skip driver tests based on changes? (defaults to master)"]]
:requires [[mage.modules]]
:task (task! (mage.modules/cli-can-skip-driver-tests (:arguments parsed)))}
module-history
- {:doc "Update the CSV files that track how the backend module graph changed on master, and optionally publish them. Measures only commits it has not measured before."
+ {:group "Modules"
+ :doc "Update the CSV files that track how the backend module graph changed on master, and optionally publish them. Measures only commits it has not measured before."
:examples [["./bin/mage module-history --dir ~/module-history" "Fetch master, measure its new commits, and write the CSV files and history.json"]
["./bin/mage module-history --dir ~/module-history --publish ~/module-history/publish.edn" "Then fill pages, replace Metabase uploads, refresh cards and update shares, as the EDN file says"]
["./bin/mage module-history --dir ~/module-history-ahead --ref origin/my-stack-tip" "Write the history as it would be with a branch merged: master up to where the branch left it, then the branch's commits"]
@@ -361,7 +393,8 @@
:task (task! (mage.module-history/cli-update parsed))}
fix-modules-config
- {:doc "Regenerate .clj-kondo/config/modules/config.edn so it passes metabase.core.modules-test."
+ {:group "Modules"
+ :doc "Regenerate .clj-kondo/config/modules/config.edn so it passes metabase.core.modules-test."
:examples [["./bin/mage fix-modules-config" "Fix the modules config (uses the running dev REPL if available, else a JVM)"]
["./bin/mage fix-modules-config --port 59498" "Use the dev REPL on a specific nREPL port"]]
;; Cold-JVM fallback invokes `clojure -X:dev dev.modules-config/fix-config!`.
@@ -370,7 +403,8 @@
:task (task! (mage.modules/cli-fix-config (cli/parse! (current-task))))}
project-tests
- {:doc "Run project-level checks."
+ {:group "Tests & checks"
+ :doc "Run project-level checks."
:examples [["./bin/mage project-tests" "Run every suite"]
["./bin/mage project-tests backend" "Run backend checks"]
["./bin/mage project-tests migrations" "Run migration checks"]
@@ -389,13 +423,15 @@
(project-tests/run!)))}
kondo-ratchets
- {:doc "Validate the kondo and module ratchet files against the source tree (about half a minute, most of it a kondo run over the files with a discouraged-var or discouraged-namespace ignore)."
+ {:group "Ratchets"
+ :doc "Validate the kondo and module ratchet files against the source tree (about half a minute, most of it a kondo run over the files with a discouraged-var or discouraged-namespace ignore)."
:examples [["./bin/mage kondo-ratchets" "Fail on an invalid ratchets file, an over-budget suppression, or a missing justification comment"]]
:requires [[dev.kondo-ratchet] [mage.kondo-ratchet]]
:task (task! (dev.kondo-ratchet/check {:attribute mage.kondo-ratchet/attribute-occurrences!}))}
kondo-ratchets-shrink
- {:doc "Lower kondo and module budgets to match the source tree. This is the only Mage task that writes the ratchet files."
+ {:group "Ratchets"
+ :doc "Lower kondo and module budgets to match the source tree. This is the only Mage task that writes the ratchet files."
:examples [["./bin/mage kondo-ratchets-shrink" "Lower budgets to current counts without raising over-budget entries"]
["./bin/mage kondo-ratchets-shrink --seed :some-linter" "Set :some-linter's budget to its current count when introducing the linter"]
["./bin/mage kondo-ratchets-shrink --seed :discouraged-var/clojure.core/println" "Set one discouraged symbol's budget to its current count"]
@@ -405,7 +441,8 @@
:task (task! (dev.kondo-ratchet/fix! (assoc (:options parsed) :attribute mage.kondo-ratchet/attribute-occurrences!)))}
kondo-ratchets-history
- {:doc "Report which commits and pull requests shrank, grew and introduced ratchet budgets."
+ {:group "Ratchets"
+ :doc "Report which commits and pull requests shrank, grew and introduced ratchet budgets."
:examples [["./bin/mage kondo-ratchets-history" "Summarize the last 7 days"]
["./bin/mage kondo-ratchets-history --days 30" "Summarize the last 30 days"]
["./bin/mage kondo-ratchets-history --all" "Summarize every change since the first ratchet"]
@@ -426,7 +463,8 @@
:task (task! (mage.kondo-ratchets-history/history parsed))}
kondo-redundant-ignores
- {:doc "Report inline kondo ignores that are no longer necessary (slow: full kondo run)."
+ {:group "Ratchets"
+ :doc "Report inline kondo ignores that are no longer necessary (slow: full kondo run)."
:examples [["./bin/mage kondo-redundant-ignores" "Scan the backend tree for removable ignores"]
["./bin/mage kondo-redundant-ignores --fix" "Also remove them from source (restores + marks [kondo-keep] any that re-trigger)"]
["./bin/mage kondo-redundant-ignores --fix --audit" "Recheck [kondo-keep] sites too, unmarking any now truly redundant"]]
@@ -436,7 +474,8 @@
:task (task! (mage.kondo-ratchet/redundant-ignores parsed))}
kondo-insert-ignores
- {:doc "Insert inline ignores at every site a linter flags -- for landing a new linter without a big-bang fix."
+ {:group "Ratchets"
+ :doc "Insert inline ignores at every site a linter flags -- for landing a new linter without a big-bang fix."
:examples [["./bin/mage kondo-insert-ignores :metabase/new-linter" "Insert ignores everywhere the linter fires, then seed its budget"]
["./bin/mage kondo-insert-ignores :equals-true test/metabase/pulse" "Only under the given paths"]]
:arg-schema [:sequential [:string {:name "linter-then-paths"}]]
@@ -444,13 +483,17 @@
:task (task! (mage.kondo-ratchet/insert-ignores (:arguments parsed)))}
ls
- {:doc "List all mage public and private tasks"
- :examples [["./bin/mage ls" "List all tasks"]]
+ {:group "Mage"
+ :doc "List all mage public and private tasks"
+ :examples [["./bin/mage ls" "List all tasks"]
+ ["./bin/mage ls kondo" "List tasks whose name contains 'kondo'"]]
+ :arg-schema [:or [:tuple] [:tuple [:string {:name "pattern" :description "Only list tasks whose name contains this"}]]]
:requires [[mage.util :as u]]
:task (task! (u/print-tasks parsed))}
generate-cursive-resolve-as
- {:doc "Generate XML configuration for Cursive's symbol resolution based on the current clj-kondo lint-as configuration."
+ {:group "Local dev"
+ :doc "Generate XML configuration for Cursive's symbol resolution based on the current clj-kondo lint-as configuration."
:examples [["./bin/mage generate-cursive-resolve-as" "Generate resolve-as XML configuration"]
["./bin/mage generate-cursive-resolve-as > /Users/bgrabow/Library/Application\\ Support/JetBrains/IntelliJIdea2025.3/options/ClojureResolveSettings.xml"
"Generate resolve-as XML configuration and install it in your global editor configuration"]]
@@ -458,7 +501,8 @@
:task (task! (cursive-resolve-as/do-it))}
docs-generate
- {:doc "Regenerate the docs that are built from source. The backend suite runs every Clojure generator in one JVM."
+ {:group "Local dev"
+ :doc "Regenerate the docs that are built from source. The backend suite runs every Clojure generator in one JVM."
:examples [["./bin/mage docs-generate" "Regenerate every generated doc"]
["./bin/mage docs-generate backend" "Environment variables, config template, API, AI providers, MCP tools, and CLI commands"]
["./bin/mage docs-generate usage-analytics" "Usage analytics reference"]
@@ -476,13 +520,15 @@
:task (task! (docs-generate/run! (first (:arguments parsed)) (:options parsed)))}
analytics:setup
- {:doc "Set up usage analytics development mode"
+ {:group "Analytics"
+ :doc "Set up usage analytics development mode"
:examples [["./bin/mage analytics:setup" "Enable usage analytics dev mode and import content"]]
:requires [[mage.analytics :as analytics]]
:task (task! (analytics/setup!))}
analytics:export
- {:doc "Export usage analytics content to YAML files"
+ {:group "Analytics"
+ :doc "Export usage analytics content to YAML files"
:examples [["./bin/mage analytics:export" "Export to default location (resources/instance_analytics)"]
["./bin/mage analytics:export my-custom-dir" "Export to custom directory"]]
:arg-schema [:or
@@ -494,13 +540,15 @@
(analytics/export!)))}
analytics:teardown
- {:doc "Tear down usage analytics development mode"
+ {:group "Analytics"
+ :doc "Tear down usage analytics development mode"
:examples [["./bin/mage analytics:teardown" "Remove usage analytics dev database and disable dev mode"]]
:requires [[mage.analytics :as analytics]]
:task (task! (analytics/teardown!))}
analytics:finalize
- {:doc "Export usage analytics content and tear down development mode"
+ {:group "Analytics"
+ :doc "Export usage analytics content and tear down development mode"
:examples [["./bin/mage analytics:finalize" "Export to default location and tear down"]]
:requires [[mage.analytics :as analytics]]
:task (task! (do
@@ -508,13 +556,15 @@
(analytics/teardown!)))}
doctor
- {:doc "Check your development environment for issues"
+ {:group "Tests & checks"
+ :doc "Check your development environment for issues"
:examples [["./bin/mage doctor" "Run all health checks"]]
:requires [[mage.doctor :as doctor]]
:task (task! (doctor/doctor!))}
ci-report
- {:doc "Generate a CI failure report for a PR, branch, or commit"
+ {:group "CI"
+ :doc "Generate a CI failure report for a PR, branch, or commit"
:examples [["./bin/mage ci-report" "Check current branch (PR or branch CI)"]
["./bin/mage ci-report 68292" "Generate report for PR #68292"]
["./bin/mage ci-report source-replacement" "Report for a branch by name"]
diff --git a/bin/mage.bb b/bin/mage.bb
index e6628369fc5..81dabf886b8 100755
--- a/bin/mage.bb
+++ b/bin/mage.bb
@@ -8,6 +8,7 @@
[babashka.tasks :as bt]
[bling.banner :refer [banner]]
[bling.fonts.ansi-shadow :as ansi-shadow]
+ [clojure.edn :as edn]
[clojure.string :as str]
[mage.color :as c]
[mage.util :as u]))
@@ -44,7 +45,10 @@
(flush)
(println (c/bold " ✨ Metabase Automation Genius Engine ✨"))
(println "")
- (println (u/sh (str u/project-root-directory "/bin/bb tasks")))
+ (println "The following tasks are available:\n")
+ (println (u/grouped-tasks-help (:tasks (edn/read-string (slurp (str u/project-root-directory "/bb.edn"))))
+ (u/terminal-width)))
+ (println "")
(println (tip-o-day)))
(defn- summarize-exception [^Exception e]
diff --git a/docs/developers-guide/mage.md b/docs/developers-guide/mage.md
index ddbefa0d684..6aba73d3f8a 100644
--- a/docs/developers-guide/mage.md
+++ b/docs/developers-guide/mage.md
@@ -16,11 +16,17 @@ $ ./bin/mage
The following tasks are available:
-cljfmt-staged Runs cljfmt on staged files
-kondo Runs Kondo against a file, directory, or everything we usually lint
-...
-start-db Start a db on a default port in docker
-jar-download Given a version, downloads a metabase jar
+Format & lint
+ cljfmt-staged Runs cljfmt on staged files
+ kondo Runs Kondo against a file, directory, or everything we usually lint
+ ...
+
+Local dev
+ jar-download Download (and optionally run) jar for a metabase version or branch
+ start-db Start a db on a default port in docker
+ ...
+$ ./bin/mage ls kondo
+<lists only tasks whose name contains "kondo", including private ones>
$ ./bin/mage kondo -h
<prints help for easily running kondo>
```
@@ -28,3 +34,22 @@ $ ./bin/mage kondo -h
### mage Autocomplete
Run `./bin/mage setup-autocomplete` and follow the instructions to set up autocomplete in your terminal.
+
+### Adding a task
+
+Add the task to the `:tasks` map in `bb.edn`. A public task (name not starting with `-`) needs:
+
+- `:group`: the section it appears under in `./bin/mage`. Use one of the names in `mage.util/task-groups`. If none fits, add a new name to that vector; its position sets the section order. `mage.core-test/public-task-has-group-test` fails if a public task has no `:group` or one that isn't in the vector.
+- `:doc`: put the useful part in the first sentence. The listing shows only the first sentence, cut to the terminal width. `-h` shows the full text.
+- `:examples`: `mage.core-test/bb-task-has-example-test` checks that `-h` prints them.
+
+```clojure
+ my-task
+ {:group "Local dev"
+ :doc "Does the thing. More detail that only `-h` shows."
+ :examples [["./bin/mage my-task" "Does the thing"]]
+ :requires [[mage.my-task :as my-task]]
+ :task (task! (my-task/run! parsed))}
+```
+
+Private tasks (names starting with `-`) don't need a `:group`. They are hidden from `./bin/mage` and appear in `./bin/mage ls`.
diff --git a/mage/resources/bash_alias.sh b/mage/resources/bash_alias.sh
index b1cacffe228..588844513a1 100644
--- a/mage/resources/bash_alias.sh
+++ b/mage/resources/bash_alias.sh
@@ -1,10 +1,16 @@
export MB_DIR="{{mb-dir}}"
+# the checkout you're in, else $MB_DIR:
+_mage_root() {
+ local root
+ root=$(git rev-parse --show-toplevel 2>/dev/null)
+ if [ -x "$root/bin/mage" ]; then echo "$root"; else echo "$MB_DIR"; fi
+}
# alias:
mage() {
- cd $MB_DIR && ./bin/mage "$@"
+ "$(_mage_root)/bin/mage" "$@"
}
# autocomplete:
_bb_tasks() {
- COMPREPLY=( $(compgen -W "$(bb tasks |tail -n +3 |cut -f1 -d ' ')" -- ${COMP_WORDS[COMP_CWORD]}) );
+ COMPREPLY=( $(compgen -W "$(bb --config "$(_mage_root)/bb.edn" tasks |tail -n +3 |cut -f1 -d ' ')" -- ${COMP_WORDS[COMP_CWORD]}) );
}
complete -f -F _bb_tasks mage
diff --git a/mage/resources/fish_completions.fish b/mage/resources/fish_completions.fish
index 6e34d9551f2..a456930a933 100644
--- a/mage/resources/fish_completions.fish
+++ b/mage/resources/fish_completions.fish
@@ -1,8 +1,6 @@
function __mage_complete_tasks
if not test "$__mage_tasks"
- if test -n "$MB_DIR"
- set -g __mage_tasks (cd $MB_DIR && bb tasks 2>/dev/null |tail -n +3 |cut -f1 -d ' ')
- end
+ set -g __mage_tasks (bb --config (__mage_root)/bb.edn tasks 2>/dev/null |tail -n +3 |cut -f1 -d ' ')
end
printf "%s\n" $__mage_tasks
diff --git a/mage/resources/fish_function.fish b/mage/resources/fish_function.fish
index b79c45f8275..69896c71fb2 100644
--- a/mage/resources/fish_function.fish
+++ b/mage/resources/fish_function.fish
@@ -1,4 +1,14 @@
set -x MB_DIR {{mb-dir}}
+# the checkout you're in, else $MB_DIR:
+function __mage_root
+ set -l root (git rev-parse --show-toplevel 2>/dev/null)
+ if test -x "$root/bin/mage"
+ echo $root
+ else
+ echo $MB_DIR
+ end
+end
function mage --description 'Metabase Automation Genius Engine'
- cd $MB_DIR && ./bin/mage $argv
+ set -l mage_bin (__mage_root)/bin/mage
+ $mage_bin $argv
end
diff --git a/mage/resources/zsh_alias.sh b/mage/resources/zsh_alias.sh
index 84a3c1181bb..6c9f6ec7fce 100644
--- a/mage/resources/zsh_alias.sh
+++ b/mage/resources/zsh_alias.sh
@@ -1,12 +1,18 @@
export MB_DIR="{{mb-dir}}"
+# the checkout you're in, else $MB_DIR:
+_mage_root() {
+ local root
+ root=$(git rev-parse --show-toplevel 2>/dev/null)
+ if [ -x "$root/bin/mage" ]; then echo "$root"; else echo "$MB_DIR"; fi
+}
# alias:
mage() {
- cd $MB_DIR && ./bin/mage "$@"
+ "$(_mage_root)/bin/mage" "$@"
}
# autocomplete:
_bb_tasks() {
- local matches=(`bb tasks |tail -n +3 |cut -f1 -d ' '`)
+ local matches=(`bb --config "$(_mage_root)/bb.edn" tasks |tail -n +3 |cut -f1 -d ' '`)
compadd -a matches
_files # autocomplete filenames as well
}
diff --git a/mage/src/mage/util.clj b/mage/src/mage/util.clj
index e6176060692..537862020f5 100644
--- a/mage/src/mage/util.clj
+++ b/mage/src/mage/util.clj
@@ -173,13 +173,51 @@
[& xs]
(doseq [x xs] (puget/cprint x {:width 10e30})))
-(defn print-tasks [& _]
+(def task-groups
+ "Display order for the `:group` of public tasks in bb.edn."
+ ["Format & lint" "Tests & checks" "Modules" "Ratchets" "Migrations" "Local dev" "CI" "Analytics" "Mage"])
+
+(defn- one-line
+ "First sentence of `doc`, cut to `width` chars."
+ [doc width]
+ (let [s (first (str/split (str doc) #"(?<=\.)\s"))]
+ (if (> (count s) width)
+ (str (subs s 0 (max 0 (dec width))) "…")
+ s)))
+
+(defn grouped-tasks-help
+ "Public tasks in `tasks` (the bb.edn :tasks map) as one section per `:group`, with one-line descriptions
+ fitted to `width` columns."
+ [tasks width]
+ (let [public (for [[task {:keys [group doc]}] tasks
+ :when (and (symbol? task) (not (str/starts-with? (name task) "-")))]
+ {:task (name task) :group group :doc doc})
+ name-w (apply max (map (comp count :task) public))
+ by-grp (group-by :group public)]
+ (str/join
+ "\n\n"
+ (for [group (concat task-groups (remove (set task-groups) (keys by-grp)))
+ :let [ts (sort-by :task (by-grp group))]
+ :when (seq ts)]
+ (str/join "\n"
+ (cons (c/bold (or group "Other"))
+ (for [{:keys [task doc]} ts]
+ (str " " (format (str "%-" name-w "s") task) " "
+ (one-line doc (- width name-w 4))))))))))
+
+(defn terminal-width
+ "Columns in the terminal, or 100 if `tput` can't tell."
+ []
+ (or (try (parse-long (sh "tput cols")) (catch Exception _ nil)) 100))
+
+(defn print-tasks [& [{[pattern] :arguments}]]
(let [task+descriptions (->> "bb.edn"
(str project-root-directory "/")
slurp
edn/read-string
:tasks
- (filter (fn [[task _v]] (symbol? task)))
+ (filter (fn [[task _v]] (and (symbol? task)
+ (str/includes? (name task) (or pattern "")))))
(sort-by (fn [[task _task-data]]
(let [task-name (name task)]
(if (str/starts-with? task-name "-")
diff --git a/mage/test/mage/core_test.clj b/mage/test/mage/core_test.clj
index ffc61201b38..cabb42a194b 100644
--- a/mage/test/mage/core_test.clj
+++ b/mage/test/mage/core_test.clj
@@ -68,6 +68,17 @@
(let [out (u/sh cmd)]
(is (str/includes? out "The following tasks are available:"))))))
+(deftest public-task-has-group-test
+ (doseq [[task {:keys [group]}] (:tasks (edn/read-string (slurp (str u/project-root-directory "/bb.edn"))))
+ :when (and (symbol? task) (not (str/starts-with? (name task) "-")))]
+ (testing (str task " has a :group listed in mage.util/task-groups, so `./bin/mage` shows it in a section")
+ (is (some #{group} u/task-groups)
+ (str "Task `" task "` in bb.edn has "
+ (if group (str ":group " (pr-str group) ", which is not in mage.util/task-groups.") "no :group.")
+ "\n\nTo fix, set :group to one of " (str/join ", " (map pr-str u/task-groups)) ":\n\n"
+ " " task "\n {:group " (pr-str (first u/task-groups)) "\n :doc ...}\n\n"
+ "If none fits, add a new name to mage.util/task-groups. Its position there sets the section order.")))))
+
(deftest bb-task-has-example-test
(doseq [task-name (u/public-bb-tasks-list)
cmd [(str "./bin/mage " task-name " -h")