From dfa01404709d12ad11f9468aeac0a548b7cdfab5 Mon Sep 17 00:00:00 2001 From: Danielle McLean Date: Thu, 18 Jun 2020 14:12:53 +1000 Subject: [PATCH] Add basic info on subcommands to README.md --- README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/README.md b/README.md index 4327b67..122a35a 100644 --- a/README.md +++ b/README.md @@ -30,3 +30,34 @@ By default, packages are installed by `dots` to `~/dotfiles` and then linked int need to change this. * `HOME` - the target directory for linking packages. Probably not a good idea to change this either. + +## Subcommands + +Much like `git` and many other tools, `dots` is based around subcommands for accessing particular functions. The available commands are: + +### `bootstrap` + +Set up dotfiles on a brand-new system. Will create a `DOTFILES` package directory, clone GNU Stow into it if necessary, clone itself and other default packages, and then link everything using Stow. This is the default command if `dots` is run on a system where `DOTFILES` doesn't already exist, leading to the succinct bootstrap snippet shown above. + +### `clone` + +Will clone one or more packages specified into your `DOTFILES` directory. Packages must be specified as Git repository URLs, but two forms of shorthand are supported: + +* GitHub package paths: "sharkdp/bat", "hlandau/acmetool". "https://github.com/" will automatically be prepended to find the correct GitHub repository. +* Simple package names: "git", "emacs", "task". The entire `DOTS_SOURCE_PREFIX` is prepended to these names, hopefully producing a URL that points to your self-hosted Git service. + +### `fetch` + +Will simply run `git fetch -p` for each of the specified package names. If there are no package names provided, will implicitly run over *all* packages. + +### `link` + +Will employ GNU Stow to symlink each of the packages specified by name into your `HOME`. If no package names are provided, will implicitly link all packages. + +### `pull` + +Very similar to `fetch`. Will simply run `git pull` for each of the specified package names. If there are no package names provided, will implicitly run over *all* packages. + +### `status` + +Can be abbreviated to `st`. Will list all packages you have cloned into your dotfiles directory, along with their Git status (whether the working directory is clean, whether there are commits to push or pull, that sort of thing). This command is the default if you have already bootstrapped.