From b8a4698831626b8f1d473c92d0a880062dedbe1d Mon Sep 17 00:00:00 2001 From: Justin Wernick Date: Thu, 15 Jun 2023 21:44:55 +0200 Subject: Added a changelog for completed todo items --- CHANGELOG.md | 44 ++++++++ Cargo.toml | 2 +- README.md | 255 ++++++++++++++++++++++++++++++++++++++++++ readme.md | 360 ----------------------------------------------------------- readme.org | 308 -------------------------------------------------- 5 files changed, 300 insertions(+), 669 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 README.md delete mode 100644 readme.md delete mode 100644 readme.org diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..cd6ea83 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,44 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +This changelog focusses on changes which affect production users of this +library. It will not mention any changes to code structure, internal design +details, documentation, or testing unless they have some affect on the public +API. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.1.1] - 2023-05-10 + +### Changed + +- Updated documentation for installing to reference the package on crates.io. + +## [0.1.0] - 2023-05-10 + +### Added + +- Initial release with minimum viable functionality + - Interactive command prompt + - Non-interactive commands can be run with -c + - Exit command + - Help command + - Responds appropriately to unknown commands + - Shell command history (only within same session) + - git init works for + - private repos + - shared repos + - git fetch / clone from a server using shackle-shell + - git push to a server using shackle-shell + - Repos are restricted to only expected paths + - List all repos + - Set the repo description, both during init or as a separate command + - Set the main branch of a repo, both during init or as a separate command + +[unreleased]: https://codeberg.org/worthe-it/shackle-shell/compare/v0.1.1...HEAD +[0.1.1]: https://codeberg.org/worthe-it/shackle-shell/releases/tag/v0.1.1 +[0.1.0]: https://codeberg.org/worthe-it/shackle-shell/releases/tag/v0.1.0 diff --git a/Cargo.toml b/Cargo.toml index f975549..02113e2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ version = "0.1.1" authors = ["Justin Wernick "] edition = "2021" description = "A shell for restricting access on a version control server" -readme = "readme.md" +readme = "README.md" # TODO: homepage = "" repository = "https://code.worthe-it.co.za/shackle.git/" license = "MIT" diff --git a/README.md b/README.md new file mode 100644 index 0000000..85e543b --- /dev/null +++ b/README.md @@ -0,0 +1,255 @@ + + +A shell for restricting access on a version control server. + +This is intended as a replacement for [Git Shell](https://git-scm.com/docs/git-shell), but with a few opinionated +differences: + +- Additional commands, like creating new repos, are built in. No extension with + shell scripts. +- Strict enforcement of a specified directory structure. Git push / pull + commands only work for these paths. New repos are created in these paths. + - Private git repos are created in `~/git//.git` + - Shared git repos are created in `~/git//.git` +- Better interactive UX than Git Shell, including: + - Command history (limited to the current session). + - Emacs-style shortcuts (eg `Ctrl+a` to move cursor to the beginning of line). + - Docs available for all commands, available in the shell itself. +- (coming soon!) Support for other other version control systems. + + +# Getting Started + +## Usage + +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. + + > + +You can see the built in help by running the `help` command. + + > 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 + +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. + + > init awesome-project-idea + Successfully created "git/shukkie/awesome-project-idea.git" + +The path given here is relative to your home directory. So the full URL to clone +this repo is `@:` + + $ git clone shukkie@example.com:git/shukkie/awesome-project-idea.git + +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. + + > init --help + Create a new repository + + Usage: init [OPTIONS] + + Arguments: + Name of the new repository + + 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 + + +## Installation + +### Background + +Shackle is designed to run on a Git server. The process of setting up your own +Git server, which is set up as described in the following two articles: + +- [initial server setup](https://www.worthe-it.co.za/blog/2022-06-10-how-to-train-your-git-server.html) +- [sharing repos](https://www.worthe-it.co.za/blog/2023-06-02-leveling-up-your-git-server-sharing-repos.html). + +### Prerequisites + +The following programs much be installed: + +- Git + - This is used for git operations which are passed through for the operation + of `git push` and `git fetch`. + - Git must be installed, with the `git-upload-pack` and `git-receive-pack` + executables on the path. +- SSH + - I assume users will be connecting over SSH. This is not enforced by the + shell, but is the primary use case I have in mind. I have tested this using + the OpenSSH daemon. + + +### Building Shackle + +Binary releases of Shackle can be downloaded from [Codeberg](https://codeberg.org/worthe-it/shackle-shell/releases/). + +You can also build it yourself from source. The easiest way to do this is using +`cargo install`. + +This requires a the Rust toolchain and a C compiler. See the Development +Environment Setup section below for more information on environment setup to +build from source. + + # This installs to Cargo's default, which is ~/.cargo/bin. Consider using the + # --root option to install it somewhere that makes more sense for your server. + cargo install shackle-shell + + +### Creating the required directory structure + +Next, Shackle expects a specific directory structure. Specifically, personal git +repos will live in `~/git/your-username` and shared repos will live in +`~/git/your-group`. + +If you have many users on your server, then consider making `~/git` a symlink to +the actual shared location for your git repos. For example, on my repo, all git +users have a `~/git` symlink in their home directory which actually points at +`/srv/git`. + + mkdir -p ~/git/$USER + chmod --recursive u=rwX,g=,o= ~/git/$USER + + # Note that this should be a group you're actually a member of! + GROUP=my-group + mkdir -p ~/git/$GROUP + chown --recursive $USER:$GROUP ~/git/$GROUP + chmod --recursive u=rwX,g=rwXs,o= ~/git/$GROUP + + +### Set Shackle as your default shell + +The next step is to set the default shell of your user to Shackle. This will +mean that if you login as the user, for example over ssh, then the default shell +will be Shackle. + + sudo usermod --shell $HOME/.cargo/bin/shackle-shell $USER + + +# Operating System Support + +Currently, Shackle Shell only supports running on Linux. + +It will likely work on other Unix-like platforms, such as MacOS, but this is not +currently tested, and there are currently no plans to do so. I would not expect +it to work on Windows. + + +# Development Guide + +## Development Environment Setup + +- Rust + - This project is built using the Rust programming language, and its build + tool Cargo. Information on how to install these tools is available on [the + Rust website](https://www.rust-lang.org/learn/get-started). +- C Compiler + - This is used to built one of the dependencies, libgit2. This can be + obtained from your operating system's package manager. +- Docker + - Some of the tests use Docker to create a simulated environment. This can be + obtained from your operating system's package manager, or the [Docker + website](https://www.docker.com/). + - Docker must be installed, with the `docker` executable on the path. + - Your user must have permission to use docker, including building and running + Docker containers. +- Git + - Some of the tests use Git to test the end to end functionality of the + shell. This can be obtained from your operating system's package manager, or + the [Git website](https://git-scm.com/). + - Git must be installed, with the `git` executable on the path. +- SSH + - Some of the tests use an SSH client to test the end to end functionality of + the shell. I have tested this with OpenSSH, which can be obtained from your + operating system's package manager, or the [Git website](https://git-scm.com/). + - with the `ssh` executable on the path. + +If you're running Arch Linux, these are the steps you'll need to get your +environment ready. + + sudo pacman -S rustup docker git openssh gcc + + # Rust + rustup default stable + + # Docker + sudo usermod -a -G docker $USER + sudo systemctl start docker.service + + # Note: you need to log out and in again for the new group to take effect + + +## Running Tests + +All unit tests are run with Cargo. + + cargo test + + +## Linting + +Clippy should be used for linting. This can be installed using Rustup. + + rustup component add clippy + +And it can be run via Cargo. + + cargo clippy + + +## Building a Release Binary + +Release binaries should be built in release mode. + + cargo build --release + +After running this, the binary is available in `./target/release/shackle-shell` + + +# Roadmap + +## Post-MVP + +- [ ] project website +- [ ] functions correctly when the git path isn't created with correct + permissions yet +- [ ] git archive with git upload-archive +- [ ] git config management around protected branches +- [ ] move a repo to a different group +- [ ] housekeeping git tasks (git fsck, git gc) +- [ ] pijul fetch and pijul push +- [ ] pijul support on other commands + + +# Support + +If you get value from this project, consider supporting me on [Patreon](https://www.patreon.com/worthe_it). Support +via Patreon helps to cover hosting, buying computer stuff, and will allow me to +spend more time writing articles and open source software. + +# License + +Licensed under [MIT License](./LICENSE). + diff --git a/readme.md b/readme.md deleted file mode 100644 index bc9bd18..0000000 --- a/readme.md +++ /dev/null @@ -1,360 +0,0 @@ - -# Table of Contents - -1. [Getting Started](#orgd504466) - 1. [Usage](#orgaa56d06) - 2. [Installation](#org26cfe7c) - 1. [Background](#orgcc164e3) - 2. [Prerequisites](#org0cfd05b) - 3. [Building Shackle](#org44ca1cf) - 4. [Creating the required directory structure](#orgc188534) - 5. [Set Shackle as your default shell](#orge6ddfb3) -2. [Operating System Support](#orgc028af6) -3. [Development Guide](#org6f989dd) - 1. [Development Environment Setup](#orgf0cf08f) - 2. [Running Tests](#org91f4451) - 3. [Linting](#org71e8518) - 4. [Building a Release Binary](#org8fb9e6c) -4. [Roadmap / Issue Tracker TODO list](#org4ee647c) - 1. [MVP](#orge1019db) - 2. [Post-MVP](#org41cb56d) -5. [Support](#orgd5588f5) -6. [License](#org36ecb42) - - - -A shell for restricting access on a version control server. - -This is intended as a replacement for [Git Shell](https://git-scm.com/docs/git-shell), but with a few opinionated -differences: - -- Additional commands, like creating new repos, are built in. No extension with - shell scripts. -- Strict enforcement of a specified directory structure. Git push / pull - commands only work for these paths. New repos are created in these paths. - - Private git repos are created in `~/git//.git` - - Shared git repos are created in `~/git//.git` -- Better interactive UX than Git Shell, including: - - Command history (limited to the current session). - - Emacs-style shortcuts (eg `Ctrl+a` to move cursor to the beginning of line). - - Docs available for all commands, available in the shell itself. -- (coming soon!) Support for other other version control systems. - - - - -# Getting Started - - - - -## Usage - -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. - - > - -You can see the built in help by running the `help` command. - - > 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 - -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. - - > init awesome-project-idea - Successfully created "git/shukkie/awesome-project-idea.git" - -The path given here is relative to your home directory. So the full URL to clone -this repo is `@:` - - $ git clone shukkie@example.com:git/shukkie/awesome-project-idea.git - -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. - - > init --help - Create a new repository - - Usage: init [OPTIONS] - - Arguments: - Name of the new repository - - 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 - - - - -## Installation - - - - -### Background - -Shackle is designed to run on a Git server. The process of setting up your own -Git server, which is set up as described in the following two articles: - -- [initial server setup](https://www.worthe-it.co.za/blog/2022-06-10-how-to-train-your-git-server.html) -- [sharing repos](https://www.worthe-it.co.za/blog/2023-06-02-leveling-up-your-git-server-sharing-repos.html). - - - - -### Prerequisites - -The following programs much be installed: - -- Git - - This is used for git operations which are passed through for the operation - of `git push` and `git fetch`. - - Git must be installed, with the `git-upload-pack` and `git-receive-pack` - executables on the path. -- SSH - - I assume users will be connecting over SSH. This is not enforced by the - shell, but is the primary use case I have in mind. I have tested this using - the OpenSSH daemon. - - - - -### Building Shackle - -Binary releases of Shackle can be downloaded from [Codeberg](https://codeberg.org/worthe-it/shackle-shell/releases/). - -You can also build it yourself from source. The easiest way to do this is using -`cargo install`. - -This requires a the Rust toolchain and a C compiler. See the Development -Environment Setup section below for more information on environment setup to -build from source. - - # This installs to Cargo's default, which is ~/.cargo/bin. Consider using the - # --root option to install it somewhere that makes more sense for your server. - cargo install shackle-shell - - - - -### Creating the required directory structure - -Next, Shackle expects a specific directory structure. Specifically, personal git -repos will live in `~/git/your-username` and shared repos will live in -`~/git/your-group`. - -If you have many users on your server, then consider making `~/git` a symlink to -the actual shared location for your git repos. For example, on my repo, all git -users have a `~/git` symlink in their home directory which actually points at -`/srv/git`. - - mkdir -p ~/git/$USER - chmod --recursive u=rwX,g=,o= ~/git/$USER - - # Note that this should be a group you're actually a member of! - GROUP=my-group - mkdir -p ~/git/$GROUP - chown --recursive $USER:$GROUP ~/git/$GROUP - chmod --recursive u=rwX,g=rwXs,o= ~/git/$GROUP - - - - -### Set Shackle as your default shell - -The next step is to set the default shell of your user to Shackle. This will -mean that if you login as the user, for example over ssh, then the default shell -will be Shackle. - - sudo usermod --shell $HOME/.cargo/bin/shackle-shell $USER - - - - -# Operating System Support - -Currently, Shackle Shell only supports running on Linux. - -It will likely work on other Unix-like platforms, such as MacOS, but this is not -currently tested, and there are currently no plans to do so. I would not expect -it to work on Windows. - - - - -# Development Guide - - - - -## Development Environment Setup - -- Rust - - This project is built using the Rust programming language, and its build - tool Cargo. Information on how to install these tools is available on [the - Rust website](https://www.rust-lang.org/learn/get-started). -- C Compiler - - This is used to built one of the dependencies, libgit2. This can be - obtained from your operating system's package manager. -- Docker - - Some of the tests use Docker to create a simulated environment. This can be - obtained from your operating system's package manager, or the [Docker - website](https://www.docker.com/). - - Docker must be installed, with the `docker` executable on the path. - - Your user must have permission to use docker, including building and running - Docker containers. -- Git - - Some of the tests use Git to test the end to end functionality of the - shell. This can be obtained from your operating system's package manager, or - the [Git website](https://git-scm.com/). - - Git must be installed, with the `git` executable on the path. -- SSH - - Some of the tests use an SSH client to test the end to end functionality of - the shell. I have tested this with OpenSSH, which can be obtained from your - operating system's package manager, or the [Git website](https://git-scm.com/). - - with the `ssh` executable on the path. - -If you're running Arch Linux, these are the steps you'll need to get your -environment ready. - - sudo pacman -S rustup docker git openssh gcc - - # Rust - rustup default stable - - # Docker - sudo usermod -a -G docker $USER - sudo systemctl start docker.service - - # Note: you need to log out and in again for the new group to take effect - - - - -## Running Tests - -All unit tests are run with Cargo. - - cargo test - - - - -## Linting - -Clippy should be used for linting. This can be installed using Rustup. - - rustup component add clippy - -And it can be run via Cargo. - - cargo clippy - - - - -## Building a Release Binary - -Release binaries should be built in release mode. - - cargo build --release - -After running this, the binary is available in `./target/release/shackle-shell` - - - - -# Roadmap / Issue Tracker TODO list - - - - -## MVP - -- [X] interactive command prompt -- [X] non-interactive commands can be run with -c -- [X] exit command -- [X] git init of private repo -- [X] responds to unknown commands -- [X] Isolation of workdir between tests -- [X] git fetch with git upload-pack -- [X] git push with git receive-pack -- [X] proper shell argument lexing, with quote stuff -- [X] history (only within same session) -- [X] don't quit interactive shell sessions if there's an error -- [X] help command -- [X] restrict repos to only acceptable paths - - [X] clone / pull - - [X] push -- [X] git init of shared repos - - [X] create the shared repo in the right place - - [X] use the right file permissions and config - - [X] don't allow this to be a group the user isn't in - - [X] allow pull and push from shared repos -- [X] listing of repos -- [X] set repo descriptions - - [X] init new repo - - [X] change an existing repo -- [X] Change `git-init` name to just be `init`. Later, the `git` part will be an - option which defaults to git. -- [X] set the main branch of a repo -- [X] help docs on all the commands - - - - -## Post-MVP - -- [X] proper licensing -- [X] all the getting started stuff in the readme -- [X] clean up crates.io metadata - - [X] crates.io friendly readme: needs to be markdown - - [X] rename to something that isn't taken on crates.io (shackle-shell) -- [X] publish to crates.io -- [ ] project website -- [ ] functions correctly when the git path isn't created with correct - permissions yet -- [ ] git archive with git upload-archive -- [ ] git config management around protected branches -- [ ] move a repo to a different group -- [ ] housekeeping git tasks (git fsck, git gc) -- [ ] pijul fetch and pijul push -- [ ] pijul support on other commands - - - - -# Support - -If you get value from this project, consider supporting me on [Patreon](https://www.patreon.com/worthe_it). Support -via Patreon helps to cover hosting, buying computer stuff, and will allow me to -spend more time writing articles and open source software. - - - - -# License - -Licensed under [MIT License](./LICENSE). - diff --git a/readme.org b/readme.org deleted file mode 100644 index 22629c1..0000000 --- a/readme.org +++ /dev/null @@ -1,308 +0,0 @@ -#+TITLE: Shackle Shell -#+AUTHOR: Justin Wernick - -[[https://img.shields.io/crates/v/shackle-shell]] - -A shell for restricting access on a version control server. - -This is intended as a replacement for [[https://git-scm.com/docs/git-shell][Git Shell]], but with a few opinionated -differences: - -- Additional commands, like creating new repos, are built in. No extension with - shell scripts. -- Strict enforcement of a specified directory structure. Git push / pull - commands only work for these paths. New repos are created in these paths. - - Private git repos are created in =~/git//.git= - - Shared git repos are created in =~/git//.git= -- Better interactive UX than Git Shell, including: - - Command history (limited to the current session). - - Emacs-style shortcuts (eg =Ctrl+a= to move cursor to the beginning of line). - - Docs available for all commands, available in the shell itself. -- (coming soon!) Support for other other version control systems. - -* Getting Started - -** Usage - -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] - - Arguments: - Name of the new repository - - 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 - -*** Background - -Shackle is designed to run on a Git server. The process of setting up your own -Git server, which is set up as described in the following two articles: - -- [[https://www.worthe-it.co.za/blog/2022-06-10-how-to-train-your-git-server.html][initial server setup]] -- [[https://www.worthe-it.co.za/blog/2023-06-02-leveling-up-your-git-server-sharing-repos.html][sharing repos]]. - -*** Prerequisites - -The following programs much be installed: - -- Git - - This is used for git operations which are passed through for the operation - of =git push= and =git fetch=. - - Git must be installed, with the =git-upload-pack= and =git-receive-pack= - executables on the path. -- SSH - - I assume users will be connecting over SSH. This is not enforced by the - shell, but is the primary use case I have in mind. I have tested this using - the OpenSSH daemon. - -*** Building Shackle - -Binary releases of Shackle can be downloaded from [[https://codeberg.org/worthe-it/shackle-shell/releases/][Codeberg]]. - -You can also build it yourself from source. The easiest way to do this is using -=cargo install=. - -This requires a the Rust toolchain and a C compiler. See the Development -Environment Setup section below for more information on environment setup to -build from source. - -#+begin_src sh - # This installs to Cargo's default, which is ~/.cargo/bin. Consider using the - # --root option to install it somewhere that makes more sense for your server. - cargo install shackle-shell -#+end_src - -*** Creating the required directory structure - -Next, Shackle expects a specific directory structure. Specifically, personal git -repos will live in =~/git/your-username= and shared repos will live in -=~/git/your-group=. - -If you have many users on your server, then consider making =~/git= a symlink to -the actual shared location for your git repos. For example, on my repo, all git -users have a =~/git= symlink in their home directory which actually points at -=/srv/git=. - -#+begin_src sh - mkdir -p ~/git/$USER - chmod --recursive u=rwX,g=,o= ~/git/$USER - - # Note that this should be a group you're actually a member of! - GROUP=my-group - mkdir -p ~/git/$GROUP - chown --recursive $USER:$GROUP ~/git/$GROUP - chmod --recursive u=rwX,g=rwXs,o= ~/git/$GROUP -#+end_src - -*** Set Shackle as your default shell - -The next step is to set the default shell of your user to Shackle. This will -mean that if you login as the user, for example over ssh, then the default shell -will be Shackle. - -#+begin_src sh - sudo usermod --shell $HOME/.cargo/bin/shackle-shell $USER -#+end_src - -* Operating System Support - -Currently, Shackle Shell only supports running on Linux. - -It will likely work on other Unix-like platforms, such as MacOS, but this is not -currently tested, and there are currently no plans to do so. I would not expect -it to work on Windows. - -* Development Guide - -** Development Environment Setup - -- Rust - - This project is built using the Rust programming language, and its build - tool Cargo. Information on how to install these tools is available on [[https://www.rust-lang.org/learn/get-started][the - Rust website]]. -- C Compiler - - This is used to built one of the dependencies, libgit2. This can be - obtained from your operating system's package manager. -- Docker - - Some of the tests use Docker to create a simulated environment. This can be - obtained from your operating system's package manager, or the [[https://www.docker.com/][Docker - website]]. - - Docker must be installed, with the =docker= executable on the path. - - Your user must have permission to use docker, including building and running - Docker containers. -- Git - - Some of the tests use Git to test the end to end functionality of the - shell. This can be obtained from your operating system's package manager, or - the [[https://git-scm.com/][Git website]]. - - Git must be installed, with the =git= executable on the path. -- SSH - - Some of the tests use an SSH client to test the end to end functionality of - the shell. I have tested this with OpenSSH, which can be obtained from your - operating system's package manager, or the [[https://git-scm.com/][Git website]]. - - with the =ssh= executable on the path. - -If you're running Arch Linux, these are the steps you'll need to get your -environment ready. - -#+begin_src sh - sudo pacman -S rustup docker git openssh gcc - - # Rust - rustup default stable - - # Docker - sudo usermod -a -G docker $USER - sudo systemctl start docker.service - - # Note: you need to log out and in again for the new group to take effect -#+end_src - -** Running Tests - -All unit tests are run with Cargo. - -#+begin_src sh - cargo test -#+end_src - -** Linting - -Clippy should be used for linting. This can be installed using Rustup. - -#+begin_src sh - rustup component add clippy -#+end_src - -And it can be run via Cargo. - -#+begin_src sh - cargo clippy -#+end_src - -** Building a Release Binary - -Release binaries should be built in release mode. - -#+begin_src sh - cargo build --release -#+end_src - -After running this, the binary is available in =./target/release/shackle-shell= - -* Roadmap / Issue Tracker TODO list - -** MVP - -- [X] interactive command prompt -- [X] non-interactive commands can be run with -c -- [X] exit command -- [X] git init of private repo -- [X] responds to unknown commands -- [X] Isolation of workdir between tests -- [X] git fetch with git upload-pack -- [X] git push with git receive-pack -- [X] proper shell argument lexing, with quote stuff -- [X] history (only within same session) -- [X] don't quit interactive shell sessions if there's an error -- [X] help command -- [X] restrict repos to only acceptable paths - - [X] clone / pull - - [X] push -- [X] git init of shared repos - - [X] create the shared repo in the right place - - [X] use the right file permissions and config - - [X] don't allow this to be a group the user isn't in - - [X] allow pull and push from shared repos -- [X] listing of repos -- [X] set repo descriptions - - [X] init new repo - - [X] change an existing repo -- [X] Change ~git-init~ name to just be ~init~. Later, the ~git~ part will be an - option which defaults to git. -- [X] set the main branch of a repo -- [X] help docs on all the commands - -** Post-MVP - -- [X] proper licensing -- [X] all the getting started stuff in the readme -- [X] clean up crates.io metadata - - [X] crates.io friendly readme: needs to be markdown - - [X] rename to something that isn't taken on crates.io (shackle-shell) -- [X] publish to crates.io -- [ ] project website -- [ ] functions correctly when the git path isn't created with correct - permissions yet -- [ ] git archive with git upload-archive -- [ ] git config management around protected branches -- [ ] move a repo to a different group -- [ ] housekeeping git tasks (git fsck, git gc) -- [ ] pijul fetch and pijul push -- [ ] pijul support on other commands - -* Support - -If you get value from this project, consider supporting me on [[https://www.patreon.com/worthe_it][Patreon]]. Support -via Patreon helps to cover hosting, buying computer stuff, and will allow me to -spend more time writing articles and open source software. - -* License - -Licensed under [[./LICENSE][MIT License]]. -- cgit v1.2.3