The gitsocial command line has global flags, core commands, an import command, scripting support, exit codes and environment variables.
Command Structure · Core Commands · Import · Scripting · Reference Format · Exit Codes · Environment Variables
gitsocial [--json] <command> [subcommand] [args] [flags]--help on a command shows all its flags. Global flags:
--json - JSON output--workdir, -C <path> - run in another directory--cache-dir <path> - cache directory (default ~/.cache/gitsocial)--help, --version| Extension | Doc | Covers |
|---|---|---|
social | SOCIAL.md | posts, comments, lists, timeline, followers |
pm | PM.md | issues, milestones, sprints, boards |
review | REVIEW.md | pull requests, feedback, forks |
release | RELEASE.md | releases, artifacts, SBOM |
memo | MEMO.md | memos across tiers |
Each extension has init, status and config, and memo has one init for each tier. Content is on gitmsg/<extension>, and only social init takes -b to name another branch.
Shows the repository, the cache, and each extension's branch, last fetch and item counts.
gitsocial statusFetches followed repositories, registered forks and identity bindings, then reports unread notifications.
gitsocial fetch # everything
gitsocial fetch <url> # one repository
gitsocial fetch --list reading # one listThe first fetch in a workspace asks whether to track the default branch only or every upstream branch. --all-branches, --json or a non-interactive stdin answer without asking. The answer is saved per workspace.
Sends the gitmsg/* branches, state refs, tags, the default branch when it is ahead, and the heads of open pull requests to each resolved remote. A push to an s3 remote with site.publish then rebuilds the site. Flags and remote resolution are in S3.md.
gitsocial push [remote...]
gitsocial push --dry-run # print the plan, send nothing
gitsocial push --site-only # rebuild the site, send no refsShows the site of the workspace in a browser. It starts a loopback bucket in the process, pushes the workspace to it and serves the site app from the bucket. A change to a branch, a tag or a state ref pushes again, and a failed push keeps the last build served. The site has no HTML pages. Ctrl-C stops it.
gitsocial serve # serving http://127.0.0.1:4747/gitsocial/<repo>/
gitsocial serve --addr 127.0.0.1:8080| Item | Value |
|---|---|
| bucket root | ~/.cache/gitsocial/serve/<hash>/, kept between runs |
| remote | gitsocial-serve, in the environment of the serve process; no git config is written |
| push | forced: a rewritten branch, tag or state ref replaces that of the bucket, and no merge is written to the workspace |
| git hooks | not run: core.hooksPath is the null device in the environment of the serve process |
| poll | git for-each-ref refs/heads refs/tags refs/gitmsg every 2 s; one push at a time |
| tracking refs | refs/remotes/gitsocial-serve/* and refs/gitsocial/tracking/gitsocial-serve/*, deleted on exit and written again from the bucket at the next start |
Mirrors a forge-hosted project into a bucket: fetch from the forge, import issues, pull requests, releases and discussions, then push data and code, and rebuild the site. Run it again, or from cron, to refresh the mirror; a run that stops before it completes continues at the next run.
gitsocial mirror <forge-url> <s3-url> --url <public-url> # cold start: clone, import, push
gitsocial mirror <s3-url> # in a workspace: attach the bucket, import, push
gitsocial mirror # refresh
gitsocial mirror --dry-run <forge-url> <s3-url> # the provider checklist and the planorigin, and the bucket is a second remote. All upstream branches are mirrored, unless you give --default-branch-only.--url sets site.url and turns the HTML pages on. -n sets the maximum number of items for each type on import. -y skips all prompts, and missing credentials then cause an error that names the gitsocial config credentials set command.git clone with s3:// support: it normalizes provider URLs and writes the helper alias to the local config of the clone, so plain git works in the clone.
gitsocial clone <url> [directory]gitsocial remote add [name] <url> [--default] [--site] # --default adds it to gitsocial.pushRemote; --site sets site.publish
gitsocial remote default [name...] # set the default push remotes, or print the current resolution
gitsocial remote put <key> <file> [--remote <name>] # upload one file to the bucket root, e.g. an installeradd normalizes an s3 URL; the accepted forms are in S3.md. Any other URL is added as an ordinary git remote.
Core configuration in refs/gitmsg/core/config, the site keys, and the credential store.
gitsocial config get <key> | set <key> <value> | list
gitsocial config site set <key> <value> # see STATIC-SITE.md
gitsocial config credentials set <host> # see S3.mdUser settings, stored in the personal bare repository and synced between machines with gitsocial personal sync. Keys are in SETTINGS.md.
gitsocial settings get <key> | set <key> <value> | listlist prints each key, its value, and the key's description on the line below:
fetch.parallel = 4
Concurrent fetch workers.
fetch.timeout = 30
Per-repo fetch timeout in seconds.
fetch.workspace_mode = (per-repo)--json adds a description field, left out for a key the registry does not carry.
The personal bare repository that holds settings and personal-tier memos. See SETTINGS.md.
gitsocial personal init [--remote <url>]
gitsocial personal sync [--push-only | --fetch-only]
gitsocial personal statusRegisters other repositories as forks of this one. Issues and pull requests of a fork appear here, and when you change one, GitSocial adopts it into this repository. An edit to an item of a different repository stays a proposal until its owner accepts it.
gitsocial fork add <url>
gitsocial fork remove <url>
gitsocial fork list
gitsocial fork create <destination> # fork on a forge or a bucket, clone it, wire origin and upstreamForks are for two-way collaboration on the same items. Lists (gitsocial social list) are for one-way following. A repository can be both.
gitsocial explore [--list <name>] [--limit <n>] # cached repositoriesgitsocial related <repository> # repositories sharing lists or authors with itActivity log of this repository, or of the timeline with --scope timeline.
gitsocial log [--type post,comment] [--after <date>] [--author <email>] [--limit <n>]Search across every extension, with per-type filters and grouping.
gitsocial search "query"
gitsocial search --type pr --state open --json
gitsocial search --type issue --labels bug --assignee [email protected]
gitsocial search --type pr --group-by state --count-only--type takes post, comment, repost, quote, pr, issue, milestone, sprint, release or memo. An inline prefix in the query sets the same filters; the flag has priority.--scope takes timeline, the default, list:<name> or repository:<url>. --sort takes score, the default, or date.--group-by takes state, author, type, extension, repo, label, assignee, reviewer, milestone or base. --top sets the maximum number of items for each group, and --count-only prints only the counts.--assignee, --milestone and --sprint imply --type issue. --reviewer, --draft and --base imply --type pr. --prerelease and --tag imply --type release.--tier applies to --type memo and takes session, personal, project, inherited or external.Inline prefixes, in the order the parser reads them:
| Prefix | Filters by |
|---|---|
author:<email> | author name or email |
repo:<url> | repository URL |
repository:<url> | repository URL, the long form of repo: |
type:<type> | item type, the values --type takes |
hash:<prefix> | commit hash prefix |
commit:<prefix> | commit hash prefix, the long form of hash: |
list:<name> | list name or ID |
after:<YYYY-MM-DD> | items after the date |
before:<YYYY-MM-DD> | items before the date |
assignee:<email> | assignee email, or a part of it; implies type:issue |
reviewer:<email> | reviewer email, or a part of it; implies type:pr |
label:<name> | a label, without case; a comma-separated list matches any |
labels:<name> | the same as label:, the name of the flag |
A token with any other prefix is text, not a filter: state:open searches for "state:open". Any space character ends a value.
gitsocial show <ref> # any item; the extension is detectedgitsocial history <ref> # the edit history of any messagegitsocial notifications [--all] [--type mention,follow] [--limit <n>]
gitsocial notifications count
gitsocial notifications read <id> | read-all
gitsocial notifications unread <id> | unread-allSignature verification and identity resolution. The trust model is in IDENTITY.md.
gitsocial id verify <commit>
gitsocial id resolve <email>The domain source is off by default. To enable it, run gitsocial settings set identity.dns_verification true.
gitsocial tuiKeys are in TUI-KEYS.md.
JSON-RPC over stdio for editor integration. See RPC.md.
gitsocial rpcgitsocial docs keybindings [--json]gitsocial import copies issues, milestones, releases, pull requests and discussions from a forge into the extensions. The origin remote is the default source. Re-running skips what is already imported.
gitsocial import [url] # everything: pm, release, review, social, in that order
gitsocial import pm [url] # milestones, issues and their comments
gitsocial import release [url] # releases and artifact metadata
gitsocial import review [url] # fork registrations, pull requests and their comments
gitsocial import social [url] # discussions and their comments
gitsocial import pm --state open --limit 100 --dry-runhttps://github.com/org/repo, [email protected]:org/repo.git or github.com/org/repo.gh CLI, GitLab through its REST API. Discussions come from GitHub only. Other hosts are detected but not imported.--host forces the host type, --api-url overrides the instance the URL names, --token overrides the platform CLI's token.GITLAB_TOKEN, then GITLAB_PRIVATE_TOKEN, when --token is not given.--update applies the changes on the forge to the items that are already imported. --labels auto|raw|skip controls label mapping. --email-map <file> maps usernames to emails. --skip-bots is on by default.base-tip and head-tip from the forge's commit ids, and from local branches only when the forge gives none. --update records the new tips of a pull request whose ids changed, also when nothing else changed.~/.cache/gitsocial/imports/<url-slug>.json maps platform ids to commit hashes; --map-file overrides it.gitsocial pm issue list --labels kind/wontfix --json | jq -r '.[].id' | xargs -I {} gitsocial pm issue close {}
gitsocial review pr list --json | jq -e 'length > 0' >/dev/null && echo "PRs pending review"
echo "Hello world" | gitsocial social post - # stdin as the body
cat CHANGELOG.md | gitsocial release create -References follow GITMSG.md §1.3:
#commit:abc123456789@main - a commit; a hash prefix (abc123) also works when it is not ambiguous#branch:main, #tag:v1.0.0#file:src/auth.go@main, #file:src/auth.go@main:L42, #file:src/auth.go@main:L42-50, #file:src/auth.go@main:v1.0.0https://github.com/user/repo#commit:abc123456789@main - a reference in another repository| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Permission denied |
| 4 | Network error |
| 5 | Not a git repository |
| Variable | Purpose |
|---|---|
XDG_CONFIG_HOME | config root, default ~/.config; gitsocial uses <root>/gitsocial |
GITSOCIAL_PERSONAL_REPO | path of the personal bare repository, default ~/.config/gitsocial/personal |
GITSOCIAL_EDITOR | editor for messages; if it is not set, gitsocial uses $EDITOR, $VISUAL, then vi |
GM_PAGER | pager for output; if it is not set, gitsocial uses $PAGER |
GITSOCIAL_PPROF | cpu, mem or trace: write a profile to /tmp/gitsocial-cpu.pprof, /tmp/gitsocial-mem.pprof or /tmp/gitsocial.trace on exit |
TERM_PROGRAM | read by the TUI; Apple_Terminal widens the layout margin |
| S3 credentials, endpoints and tuning | see S3.md |