resulgit

A powerful command-line interface (CLI) tool for version control system operations.

Installation

npm install -g resulgit

Or install locally:

npm install resulgit

Uninstall

npm uninstall -g resulgit

Uninstall runs a preuninstall cleanup that:

1. Best-effort revokes the Gitu server session (POST /api/auth/logout)
2. Clears local auth fields in ~/.resulgit/config.json (token, authMethod, tokenExpiresAt) while keeping server and workspaceRoot
3. Strips JWT copies from known repositories (.vcs-next/remote.json, .git/vcs-next.json, .git/config, workspace .vscode/settings.json)

Deleting the package folder by hand does not run this hook — use npm uninstall (or run resulgit auth logout first).

Usage

resulgit <command> [options]
gitu <command> [options]

resulgit and gitu are equivalent aliases for the same CLI.

Commands

Authentication

• resulgit auth set-token --token <token> - Set authentication token (valid for 90 days)
• resulgit auth set-server --server <url> - Set server URL
• resulgit auth login --email <email> --password <password> - Login with password
• resulgit auth sso / resulgit auth login --sso - Login with SSO (browser + localhost callback)
• resulgit auth sso --device - Headless/device SSO (Gitu-hosted user code; open the printed URL on any browser)
• resulgit auth logout [--idp] - Revoke Gitu session and clear local token (--idp also opens IdP logout)
• resulgit auth status [--json] - Show auth method, expiry, and session validity
• resulgit auth refresh - Sliding session renew (new Gitu JWT if DB session still valid; no IdP)
• resulgit auth register --username <name> --email <email> --password <password> - Register new account

SSO notes

1. Register IdP redirect URI: {APP_URL}/api/auth/sso/cli/callback (see docs/sso-idp-registration.md).
2. Tokens are stored in ~/.resulgit/config.json (token, authMethod, tokenExpiresAt) with file mode 0600 on Unix.
3. SSO logins do not embed the JWT into .vcs-next/remote.json; the CLI uses the global config token at runtime.
4. Session lifetime matches the server (90 days). Use resulgit auth refresh to slide the window, or resulgit auth sso after revoke/expiry.
5. Break-glass: complete web SSO, copy the JWT, then resulgit auth set-token --token <jwt>.
6. Deploy checklist: docs/sso-deploy-checklist.md.

Repository Management

• resulgit repo list - List all repositories
• resulgit repo create --name <name> [--description <text>] [--visibility <private|public>] - Create new repository
• resulgit repo log --repo <id> [--branch <name>] - View commit log
• resulgit repo head --repo <id> [--branch <name>] - Get HEAD commit
• resulgit repo select - Interactive repository selection

Clone & Workspace

• resulgit clone --repo <id> --branch <name> [--dest <dir>] - Clone a repository
• resulgit workspace set-root --path <dir> - Set workspace root directory

Branch Operations

• resulgit branch list - List all branches
• resulgit branch create --name <branch> [--base <branch>] - Create new branch
• resulgit branch delete --name <branch> - Delete a branch
• resulgit switch --branch <name> - Switch to a branch
• resulgit checkout --branch <name> - Checkout a branch

File Operations

• resulgit status - Show working directory status
• resulgit diff [--path <file>] [--commit <id>] - Show differences
• resulgit add <file> [--content <text>] [--all] - Add files
• resulgit rm --path <file> - Remove files
• resulgit mv --from <old> --to <new> - Move/rename files
• resulgit restore --path <file> [--source <commit>] - Restore file from commit

Version Control

• resulgit commit --message <text> - Create a commit
• resulgit push - Push changes to remote (validates auth, repo write access, branch protection, and remote tip before upload)
• resulgit pull - Pull changes from remote
• resulgit merge --branch <name> [--squash] [--no-push] - Merge branches
• resulgit cherry-pick --commit <id> [--branch <name>] [--no-push] - Cherry-pick a commit
• resulgit revert --commit <id> [--no-push] - Revert a commit
• resulgit reset [--commit <id>] [--mode <soft|mixed|hard>] - Reset to commit

Stash Operations

• resulgit stash or resulgit stash save [--message <msg>] - Save changes to stash
• resulgit stash list - List all stashes
• resulgit stash pop [--index <n>] - Apply and remove stash
• resulgit stash apply [--index <n>] - Apply stash without removing
• resulgit stash drop [--index <n>] - Delete a stash
• resulgit stash clear - Clear all stashes

Tags

• resulgit tag list - List all tags
• resulgit tag create --name <tag> [--branch <name>] - Create a tag
• resulgit tag delete --name <tag> - Delete a tag

Pull Requests

• resulgit pr list - List pull requests
• resulgit pr create --title <title> [--source <branch>] [--target <branch>] - Create pull request
• resulgit pr merge --id <id> - Merge a pull request

Information

• resulgit current - Show current repository and branch
• resulgit head - Show HEAD commit ID
• resulgit show --commit <id> - Show commit details

Global Options

• --server <url> - Override default server
• --token <token> - Override stored token
• --json - Output in JSON format
• --dir <path> - Specify working directory

Examples

# Login to server
resulgit auth login --email [email protected] --password mypassword

# List repositories
resulgit repo list

# Clone a repository
resulgit clone --repo 123 --branch main

# Check status
resulgit status

# Create and commit changes
resulgit add file.txt --content "Hello World"
resulgit commit --message "Add file.txt"
resulgit push

# Create a branch
resulgit branch create --name feature-branch

# Merge branches
resulgit merge --branch feature-branch

Configuration

Configuration is stored in ~/.resulgit/config.json (mode 0600 on Unix). You can set:

• server: Default server URL
• token: Authentication token (Gitu JWT)
• authMethod: sso | password | token
• tokenExpiresAt: ISO timestamp from the JWT exp claim
• workspaceRoot: Default workspace directory

License

MIT