From 4bb750335485169e469bdb191c8ca29bb107b358 Mon Sep 17 00:00:00 2001 From: cam Date: Mon, 24 Jan 2022 01:42:50 -0700 Subject: [PATCH] docs: add all commands to README, closes #29 (#30) * docs: add all commands to README, closes #29 * docs: fix lints, add language specifier to codeblocks --- .gitignore | 1 + CONTRIBUTING.md | 16 ++++++++-------- README.md | 50 ++++++++++++++++++++++++++++++++++++++++--------- cmd/create.go | 18 +++++++++++------- cmd/running.go | 2 +- 5 files changed, 62 insertions(+), 25 deletions(-) diff --git a/.gitignore b/.gitignore index 01bb277..312f210 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,4 @@ ch .vscode dist/ +.DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62b24e9..fe3aae4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,13 +18,13 @@ On a Linux/macOS machine, you should be able to use `make` command to build, tes Install cobra dependencies: (required to generate new commands) -```shell script -go get github.com/spf13/cobra/cobra +```bash +go install github.com/spf13/cobra/cobra@v1.3.0 ``` Add new cobra command -```shell script +```bash # add new subcommand cobra add -p cobra add childCommand -p 'parentCommand' @@ -36,7 +36,7 @@ Add or adjust `~/.cobra.yaml` file for your name, license, year, etc. [Docs](htt Go Module: -```shell script +```bash # you don't have to run this since we already have a go.mod and go.sum file go mod init github.com// @@ -57,7 +57,7 @@ When writing instructions in the CLI and in the README, please follow syntax rec Change package name: -```shell script +```bash # change module name in all files find . -type f \( -name '*.go' -o -name '*.mod' \) -exec sed -i -e "s;container-helper;ch;g" {} + ``` @@ -69,21 +69,21 @@ Change package name: > I can't remember how on Earth to git tag stuff sometimes! -```shell +```bash # releasing a new version git tag -a v1.4 -m "Version notes here" ``` To delete tagging mistakes locally: -```shell +```bash # delete local tag git tag -d tagname ``` To delete remote tags: -```shell +```bash # delete a tag already pushed to github git push --delete origin tagname ``` diff --git a/README.md b/README.md index 11b4e20..a2b85f0 100644 --- a/README.md +++ b/README.md @@ -128,15 +128,19 @@ This environment is based on this repository: [csci104/docker](https://github.co #### Create the CSCI 350 Environment The commands here assume `csci350-work` is your homework folder in the current directory. Alternatively, you can provide the absolute path -to wherever your homework is on your machine. For Windows, your volume command should look like `--volume "C:\Users\user\path\to\csci350:/work"`, on macOS your command should look like `--volume /Users/username/path/to/csci350:/work`. +to wherever your homework is on your machine. For Windows, your volume command should look like `--volume "C:\Users\user\path\to\csci350:/xv6_docker"`, on macOS your command should look like `--volume /Users/username/path/to/csci350:/xv6_docker`. This environment is based on the this repository: [camerondurham/cs350-docker](https://github.com/camerondurham/cs350-docker) -1. use `ch create` to create and save the environment settings +1. find the absolute path to your `csci350` directory where you keep your homework (see [Filepaths in terminal](https://github.com/csci104/docker#filepaths-in-the-terminal) wiki from csci104/docker if you are having issues) + 1. (macOS/Linux) navigate to your directory in the terminal and run `pwd`, the output should be something like `/Users/username/path/to/csci350` + 2. (Windows Powershell) navigate to the directory in Powershell and run `Get-Location`, you will want the output like `C:\Users\Username\path\to\csci350` + +1. use `ch create` to create and save the environment settings, replacing `PATH_TO_YOUR_WORKDIR` with the path from step 1. ```bash ch create csci350 \ --image camerondurham/cs350-docker:v1 \ - --volume csci350-work:/xv6_docker \ + --volume PATH_TO_YOUR_WORKDIR:/xv6_docker \ --security-opt seccomp:unconfined \ --port 7776:22 \ --port 7777:7777 \ @@ -185,6 +189,24 @@ Flags: ``` +### `ch list` + +list all saved configs + +```txt +Usage: + ch list [ENVIRONMENT_NAME] +``` + +### `ch delete` + +delete an environment from your `.ch.yaml` config file + +```txt +Usage: + ch delete ENVIRONMENT_NAME [flags] +``` + ### `ch start` start docker container in background and save container ID to config file @@ -215,22 +237,32 @@ Usage: ch stop ENVIRONMENT_NAME ``` -### `ch list` -list all saved configs +### `ch running` + +list all running environments ```txt Usage: - ch list [ENVIRONMENT_NAME] + ch running ``` -### `ch running` +### `ch update` -list all running environments +update your Docker image to the latest version or rebuild the container ```txt Usage: - ch running + ch update [ENVIRONMENT_NAME] [flags] +``` + +### `ch upgrade` + +check if you are running the latest version of `ch` and print install commands if an upgrade is available + +```txt +Usage: + ch upgrade ``` ## More Examples diff --git a/cmd/create.go b/cmd/create.go index fb08b30..5b43e7c 100644 --- a/cmd/create.go +++ b/cmd/create.go @@ -4,26 +4,31 @@ import ( "context" "errors" "fmt" + "log" + "os" + "path/filepath" + "strings" + "github.com/camerondurham/ch/cmd/util" "github.com/docker/go-connections/nat" "github.com/mitchellh/go-homedir" "github.com/spf13/cobra" "github.com/spf13/viper" - "log" - "os" - "path/filepath" - "strings" ) // createCmd represents the create command var ( createCmd = &cobra.Command{ - Use: "create ENVIRONMENT_NAME {--file DOCKERFILE |--image DOCKER_IMAGE } [OPTIONS]", + Use: "create ENVIRONMENT_NAME [FLAGS] {--file DOCKERFILE |--image DOCKER_IMAGE } [OPTIONS]", Short: "create docker environment config", Long: `Create docker environment config with new name. + + You can use the following flag to replace an environment name if it already exists: + --replace Replace existing named environment, if one exists already. + Will look for your Dockerfile in the current directory if you do not explicitly set --file. - + To create environment from a Dockerfile, use: --file DOCKERFILE Path to Dockerfile. If context is used, filepath must be relative to that path. @@ -35,7 +40,6 @@ var ( You can use the following options: - --replace Replace existing named environment, if one exists --volume list Bind mount a volume --shell PATH Command to run for shell (i.e. /bin/sh, /bin/bash) --cap-add CAPABILITY Add Linux capability (i.e. SYS_PTRACE) diff --git a/cmd/running.go b/cmd/running.go index 55423f2..22f2f0e 100644 --- a/cmd/running.go +++ b/cmd/running.go @@ -17,7 +17,7 @@ var runningCmd = &cobra.Command{ Short: "list running environments", Long: `List all running Docker containers created by the container-helper. Any Docker containers not managed by the container-helper will be ignored. -To see all running containers, run: +To see all running containers, run: docker ps`, Run: RunningCmd, }