Snider/Borg
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions
Borg/docs/cli.md
google-labs-jules[bot] c3865faf56 feat(search): Add full-text search and indexing for archives 
This commit introduces two new commands: `borg search` and `borg index`.

The `borg index` command builds a trigram index for an archive, which can be used to significantly speed up searches.

The `borg search` command allows users to search for patterns within archives. It supports regular expressions, context control, file type filtering, and result limits. The command will automatically use a pre-built index if one is available, falling back to a full scan if not.

This commit also includes:
- Unit tests for the new commands.
- Documentation for the new commands in `docs/cli.md`.
- Updates to `.gitignore` to exclude index files.
- Improvements to the test infrastructure to prevent state pollution.

Co-authored-by: Snider <631881+Snider@users.noreply.github.com>
2026-02-02 00:52:46 +00:00

3.1 KiB
Raw Blame History

CLI Usage

borg is a command-line tool for collecting repositories, websites, and PWAs into portable data artifacts (DataNodes) or Terminal Isolation Matrices.

Use borg --help and borg <command> --help to see all flags.

Top-level

  • borg --help
  • borg --version

Commands

collect

Collect and package inputs.

Subcommands:

  • borg collect github repo <repo-url> [--output <file>] [--format datanode|tim|trix] [--compression none|gz|xz]
  • borg collect github release <release-url> [--output <file>]
  • borg collect github repos <org-or-user> [--output <file>] [--format ...] [--compression ...]
  • borg collect website <url> [--depth N] [--output <file>] [--format ...] [--compression ...]
  • borg collect pwa --uri <url> [--output <file>] [--format ...] [--compression ...]

Examples:

  • borg collect github repo https://github.com/Snider/Borg --output borg.dat
  • borg collect website https://example.com --depth 1 --output site.dat
  • borg collect pwa --uri https://squoosh.app --output squoosh.dat

all

Collect all public repositories from a GitHub user or organization.

  • borg all <url> [--output <file>]

Example:

  • borg all https://github.com/Snider --output snider.dat

compile

Compile a Borgfile into a Terminal Isolation Matrix (TIM).

  • borg compile [--file <Borgfile>] [--output <file>]

Example:

  • borg compile --file Borgfile --output a.tim

run

Execute a Terminal Isolation Matrix (TIM).

  • borg run <tim-file>

Example:

  • borg run a.tim

serve

Serve a packaged DataNode or TIM via a static file server.

  • borg serve <file> [--port 8080]

Examples:

  • borg serve squoosh.dat --port 8888
  • borg serve borg.tim --port 9999

decode

Decode a .trix or .tim file back into a DataNode (.dat).

  • borg decode <file> [--output <file>] [--password <password>]

Examples:

  • borg decode borg.trix --output borg.dat --password "secret"
  • borg decode borg.tim --output borg.dat --i-am-in-isolation

index

Build a search index for an archive to speed up searches.

  • borg index <archive-file>

Example:

  • borg index my-project.dat

This will create a .borg-index directory next to the archive.

search

Search for a pattern within an archive. Uses a pre-built index if available.

  • borg search <archive-file> <pattern>

Flags:

  • --regex: Treat the pattern as a regular expression.
  • -C, --context N: Show N lines of context before and after each match.
  • --type <ext>: Filter search by file extension (e.g., go, md).
  • --max-results N: Limit the number of results returned.

Examples:

  • borg search my-project.dat "TODO:"
  • borg search my-project.dat "func.*main" --regex --type go
  • borg search my-project.dat "important" -C 3

Compression

All collect commands accept --compression with values:

  • none (default)
  • gz
  • xz

Output filenames gain the appropriate extension automatically.

Formats

Borg supports three output formats via the --format flag:

  • datanode: A simple tarball containing the collected resources. (Default)
  • tim: Terminal Isolation Matrix, a runc-compatible bundle.
  • trix: Encrypted and structured file format.