Update documentation for CLI and library usage
- Update docs/cli.md to include all current commands (all, compile, run, decode) and correct terminology (TIM). - Update docs/library.md with correct, runnable Go code examples and updated import paths. - Update docs/development.md, docs/installation.md, and docs/releasing.md to reflect the project's Go version (1.25.0). - Remove outdated "No functional changes" notes from documentation files.
This commit is contained in:
google-labs-jules[bot]
parent
89388e9c9b
commit
629a6e6464
5 changed files with 125 additions and 55 deletions
70
docs/cli.md
70
docs/cli.md
|
|
@ -16,35 +16,77 @@ Use `borg --help` and `borg <command> --help` to see all flags.
|
|||
Collect and package inputs.
|
||||
|
||||
Subcommands:
|
||||
- `borg collect github repo <repo-url> [--output <file>] [--format datanode|matrix] [--compression none|gz|xz]`
|
||||
- `borg collect github repos <org-or-user> [--output <file>] [--format ...] [--compression ...]` (if available)
|
||||
- `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
|
||||
- `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 Matrix via a static file server.
|
||||
Serve a packaged DataNode or TIM via a static file server.
|
||||
|
||||
- borg serve <file> [--port 8080]
|
||||
- `borg serve <file> [--port 8080]`
|
||||
|
||||
Examples:
|
||||
- borg serve squoosh.dat --port 8888
|
||||
- borg serve borg.matrix --port 9999
|
||||
- `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`
|
||||
|
||||
## Compression
|
||||
|
||||
All collect commands accept `--compression` with values:
|
||||
- none (default)
|
||||
- gz
|
||||
- xz
|
||||
- `none` (default)
|
||||
- `gz`
|
||||
- `xz`
|
||||
|
||||
Output filenames gain the appropriate extension automatically.
|
||||
|
||||
## Matrix format
|
||||
## Formats
|
||||
|
||||
Use `--format matrix` to produce a runc-compatible bundle (Terminal Isolation Matrix). See the Overview page for details.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -11,26 +11,26 @@ This repo includes a `go.work` file configured for Go 1.25 to align with common
|
|||
|
||||
## Build
|
||||
|
||||
- go build ./...
|
||||
- task build
|
||||
- `go build ./...`
|
||||
- `task build`
|
||||
|
||||
## Test
|
||||
|
||||
- go test ./...
|
||||
- task test
|
||||
- `go test ./...`
|
||||
- `task test`
|
||||
|
||||
Note: Some tests may require network or git tooling depending on environment (e.g., pushing to a temporary repo). No functional changes were made in this task.
|
||||
Note: Some tests may require network or git tooling depending on environment (e.g., pushing to a temporary repo).
|
||||
|
||||
## Run
|
||||
|
||||
- task run
|
||||
- ./borg --help
|
||||
- `task run`
|
||||
- `./borg --help`
|
||||
|
||||
## Docs
|
||||
|
||||
Serve the documentation locally with MkDocs:
|
||||
|
||||
- pip install mkdocs-material
|
||||
- mkdocs serve
|
||||
- `pip install mkdocs-material`
|
||||
- `mkdocs serve`
|
||||
|
||||
The site configuration lives in `mkdocs.yml` and content in `docs/`.
|
||||
|
|
|
|||
|
|
@ -6,17 +6,17 @@ Options to install:
|
|||
|
||||
- From source (requires Go 1.25 or newer):
|
||||
- Clone the repository and build:
|
||||
- go build -o borg ./
|
||||
- `go build -o borg ./`
|
||||
- Or use the Taskfile:
|
||||
- task build
|
||||
- `task build`
|
||||
|
||||
- From releases (recommended):
|
||||
- Download an archive for your OS/ARCH from GitHub Releases once you publish with GoReleaser.
|
||||
- Unpack and place `borg` on your PATH.
|
||||
|
||||
- Homebrew (if you publish to a tap):
|
||||
- brew tap Snider/homebrew-tap
|
||||
- brew install borg
|
||||
- `brew tap Snider/homebrew-tap`
|
||||
- `brew install borg`
|
||||
|
||||
Requirements:
|
||||
- Go 1.25+ to build from source.
|
||||
|
|
|
|||
|
|
@ -2,29 +2,32 @@
|
|||
|
||||
Borg can also be used as a Go library. The public API is exposed under the `pkg` directory. Import paths use the module `github.com/Snider/Borg`.
|
||||
|
||||
Note: This documentation describes usage only; functionality remains unchanged.
|
||||
|
||||
## Collecting a GitHub repo into a DataNode
|
||||
|
||||
```
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"os"
|
||||
|
||||
"github.com/Snider/Borg/pkg/datanode"
|
||||
borggithub "github.com/Snider/Borg/pkg/github"
|
||||
"github.com/Snider/Borg/pkg/vcs"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// Create a DataNode writer (uncompressed example)
|
||||
dn, err := datanode.NewFileDataNodeWriter("repo.dat")
|
||||
if err != nil { log.Fatal(err) }
|
||||
defer dn.Close()
|
||||
// Clone and package the repository
|
||||
cloner := vcs.NewGitCloner()
|
||||
dn, err := cloner.CloneGitRepository("https://github.com/Snider/Borg", nil)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
client := borggithub.NewDefaultClient(nil) // uses http.DefaultClient
|
||||
if err := borggithub.CollectRepo(client, "https://github.com/Snider/Borg", dn); err != nil {
|
||||
// Save to disk
|
||||
tarBytes, err := dn.ToTar()
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile("repo.dat", tarBytes, 0644); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
|
@ -32,21 +35,30 @@ func main() {
|
|||
|
||||
## Collecting a Website
|
||||
|
||||
```
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"github.com/Snider/Borg/pkg/datanode"
|
||||
"os"
|
||||
|
||||
"github.com/Snider/Borg/pkg/website"
|
||||
)
|
||||
|
||||
func main() {
|
||||
dn, err := datanode.NewFileDataNodeWriter("website.dat")
|
||||
if err != nil { log.Fatal(err) }
|
||||
defer dn.Close()
|
||||
// Download and package the website
|
||||
// 1 is the depth (0 = just the page, 1 = page + links on page)
|
||||
dn, err := website.DownloadAndPackageWebsite("https://example.com", 1, nil)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
if err := website.Collect("https://example.com", 1, dn); err != nil {
|
||||
// Save to disk
|
||||
tarBytes, err := dn.ToTar()
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile("website.dat", tarBytes, 0644); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
|
@ -54,21 +66,38 @@ func main() {
|
|||
|
||||
## PWA Collection
|
||||
|
||||
```
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"github.com/Snider/Borg/pkg/datanode"
|
||||
"os"
|
||||
|
||||
"github.com/Snider/Borg/pkg/pwa"
|
||||
)
|
||||
|
||||
func main() {
|
||||
dn, err := datanode.NewFileDataNodeWriter("pwa.dat")
|
||||
if err != nil { log.Fatal(err) }
|
||||
defer dn.Close()
|
||||
client := pwa.NewPWAClient()
|
||||
pwaURL := "https://squoosh.app"
|
||||
|
||||
if err := pwa.Collect("https://squoosh.app", dn); err != nil {
|
||||
// Find the manifest
|
||||
manifestURL, err := client.FindManifest(pwaURL)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Download and package the PWA
|
||||
dn, err := client.DownloadAndPackagePWA(pwaURL, manifestURL, nil)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Save to disk
|
||||
tarBytes, err := dn.ToTar()
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile("pwa.dat", tarBytes, 0644); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -11,17 +11,17 @@ This project is configured for GoReleaser.
|
|||
|
||||
Generate local artifacts without publishing:
|
||||
|
||||
- goreleaser release --snapshot --clean
|
||||
- `goreleaser release --snapshot --clean`
|
||||
|
||||
Artifacts appear under `dist/`.
|
||||
|
||||
## Full release
|
||||
|
||||
1. Tag a new version:
|
||||
- git tag -a v0.1.0 -m "v0.1.0"
|
||||
- git push origin v0.1.0
|
||||
- `git tag -a v0.1.0 -m "v0.1.0"`
|
||||
- `git push origin v0.1.0`
|
||||
2. Run GoReleaser:
|
||||
- GITHUB_TOKEN=... goreleaser release --clean
|
||||
- `GITHUB_TOKEN=... goreleaser release --clean`
|
||||
|
||||
This will:
|
||||
- Build binaries for multiple OS/ARCH
|
||||
|
|
@ -31,4 +31,3 @@ This will:
|
|||
|
||||
## Notes
|
||||
- The Go toolchain version is 1.25 (see go.mod and go.work).
|
||||
- No functional changes were made as part of this task; configuration and documentation only.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue