archive_hook.sh/docs/cli.md

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 provide help to the user
• list list user's current subscriptions, or a repository's current subscribers
• add register or subscribe to a remote
• remove (alias: rm) unsubscribe, or remove a repository you own
• subscribe (alias: sub) subscribe to a repository
• unsubscribe (alias unsub) unsubscribe from a repository
• 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)
3. TODO: Here is where we introduce additional authentication steps to prevent accidentally claiming a repository you do not own
4. Register $u as owner for $r
5. If a secret $s was provided, save it. Otherwise, generate a random hexadecimal secret
6. Print the current secret
7. Subscribe $u to $r (usually through the subscribe command)
8. 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
3. If $u owns $r, inform the user about the --force flag
4. Unsubscribe $u from $r and exit with 0 when this is successful, 2 otherwise
5. Otherwise, if the force flag is set
6. If $u does not own $r, print an error an exit with 3
7. Unsubscribe all subscribers from $r (cannot fail)
8. 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
4. Print the curent secret for $r

Returns: 0 on success, 1 on unknown repository, and 2 on wrong ownership for the repository