From f7c4d9245e246f145b101c0dc8ca43820390e961 Mon Sep 17 00:00:00 2001 From: Justin Wernick Date: Wed, 26 Apr 2023 17:15:30 +0200 Subject: Add usage docs --- readme.org | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 64 insertions(+), 9 deletions(-) diff --git a/readme.org b/readme.org index 99e84f9..1aeb9a1 100644 --- a/readme.org +++ b/readme.org @@ -22,16 +22,69 @@ differences: ** Usage -# TODO +Shackle Shell is intended to be set as the default shell for a user on a git +server, where the user connects over SSH (see the Installation section below). + +When you log in over SSH, you'll see a prompt, ready for you to type commands. + +#+begin_src fundamental + > +#+end_src + +You can see the built in help by running the =help= command. + +#+begin_src fundamental + > help + Usage: + + Commands: + init Create a new repository + list List all repositories available + set-description Sets the description of a repository, as shown in the CLI listing and web interfaces + set-branch Sets the main branch of the repository + exit Quit the shell + git-upload-pack Server side command required to git fetch from the server + git-receive-pack Server side command required by git push to the server + help Print this message or the help of the given subcommand(s) + + Options: + -h, --help Print help +#+end_src + +The =init= command is used to create a new repo. In its simplest form, you just +provide it with the name of your new repo. This will create a git repo with +individual ownership. + +#+begin_src fundamental + > init awesome-project-idea + Successfully created "git/shukkie/awesome-project-idea.git" +#+end_src + +The path given here is relative to your home directory. So the full URL to clone +this repo is =@:= + +#+begin_src fundamental + $ git clone shukkie@example.com:git/shukkie/awesome-project-idea.git +#+end_src + +You can learn its advanced options by using the =--help= flag. This works for +all of the options, and is a great way to learn what all the commands do. + +#+begin_src fundamental + > init --help + Create a new repository + + Usage: init [OPTIONS] -# When you login, you'll see the prompt > -# Type help to see the list of commands -# init my-awesome-repo will create the repo git//my-awesome-repo.git -# init --group my-group my-awesome-repo will create the repo -# git/my-group/my-awesome-repo.git in shared mode. -# list to see all your repos + Arguments: + Name of the new repository -# From outside, git clone me@myserver:git/me/my-awesome-repo.git + Options: + --group Share repository ownership with the specified group (user must be a member of the group) + --description Sets the description of the repository, as shown in the CLI listing and web interfaces + --branch Sets the main branch of the repository [default: main] + -h, --help Print help +#+end_src ** Installation @@ -39,12 +92,13 @@ differences: # cargo install to build from source # set as the user's shell +# create the appropriate directory structure * Development Guide # TODO -# cargo build +# need to have docker installed # cargo test --workspace # cargo clippy @@ -85,6 +139,7 @@ differences: - [X] proper licensing - [ ] all the getting started stuff in the readme +- [ ] consider having the workspace root abstract so that --workspace isn't needed - [ ] publish to crates.io - [ ] project website - [ ] functions correctly when the git path isn't created yet -- cgit v1.2.3