122 lines
5.6 KiB
Markdown
122 lines
5.6 KiB
Markdown
# CLI reference
|
|
|
|
In this document, you will find all there is to know about the `forgehook` CLI interface. If you are looking to develop another database for forgehook, this is the reference documentation you're looking for!
|
|
|
|
**TODO**: Investigate return codes that would not collide with one another because of command nesting + investigate semantic codes (eg. 1=repo not found, 2=noperm 3=dberror etc..)
|
|
|
|
`forgehook` accepts a number of subcommands, which are detailed in this document. When no command is supplied, the `list` command is implied:
|
|
|
|
- [help](#help) provide help to the user
|
|
- [list](#list) list user's current subscriptions, or a repository's current subscribers
|
|
- [add](#add) register or subscribe to a remote
|
|
- [remove](#remove) (alias: `rm`) unsubscribe, or remove a repository you own
|
|
- [subscribe](#subscribe) (alias: `sub`) subscribe to a repository
|
|
- [unsubscribe](#unsubscribe) (alias `unsub`) unsubscribe from a repository
|
|
- [secret](#secret) view/update the secret for a repository you own
|
|
|
|
The opposite of `add` is `remove`. The opposite of `subscribe` is `unsubscribe`. Subscribe automatically implies Add, and vice-versa. Remove only means unsubscribe unless the `--force` flag is passed, but unsubscribe never implies Remove.
|
|
|
|
**Returns**: `forgehook` always returns the return code of its command run, unless the command was not found in which case `32` is returned (reserved code).
|
|
|
|
In the following reference, we use the following conventions:
|
|
|
|
- `$r` is a repository URL
|
|
- `$rhex` is the same URL, hex-encoded
|
|
- `$s` is a secret
|
|
- `$u` is the real user running `forgehook`
|
|
|
|
## help
|
|
|
|
`help` command takes no further argument, and prints a friendly help message.
|
|
|
|
**Returns**: `0`, always
|
|
|
|
## list
|
|
|
|
`list` lists the current user's subscriptions, or the list of users subscribed to a repository.
|
|
|
|
When no argument is passed, `forgehook list` prints the user's current subscriptions, with one line per repository. Each line contains, separated by tabulations (`\t`):
|
|
|
|
- the remote URL
|
|
- (for owners) the remote's secret
|
|
- (for owners who unsubscribed to the remote) a literal `x`
|
|
|
|
Example:
|
|
|
|
```
|
|
$ forgehook list
|
|
https://tildegit.org/southerntofu/git-build.sh 20cd982ebc2d8dbe37259e6d860dc4a83105510f80342083a4bf407cacc66283
|
|
```
|
|
|
|
When `$r` is passed as argument, `forgehook list REPO` prints one line per subscriber, each containing the subscriber's name.
|
|
|
|
```
|
|
$ forgehook list https://tildegit.org/southerntofu/git-build.sh
|
|
southerntofu
|
|
```
|
|
|
|
**Returns**: `0` on success, `1` when the URL passed as argument does not match a known repository
|
|
|
|
## add
|
|
|
|
`add` command takes `$r` and optionally `$s`. The command does the following:
|
|
|
|
1. If the repository is already claimed by someone on the machine, exit with code `1` (TODO)
|
|
2. Ensure the repository $r is clonable, otherwise exit with code `2` (TODO)
|
|
2. **TODO**: Here is where we introduce additional authentication steps to prevent accidentally claiming a repository you do not own
|
|
3. Register `$u` as owner for `$r`
|
|
4. If a secret `$s` was provided, save it. Otherwise, generate a random hexadecimal secret
|
|
5. Print the current secret
|
|
6. Subscribe `$u` to `$r` (usually through the `subscribe` command)
|
|
7. Exit with `0` (subscription should not fail because we ensure its conditions)
|
|
|
|
**Returns**: `0` on success, `1` when the repository is already claimed, `2` when the repository was not understood to be such
|
|
|
|
## remove
|
|
|
|
`remove` command takes a `$r` and an optional `-f` or `--force` flag. When the forge flag is set, the command removes all subscriptions to a given repository `$u` owns, and deletes associated secret and ownership information. Otherwise, it is equivalent to `unsubscribe`:
|
|
|
|
1. Ensure repository `$r` is known, otherwise exit with `1`
|
|
2. If the force flag is not set
|
|
1. If `$u` owns `$r`, inform the user about the `--force` flag
|
|
2. Unsubscribe `$u` from `$r` and exit with `0` when this is successful, `2` otherwise
|
|
3. Otherwise, if the force flag is set
|
|
1. If `$u` does not own `$r`, print an error an exit with `3`
|
|
2. Unsubscribe all subscribers from `$r` (cannot fail)
|
|
3. Delete secret and ownership info for `$r` and exit with `0` on success, `4` otherwise
|
|
|
|
Unless the force flag is set, the user is warned that removing the remote they own (and the associated secret) would break stuff for other users, but they are still informed on how to proceed.
|
|
|
|
**Returns**: `0` on success, `1` when the repository is unknown, `2` when unsubscription was unsuccessful, `3` when the user attempted to forcibly remove a repository they do not own, `4` when removing associated information was unsuccessful (should not happen)
|
|
|
|
## subscribe
|
|
|
|
`subscribe` command takes `$r` and makes `$u` susbcribe to `$r`:
|
|
|
|
1. If `$r` is unknown, the `add` command is run with the same arguments, and `subscribe` exits with the exit code of `add` command
|
|
2. Subscribe `$u` to `$r`
|
|
|
|
**Retuns**: `0` on success, the exit code from `add` on failure
|
|
|
|
## unsubscribe
|
|
|
|
`unsubscribe` command takes `$r`, and makes `$u` unsubscribe to `$r`:
|
|
|
|
1. If `$r` is unknown, exit with `1`
|
|
2. Unsubscribe `$u` from `$r`
|
|
|
|
**Returns**: `0` on success, or `1` when the repository was not found
|
|
|
|
If `$rhex.$u` doesn't exist, the user isn't subscribed, so a warning is emitted and the command does nothing. Otherwise, the file `$rhex.$u` is removed.
|
|
|
|
## secret
|
|
|
|
`secret` command takes `$r` and an optional `$s`. It either displays the current secret for a repository `$u` owns, or replaces it with `$s`:
|
|
|
|
1. If `$r` is unknown, exit with `1`
|
|
2. If `$u` is not owner of `$r`, exit with `2`
|
|
3. If `$s` was supplied, replace the current secret for `$r`
|
|
3. Print the curent secret for `$r`
|
|
|
|
**Returns**: `0` on success, `1` on unknown repository, and `2` on wrong ownership for the repository
|