Sign in

Search issue titles and bodies, change requests and comments. Private repositories you cannot read are not included.
vole
Clone

Read only, no credentials:

https://rodent.software/git/vole.git

Write over SSH with a registered key:

git clone ssh://git@0.0.0.0:2222/vole.git

A free and open-source forge that lives in your Git repo.

Docs: rewrite the README and organize the guides

520470e19cd906bd6fff987e2d132d793ce56486 · Keenan Nemetz · 16d ago · parent c5902451 

Docs: rewrite the README and organize the guides

Replace the long README with a landing page, split feature details into focused guides, and remove the roadmap and spike notes. Update comments that referenced them.

docs/cli.md +152

@@ -0,0 +1,152 @@
1 # CLI reference
2
3 The command line is Vole's admin interface. That is deliberate: if you can run
4 Vole on the machine, you are the operator. There is no separate admin panel to
5 secure or keep in sync.
6
7 Run `vole help` for the built-in summary. If you make a usage mistake, Vole exits
8 with code `129`, just like Git.
9
10 ## Common options
11
12 | Option | Used by | Meaning |
13 |---|---|---|
14 | `--config <path>` | Commands that read local settings | Use a different `vole.toml` (default `vole.toml`) |
15 | `--remote <name>` | Issue, request, release, and pages commands | Git remote that points at the instance (default `origin`) |
16 | `--no-push` | `issue`, `request` | Commit locally without pushing |
17 | `--dir <path>` | `init`, `workflow`, `runner` | Working or checkout directory |
18 | `--branch <name>` | `pages` | Site branch (default `pages`) |
19 | `--format <fmt>` | `issue list` | Output fields such as `%(id)` and `%(title)` |
20 | `-h`, `--help` | All | Print usage |
21
22 Options follow Git's conventions: `--long value`, `--long=value`, `-o value`,
23 `-ovalue`, repeated options, and `--` to end option parsing. Options may appear
24 before or after arguments.
25
26 ## Instance
27
28 ```sh
29 vole init [--dir <path>]
30 vole serve [--config <path>] [--log debug]
31 vole version
32 ```
33
34 ## Users
35
36 ```sh
37 vole user create <name>
38 vole user add-key --key <file|-> <name|id>
39 vole user rm-key <name|id> <fingerprint>
40 vole user rename <name|id> <new-name>
41 vole user retire <name|id>
42 vole user list
43 vole user backup <path>
44 vole whoami [--id] [--remote <name>]
45 ```
46
47 See [Users and access](users-and-access.md).
48
49 ## Repositories
50
51 ```sh
52 vole repo create --owner <user> <name> [--description <text>]
53 vole repo list
54 vole repo rename <old> <new>
55 vole repo delete <name>
56 ```
57
58 New repositories are private. The owner becomes the first admin.
59
60 ## Access
61
62 ```sh
63 vole acl show <repo>
64 vole acl set <repo> <user> <none|read|write|admin>
65 vole acl default <repo> <none|read|write|admin>
66 vole acl protect <repo> <ref-pattern>...
67 vole acl approvals <repo> <n>
68 vole acl checks <repo> <on|off>
69 vole acl runners <repo> [<user>...] [--add <user> | --remove <user> | --clear]
70 ```
71
72 See [Users and access](users-and-access.md) and [CI](ci.md).
73
74 ## Issues
75
76 ```sh
77 vole issue new --title <title> [-m <text> | -F <file>] [-l <label>]... [-a <user>]...
78 vole issue comment <id> [-m <text> | -F <file>]
79 vole issue edit-comment <id> <comment-id> [-m <text> | -F <file>]
80 vole issue rm-comment <id> <comment-id>
81 vole issue edit <id> [--title <title>] [-m <text> | -F <file>] [-l <label>]... [-a <user>]... [--unassign <user>]...
82 vole issue assign <id> <user>...
83 vole issue unassign <id> <user>...
84 vole issue close <id>
85 vole issue reopen <id>
86 vole issue list [--state open|closed|all] [-l <label>]... [--assignee <user>]... [--format <fmt>]
87 vole issue show <id>
88 ```
89
90 Ids and comment ids accept a unique prefix. See [Issues](issues.md).
91
92 ## Change requests
93
94 ```sh
95 vole request new --title <title> --base <branch> [--head <rev>] [-m <text> | -F <file>]
96 vole request list [--state open|closed]
97 vole request show <id>
98 vole request comment <id> [-m <text> | -F <file>] [--path <file> --line <n> [--side new|old]]
99 vole request edit-comment <id> <comment-id> [-m <text> | -F <file>]
100 vole request rm-comment <id> <comment-id>
101 vole request update <id> --head <rev>
102 vole request approve <id> [--as <user>]
103 vole request close <id>
104 vole request reopen <id>
105 ```
106
107 `request` also accepts `requests` and `cr` as aliases. An approval is only accepted
108 from the account it names. See [Change requests](change-requests.md).
109
110 ## Releases
111
112 ```sh
113 vole release create <tag> (-m <text> | -F <file|->)
114 vole release attach <tag> <file>... [--remote <name>]
115 ```
116
117 `create` writes the annotated tag in the current repository; push it with
118 `git push --follow-tags`. See [Releases](releases.md).
119
120 ## Pages
121
122 ```sh
123 vole pages deploy [<dir>] [--branch <name>] [-m <text>] [--dry-run] [--remote <name>]
124 vole pages status [--branch <name>] [--remote <name>]
125 vole pages unpublish [--branch <name>] [--remote <name>]
126 ```
127
128 See [Sites](sites.md).
129
130 ## CI
131
132 ```sh
133 vole runner --remote <ssh-url> [--once] [--dir <path>] [--repos <name>]... [--label <name>]...
134 vole workflow check [--dir <path>]
135 vole workflow list [--dir <path>]
136 ```
137
138 See [CI](ci.md).
139
140 ## Maintenance
141
142 ```sh
143 vole gc [--dry-run] [--grace <duration>]
144 vole index rebuild
145 ```
146
147 See [Operations](operations.md).
148
149 ## Internal
150
151 `vole hook pre-receive|post-receive` is installed in repositories by Vole. It is
152 not intended to be run by hand.