KtsuTools

A unified developer tools suite consolidating multiple ktsu-dev utilities into a single CLI application.

Introduction

KtsuTools collects a number of standalone ktsu-dev utilities behind one ktools command with a consistent user experience powered by Spectre.Console. Instead of installing and remembering a separate tool per task, each utility becomes a command group under a single CLI.

The suite is organised as one module per capability, each shipped as its own ktsu.KtsuTools.* package, with ktsu.KtsuTools.Core providing the shared command infrastructure.

Installation

git clone https://github.com/ktsu-dev/KtsuTools.git
cd KtsuTools
dotnet build

Usage

ktools <command> [options]

Run ktools --help for the full command list, or ktools <command> --help for a specific command's options.

ktools git runs one git command in every repository beneath a directory, so the directory itself doesn't have to be a repository. Repositories are never descended into, so pointing it at a repository runs the command only there.

ktools git status                      # every repo under the current directory
ktools git --path c:/dev -- fetch --prune

Flags belong after a -- separator, otherwise ktools claims them as its own options.

ktools repo fetch is the read-only way to survey a workspace. It updates remote-tracking refs and reports how far each repository has drifted from its upstream, without the merge and --autostash that ktools repo pull performs, so it is safe to run over dirty working trees.

ktools repo fetch --path c:/dev/ktsu-dev

Repositories are fetched concurrently; pass --sequential to fetch them one at a time. Each row shows ↑n ↓n for a diverged branch, ≡ when it matches its upstream, and — when it has none.

ktools repo list shows what repo discover actually found — each cached repository and the solutions inside it. It reads the cache rather than walking the filesystem again, so it returns immediately. Pass --refresh to re-walk and rewrite the cache; an empty cache is walked anyway, since there would be nothing to show otherwise.

ktools repo list
ktools repo list --format json        # stable output for piping
ktools repo list --refresh --path c:/dev/ktsu-dev

A cached solution that no cached repository contains is reported separately rather than dropped.

ktools repo validate checks the cached repository and solution paths created by repo discover, reports stale entries, and prunes them. Use --dry-run to preview without pruning.

ktools sync commits onto whatever branch each repository has checked out, which across a workspace of thirty repositories means thirty commits on thirty mains. Pass --branch <NAME> to commit onto a dedicated branch instead: it is created at the current HEAD where it does not exist and reused where it does, and every repository is returned to the branch it was on once the run finishes.

ktools sync --path c:/dev/ktsu-dev --filename .editorconfig --branch sync/editorconfig

With --auto-push, a --branch run pushes that branch and sets its upstream, so the sync lands somewhere a pull request can be opened from rather than on the default branch.

--path assumes every repository you want to sync sits under one parent, and that everything under that parent should be synced. Where neither holds, name the repositories instead, with --repo repeated or comma-separated, or with --repo-list pointing at a file of paths one per line:

ktools sync --repo c:/dev/ktsu-dev/Semantics --repo c:/dev/3k/Engine --filename .editorconfig
ktools sync --repo-list c:/dev/ktsu-repos.txt --filename .editorconfig

A list file ignores blank lines and # comments, and resolves a relative entry against its own directory. --path keeps working unchanged and combines with both, so a workspace scan can be topped up with clones from elsewhere, and a file reached through two roots is still synced once.

--exclude drops directories from the scan, which is what keeps third-party clones inside a workspace out of a --path run. A bare name excludes every directory so named; a path excludes that one directory:

ktools sync --path c:/dev --exclude third-party,node_modules --filename .editorconfig

Pass --pr to open that pull request in each repository the branch was pushed to, which is what turns a thirty-repository sync into something reviewable rather than thirty branches waiting for someone to raise them by hand.

ktools sync --path c:/dev/ktsu-dev --filename .editorconfig --branch sync/editorconfig --auto-push --pr

--pr requires --branch, since there is nothing to open a pull request from when sync commits onto the checked-out branch. Each pull request targets the branch that repository was on before the sync, and its body records every synced file and the version it was brought to. The gh CLI is used when it is installed, because it carries your own credentials; otherwise the GitHub API is used with a token from GH_TOKEN or GITHUB_TOKEN. A repository whose remote is not on GitHub is named and skipped rather than failing the run, and a branch that already has an open pull request is left alone.

A real sync run means retyping the same long filename list every time, so sync-config saves one under a name, on the same ktsu.AppDataStorage path as saved merge batches rather than in a second config format.

ktools sync-config save org-shared c:/dev/ktsu-dev --filename .editorconfig,.gitignore --branch sync/shared
ktools sync --config org-shared

sync-config list, sync-config show <name> and sync-config delete <name> round out the verbs, matching merge-batch. Flags given alongside --config override the saved values, so ktools sync --config org-shared --filename Directory.Build.props reuses the saved path and branch for a one-off file. The two boolean flags are the exception: an absent --auto-push or --pr is indistinguishable from one passed as false, so they can only turn a saved false on. Save a second configuration for the quieter run.

Command Groups

Group	Module	What it does
git	KtsuTools.Repo	Run one git command in every repository under a directory
repo	KtsuTools.Repo	Cross-repository git operations — discover, list, validate, build, fetch, pull, update-packages
packages	KtsuTools.Packages	NuGet package maintenance — update-packages, migrate-cpm
dedup	KtsuTools.FileDedupe	Duplicate file detection and removal — scan, dry-run, dedupe, stats
merge-batch	KtsuTools.Merge	Iterative multi-version file merging — merge, merge-history
sync	KtsuTools.Sync	Synchronize shared file contents across directories — sync, sync-config
markdown	KtsuTools.Markdown	Markdown processing and linting — lint
memfrag	KtsuTools.MemFrag	Memory fragmentation analysis
project	KtsuTools.Project	Project and solution operations — build, clean
codegen	KtsuTools.CodeGen	Generates C#, C++, JavaScript or Python from a YAML syntax tree, through ktsu.Coder
image	KtsuTools.Image	Batch image processing and icon normalization
explorer	KtsuTools.FileExplorer	Interactive file browsing
build-monitor	KtsuTools.BuildMonitor	CI/CD build status monitoring
machine-monitor	KtsuTools.Machine	Local machine resource monitoring
svn-migrate	KtsuTools.SvnMigrate	Guided Subversion to Git migration

Related Tools

For per-repo release automation — semver bumps, changelog generation, publishing, and package manifest emission — see KtsuBuild. KtsuTools focuses on cross-repo orchestration; KtsuBuild handles the inside-one-repo release workflow. The two are complementary and intentionally not merged.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.