Merge pull request #700 from chrisallenlane/4.3.3

4.3.3

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Submit a bug report
+title: ''
+labels: 'bug'
+assignees: ''
+
+---
+
+Thanks for submitting a bug report. Please provide the following information:
+
+**A description of the problem**
+Describe the problem here.
+
+**cheat version info**
+Please paste the output of `cheat -v` here.
+
+**cheat configuration info**
+If your bug pertains to how cheatsheets are loaded and/or displayed, please
+paste here the following information:
+
+1. The output of `cheat -d`
+2. The contents of your `conf.yml` file

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: 'enhancement'
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+- package-ecosystem: gomod
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+  ignore:
+  - dependency-name: github.com/alecthomas/chroma
+    versions:
+    - 0.9.1

.github/workflows/build.yml

@@ -0,0 +1,46 @@
+---
+name: Go
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  # TODO: is it possible to DRY out these jobs? Aside from `runs-on`, they are
+  # identical.
+  # See: https://github.com/actions/runner/issues/1182
+  build-linux:
+    runs-on: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.19
+      - name: Set up Revive (linter)
+        run: go get -u github.com/boyter/scc github.com/mgechev/revive
+        env:
+          GO111MODULE: "off"
+      - name: Build
+        run: make build
+      - name: Test
+        run: make test
+
+  build-osx:
+    runs-on: [macos-latest]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.19
+      - name: Set up Revive (linter)
+        run: go get -u github.com/boyter/scc github.com/mgechev/revive
+        env:
+          GO111MODULE: "off"
+      - name: Build
+        run: make build
+      - name: Test
+        run: make test

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,30 @@
+---
+name: CodeQL
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  schedule:
+    - cron: '45 23 * * 0'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [go]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v1
+        with:
+          languages: ${{ matrix.language }}
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v1
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v1

.github/workflows/homebrew.yml

@@ -0,0 +1,19 @@
+---
+name: homebrew
+
+on:
+  push:
+    tags: '*'
+
+jobs:
+  homebrew:
+    name: Bump Homebrew formula
+    runs-on: ubuntu-latest
+    steps:
+      - uses: mislav/bump-homebrew-formula-action@v1
+        with:
+          # A PR will be sent to github.com/Homebrew/homebrew-core to update
+          # this formula:
+          formula-name: cheat
+        env:
+          COMMITTER_TOKEN: ${{ secrets.COMMITTER_TOKEN }}

.gitignore

@@ -1 +1,2 @@
 dist
+tags

CONTRIBUTING.md

@@ -19,7 +19,8 @@ tracker][issues] to discuss with the maintainer whether it would be considered
 for merging.
 
 `cheat` is mostly mature and feature-complete, but may still have some room for
-new features.
+new features. See [HACKING.md][hacking] for a quick-start guide to `cheat`
+development.
 
 #### Add documentation ####
 Did you encounter features, bugs, edge-cases, use-cases, or environment
@@ -35,9 +36,13 @@ Are you unable to do the above, but still want to contribute? You can help
 `cheat` simply by telling others about it. Share it with friends and coworkers
 that might benefit from using it.
 
+#### Pull Requests ####
+Please open all pull-requests against the `develop` branch.
+
 
 [cheat]: https://github.com/cheat/cheat
 [cheatsheets]: https://github.com/cheat/cheatsheets
+[hacking]: HACKING.md
 [issues]: https://github.com/cheat/cheat/issues 
 [pr]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork
 [wiki]: https://github.com/cheat/cheat/wiki

Dockerfile

@@ -0,0 +1,8 @@
+# NB: this image isn't used anywhere in the build pipeline. It exists to
+# conveniently facilitate ad-hoc experimentation in a sandboxed environment
+# during development.
+FROM golang:1.15-alpine
+
+RUN apk add git less make
+
+WORKDIR /app

HACKING.md

@@ -0,0 +1,57 @@
+Hacking
+=======
+The following is a quickstart guide for developing `cheat`.
+
+## 1. Install system dependencies
+Before you begin, you must install a handful of system dependencies. The
+following are required, and must be available on your `PATH`:
+
+- `git`
+- `go` (>= 1.17 is recommended)
+- `make`
+
+The following dependencies are optional:
+- `docker`
+- `pandoc` (necessary to generate a `man` page)
+
+## 2. Install utility applications
+Run `make setup` to install `scc` and `revive`, which are used by various
+`make` targets.
+
+## 3. Development workflow
+After your environment has been configured, your development workflow will
+resemble the following:
+
+1. Make changes to the `cheat` source code.
+2. Run `make test` to run unit-tests.
+3. Fix compiler errors and failing tests as necessary.
+4. Run `make`. A `cheat` executable will be written to the `dist` directory.
+5. Use the new executable by running `dist/cheat <command>`.
+6. Run `make install` to install `cheat` to your `PATH`.
+7. Run `make build-release` to build cross-platform binaries in `dist`.
+8. Run `make clean` to clean the `dist` directory when desired.
+
+You may run `make help` to see a list of available `make` commands.
+
+### Developing with docker
+It may be useful to test your changes within a pristine environment. An
+Alpine-based docker container has been provided for that purpose.
+
+If you would like to build the docker container, run:
+```sh
+make docker-setup
+```
+
+To shell into the container, run:
+```sh
+make docker-sh
+```
+
+The `cheat` source code will be mounted at `/app` within the container.
+
+If you would like to destroy this container, you may run:
+```sh
+make distclean
+```
+
+[go]: https://go.dev/

INSTALLING.md

@@ -0,0 +1,79 @@
+Installing
+==========
+`cheat` has no runtime dependencies. As such, installing it is generally
+straightforward. There are a few methods available:
+
+### Install manually
+#### Unix-like
+On Unix-like systems, you may simply paste the following snippet into your terminal:
+
+```sh
+cd /tmp \
+  && wget https://github.com/cheat/cheat/releases/download/4.3.3/cheat-linux-amd64.gz \
+  && gunzip cheat-linux-amd64.gz \
+  && chmod +x cheat-linux-amd64 \
+  && sudo mv cheat-linux-amd64 /usr/local/bin/cheat
+```
+
+You may need to need to change the version number (`4.3.3`) and the archive
+(`cheat-linux-amd64.gz`) depending on your platform.
+
+See the [releases page][releases] for a list of supported platforms.
+
+#### Windows
+TODO: community support is requested here. Please open a PR if you'd like to
+contribute installation instructions for Windows.
+
+### Install via `go install`
+If you have `go` version `>=1.17` available on your `PATH`, you can install
+`cheat` via `go install`:
+
+```sh
+go install github.com/cheat/cheat/cmd/cheat@latest
+```
+
+### Install via package manager
+Several community-maintained packages are also available:
+
+Package manager  | Package(s)
+---------------- | -----------
+aur              | [cheat][pkg-aur-cheat], [cheat-bin][pkg-aur-cheat-bin]
+brew             | [cheat][pkg-brew]
+docker           | [docker-cheat][pkg-docker]
+nix              | [nixos.cheat][pkg-nix]
+snap             | [cheat][pkg-snap]
+
+<!--[pacman][]       |-->
+
+## Configuring
+Three things must be done before you can use `cheat`:
+1. A config file must be generated
+2. [`cheatpaths`][cheatpaths] must be configured
+3. [Community cheatsheets][community] must be downloaded
+
+On first run, `cheat` will run an installer that will do all of the above
+automatically. After the installer is complete, it is strongly advised that you
+view the configuration file that was generated, as you may want to change some
+of its default values (to enable colorization, change the paginator, etc).
+
+### conf.yml ###
+`cheat` is configured by a YAML file that will be auto-generated on first run.
+
+By default, the config file is assumed to exist on an XDG-compliant
+configuration path like `~/.config/cheat/conf.yml`. If you would like to store
+it elsewhere, you may export a `CHEAT_CONFIG_PATH` environment variable that
+specifies its path:
+
+```sh
+export CHEAT_CONFIG_PATH="~/.dotfiles/cheat/conf.yml"
+```
+
+[cheatpaths]:        README.md#cheatpaths
+[community]:         https://github.com/cheat/cheatsheets/
+[pkg-aur-cheat-bin]: https://aur.archlinux.org/packages/cheat-bin
+[pkg-aur-cheat]:     https://aur.archlinux.org/packages/cheat
+[pkg-brew]:          https://formulae.brew.sh/formula/cheat 
+[pkg-docker]:        https://github.com/bannmann/docker-cheat
+[pkg-nix]:           https://search.nixos.org/packages?channel=unstable&show=cheat&from=0&size=50&sort=relevance&type=packages&query=cheat 
+[pkg-snap]:          https://snapcraft.io/cheat
+[releases]:          https://github.com/cheat/cheat/releases

Makefile

@@ -0,0 +1,195 @@
+# paths
+makefile := $(realpath $(lastword $(MAKEFILE_LIST)))
+cmd_dir  := ./cmd/cheat
+dist_dir := ./dist
+
+# executables
+CAT    := cat
+COLUMN := column
+CTAGS  := ctags
+DOCKER := docker
+GO     := go
+GREP   := grep
+GZIP   := gzip --best
+LINT   := revive
+MAN    := man
+MKDIR  := mkdir -p
+PANDOC := pandoc
+RM     := rm
+SCC    := scc
+SED    := sed
+SORT   := sort
+ZIP    := zip -m
+
+docker_image := cheat-devel:latest
+
+# build flags
+BUILD_FLAGS  := -ldflags="-s -w" -mod vendor -trimpath
+GOBIN        :=
+TMPDIR       := /tmp
+
+# release binaries
+releases :=                        \
+	$(dist_dir)/cheat-darwin-amd64 \
+	$(dist_dir)/cheat-linux-386    \
+	$(dist_dir)/cheat-linux-amd64  \
+	$(dist_dir)/cheat-linux-arm5   \
+	$(dist_dir)/cheat-linux-arm6   \
+	$(dist_dir)/cheat-linux-arm7   \
+	$(dist_dir)/cheat-linux-arm64  \
+	$(dist_dir)/cheat-windows-amd64.exe
+
+## build: build an executable for your architecture
+.PHONY: build
+build: $(dist_dir) | clean generate fmt lint vet vendor man
+	$(GO) build $(BUILD_FLAGS) -o $(dist_dir)/cheat $(cmd_dir)
+
+## build-release: build release executables
+.PHONY: build-release
+build-release: $(releases)
+
+# cheat-darwin-amd64
+$(dist_dir)/cheat-darwin-amd64: prepare
+	GOARCH=amd64 GOOS=darwin \
+	$(GO) build $(BUILD_FLAGS) -o $@ $(cmd_dir) && $(GZIP) $@ && chmod -x $@.gz
+
+# cheat-linux-386
+$(dist_dir)/cheat-linux-386: prepare
+	GOARCH=386 GOOS=linux \
+	$(GO) build $(BUILD_FLAGS) -o $@ $(cmd_dir) && $(GZIP) $@ && chmod -x $@.gz
+
+# cheat-linux-amd64
+$(dist_dir)/cheat-linux-amd64: prepare
+	GOARCH=amd64 GOOS=linux \
+	$(GO) build $(BUILD_FLAGS) -o $@ $(cmd_dir) && $(GZIP) $@ && chmod -x $@.gz
+
+# cheat-linux-arm5
+$(dist_dir)/cheat-linux-arm5: prepare
+	GOARCH=arm GOOS=linux GOARM=5 \
+	$(GO) build $(BUILD_FLAGS) -o $@ $(cmd_dir) && $(GZIP) $@ && chmod -x $@.gz
+
+# cheat-linux-arm6
+$(dist_dir)/cheat-linux-arm6: prepare
+	GOARCH=arm GOOS=linux GOARM=6 \
+	$(GO) build $(BUILD_FLAGS) -o $@ $(cmd_dir) && $(GZIP) $@ && chmod -x $@.gz
+
+# cheat-linux-arm7
+$(dist_dir)/cheat-linux-arm7: prepare
+	GOARCH=arm GOOS=linux GOARM=7 \
+	$(GO) build $(BUILD_FLAGS) -o $@ $(cmd_dir) && $(GZIP) $@ && chmod -x $@.gz
+	
+# cheat-linux-arm64
+$(dist_dir)/cheat-linux-arm64: prepare
+	GOARCH=arm64 GOOS=linux \
+	$(GO) build $(BUILD_FLAGS) -o $@ $(cmd_dir) && $(GZIP) $@ && chmod -x $@.gz
+
+# cheat-windows-amd64
+$(dist_dir)/cheat-windows-amd64.exe: prepare
+	GOARCH=amd64 GOOS=windows \
+	$(GO) build $(BUILD_FLAGS) -o $@ $(cmd_dir) && $(ZIP) $@.zip $@ -j
+
+# ./dist
+$(dist_dir):
+	$(MKDIR) $(dist_dir)
+
+.PHONY: generate
+generate:
+	$(GO) generate $(cmd_dir)
+
+## install: build and install cheat on your PATH
+.PHONY: install
+install: build
+	$(GO) install $(BUILD_FLAGS) $(GOBIN) $(cmd_dir) 
+
+## clean: remove compiled executables
+.PHONY: clean
+clean: $(dist_dir)
+	$(RM) -f $(dist_dir)/* $(cmd_dir)/str_config.go $(cmd_dir)/str_usage.go
+
+## distclean: remove the tags file
+.PHONY: distclean
+distclean:
+	$(RM) -f tags
+	@$(DOCKER) image rm -f $(docker_image)
+
+## setup: install revive (linter) and scc (sloc tool)
+.PHONY: setup
+setup:
+	GO111MODULE=off $(GO) get -u github.com/boyter/scc github.com/mgechev/revive
+
+## sloc: count "semantic lines of code"
+.PHONY: sloc
+sloc:
+	$(SCC) --exclude-dir=vendor
+
+## tags: build a tags file
+.PHONY: tags
+tags:
+	$(CTAGS) -R --exclude=vendor --languages=go
+
+## man: build a man page
+# NB: pandoc may not be installed, so we're ignoring this error on failure
+.PHONY: man
+man:
+	-$(PANDOC) -s -t man doc/cheat.1.md -o doc/cheat.1
+
+## vendor: download, tidy, and verify dependencies
+.PHONY: vendor
+vendor:
+	$(GO) mod vendor && $(GO) mod tidy && $(GO) mod verify
+
+## vendor-update: update vendored dependencies
+vendor-update:
+	$(GO) get -t -u ./... && $(GO) mod vendor
+
+## fmt: run go fmt
+.PHONY: fmt
+fmt:
+	$(GO) fmt ./...
+
+## lint: lint go source files
+.PHONY: lint
+lint: vendor
+	$(LINT) -exclude vendor/... ./...
+
+## vet: vet go source files
+.PHONY: vet
+vet:
+	$(GO) vet ./...
+
+## test: run unit-tests
+.PHONY: test
+test: 
+	$(GO) test ./...
+
+## coverage: generate a test coverage report
+.PHONY: coverage
+coverage:
+	$(GO) test ./... -coverprofile=$(TMPDIR)/cheat-coverage.out && \
+	$(GO) tool cover -html=$(TMPDIR)/cheat-coverage.out
+
+## check: format, lint, vet, vendor, and run unit-tests
+.PHONY: check
+check: | vendor fmt lint vet test
+
+.PHONY: prepare
+prepare: | $(dist_dir) clean generate vendor fmt lint vet test
+
+## docker-setup: create a docker image for use during development
+.PHONY: docker-setup
+docker-setup:
+	$(DOCKER) build  -t $(docker_image) -f Dockerfile .
+
+## docker-sh: shell into the docker development container
+.PHONY: docker-sh
+docker-sh:
+	$(DOCKER) run -v $(shell pwd):/app -ti $(docker_image) /bin/ash
+
+## help: display this help text
+.PHONY: help
+help:
+	@$(CAT) $(makefile) | \
+	$(SORT)             | \
+	$(GREP) "^##"       | \
+	$(SED) 's/## //g'   | \
+	$(COLUMN) -t -s ':'

README.md

@@ -1,5 +1,9 @@
+![Workflow status](https://github.com/cheat/cheat/actions/workflows/build.yml/badge.svg)
+
+
 cheat
 =====
+
 `cheat` allows you to create and view interactive cheatsheets on the
 command-line. It was designed to help remind \*nix system administrators of
 options for commands that they use frequently, but not frequently enough to
@@ -38,91 +42,6 @@ tar -xjvf '/path/to/foo.tgz'
 tar -cjvf '/path/to/foo.tgz' '/path/to/foo/'
 ```
 
-
-Installing
-----------
-`cheat` has no dependencies. To install it, download the executable from the
-[releases][] page and place it on your `PATH`.
-
-
-Configuring
------------
-### conf.yml ###
-`cheat` is configured by a YAML file that can be generated with `cheat --init`:
-
-```sh
-mkdir -p ~/.config/cheat && cheat --init > ~/.config/cheat/conf.yml
-```
-
-By default, the config file is assumed to exist on an XDG-compliant
-configuration path like `~/.config/cheat/conf.yml`. If you would like to store
-it elsewhere, you may export a `CHEAT_CONFIG_PATH` environment variable that
-specifies its path:
-
-```sh
-export CHEAT_CONFIG_PATH="~/.dotfiles/cheat/conf.yml"
-```
-
-Cheatsheets
------------
-Cheatsheets are plain-text files with no file extension, and are named
-according to the command used to view them:
-
-```sh
-cheat tar     # file is named "tar"
-cheat foo/bar # file is named "bar", in a "foo" subdirectory
-```
-
-Cheatsheet text may optionally be preceeded by a YAML frontmatter header that
-assigns tags and specifies syntax:
-
-```
----
-syntax: javascript
-tags: [ array, map ]
----
-// To map over an array:
-const squares = [1, 2, 3, 4].map(x => x * x);
-```
-
-The `cheat` executable includes no cheatsheets, but [community-sourced
-cheatsheets are available][cheatsheets].
-
-
-Cheatpaths
-----------
-Cheatsheets are stored on "cheatpaths", which are directories that contain
-cheetsheets. Cheatpaths are specified in the `conf.yml` file.
-
-It can be useful to configure `cheat` against multiple cheatpaths. A common
-pattern is to store cheatsheets from multiple repositories on individual
-cheatpaths:
-
-```yaml
-# conf.yml:
-# ...
-cheatpaths:
-  - name: community                   # a name for the cheatpath
-    path: ~/documents/cheat/community # the path's location on the filesystem
-    tags: [ community ]               # these tags will be applied to all sheets on the path
-    readonly: true                    # if true, `cheat` will not create new cheatsheets here
-
-  - name: personal
-    path: ~/documents/cheat/personal  # this is a separate directory and repository than above
-    tags: [ personal ]
-    readonly: false                   # new sheets may be written here
-# ...
-```
-
-The `readonly` option instructs `cheat` not to edit (or create) any cheatsheets
-on the path. This is useful to prevent merge-conflicts from arising on upstream
-cheatsheet repositories.
-
-If a user attempts to edit a cheatsheet on a read-only cheatpath, `cheat` will
-transparently copy that sheet to a writeable directory before opening it for
-editing.
-
-
 Usage
 -----
 To view a cheatsheet:
@@ -175,21 +94,100 @@ To search (by regex) for cheatsheets that contain an IP address:
 cheat -r -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'
 ```
 
-Flags may be combined in inuitive ways. Example: to search sheets on the
+Flags may be combined in intuitive ways. Example: to search sheets on the
 "personal" cheatpath that are tagged with "networking" and match a regex:
 
 ```sh
-cheat -p personal -t networking -s --regex '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'
+cheat -p personal -t networking --regex -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'
 ```
 
 
-Advanced Usage
+
+Installing
+----------
+For installation and configuration instructions, see [INSTALLING.md][].
+
+Cheatsheets
+-----------
+Cheatsheets are plain-text files with no file extension, and are named
+according to the command used to view them:
+
+```sh
+cheat tar     # file is named "tar"
+cheat foo/bar # file is named "bar", in a "foo" subdirectory
+```
+
+Cheatsheet text may optionally be preceeded by a YAML frontmatter header that
+assigns tags and specifies syntax:
+
+```
+---
+syntax: javascript
+tags: [ array, map ]
+---
+// To map over an array:
+const squares = [1, 2, 3, 4].map(x => x * x);
+```
+
+The `cheat` executable includes no cheatsheets, but [community-sourced
+cheatsheets are available][cheatsheets]. You will be asked if you would like to
+install the community-sourced cheatsheets the first time you run `cheat`.
+
+Cheatpaths
+----------
+Cheatsheets are stored on "cheatpaths", which are directories that contain
+cheatsheets. Cheatpaths are specified in the `conf.yml` file.
+
+It can be useful to configure `cheat` against multiple cheatpaths. A common
+pattern is to store cheatsheets from multiple repositories on individual
+cheatpaths:
+
+```yaml
+# conf.yml:
+# ...
+cheatpaths:
+  - name: community                   # a name for the cheatpath
+    path: ~/documents/cheat/community # the path's location on the filesystem
+    tags: [ community ]               # these tags will be applied to all sheets on the path
+    readonly: true                    # if true, `cheat` will not create new cheatsheets here
+
+  - name: personal
+    path: ~/documents/cheat/personal  # this is a separate directory and repository than above
+    tags: [ personal ]
+    readonly: false                   # new sheets may be written here
+# ...
+```
+
+The `readonly` option instructs `cheat` not to edit (or create) any cheatsheets
+on the path. This is useful to prevent merge-conflicts from arising on upstream
+cheatsheet repositories.
+
+If a user attempts to edit a cheatsheet on a read-only cheatpath, `cheat` will
+transparently copy that sheet to a writeable directory before opening it for
+editing.
+
+### Directory-scoped Cheatpaths ###
+At times, it can be useful to closely associate cheatsheets with a directory on
+your filesystem. `cheat` facilitates this by searching for a `.cheat` folder in
+the current working directory. If found, the `.cheat` directory will
+(temporarily) be added to the cheatpaths.
+
+Autocompletion
 --------------
-`cheat` may be integrated with [fzf][]. See [fzf.bash][bash] for instructions.
-(Support for other shells will be added in future releases.)
+Shell autocompletion is currently available for `bash`, `fish`, and `zsh`. Copy
+the relevant [completion script][completions] into the appropriate directory on
+your filesystem to enable autocompletion. (This directory will vary depending
+on operating system and shell specifics.)
 
+Additionally, `cheat` supports enhanced autocompletion via integration with
+[fzf][]. To enable `fzf` integration:
 
-[Releases]:    https://github.com/cheat/cheat/releases
-[bash]:        https://github.com/cheat/cheat/blob/master/scripts/fzf.bash
-[cheatsheets]: https://github.com/cheat/cheatsheets
-[fzf]:         https://github.com/junegunn/fzf
+1. Ensure that `fzf` is available on your `$PATH`
+2. Set an envvar: `export CHEAT_USE_FZF=true`
+
+[INSTALLING.md]: INSTALLING.md
+[Releases]:      https://github.com/cheat/cheat/releases
+[cheatsheets]:   https://github.com/cheat/cheatsheets
+[completions]:   https://github.com/cheat/cheat/tree/master/scripts
+[fzf]:           https://github.com/junegunn/fzf
+[go]:            https://golang.org

bin/build_devel.sh

@@ -1,13 +0,0 @@
-#!/bin/bash
-
-# locate the cheat project root
-BINDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-APPDIR=$(readlink -f "$BINDIR/..")
-
-# compile the executable
-cd "$APPDIR/cmd/cheat"
-go clean && go generate && go build
-mv "$APPDIR/cmd/cheat/cheat" "$APPDIR/dist/cheat"
-
-# display a build checksum
-md5sum "$APPDIR/dist/cheat"

bin/build_release.sh

@@ -1,14 +0,0 @@
-#!/bin/bash
-
-# locate the cheat project root
-BINDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-APPDIR=$(readlink -f "$BINDIR/..")
-
-# build embeds
-cd "$APPDIR/cmd/cheat"
-go clean && go generate
-
-# compile AMD64 for Linux, OSX, and Windows
-env GOOS=darwin  GOARCH=amd64 go build -o "$APPDIR/dist/cheat-darwin-amd64"  "$APPDIR/cmd/cheat"
-env GOOS=linux   GOARCH=amd64 go build -o "$APPDIR/dist/cheat-linux-amd64"   "$APPDIR/cmd/cheat"
-env GOOS=windows GOARCH=amd64 go build -o "$APPDIR/dist/cheat-win-amd64.exe" "$APPDIR/cmd/cheat"

build/embed.go

@@ -1,3 +1,4 @@
+//go:build ignore
 // +build ignore
 
 // This script embeds `docopt.txt and `conf.yml` into the binary during at
@@ -5,13 +6,11 @@
 
 package main
 
-
 import (
 	"fmt"
 	"io/ioutil"
 	"log"
 	"os"
-	"path"
 	"path/filepath"
 )
 
@@ -52,10 +51,10 @@ func main() {
 	for _, file := range files {
 
 		// delete the outfile
-		os.Remove(path.Join(root, file.Out))
+		os.Remove(filepath.Join(root, file.Out))
 
 		// read the static template
-		bytes, err := ioutil.ReadFile(path.Join(root, file.In))
+		bytes, err := ioutil.ReadFile(filepath.Join(root, file.In))
 		if err != nil {
 			log.Fatal(err)
 		}
@@ -64,7 +63,7 @@ func main() {
 		data := template(file.Method, string(bytes))
 
 		// write the file to the specified outpath
-		spath := path.Join(root, file.Out)
+		spath := filepath.Join(root, file.Out)
 		err = ioutil.WriteFile(spath, []byte(data), 0644)
 		if err != nil {
 			log.Fatal(err)

cmd/cheat/cmd_conf.go

@@ -0,0 +1,11 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/cheat/cheat/internal/config"
+)
+
+func cmdConf(opts map[string]interface{}, conf config.Config) {
+	fmt.Println(conf.Path)
+}

cmd/cheat/cmd_directories.go

@@ -1,28 +1,27 @@
 package main
 
 import (
+	"bytes"
 	"fmt"
-	"os"
 	"text/tabwriter"
 
 	"github.com/cheat/cheat/internal/config"
+	"github.com/cheat/cheat/internal/display"
 )
 
 // cmdDirectories lists the configured cheatpaths.
 func cmdDirectories(opts map[string]interface{}, conf config.Config) {
 
 	// initialize a tabwriter to produce cleanly columnized output
-	w := tabwriter.NewWriter(os.Stdout, 0, 0, 1, ' ', 0)
+	var out bytes.Buffer
+	w := tabwriter.NewWriter(&out, 0, 0, 1, ' ', 0)
 
 	// generate sorted, columnized output
 	for _, path := range conf.Cheatpaths {
-		fmt.Fprintln(w, fmt.Sprintf(
-			"%s:\t%s",
-			path.Name,
-			path.Path,
-		))
+		fmt.Fprintf(w, "%s:\t%s\n", path.Name, path.Path)
 	}
 
 	// write columnized output to stdout
 	w.Flush()
+	display.Write(out.String(), conf)
 }

cmd/cheat/cmd_edit.go

@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"os"
 	"os/exec"
-	"path"
+	"path/filepath"
 	"strings"
 
 	"github.com/cheat/cheat/internal/cheatpath"
@@ -20,7 +20,7 @@ func cmdEdit(opts map[string]interface{}, conf config.Config) {
 	// load the cheatsheets
 	cheatsheets, err := sheets.Load(conf.Cheatpaths)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, fmt.Sprintf("failed to list cheatsheets: %v", err))
+		fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
 		os.Exit(1)
 	}
 
@@ -58,10 +58,10 @@ func cmdEdit(opts map[string]interface{}, conf config.Config) {
 		}
 
 		// compute the new edit path
-		editpath = path.Join(writepath.Path, sheet.Title)
+		editpath = filepath.Join(writepath.Path, sheet.Title)
 
 		// create any necessary subdirectories
-		dirs := path.Dir(editpath)
+		dirs := filepath.Dir(editpath)
 		if dirs != "." {
 			if err := os.MkdirAll(dirs, 0755); err != nil {
 				fmt.Fprintf(os.Stderr, "failed to create directory: %s, %v\n", dirs, err)
@@ -87,10 +87,10 @@ func cmdEdit(opts map[string]interface{}, conf config.Config) {
 		}
 
 		// compute the new edit path
-		editpath = path.Join(writepath.Path, cheatsheet)
+		editpath = filepath.Join(writepath.Path, cheatsheet)
 
 		// create any necessary subdirectories
-		dirs := path.Dir(editpath)
+		dirs := filepath.Dir(editpath)
 		if dirs != "." {
 			if err := os.MkdirAll(dirs, 0755); err != nil {
 				fmt.Fprintf(os.Stderr, "failed to create directory: %s, %v\n", dirs, err)
@@ -99,8 +99,15 @@ func cmdEdit(opts map[string]interface{}, conf config.Config) {
 		}
 	}
 
+	// split `conf.Editor` into parts to separate the editor's executable from
+	// any arguments it may have been passed. If this is not done, the nearby
+	// call to `exec.Command` will fail.
+	parts := strings.Fields(conf.Editor)
+	editor := parts[0]
+	args := append(parts[1:], editpath)
+
 	// edit the cheatsheet
-	cmd := exec.Command(conf.Editor, editpath)
+	cmd := exec.Command(editor, args...)
 	cmd.Stdout = os.Stdout
 	cmd.Stdin = os.Stdin
 	cmd.Stderr = os.Stderr

cmd/cheat/cmd_init.go

@@ -2,9 +2,56 @@ package main
 
 import (
 	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/mitchellh/go-homedir"
+
+	"github.com/cheat/cheat/internal/config"
 )
 
 // cmdInit displays an example config file.
 func cmdInit() {
-	fmt.Println(configs())
+
+	// get the user's home directory
+	home, err := homedir.Dir()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to get user home directory: %v\n", err)
+		os.Exit(1)
+	}
+
+	// read the envvars into a map of strings
+	envvars := map[string]string{}
+	for _, e := range os.Environ() {
+		pair := strings.SplitN(e, "=", 2)
+		envvars[pair[0]] = pair[1]
+	}
+
+	// load the config template
+	configs := configs()
+
+	// identify the os-specifc paths at which configs may be located
+	confpaths, err := config.Paths(runtime.GOOS, home, envvars)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to read config paths: %v\n", err)
+		os.Exit(1)
+	}
+
+	// determine the appropriate paths for config data and (optional) community
+	// cheatsheets based on the user's platform
+	confpath := confpaths[0]
+	confdir := filepath.Dir(confpath)
+
+	// create paths for community and personal cheatsheets
+	community := filepath.Join(confdir, "cheatsheets", "community")
+	personal := filepath.Join(confdir, "cheatsheets", "personal")
+
+	// template the above paths into the default configs
+	configs = strings.Replace(configs, "COMMUNITY_PATH", community, -1)
+	configs = strings.Replace(configs, "PERSONAL_PATH", personal, -1)
+
+	// output the templated configs
+	fmt.Println(configs)
 }

cmd/cheat/cmd_list.go

@@ -1,13 +1,16 @@
 package main
 
 import (
+	"bytes"
 	"fmt"
 	"os"
+	"regexp"
 	"sort"
 	"strings"
 	"text/tabwriter"
 
 	"github.com/cheat/cheat/internal/config"
+	"github.com/cheat/cheat/internal/display"
 	"github.com/cheat/cheat/internal/sheet"
 	"github.com/cheat/cheat/internal/sheets"
 )
@@ -18,11 +21,11 @@ func cmdList(opts map[string]interface{}, conf config.Config) {
 	// load the cheatsheets
 	cheatsheets, err := sheets.Load(conf.Cheatpaths)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, fmt.Sprintf("failed to list cheatsheets: %v", err))
+		fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
 		os.Exit(1)
 	}
 
-	// filter cheatcheats by tag if --tag was provided
+	// filter cheatsheets by tag if --tag was provided
 	if opts["--tag"] != nil {
 		cheatsheets = sheets.Filter(
 			cheatsheets,
@@ -34,8 +37,8 @@ func cmdList(opts map[string]interface{}, conf config.Config) {
 	// sheets with local sheets), here we simply want to create a slice
 	// containing all sheets.
 	flattened := []sheet.Sheet{}
-	for _, pathSheets := range cheatsheets {
-		for _, s := range pathSheets {
+	for _, pathsheets := range cheatsheets {
+		for _, s := range pathsheets {
 			flattened = append(flattened, s)
 		}
 	}
@@ -45,25 +48,54 @@ func cmdList(opts map[string]interface{}, conf config.Config) {
 		return flattened[i].Title < flattened[j].Title
 	})
 
-	// exit early if no cheatsheets are available
+	// filter if <cheatsheet> was specified
+	// NB: our docopt specification is misleading here. When used in conjunction
+	// with `-l`, `<cheatsheet>` is really a pattern against which to filter
+	// sheet titles.
+	if opts["<cheatsheet>"] != nil {
+
+		// initialize a slice of filtered sheets
+		filtered := []sheet.Sheet{}
+
+		// initialize our filter pattern
+		pattern := "(?i)" + opts["<cheatsheet>"].(string)
+
+		// compile the regex
+		reg, err := regexp.Compile(pattern)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to compile regexp: %s, %v\n", pattern, err)
+			os.Exit(1)
+		}
+
+		// iterate over each cheatsheet, and pass-through those which match the
+		// filter pattern
+		for _, s := range flattened {
+			if reg.MatchString(s.Title) {
+				filtered = append(filtered, s)
+			}
+		}
+
+		flattened = filtered
+	}
+
+	// return exit code 2 if no cheatsheets are available
 	if len(flattened) == 0 {
-		os.Exit(0)
+		os.Exit(2)
 	}
 
 	// initialize a tabwriter to produce cleanly columnized output
-	w := tabwriter.NewWriter(os.Stdout, 0, 0, 1, ' ', 0)
+	var out bytes.Buffer
+	w := tabwriter.NewWriter(&out, 0, 0, 1, ' ', 0)
+
+	// write a header row
+	fmt.Fprintln(w, "title:\tfile:\ttags:")
 
 	// generate sorted, columnized output
-	fmt.Fprintln(w, "title:\tfile:\ttags:")
 	for _, sheet := range flattened {
-		fmt.Fprintln(w, fmt.Sprintf(
-			"%s\t%s\t%s",
-			sheet.Title,
-			sheet.Path,
-			strings.Join(sheet.Tags, ","),
-		))
+		fmt.Fprintf(w, "%s\t%s\t%s\n", sheet.Title, sheet.Path, strings.Join(sheet.Tags, ","))
 	}
 
 	// write columnized output to stdout
 	w.Flush()
+	display.Write(out.String(), conf)
 }

cmd/cheat/cmd_remove.go

@@ -0,0 +1,55 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/cheat/cheat/internal/config"
+	"github.com/cheat/cheat/internal/sheets"
+)
+
+// cmdRemove opens a cheatsheet for editing (or creates it if it doesn't exist).
+func cmdRemove(opts map[string]interface{}, conf config.Config) {
+
+	cheatsheet := opts["--rm"].(string)
+
+	// load the cheatsheets
+	cheatsheets, err := sheets.Load(conf.Cheatpaths)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
+		os.Exit(1)
+	}
+
+	// filter cheatcheats by tag if --tag was provided
+	if opts["--tag"] != nil {
+		cheatsheets = sheets.Filter(
+			cheatsheets,
+			strings.Split(opts["--tag"].(string), ","),
+		)
+	}
+
+	// consolidate the cheatsheets found on all paths into a single map of
+	// `title` => `sheet` (ie, allow more local cheatsheets to override less
+	// local cheatsheets)
+	consolidated := sheets.Consolidate(cheatsheets)
+
+	// fail early if the requested cheatsheet does not exist
+	sheet, ok := consolidated[cheatsheet]
+	if !ok {
+		fmt.Fprintf(os.Stderr, "No cheatsheet found for '%s'.\n", cheatsheet)
+		os.Exit(2)
+	}
+
+	// fail early if the sheet is read-only
+	if sheet.ReadOnly {
+		fmt.Fprintf(os.Stderr, "cheatsheet '%s' is read-only.\n", cheatsheet)
+		os.Exit(1)
+	}
+
+	// otherwise, attempt to delete the sheet
+	if err := os.Remove(sheet.Path); err != nil {
+		fmt.Fprintf(os.Stderr, "failed to delete sheet: %s, %v\n", sheet.Title, err)
+		os.Exit(1)
+	}
+}

cmd/cheat/cmd_search.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 
 	"github.com/cheat/cheat/internal/config"
+	"github.com/cheat/cheat/internal/display"
 	"github.com/cheat/cheat/internal/sheets"
 )
 
@@ -18,7 +19,7 @@ func cmdSearch(opts map[string]interface{}, conf config.Config) {
 	// load the cheatsheets
 	cheatsheets, err := sheets.Load(conf.Cheatpaths)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, fmt.Sprintf("failed to list cheatsheets: %v", err))
+		fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
 		os.Exit(1)
 	}
 
@@ -30,46 +31,67 @@ func cmdSearch(opts map[string]interface{}, conf config.Config) {
 		)
 	}
 
-	// consolidate the cheatsheets found on all paths into a single map of
-	// `title` => `sheet` (ie, allow more local cheatsheets to override less
-	// local cheatsheets)
-	consolidated := sheets.Consolidate(cheatsheets)
+	// iterate over each cheatpath
+	out := ""
+	for _, pathcheats := range cheatsheets {
 
-	// sort the cheatsheets alphabetically, and search for matches
-	for _, sheet := range sheets.Sort(consolidated) {
+		// sort the cheatsheets alphabetically, and search for matches
+		for _, sheet := range sheets.Sort(pathcheats) {
 
-		// colorize output?
-		colorize := false
-		if conf.Colorize == true || opts["--colorize"] == true {
-			colorize = true
-		}
-
-		// assume that we want to perform a case-insensitive search for <phrase>
-		pattern := "(?i)" + phrase
-
-		// unless --regex is provided, in which case we pass the regex unaltered
-		if opts["--regex"] == true {
-			pattern = phrase
-		}
-
-		// compile the regex
-		reg, err := regexp.Compile(pattern)
-		if err != nil {
-			fmt.Errorf("failed to compile regexp: %s, %v", pattern, err)
-			os.Exit(1)
-		}
-
-		// search the sheet
-		matches := sheet.Search(reg, colorize)
-
-		// display the results
-		if len(matches) > 0 {
-			fmt.Printf("%s:\n", sheet.Title)
-			for _, m := range matches {
-				fmt.Printf("  %d: %s\n", m.Line, m.Text)
+			// if <cheatsheet> was provided, constrain the search only to
+			// matching cheatsheets
+			if opts["<cheatsheet>"] != nil && sheet.Title != opts["<cheatsheet>"] {
+				continue
 			}
-			fmt.Print("\n")
+
+			// assume that we want to perform a case-insensitive search for <phrase>
+			pattern := "(?i)" + phrase
+
+			// unless --regex is provided, in which case we pass the regex unaltered
+			if opts["--regex"] == true {
+				pattern = phrase
+			}
+
+			// compile the regex
+			reg, err := regexp.Compile(pattern)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "failed to compile regexp: %s, %v\n", pattern, err)
+				os.Exit(1)
+			}
+
+			// `Search` will return text entries that match the search terms.
+			// We're using it here to overwrite the prior cheatsheet Text,
+			// filtering it to only what is relevant.
+			sheet.Text = sheet.Search(reg)
+
+			// if the sheet did not match the search, ignore it and move on
+			if sheet.Text == "" {
+				continue
+			}
+
+			// if colorization was requested, apply it here
+			if conf.Color(opts) {
+				sheet.Colorize(conf)
+			}
+
+			// display the cheatsheet body
+			out += fmt.Sprintf(
+				"%s %s\n%s\n",
+				// append the cheatsheet title
+				sheet.Title,
+				// append the cheatsheet path
+				display.Faint(fmt.Sprintf("(%s)", sheet.CheatPath), conf),
+				// indent each line of content
+				display.Indent(sheet.Text),
+			)
 		}
 	}
 
+	// trim superfluous newlines
+	out = strings.TrimSpace(out)
+
+	// display the output
+	// NB: resist the temptation to call `display.Write` multiple times in the
+	// loop above. That will not play nicely with the paginator.
+	display.Write(out, conf)
 }

cmd/cheat/cmd_tags.go

@@ -0,0 +1,30 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/cheat/cheat/internal/config"
+	"github.com/cheat/cheat/internal/display"
+	"github.com/cheat/cheat/internal/sheets"
+)
+
+// cmdTags lists all tags in use.
+func cmdTags(opts map[string]interface{}, conf config.Config) {
+
+	// load the cheatsheets
+	cheatsheets, err := sheets.Load(conf.Cheatpaths)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
+		os.Exit(1)
+	}
+
+	// assemble the output
+	out := ""
+	for _, tag := range sheets.Tags(cheatsheets) {
+		out += fmt.Sprintln(tag)
+	}
+
+	// display the output
+	display.Write(out, conf)
+}

cmd/cheat/cmd_view.go

@@ -5,9 +5,8 @@ import (
 	"os"
 	"strings"
 
-	"github.com/alecthomas/chroma/quick"
-
 	"github.com/cheat/cheat/internal/config"
+	"github.com/cheat/cheat/internal/display"
 	"github.com/cheat/cheat/internal/sheets"
 )
 
@@ -19,7 +18,7 @@ func cmdView(opts map[string]interface{}, conf config.Config) {
 	// load the cheatsheets
 	cheatsheets, err := sheets.Load(conf.Cheatpaths)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, fmt.Sprintf("failed to list cheatsheets: %v", err))
+		fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
 		os.Exit(1)
 	}
 
@@ -31,42 +30,53 @@ func cmdView(opts map[string]interface{}, conf config.Config) {
 		)
 	}
 
-	// consolidate the cheatsheets found on all paths into a single map of
-	// `title` => `sheet` (ie, allow more local cheatsheets to override less
-	// local cheatsheets)
+	// if --all was passed, display cheatsheets from all cheatpaths
+	if opts["--all"].(bool) {
+		// iterate over the cheatpaths
+		out := ""
+		for _, cheatpath := range cheatsheets {
+
+			// if the cheatpath contains the specified cheatsheet, display it
+			if sheet, ok := cheatpath[cheatsheet]; ok {
+
+				// identify the matching cheatsheet
+				out += fmt.Sprintf("%s %s\n",
+					sheet.Title,
+					display.Faint(fmt.Sprintf("(%s)", sheet.CheatPath), conf),
+				)
+
+				// apply colorization if requested
+				if conf.Color(opts) {
+					sheet.Colorize(conf)
+				}
+
+				// display the cheatsheet
+				out += display.Indent(sheet.Text) + "\n"
+			}
+		}
+
+		// display and exit
+		display.Write(strings.TrimSuffix(out, "\n"), conf)
+		os.Exit(0)
+	}
+
+	// otherwise, consolidate the cheatsheets found on all paths into a single
+	// map of `title` => `sheet` (ie, allow more local cheatsheets to override
+	// less local cheatsheets)
 	consolidated := sheets.Consolidate(cheatsheets)
 
 	// fail early if the requested cheatsheet does not exist
 	sheet, ok := consolidated[cheatsheet]
 	if !ok {
 		fmt.Printf("No cheatsheet found for '%s'.\n", cheatsheet)
-		os.Exit(0)
+		os.Exit(2)
 	}
 
-	// if colorization is not desired, output un-colorized text and exit
-	if conf.Colorize == false && opts["--colorize"] == false {
-		fmt.Print(sheet.Text)
-		os.Exit(0)
+	// apply colorization if requested
+	if conf.Color(opts) {
+		sheet.Colorize(conf)
 	}
 
-	// otherwise, colorize the output
-	// if the syntax was not specified, default to bash
-	lex := sheet.Syntax
-	if lex == "" {
-		lex = "bash"
-	}
-
-	// apply syntax highlighting
-	err = quick.Highlight(
-		os.Stdout,
-		sheet.Text,
-		lex,
-		conf.Formatter,
-		conf.Style,
-	)
-
-	// if colorization somehow failed, output non-colorized text
-	if err != nil {
-		fmt.Print(sheet.Text)
-	}
+	// display the cheatsheet
+	display.Write(sheet.Text, conf)
 }

cmd/cheat/docopt.txt

@@ -2,16 +2,20 @@ Usage:
   cheat [options] [<cheatsheet>]
 
 Options:
-  --init                Write a default config file to stdout
-  -c --colorize         Colorize output
-  -d --directories      List cheatsheet directories
-  -e --edit=<sheet>     Edit cheatsheet
-  -l --list             List cheatsheets
-  -p --path=<name>      Return only sheets found on path <name>
-  -r --regex            Treat search <phrase> as a regex
-  -s --search=<phrase>  Search cheatsheets for <phrase>
-  -t --tag=<tag>        Return only sheets matching <tag>
-  -v --version          Print the version number
+  --init                  Write a default config file to stdout
+  -a --all                Search among all cheatpaths
+  -c --colorize           Colorize output
+  -d --directories        List cheatsheet directories
+  -e --edit=<cheatsheet>  Edit <cheatsheet>
+  -l --list               List cheatsheets
+  -p --path=<name>        Return only sheets found on cheatpath <name>
+  -r --regex              Treat search <phrase> as a regex
+  -s --search=<phrase>    Search cheatsheets for <phrase>
+  -t --tag=<tag>          Return only sheets matching <tag>
+  -T --tags               List all tags in use
+  -v --version            Print the version number
+  --rm=<cheatsheet>       Remove (delete) <cheatsheet>
+  --conf                  Display the config file path
 
 Examples:
 
@@ -33,6 +37,12 @@ Examples:
   To list all available cheatsheets:
     cheat -l
 
+  To list all cheatsheets whose titles match "apt":
+    cheat -l apt
+
+  To list all tags in use:
+    cheat -T
+
   To list available cheatsheets that are tagged as "personal":
     cheat -l -t personal
 
@@ -41,3 +51,9 @@ Examples:
 
   To search (by regex) for cheatsheets that contain an IP address:
     cheat -c -r -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'
+
+  To remove (delete) the foo/bar cheatsheet:
+    cheat --rm foo/bar
+
+  To view the configuration file path:
+    cheat --conf

cmd/cheat/main.go

@@ -6,19 +6,22 @@ import (
 	"fmt"
 	"os"
 	"runtime"
+	"strings"
 
 	"github.com/docopt/docopt-go"
+	"github.com/mitchellh/go-homedir"
 
 	"github.com/cheat/cheat/internal/cheatpath"
 	"github.com/cheat/cheat/internal/config"
+	"github.com/cheat/cheat/internal/installer"
 )
 
-const version = "3.0.1"
+const version = "4.3.3"
 
 func main() {
 
 	// initialize options
-	opts, err := docopt.Parse(usage(), nil, true, version, false)
+	opts, err := docopt.ParseArgs(usage(), nil, version)
 	if err != nil {
 		// panic here, because this should never happen
 		panic(fmt.Errorf("docopt failed to parse: %v", err))
@@ -31,15 +34,65 @@ func main() {
 		os.Exit(0)
 	}
 
-	// load the config file
-	confpath, err := config.Path(runtime.GOOS)
+	// get the user's home directory
+	home, err := homedir.Dir()
 	if err != nil {
-		fmt.Fprintln(os.Stderr, "could not locate config file")
+		fmt.Fprintf(os.Stderr, "failed to get user home directory: %v\n", err)
 		os.Exit(1)
 	}
 
+	// read the envvars into a map of strings
+	envvars := map[string]string{}
+	for _, e := range os.Environ() {
+		pair := strings.SplitN(e, "=", 2)
+		if runtime.GOOS == "windows" {
+			pair[0] = strings.ToUpper(pair[0])
+		}
+		envvars[pair[0]] = pair[1]
+	}
+
+	// identify the os-specifc paths at which configs may be located
+	confpaths, err := config.Paths(runtime.GOOS, home, envvars)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to load config: %v\n", err)
+		os.Exit(1)
+	}
+
+	// search for the config file in the above paths
+	confpath, err := config.Path(confpaths)
+	if err != nil {
+		// prompt the user to create a config file
+		yes, err := installer.Prompt(
+			"A config file was not found. Would you like to create one now? [Y/n]",
+			true,
+		)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to create config: %v\n", err)
+			os.Exit(1)
+		}
+
+		// exit early on a negative answer
+		if !yes {
+			os.Exit(0)
+		}
+
+		// choose a confpath
+		confpath = confpaths[0]
+
+		// run the installer
+		if err := installer.Run(configs(), confpath); err != nil {
+			fmt.Fprintf(os.Stderr, "failed to run installer: %v\n", err)
+			os.Exit(1)
+		}
+
+		// notify the user and exit
+		fmt.Printf("Created config file: %s\n", confpath)
+		fmt.Println("Please read this file for advanced configuration information.")
+		os.Exit(0)
+	}
+
 	// initialize the configs
-	conf, err := config.New(opts, confpath)
+	conf, err := config.New(opts, confpath, true)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "failed to load config: %v\n", err)
 		os.Exit(1)
@@ -67,6 +120,9 @@ func main() {
 	var cmd func(map[string]interface{}, config.Config)
 
 	switch {
+	case opts["--conf"].(bool):
+		cmd = cmdConf
+
 	case opts["--directories"].(bool):
 		cmd = cmdDirectories
 
@@ -76,12 +132,21 @@ func main() {
 	case opts["--list"].(bool):
 		cmd = cmdList
 
+	case opts["--tags"].(bool):
+		cmd = cmdTags
+
 	case opts["--search"] != nil:
 		cmd = cmdSearch
 
+	case opts["--rm"] != nil:
+		cmd = cmdRemove
+
 	case opts["<cheatsheet>"] != nil:
 		cmd = cmdView
 
+	case opts["--tag"] != nil && opts["--tag"].(string) != "":
+		cmd = cmdList
+
 	default:
 		fmt.Println(usage())
 		os.Exit(0)

cmd/cheat/str_config.go

@@ -9,10 +9,10 @@ import (
 func configs() string {
 	return strings.TrimSpace(`---
 # The editor to use with 'cheat -e <sheet>'. Defaults to $EDITOR or $VISUAL.
-editor: vim
+editor: EDITOR_PATH
 
 # Should 'cheat' always colorize output?
-colorize: true
+colorize: false
 
 # Which 'chroma' colorscheme should be applied to the output?
 # Options are available here:
@@ -21,45 +21,73 @@ style: monokai
 
 # Which 'chroma' "formatter" should be applied?
 # One of: "terminal", "terminal256", "terminal16m"
-formatter: terminal16m
+formatter: terminal256
 
-# The paths at which cheatsheets are available. Tags associated with a cheatpath
-# are automatically attached to all cheatsheets residing on that path.
+# Through which pager should output be piped?
+# 'less -FRX' is recommended on Unix systems
+# 'more' is recommended on Windows
+pager: PAGER_PATH
+
+# Cheatpaths are paths at which cheatsheets are available on your local
+# filesystem.
 #
-# Whenever cheatsheets share the same title (like 'tar'), the most local
-# cheatsheets (those which come later in this file) take precedent over the
-# less local sheets. This allows you to create your own "overides" for
-# "upstream" cheatsheets.
+# It is useful to sort cheatsheets into different cheatpaths for organizational
+# purposes. For example, you might want one cheatpath for community
+# cheatsheets, one for personal cheatsheets, one for cheatsheets pertaining to
+# your day job, one for code snippets, etc.
 #
-# But what if you want to view the "upstream" cheatsheets instead of your own?
-# Cheatsheets may be filtered via 'cheat -f <tag>' in combination with other
-# commands. So, if you want to view the 'tar' cheatsheet that is tagged as
-# 'community' rather than your own, you can use: cheat tar -f community
+# Cheatpaths are scoped, such that more "local" cheatpaths take priority over
+# more "global" cheatpaths. (The most global cheatpath is listed first in this
+# file; the most local is listed last.) For example, if there is a 'tar'
+# cheatsheet on both global and local paths, you'll be presented with the local
+# one by default. ('cheat -p' can be used to view cheatsheets from alternative
+# cheatpaths.)
+#
+# Cheatpaths can also be tagged as "read only". This instructs cheat not to
+# automatically create cheatsheets on a read-only cheatpath. Instead, when you
+# would like to edit a read-only cheatsheet using 'cheat -e', cheat will
+# perform a copy-on-write of that cheatsheet from a read-only cheatpath to a
+# writeable cheatpath.
+#
+# This is very useful when you would like to maintain, for example, a
+# "pristine" repository of community cheatsheets on one cheatpath, and an
+# editable personal reponsity of cheatsheets on another cheatpath.
+#
+# Cheatpaths can be also configured to automatically apply tags to cheatsheets
+# on certain paths, which can be useful for querying purposes.
+# Example: 'cheat -t work jenkins'.
+#
+# Community cheatsheets must be installed separately, though you may have
+# downloaded them automatically when installing 'cheat'. If not, you may
+# download them here:
+#
+# https://github.com/cheat/cheatsheets
 cheatpaths:
-
-  # Paths that come earlier are considered to be the most "global", and will
-  # thus be overridden by more local cheatsheets. That being the case, you
-  # should probably list community cheatsheets first.
-  #
-  # Note that the paths and tags listed below are just examples. You may freely
-  # change them to suit your needs.
+  # Cheatpath properties mean the following:
+  #   'name': the name of the cheatpath (view with 'cheat -d', filter with 'cheat -p')
+  #   'path': the filesystem path of the cheatsheet directory (view with 'cheat -d')
+  #   'tags': tags that should be automatically applied to sheets on this path
+  #   'readonly': shall user-created ('cheat -e') cheatsheets be saved here?
   - name: community
-    path: ~/.dotfiles/cheat/community
+    path: COMMUNITY_PATH
     tags: [ community ]
     readonly: true
 
-  # Maybe your company or department maintains a repository of cheatsheets as
-  # well. It's probably sensible to list those second.
-  - name: work
-    path: ~/.dotfiles/cheat/work
-    tags: [ work ]
-    readonly: false
-
   # If you have personalized cheatsheets, list them last. They will take
   # precedence over the more global cheatsheets.
   - name: personal
-    path: ~/.dotfiles/cheat/personal
+    path: PERSONAL_PATH
     tags: [ personal ]
     readonly: false
+
+  # While it requires no configuration here, it's also worth noting that
+  # cheat will automatically append directories named '.cheat' within the
+  # current working directory to the 'cheatpath'. This can be very useful if
+  # you'd like to closely associate cheatsheets with, for example, a directory
+  # containing source code.
+  #
+  # Such "directory-scoped" cheatsheets will be treated as the most "local"
+  # cheatsheets, and will override less "local" cheatsheets. Similarly,
+  # directory-scoped cheatsheets will always be editable ('readonly: false').
 `)
 }

cmd/cheat/str_usage.go

@@ -11,16 +11,20 @@ func usage() string {
   cheat [options] [<cheatsheet>]
 
 Options:
-  --init                Write a default config file to stdout
-  -c --colorize         Colorize output
-  -d --directories      List cheatsheet directories
-  -e --edit=<sheet>     Edit cheatsheet
-  -l --list             List cheatsheets
-  -p --path=<name>      Return only sheets found on path <name>
-  -r --regex            Treat search <phrase> as a regex
-  -s --search=<phrase>  Search cheatsheets for <phrase>
-  -t --tag=<tag>        Return only sheets matching <tag>
-  -v --version          Print the version number
+  --init                  Write a default config file to stdout
+  -a --all                Search among all cheatpaths
+  -c --colorize           Colorize output
+  -d --directories        List cheatsheet directories
+  -e --edit=<cheatsheet>  Edit <cheatsheet>
+  -l --list               List cheatsheets
+  -p --path=<name>        Return only sheets found on cheatpath <name>
+  -r --regex              Treat search <phrase> as a regex
+  -s --search=<phrase>    Search cheatsheets for <phrase>
+  -t --tag=<tag>          Return only sheets matching <tag>
+  -T --tags               List all tags in use
+  -v --version            Print the version number
+  --rm=<cheatsheet>       Remove (delete) <cheatsheet>
+  --conf                  Display the config file path
 
 Examples:
 
@@ -42,6 +46,12 @@ Examples:
   To list all available cheatsheets:
     cheat -l
 
+  To list all cheatsheets whose titles match "apt":
+    cheat -l apt
+
+  To list all tags in use:
+    cheat -T
+
   To list available cheatsheets that are tagged as "personal":
     cheat -l -t personal
 
@@ -50,5 +60,11 @@ Examples:
 
   To search (by regex) for cheatsheets that contain an IP address:
     cheat -c -r -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'
+
+  To remove (delete) the foo/bar cheatsheet:
+    cheat --rm foo/bar
+
+  To view the configuration file path:
+    cheat --conf
 `)
 }

configs/conf.yml

@@ -1,9 +1,9 @@
 ---
 # The editor to use with 'cheat -e <sheet>'. Defaults to $EDITOR or $VISUAL.
-editor: vim
+editor: EDITOR_PATH
 
 # Should 'cheat' always colorize output?
-colorize: true
+colorize: false
 
 # Which 'chroma' colorscheme should be applied to the output?
 # Options are available here:
@@ -12,43 +12,71 @@ style: monokai
 
 # Which 'chroma' "formatter" should be applied?
 # One of: "terminal", "terminal256", "terminal16m"
-formatter: terminal16m
+formatter: terminal256
 
-# The paths at which cheatsheets are available. Tags associated with a cheatpath
-# are automatically attached to all cheatsheets residing on that path.
+# Through which pager should output be piped?
+# 'less -FRX' is recommended on Unix systems
+# 'more' is recommended on Windows
+pager: PAGER_PATH
+
+# Cheatpaths are paths at which cheatsheets are available on your local
+# filesystem.
 #
-# Whenever cheatsheets share the same title (like 'tar'), the most local
-# cheatsheets (those which come later in this file) take precedent over the
-# less local sheets. This allows you to create your own "overides" for
-# "upstream" cheatsheets.
+# It is useful to sort cheatsheets into different cheatpaths for organizational
+# purposes. For example, you might want one cheatpath for community
+# cheatsheets, one for personal cheatsheets, one for cheatsheets pertaining to
+# your day job, one for code snippets, etc.
 #
-# But what if you want to view the "upstream" cheatsheets instead of your own?
-# Cheatsheets may be filtered via 'cheat -f <tag>' in combination with other
-# commands. So, if you want to view the 'tar' cheatsheet that is tagged as
-# 'community' rather than your own, you can use: cheat tar -f community
+# Cheatpaths are scoped, such that more "local" cheatpaths take priority over
+# more "global" cheatpaths. (The most global cheatpath is listed first in this
+# file; the most local is listed last.) For example, if there is a 'tar'
+# cheatsheet on both global and local paths, you'll be presented with the local
+# one by default. ('cheat -p' can be used to view cheatsheets from alternative
+# cheatpaths.)
+#
+# Cheatpaths can also be tagged as "read only". This instructs cheat not to
+# automatically create cheatsheets on a read-only cheatpath. Instead, when you
+# would like to edit a read-only cheatsheet using 'cheat -e', cheat will
+# perform a copy-on-write of that cheatsheet from a read-only cheatpath to a
+# writeable cheatpath.
+#
+# This is very useful when you would like to maintain, for example, a
+# "pristine" repository of community cheatsheets on one cheatpath, and an
+# editable personal reponsity of cheatsheets on another cheatpath.
+#
+# Cheatpaths can be also configured to automatically apply tags to cheatsheets
+# on certain paths, which can be useful for querying purposes.
+# Example: 'cheat -t work jenkins'.
+#
+# Community cheatsheets must be installed separately, though you may have
+# downloaded them automatically when installing 'cheat'. If not, you may
+# download them here:
+#
+# https://github.com/cheat/cheatsheets
 cheatpaths:
-
-  # Paths that come earlier are considered to be the most "global", and will
-  # thus be overridden by more local cheatsheets. That being the case, you
-  # should probably list community cheatsheets first.
-  #
-  # Note that the paths and tags listed below are just examples. You may freely
-  # change them to suit your needs.
+  # Cheatpath properties mean the following:
+  #   'name': the name of the cheatpath (view with 'cheat -d', filter with 'cheat -p')
+  #   'path': the filesystem path of the cheatsheet directory (view with 'cheat -d')
+  #   'tags': tags that should be automatically applied to sheets on this path
+  #   'readonly': shall user-created ('cheat -e') cheatsheets be saved here?
   - name: community
-    path: ~/.dotfiles/cheat/community
+    path: COMMUNITY_PATH
     tags: [ community ]
     readonly: true
 
-  # Maybe your company or department maintains a repository of cheatsheets as
-  # well. It's probably sensible to list those second.
-  - name: work
-    path: ~/.dotfiles/cheat/work
-    tags: [ work ]
-    readonly: false
-
   # If you have personalized cheatsheets, list them last. They will take
   # precedence over the more global cheatsheets.
   - name: personal
-    path: ~/.dotfiles/cheat/personal
+    path: PERSONAL_PATH
     tags: [ personal ]
     readonly: false
+
+  # While it requires no configuration here, it's also worth noting that
+  # cheat will automatically append directories named '.cheat' within the
+  # current working directory to the 'cheatpath'. This can be very useful if
+  # you'd like to closely associate cheatsheets with, for example, a directory
+  # containing source code.
+  #
+  # Such "directory-scoped" cheatsheets will be treated as the most "local"
+  # cheatsheets, and will override less "local" cheatsheets. Similarly,
+  # directory-scoped cheatsheets will always be editable ('readonly: false').

doc/cheat.1

@@ -0,0 +1,221 @@
+.\" Automatically generated by Pandoc 2.2.1
+.\"
+.TH "CHEAT" "1" "" "" "General Commands Manual"
+.hy
+.SH NAME
+.PP
+\f[B]cheat\f[] \[em] create and view command\-line cheatsheets
+.SH SYNOPSIS
+.PP
+\f[B]cheat\f[] [options] [\f[I]CHEATSHEET\f[]]
+.SH DESCRIPTION
+.PP
+\f[B]cheat\f[] allows you to create and view interactive cheatsheets on
+the command\-line.
+It was designed to help remind *nix system administrators of options for
+commands that they use frequently, but not frequently enough to
+remember.
+.SH OPTIONS
+.TP
+.B \[en]init
+Print a config file to stdout.
+.RS
+.RE
+.TP
+.B \-c, \[en]colorize
+Colorize output.
+.RS
+.RE
+.TP
+.B \-d, \[en]directories
+List cheatsheet directories.
+.RS
+.RE
+.TP
+.B \-e, \[en]edit=\f[I]CHEATSHEET\f[]
+Open \f[I]CHEATSHEET\f[] for editing.
+.RS
+.RE
+.TP
+.B \-l, \[en]list
+List available cheatsheets.
+.RS
+.RE
+.TP
+.B \-p, \[en]path=\f[I]PATH\f[]
+Filter only to sheets found on path \f[I]PATH\f[].
+.RS
+.RE
+.TP
+.B \-r, \[en]regex
+Treat search \f[I]PHRASE\f[] as a regular expression.
+.RS
+.RE
+.TP
+.B \-s, \[en]search=\f[I]PHRASE\f[]
+Search cheatsheets for \f[I]PHRASE\f[].
+.RS
+.RE
+.TP
+.B \-t, \[en]tag=\f[I]TAG\f[]
+Filter only to sheets tagged with \f[I]TAG\f[].
+.RS
+.RE
+.TP
+.B \-T, \[en]tags
+List all tags in use.
+.RS
+.RE
+.TP
+.B \-v, \[en]version
+Print the version number.
+.RS
+.RE
+.TP
+.B \[en]rm=\f[I]CHEATSHEET\f[]
+Remove (deletes) \f[I]CHEATSHEET\f[].
+.RS
+.RE
+.SH EXAMPLES
+.TP
+.B To view the foo cheatsheet:
+cheat \f[I]foo\f[]
+.RS
+.RE
+.TP
+.B To edit (or create) the foo cheatsheet:
+cheat \-e \f[I]foo\f[]
+.RS
+.RE
+.TP
+.B To edit (or create) the foo/bar cheatsheet on the `work' cheatpath:
+cheat \-p \f[I]work\f[] \-e \f[I]foo/bar\f[]
+.RS
+.RE
+.TP
+.B To view all cheatsheet directories:
+cheat \-d
+.RS
+.RE
+.TP
+.B To list all available cheatsheets:
+cheat \-l
+.RS
+.RE
+.TP
+.B To list all cheatsheets whose titles match `apt':
+cheat \-l \f[I]apt\f[]
+.RS
+.RE
+.TP
+.B To list all tags in use:
+cheat \-T
+.RS
+.RE
+.TP
+.B To list available cheatsheets that are tagged as `personal':
+cheat \-l \-t \f[I]personal\f[]
+.RS
+.RE
+.TP
+.B To search for `ssh' among all cheatsheets, and colorize matches:
+cheat \-c \-s \f[I]ssh\f[]
+.RS
+.RE
+.TP
+.B To search (by regex) for cheatsheets that contain an IP address:
+cheat \-c \-r \-s \f[I]`(?:[0\-9]{1,3}.){3}[0\-9]{1,3}'\f[]
+.RS
+.RE
+.TP
+.B To remove (delete) the foo/bar cheatsheet:
+cheat \[en]rm \f[I]foo/bar\f[]
+.RS
+.RE
+.SH FILES
+.SS Configuration
+.PP
+\f[B]cheat\f[] is configured via a YAML file that is conventionally
+named \f[I]conf.yaml\f[].
+\f[B]cheat\f[] will search for \f[I]conf.yaml\f[] in varying locations,
+depending upon your platform:
+.SS Linux, OSX, and other Unixes
+.IP "1." 3
+\f[B]CHEAT_CONFIG_PATH\f[]
+.IP "2." 3
+\f[B]XDG_CONFIG_HOME\f[]/cheat/conf.yaml
+.IP "3." 3
+\f[B]$HOME\f[]/.config/cheat/conf.yml
+.IP "4." 3
+\f[B]$HOME\f[]/.cheat/conf.yml
+.SS Windows
+.IP "1." 3
+\f[B]CHEAT_CONFIG_PATH\f[]
+.IP "2." 3
+\f[B]APPDATA\f[]/cheat/conf.yml
+.IP "3." 3
+\f[B]PROGRAMDATA\f[]/cheat/conf.yml
+.PP
+\f[B]cheat\f[] will search in the order specified above.
+The first \f[I]conf.yaml\f[] encountered will be respected.
+.PP
+If \f[B]cheat\f[] cannot locate a config file, it will ask if you'd like
+to generate one automatically.
+Alternatively, you may also generate a config file manually by running
+\f[B]cheat \[en]init\f[] and saving its output to the appropriate
+location for your platform.
+.SS Cheatpaths
+.PP
+\f[B]cheat\f[] reads its cheatsheets from \[lq]cheatpaths\[rq], which
+are the directories in which cheatsheets are stored.
+Cheatpaths may be configured in \f[I]conf.yaml\f[], and viewed via
+\f[B]cheat \-d\f[].
+.PP
+For detailed instructions on how to configure cheatpaths, please refer
+to the comments in conf.yml.
+.SS Autocompletion
+.PP
+Autocompletion scripts for \f[B]bash\f[], \f[B]zsh\f[], and
+\f[B]fish\f[] are available for download:
+.IP \[bu] 2
+<https://github.com/cheat/cheat/blob/master/scripts/cheat.bash>
+.IP \[bu] 2
+<https://github.com/cheat/cheat/blob/master/scripts/cheat.fish>
+.IP \[bu] 2
+<https://github.com/cheat/cheat/blob/master/scripts/cheat.zsh>
+.PP
+The \f[B]bash\f[] and \f[B]zsh\f[] scripts provide optional integration
+with \f[B]fzf\f[], if the latter is available on your \f[B]PATH\f[].
+.PP
+The installation process will vary per system and shell configuration,
+and thus will not be discussed here.
+.SH ENVIRONMENT
+.TP
+.B \f[B]CHEAT_CONFIG_PATH\f[]
+The path at which the config file is available.
+If \f[B]CHEAT_CONFIG_PATH\f[] is set, all other config paths will be
+ignored.
+.RS
+.RE
+.TP
+.B \f[B]CHEAT_USE_FZF\f[]
+If set, autocompletion scripts will attempt to integrate with
+\f[B]fzf\f[].
+.RS
+.RE
+.SH RETURN VALUES
+.IP "0." 3
+Successful termination
+.IP "1." 3
+Application error
+.IP "2." 3
+Cheatsheet(s) not found
+.SH BUGS
+.PP
+See GitHub issues: <https://github.com/cheat/cheat/issues>
+.SH AUTHOR
+.PP
+Christopher Allen Lane <chris@chris-allen-lane.com>
+.SH SEE ALSO
+.PP
+\f[B]fzf(1)\f[]

doc/cheat.1.md

@@ -0,0 +1,192 @@
+% CHEAT(1) | General Commands Manual
+
+NAME
+====
+
+**cheat** — create and view command-line cheatsheets
+
+SYNOPSIS
+========
+
+| **cheat** \[options] \[_CHEATSHEET_]
+
+DESCRIPTION
+===========
+**cheat** allows you to create and view interactive cheatsheets on the
+command-line. It was designed to help remind \*nix system administrators of
+options for commands that they use frequently, but not frequently enough to
+remember.
+
+OPTIONS
+=======
+
+--init
+: Print a config file to stdout.
+
+-c, --colorize
+: Colorize output.
+
+-d, --directories
+: List cheatsheet directories.
+
+-e, --edit=_CHEATSHEET_
+: Open _CHEATSHEET_ for editing.
+
+-l, --list
+: List available cheatsheets.
+
+-p, --path=_PATH_
+: Filter only to sheets found on path _PATH_.
+
+-r, --regex
+: Treat search _PHRASE_ as a regular expression.
+
+-s, --search=_PHRASE_
+: Search cheatsheets for _PHRASE_.
+
+-t, --tag=_TAG_
+: Filter only to sheets tagged with _TAG_.
+
+-T, --tags
+: List all tags in use.
+
+-v, --version
+: Print the version number.
+
+--rm=_CHEATSHEET_
+: Remove (deletes) _CHEATSHEET_.
+
+
+EXAMPLES
+========
+
+To view the foo cheatsheet:
+: cheat _foo_
+
+To edit (or create) the foo cheatsheet:
+: cheat -e _foo_
+
+To edit (or create) the foo/bar cheatsheet on the 'work' cheatpath:
+: cheat -p _work_ -e _foo/bar_
+
+To view all cheatsheet directories:
+: cheat -d
+
+To list all available cheatsheets:
+: cheat -l
+
+To list all cheatsheets whose titles match 'apt':
+: cheat -l _apt_
+
+To list all tags in use:
+: cheat -T
+
+To list available cheatsheets that are tagged as 'personal':
+: cheat -l -t _personal_
+
+To search for 'ssh' among all cheatsheets, and colorize matches:
+: cheat -c -s _ssh_
+
+To search (by regex) for cheatsheets that contain an IP address:
+: cheat -c -r -s _'(?:[0-9]{1,3}\.){3}[0-9]{1,3}'_
+
+To remove (delete) the foo/bar cheatsheet:
+: cheat --rm _foo/bar_
+
+
+FILES
+=====
+
+Configuration
+-------------
+**cheat** is configured via a YAML file that is conventionally named
+_conf.yaml_.  **cheat** will search for _conf.yaml_ in varying locations,
+depending upon your platform:
+
+### Linux, OSX, and other Unixes ###
+
+1. **CHEAT_CONFIG_PATH**
+2. **XDG_CONFIG_HOME**/cheat/conf.yaml
+3. **$HOME**/.config/cheat/conf.yml
+4. **$HOME**/.cheat/conf.yml
+
+### Windows ###
+
+1. **CHEAT_CONFIG_PATH**
+2. **APPDATA**/cheat/conf.yml
+3. **PROGRAMDATA**/cheat/conf.yml
+
+**cheat** will search in the order specified above. The first _conf.yaml_
+encountered will be respected.
+
+If **cheat** cannot locate a config file, it will ask if you'd like to generate
+one automatically. Alternatively, you may also generate a config file manually
+by running **cheat --init** and saving its output to the appropriate location
+for your platform.
+
+
+Cheatpaths
+----------
+**cheat** reads its cheatsheets from "cheatpaths", which are the directories in
+which cheatsheets are stored. Cheatpaths may be configured in _conf.yaml_, and
+viewed via **cheat -d**.
+
+For detailed instructions on how to configure cheatpaths, please refer to the
+comments in conf.yml.
+
+
+Autocompletion
+--------------
+Autocompletion scripts for **bash**, **zsh**, and **fish** are available for
+download:
+
+- <https://github.com/cheat/cheat/blob/master/scripts/cheat.bash>
+- <https://github.com/cheat/cheat/blob/master/scripts/cheat.fish>
+- <https://github.com/cheat/cheat/blob/master/scripts/cheat.zsh>
+
+The **bash** and **zsh** scripts provide optional integration with **fzf**, if
+the latter is available on your **PATH**.
+
+The installation process will vary per system and shell configuration, and thus
+will not be discussed here.
+
+
+ENVIRONMENT
+===========
+
+**CHEAT_CONFIG_PATH**
+
+: The path at which the config file is available. If **CHEAT_CONFIG_PATH** is
+set, all other config paths will be ignored.
+
+**CHEAT_USE_FZF**
+
+: If set, autocompletion scripts will attempt to integrate with **fzf**.
+
+RETURN VALUES
+=============
+
+0. Successful termination
+
+1. Application error
+
+2. Cheatsheet(s) not found
+
+
+BUGS
+====
+
+See GitHub issues: <https://github.com/cheat/cheat/issues>
+
+
+AUTHOR
+======
+
+Christopher Allen Lane <chris@chris-allen-lane.com>
+
+
+SEE ALSO
+========
+
+**fzf(1)**
+

go.mod

@@ -1,14 +1,34 @@
 module github.com/cheat/cheat
 
-go 1.13
+go 1.19
 
 require (
-	github.com/alecthomas/chroma v0.6.7
+	github.com/alecthomas/chroma v0.10.0
 	github.com/davecgh/go-spew v1.1.1
 	github.com/docopt/docopt-go v0.0.0-20180111231733-ee0de3bc6815
-	github.com/mgutz/ansi v0.0.0-20170206155736-9520e82c474b
+	github.com/go-git/go-git/v5 v5.4.2
+	github.com/mattn/go-isatty v0.0.16
 	github.com/mitchellh/go-homedir v1.1.0
-	github.com/tj/front v0.0.0-20170212063142-739be213b0a1
-	gopkg.in/yaml.v1 v1.0.0-20140924161607-9f9df34309c0 // indirect
-	gopkg.in/yaml.v2 v2.2.4
+	gopkg.in/yaml.v1 v1.0.0-20140924161607-9f9df34309c0
+	gopkg.in/yaml.v2 v2.4.0
+)
+
+require (
+	github.com/Microsoft/go-winio v0.5.2 // indirect
+	github.com/ProtonMail/go-crypto v0.0.0-20220824120805-4b6e5c587895 // indirect
+	github.com/acomagu/bufpipe v1.0.3 // indirect
+	github.com/cloudflare/circl v1.2.0 // indirect
+	github.com/dlclark/regexp2 v1.7.0 // indirect
+	github.com/emirpasic/gods v1.18.1 // indirect
+	github.com/go-git/gcfg v1.5.0 // indirect
+	github.com/go-git/go-billy/v5 v5.3.1 // indirect
+	github.com/imdario/mergo v0.3.13 // indirect
+	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
+	github.com/kevinburke/ssh_config v1.2.0 // indirect
+	github.com/sergi/go-diff v1.2.0 // indirect
+	github.com/xanzy/ssh-agent v0.3.2 // indirect
+	golang.org/x/crypto v0.0.0-20220826181053-bd7e27e6170d // indirect
+	golang.org/x/net v0.0.0-20220826154423-83b083e8dc8b // indirect
+	golang.org/x/sys v0.0.0-20220825204002-c680a09ffe64 // indirect
+	gopkg.in/warnings.v0 v0.1.2 // indirect
 )

go.sum

@@ -1,62 +1,143 @@
-github.com/GeertJohan/go.incremental v1.0.0/go.mod h1:6fAjUhbVuX1KcMD3c8TEgVUqmo4seqhv0i0kdATSkM0=
-github.com/GeertJohan/go.rice v1.0.0/go.mod h1:eH6gbSOAUv07dQuZVnBmoDP8mgsM1rtixis4Tib9if0=
-github.com/akavel/rsrc v0.8.0/go.mod h1:uLoCtb9J+EyAqh+26kdrTgmzRBFPGOolLWKpdxkKq+c=
-github.com/alecthomas/assert v0.0.0-20170929043011-405dbfeb8e38 h1:smF2tmSOzy2Mm+0dGI2AIUHY+w0BUc+4tn40djz7+6U=
-github.com/alecthomas/assert v0.0.0-20170929043011-405dbfeb8e38/go.mod h1:r7bzyVFMNntcxPZXK3/+KdruV1H5KSlyVY0gc+NgInI=
-github.com/alecthomas/chroma v0.6.7 h1:1hKci+AyKOxJrugR9veaocu9DQGR2/GecI72BpaO0Rg=
-github.com/alecthomas/chroma v0.6.7/go.mod h1:zVlgtbRS7BJDrDY9SB238RmpoCBCYFlLmcfZ3durxTk=
-github.com/alecthomas/colour v0.0.0-20160524082231-60882d9e2721 h1:JHZL0hZKJ1VENNfmXvHbgYlbUOvpzYzvy2aZU5gXVeo=
-github.com/alecthomas/colour v0.0.0-20160524082231-60882d9e2721/go.mod h1:QO9JBoKquHd+jz9nshCh40fOfO+JzsoXy8qTHF68zU0=
-github.com/alecthomas/kong v0.1.17-0.20190424132513-439c674f7ae0/go.mod h1:+inYUSluD+p4L8KdviBSgzcqEjUQOfC5fQDRFuc36lI=
-github.com/alecthomas/kong v0.2.1-0.20190708041108-0548c6b1afae/go.mod h1:+inYUSluD+p4L8KdviBSgzcqEjUQOfC5fQDRFuc36lI=
-github.com/alecthomas/kong-hcl v0.1.8-0.20190615233001-b21fea9723c8/go.mod h1:MRgZdU3vrFd05IQ89AxUZ0aYdF39BYoNFa324SodPCA=
-github.com/alecthomas/repr v0.0.0-20180818092828-117648cd9897 h1:p9Sln00KOTlrYkxI1zYWl1QLnEqAqEARBEYa8FQnQcY=
-github.com/alecthomas/repr v0.0.0-20180818092828-117648cd9897/go.mod h1:xTS7Pm1pD1mvyM075QCDSRqH6qRLXylzS24ZTpRiSzQ=
-github.com/daaku/go.zipexe v1.0.0/go.mod h1:z8IiR6TsVLEYKwXAoE/I+8ys/sDkgTzSL0CLnGVd57E=
-github.com/danwakefield/fnmatch v0.0.0-20160403171240-cbb64ac3d964 h1:y5HC9v93H5EPKqaS1UYVg1uYah5Xf51mBfIoWehClUQ=
-github.com/danwakefield/fnmatch v0.0.0-20160403171240-cbb64ac3d964/go.mod h1:Xd9hchkHSWYkEqJwUGisez3G1QY8Ryz0sdWrLPMGjLk=
+github.com/Microsoft/go-winio v0.4.14/go.mod h1:qXqCSQ3Xa7+6tgxaGTIe4Kpcdsi+P8jBhyzoq1bpyYA=
+github.com/Microsoft/go-winio v0.4.16/go.mod h1:XB6nPKklQyQ7GC9LdcBEcBl8PF76WugXOPRXwdLnMv0=
+github.com/Microsoft/go-winio v0.5.2 h1:a9IhgEQBCUEk6QCdml9CiJGhAws+YwffDHEMp1VMrpA=
+github.com/Microsoft/go-winio v0.5.2/go.mod h1:WpS1mjBmmwHBEWmogvA2mj8546UReBk4v8QkMxJ6pZY=
+github.com/ProtonMail/go-crypto v0.0.0-20210428141323-04723f9f07d7/go.mod h1:z4/9nQmJSSwwds7ejkxaJwO37dru3geImFUdJlaLzQo=
+github.com/ProtonMail/go-crypto v0.0.0-20220824120805-4b6e5c587895 h1:NsReiLpErIPzRrnogAXYwSoU7txA977LjDGrbkewJbg=
+github.com/ProtonMail/go-crypto v0.0.0-20220824120805-4b6e5c587895/go.mod h1:UBYPn8k0D56RtnR8RFQMjmh4KrZzWJ5o7Z9SYjossQ8=
+github.com/acomagu/bufpipe v1.0.3 h1:fxAGrHZTgQ9w5QqVItgzwj235/uYZYgbXitB+dLupOk=
+github.com/acomagu/bufpipe v1.0.3/go.mod h1:mxdxdup/WdsKVreO5GpW4+M/1CE2sMG4jeGJ2sYmHc4=
+github.com/alecthomas/chroma v0.10.0 h1:7XDcGkCQopCNKjZHfYrNLraA+M7e0fMiJ/Mfikbfjek=
+github.com/alecthomas/chroma v0.10.0/go.mod h1:jtJATyUxlIORhUOFNA9NZDWGAQ8wpxQQqNSB4rjA/1s=
+github.com/anmitsu/go-shlex v0.0.0-20161002113705-648efa622239 h1:kFOfPq6dUM1hTo4JG6LR5AXSUEsOjtdm0kw0FtQtMJA=
+github.com/anmitsu/go-shlex v0.0.0-20161002113705-648efa622239/go.mod h1:2FmKhYUyUczH0OGQWaF5ceTx0UBShxjsH6f8oGKYe2c=
+github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio=
+github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
+github.com/bwesterb/go-ristretto v1.2.0/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0=
+github.com/bwesterb/go-ristretto v1.2.1/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0=
+github.com/cloudflare/circl v1.1.0/go.mod h1:prBCrKB9DV4poKZY1l9zBXg2QJY7mvgRvtMxxK7fi4I=
+github.com/cloudflare/circl v1.2.0 h1:NheeISPSUcYftKlfrLuOo4T62FkmD4t4jviLfFFYaec=
+github.com/cloudflare/circl v1.2.0/go.mod h1:Ch2UgYr6ti2KTtlejELlROl0YIYj7SLjAC8M+INXlMk=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/dlclark/regexp2 v1.1.6 h1:CqB4MjHw0MFCDj+PHHjiESmHX+N7t0tJzKvC6M97BRg=
-github.com/dlclark/regexp2 v1.1.6/go.mod h1:2pZnwuY/m+8K6iRw6wQdMtk+rH5tNGR1i55kozfMjCc=
+github.com/dlclark/regexp2 v1.4.0/go.mod h1:2pZnwuY/m+8K6iRw6wQdMtk+rH5tNGR1i55kozfMjCc=
+github.com/dlclark/regexp2 v1.7.0 h1:7lJfhqlPssTb1WQx4yvTHN0uElPEv52sbaECrAQxjAo=
+github.com/dlclark/regexp2 v1.7.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/docopt/docopt-go v0.0.0-20180111231733-ee0de3bc6815 h1:bWDMxwH3px2JBh6AyO7hdCn/PkvCZXii8TGj7sbtEbQ=
 github.com/docopt/docopt-go v0.0.0-20180111231733-ee0de3bc6815/go.mod h1:WwZ+bS3ebgob9U8Nd0kOddGdZWjyMGR8Wziv+TBNwSE=
-github.com/gorilla/csrf v1.6.0/go.mod h1:7tSf8kmjNYr7IWDCYhd3U8Ck34iQ/Yw5CJu7bAkHEGI=
-github.com/gorilla/handlers v1.4.1/go.mod h1:Qkdc/uu4tH4g6mTK6auzZ766c4CA0Ng8+o/OAirnOIQ=
-github.com/gorilla/mux v1.7.3/go.mod h1:1lud6UwP+6orDFRuTfBEV8e9/aOM/c4fVVCaMa2zaAs=
-github.com/gorilla/securecookie v1.1.1/go.mod h1:ra0sb63/xPlUeL+yeDciTfxMRAA+MP+HVt/4epWDjd4=
-github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
-github.com/jessevdk/go-flags v1.4.0/go.mod h1:4FA24M0QyGHXBuZZK/XkWh8h0e1EYbRYJSGM75WSRxI=
-github.com/mattn/go-colorable v0.0.9 h1:UVL0vNpWh04HeJXV0KLcaT7r06gOH2l4OW6ddYRUIY4=
-github.com/mattn/go-colorable v0.0.9/go.mod h1:9vuHe8Xs5qXnSaW/c/ABM9alt+Vo+STaOChaDxuIBZU=
-github.com/mattn/go-isatty v0.0.4 h1:bnP0vzxcAdeI1zdubAl5PjU6zsERjGZb7raWodagDYs=
-github.com/mattn/go-isatty v0.0.4/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4=
-github.com/mgutz/ansi v0.0.0-20170206155736-9520e82c474b h1:j7+1HpAFS1zy5+Q4qx1fWh90gTKwiN4QCGoY9TWyyO4=
-github.com/mgutz/ansi v0.0.0-20170206155736-9520e82c474b/go.mod h1:01TrycV0kFyexm33Z7vhZRXopbI8J3TDReVlkTgMUxE=
+github.com/emirpasic/gods v1.12.0/go.mod h1:YfzfFFoVP/catgzJb4IKIqXjX78Ha8FMSDh3ymbK86o=
+github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc=
+github.com/emirpasic/gods v1.18.1/go.mod h1:8tpGGwCnJ5H4r6BWwaV6OrWmMoPhUl5jm/FMNAnJvWQ=
+github.com/flynn/go-shlex v0.0.0-20150515145356-3f9db97f8568/go.mod h1:xEzjJPgXI435gkrCt3MPfRiAkVrwSbHsst4LCFVfpJc=
+github.com/gliderlabs/ssh v0.2.2 h1:6zsha5zo/TWhRhwqCD3+EarCAgZ2yN28ipRnGPnwkI0=
+github.com/gliderlabs/ssh v0.2.2/go.mod h1:U7qILu1NlMHj9FlMhZLlkCdDnU1DBEAqr0aevW3Awn0=
+github.com/go-git/gcfg v1.5.0 h1:Q5ViNfGF8zFgyJWPqYwA7qGFoMTEiBmdlkcfRmpIMa4=
+github.com/go-git/gcfg v1.5.0/go.mod h1:5m20vg6GwYabIxaOonVkTdrILxQMpEShl1xiMF4ua+E=
+github.com/go-git/go-billy/v5 v5.2.0/go.mod h1:pmpqyWchKfYfrkb/UVH4otLvyi/5gJlGI4Hb3ZqZ3W0=
+github.com/go-git/go-billy/v5 v5.3.1 h1:CPiOUAzKtMRvolEKw+bG1PLRpT7D3LIs3/3ey4Aiu34=
+github.com/go-git/go-billy/v5 v5.3.1/go.mod h1:pmpqyWchKfYfrkb/UVH4otLvyi/5gJlGI4Hb3ZqZ3W0=
+github.com/go-git/go-git-fixtures/v4 v4.2.1 h1:n9gGL1Ct/yIw+nfsfr8s4+sbhT+Ncu2SubfXjIWgci8=
+github.com/go-git/go-git-fixtures/v4 v4.2.1/go.mod h1:K8zd3kDUAykwTdDCr+I0per6Y6vMiRR/nnVTBtavnB0=
+github.com/go-git/go-git/v5 v5.4.2 h1:BXyZu9t0VkbiHtqrsvdq39UDhGJTl1h55VW6CSC4aY4=
+github.com/go-git/go-git/v5 v5.4.2/go.mod h1:gQ1kArt6d+n+BGd+/B/I74HwRTLhth2+zti4ihgckDc=
+github.com/google/go-cmp v0.3.0 h1:crn/baboCvb5fXaQ0IJ1SGTsTVrWpDsCWC8EGETZijY=
+github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
+github.com/imdario/mergo v0.3.12/go.mod h1:jmQim1M+e3UYxmgPu/WyfjB3N3VflVyUjjjwH0dnCYA=
+github.com/imdario/mergo v0.3.13 h1:lFzP57bqS/wsqKssCGmtLAb8A0wKjLGrve2q3PPVcBk=
+github.com/imdario/mergo v0.3.13/go.mod h1:4lJ1jqUDcsbIECGy0RUJAXNIhg+6ocWgb1ALK2O4oXg=
+github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 h1:BQSFePA1RWJOlocH6Fxy8MmwDt+yVQYULKfN0RoTN8A=
+github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99/go.mod h1:1lJo3i6rXxKeerYnT8Nvf0QmHCRC1n8sfWVwXF2Frvo=
+github.com/jessevdk/go-flags v1.5.0/go.mod h1:Fw0T6WPc1dYxT4mKEZRfG5kJhaTDP9pj1c2EWnYs/m4=
+github.com/kevinburke/ssh_config v0.0.0-20201106050909-4977a11b4351/go.mod h1:CT57kijsi8u/K/BOFA39wgDQJ9CxiF4nAY/ojJ6r6mM=
+github.com/kevinburke/ssh_config v1.2.0 h1:x584FjTGwHzMwvHx18PXxbBVzfnxogHaAReU4gf13a4=
+github.com/kevinburke/ssh_config v1.2.0/go.mod h1:CT57kijsi8u/K/BOFA39wgDQJ9CxiF4nAY/ojJ6r6mM=
+github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.2.1 h1:Fmg33tUaq4/8ym9TJN1x7sLJnHVwhP33CNkpYV/7rwI=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/matryer/is v1.2.0 h1:92UTHpy8CDwaJ08GqLDzhhuixiBUUD1p3AU6PHddz4A=
+github.com/matryer/is v1.2.0/go.mod h1:2fLPjFQM9rhQ15aVEtbuwhJinnOqrmgXPNdZsdwlWXA=
+github.com/mattn/go-isatty v0.0.16 h1:bq3VjFmv/sOjHtdEhmkEV4x1AJtvUvOJ2PFAZ5+peKQ=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
 github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
 github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
-github.com/mitchellh/mapstructure v1.1.2/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
-github.com/nkovacs/streamquote v0.0.0-20170412213628-49af9bddb229/go.mod h1:0aYXnNPJ8l7uZxf45rWW1a/uME32OF0rhiYGNQ2oF2E=
-github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/sergi/go-diff v1.0.0 h1:Kpca3qRNrduNnOQeazBd0ysaKrUJiIuISHxogkT9RPQ=
-github.com/sergi/go-diff v1.0.0/go.mod h1:0CfEIISq7TuYL3j771MWULgwwjU+GofnZX9QAmXWZgo=
+github.com/sergi/go-diff v1.1.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
+github.com/sergi/go-diff v1.2.0 h1:XU+rvMAioB0UC3q1MFrIQy4Vo5/4VsRDQQXHsEya6xQ=
+github.com/sergi/go-diff v1.2.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
+github.com/sirupsen/logrus v1.4.1/go.mod h1:ni0Sbl8bgC9z8RoU9G6nDWqqs/fq4eDPysMBDgk/93Q=
+github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.1.1/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
-github.com/stretchr/testify v1.3.0 h1:TivCn/peBQ7UY8ooIcPgZFpTNSz0Q2U6UrFlUfqbe0Q=
-github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
-github.com/tj/front v0.0.0-20170212063142-739be213b0a1 h1:lA+aPRvltlx2fwv/BnxyYSDQo3pIeqzHgMO5GvK0T9E=
-github.com/tj/front v0.0.0-20170212063142-739be213b0a1/go.mod h1:deJrtusCTptAW4EUn5vBLpl3dhNqPqUwEjWJz5UNxpQ=
-github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
-github.com/valyala/fasttemplate v1.0.1/go.mod h1:UQGH1tvbgY+Nz5t2n7tXsz52dQxojPUpymEIMZ47gx8=
-golang.org/x/sys v0.0.0-20181128092732-4ed8d59d0b35 h1:YAFjXN64LMvktoUZH9zgY4lGc/msGN7HQfoSuKCgaDU=
-golang.org/x/sys v0.0.0-20181128092732-4ed8d59d0b35/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
+github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/xanzy/ssh-agent v0.3.0/go.mod h1:3s9xbODqPuuhK9JV1R321M/FlMZSBvE5aY6eAcqrDh0=
+github.com/xanzy/ssh-agent v0.3.2 h1:eKj4SX2Fe7mui28ZgnFW5fmTz1EIr7ugo5s6wDxdHBM=
+github.com/xanzy/ssh-agent v0.3.2/go.mod h1:6dzNDKs0J9rVPHPhaGCukekBHKqfl+L3KghI1Bc68Uw=
+golang.org/x/crypto v0.0.0-20190219172222-a4c6cb3142f2/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
+golang.org/x/crypto v0.0.0-20210322153248-0c34fe9e7dc2/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
+golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/crypto v0.0.0-20220315160706-3147a52a75dd/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
+golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
+golang.org/x/crypto v0.0.0-20220826181053-bd7e27e6170d h1:3qF+Z8Hkrw9sOhrFHti9TlB1Hkac1x+DNRkv0XQiFjo=
+golang.org/x/crypto v0.0.0-20220826181053-bd7e27e6170d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20210326060303-6b1517762897/go.mod h1:uSPa2vr4CLtc/ILN5odXGNXS6mhrKVzTaCXzk9m6W3k=
+golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
+golang.org/x/net v0.0.0-20220826154423-83b083e8dc8b h1:ZmngSVLe/wycRns9MKikG9OWIEjGcGAkacif7oYQaUY=
+golang.org/x/net v0.0.0-20220826154423-83b083e8dc8b/go.mod h1:YDH+HFinaLZZlnHAfSS6ZXJJ9M9t4Dl22yv3iI2vPwk=
+golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190507160741-ecd444e8653b/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200302150141-5c8b2ff67527/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210320140829-1e4c9ba3b0c4/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210324051608-47abb6519492/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210502180810-71e4cd670f79/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220315194320-039c03cc5b86/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220825204002-c680a09ffe64 h1:UiNENfZ8gDvpiWw7IpOMQ27spWmThO1RwwdQVbJahJM=
+golang.org/x/sys v0.0.0-20220825204002-c680a09ffe64/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211 h1:JGgROgKl9N8DuW20oFS5gxc+lE67/N3FcwmBPMe7ArY=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7 h1:olpwvP2KacW1ZWvsR7uQhoyTYvKAupfQrRGBFM352Gk=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/warnings.v0 v0.1.2 h1:wFXVbFY8DY5/xOe1ECiWdKCzZlxgshcYVNkBHstARME=
+gopkg.in/warnings.v0 v0.1.2/go.mod h1:jksf8JmL6Qr/oQM2OXTHunEvvTAsrWBLb6OOjuVWRNI=
 gopkg.in/yaml.v1 v1.0.0-20140924161607-9f9df34309c0 h1:POO/ycCATvegFmVuPpQzZFJ+pGZeX22Ufu6fibxDVjU=
 gopkg.in/yaml.v1 v1.0.0-20140924161607-9f9df34309c0/go.mod h1:WDnlLJ4WF5VGsH/HVa3CI79GS0ol3YnhVnKP89i0kNg=
-gopkg.in/yaml.v2 v2.2.4 h1:/eiJrUcujPVeJ3xlSWaiNi3uSVmDGBK1pDHUHAnao1I=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0 h1:hjy8E9ON/egN1tAYqKb61G10WtihqetD4sz2H+8nIeA=
+gopkg.in/yaml.v3 v3.0.0/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/cheatpath/cheatpath.go

@@ -2,8 +2,8 @@ package cheatpath
 
 // Cheatpath encapsulates cheatsheet path information
 type Cheatpath struct {
-	Name     string   `yaml:name`
-	Path     string   `yaml:path`
-	ReadOnly bool     `yaml:readonly`
-	Tags     []string `yaml:tags`
+	Name     string   `yaml:"name"`
+	Path     string   `yaml:"path"`
+	ReadOnly bool     `yaml:"readonly"`
+	Tags     []string `yaml:"tags"`
 }

internal/cheatpath/filter_test.go

@@ -46,7 +46,7 @@ func TestFilterFailure(t *testing.T) {
 	}
 
 	// filter the paths
-	paths, err := Filter(paths, "qux")
+	_, err := Filter(paths, "qux")
 	if err == nil {
 		t.Errorf("failed to return an error on non-existent cheatpath")
 	}

internal/cheatpath/writeable.go

@@ -11,12 +11,10 @@ func Writeable(cheatpaths []Cheatpath) (Cheatpath, error) {
 	// NB: we're going backwards because we assume that the most "local"
 	// cheatpath will be specified last in the configs
 	for i := len(cheatpaths) - 1; i >= 0; i-- {
-
 		// if the cheatpath is not read-only, it is writeable, and thus returned
-		if cheatpaths[i].ReadOnly == false {
+		if !cheatpaths[i].ReadOnly {
 			return cheatpaths[i], nil
 		}
-
 	}
 
 	// otherwise, return an error

internal/config/color.go

@@ -0,0 +1,26 @@
+package config
+
+import (
+	"os"
+
+	"github.com/mattn/go-isatty"
+)
+
+// Color indicates whether colorization should be applied to the output
+func (c *Config) Color(opts map[string]interface{}) bool {
+
+	// default to the colorization specified in the configs...
+	colorize := c.Colorize
+
+	// ... however, only apply colorization if we're writing to a tty...
+	if !isatty.IsTerminal(os.Stdout.Fd()) && !isatty.IsCygwinTerminal(os.Stdout.Fd()) {
+		colorize = false
+	}
+
+	// ... *unless* the --colorize flag was passed
+	if opts["--colorize"] == true {
+		colorize = true
+	}
+
+	return colorize
+}

internal/config/color_test.go

@@ -0,0 +1,22 @@
+package config
+
+import (
+	"testing"
+)
+
+// TestColor asserts that colorization rules are properly respected
+func TestColor(t *testing.T) {
+
+	// mock a config
+	conf := Config{}
+
+	opts := map[string]interface{}{"--colorize": false}
+	if conf.Color(opts) {
+		t.Errorf("failed to respect --colorize (false)")
+	}
+
+	opts = map[string]interface{}{"--colorize": true}
+	if !conf.Color(opts) {
+		t.Errorf("failed to respect --colorize (true)")
+	}
+}

internal/config/config.go

@@ -2,8 +2,9 @@ package config
 
 import (
 	"fmt"
-	"io/ioutil"
 	"os"
+	"path/filepath"
+	"strings"
 
 	cp "github.com/cheat/cheat/internal/cheatpath"
 
@@ -13,18 +14,20 @@ import (
 
 // Config encapsulates configuration parameters
 type Config struct {
-	Colorize   bool           `yaml:colorize`
-	Editor     string         `yaml:editor`
-	Cheatpaths []cp.Cheatpath `yaml:cheatpaths`
-	Style      string         `yaml:style`
-	Formatter  string         `yaml:formatter`
+	Colorize   bool           `yaml:"colorize"`
+	Editor     string         `yaml:"editor"`
+	Cheatpaths []cp.Cheatpath `yaml:"cheatpaths"`
+	Style      string         `yaml:"style"`
+	Formatter  string         `yaml:"formatter"`
+	Pager      string         `yaml:"pager"`
+	Path       string
 }
 
 // New returns a new Config struct
-func New(opts map[string]interface{}, confPath string) (Config, error) {
+func New(opts map[string]interface{}, confPath string, resolve bool) (Config, error) {
 
 	// read the config file
-	buf, err := ioutil.ReadFile(confPath)
+	buf, err := os.ReadFile(confPath)
 	if err != nil {
 		return Config{}, fmt.Errorf("could not read config file: %v", err)
 	}
@@ -32,31 +35,71 @@ func New(opts map[string]interface{}, confPath string) (Config, error) {
 	// initialize a config object
 	conf := Config{}
 
+	// store the config path
+	conf.Path = confPath
+
 	// unmarshal the yaml
 	err = yaml.UnmarshalStrict(buf, &conf)
 	if err != nil {
 		return Config{}, fmt.Errorf("could not unmarshal yaml: %v", err)
 	}
 
-	// expand ~ in config paths
+	// if a .cheat directory exists locally, append it to the cheatpaths
+	cwd, err := os.Getwd()
+	if err != nil {
+		return Config{}, fmt.Errorf("failed to get cwd: %v", err)
+	}
+
+	local := filepath.Join(cwd, ".cheat")
+	if _, err := os.Stat(local); err == nil {
+		path := cp.Cheatpath{
+			Name:     "cwd",
+			Path:     local,
+			ReadOnly: false,
+			Tags:     []string{},
+		}
+
+		conf.Cheatpaths = append(conf.Cheatpaths, path)
+	}
+
+	// process cheatpaths
 	for i, cheatpath := range conf.Cheatpaths {
 
+		// expand ~ in config paths
 		expanded, err := homedir.Expand(cheatpath.Path)
 		if err != nil {
 			return Config{}, fmt.Errorf("failed to expand ~: %v", err)
 		}
 
+		// follow symlinks
+		//
+		// NB: `resolve` is an ugly kludge that exists for the sake of unit-tests.
+		// It's necessary because `EvalSymlinks` will error if the symlink points
+		// to a non-existent location on the filesystem. When unit-testing,
+		// however, we don't want to have dependencies on the filesystem. As such,
+		// `resolve` is a switch that allows us to turn off symlink resolution when
+		// running the config tests.
+		if resolve {
+			evaled, err := filepath.EvalSymlinks(expanded)
+			if err != nil {
+				return Config{}, fmt.Errorf(
+					"failed to resolve symlink: %s: %v",
+					expanded,
+					err,
+				)
+			}
+
+			expanded = evaled
+		}
+
 		conf.Cheatpaths[i].Path = expanded
 	}
 
-	// if an editor was not provided in the configs, look to envvars
+	// if an editor was not provided in the configs, attempt to choose one
+	// that's appropriate for the environment
 	if conf.Editor == "" {
-		if os.Getenv("VISUAL") != "" {
-			conf.Editor = os.Getenv("VISUAL")
-		} else if os.Getenv("EDITOR") != "" {
-			conf.Editor = os.Getenv("EDITOR")
-		} else {
-			return Config{}, fmt.Errorf("no editor set")
+		if conf.Editor, err = Editor(); err != nil {
+			return Config{}, err
 		}
 	}
 
@@ -67,8 +110,11 @@ func New(opts map[string]interface{}, confPath string) (Config, error) {
 
 	// if a chroma formatter was not provided, set a default
 	if conf.Formatter == "" {
-		conf.Formatter = "terminal16m"
+		conf.Formatter = "terminal"
 	}
 
+	// load the pager
+	conf.Pager = strings.TrimSpace(conf.Pager)
+
 	return conf, nil
 }

internal/config/config_test.go

@@ -17,7 +17,7 @@ import (
 func TestConfigSuccessful(t *testing.T) {
 
 	// initialize a config
-	conf, err := New(map[string]interface{}{}, mock.Path("conf/conf.yml"))
+	conf, err := New(map[string]interface{}{}, mock.Path("conf/conf.yml"), false)
 	if err != nil {
 		t.Errorf("failed to parse config file: %v", err)
 	}
@@ -39,17 +39,17 @@ func TestConfigSuccessful(t *testing.T) {
 	// assert that the cheatpaths are correct
 	want := []cheatpath.Cheatpath{
 		cheatpath.Cheatpath{
-			Path:     filepath.Join(home, ".dotfiles/cheat/community"),
+			Path:     filepath.Join(home, ".dotfiles", "cheat", "community"),
 			ReadOnly: true,
 			Tags:     []string{"community"},
 		},
 		cheatpath.Cheatpath{
-			Path:     filepath.Join(home, ".dotfiles/cheat/work"),
+			Path:     filepath.Join(home, ".dotfiles", "cheat", "work"),
 			ReadOnly: false,
 			Tags:     []string{"work"},
 		},
 		cheatpath.Cheatpath{
-			Path:     filepath.Join(home, ".dotfiles/cheat/personal"),
+			Path:     filepath.Join(home, ".dotfiles", "cheat", "personal"),
 			ReadOnly: false,
 			Tags:     []string{"personal"},
 		},
@@ -69,7 +69,7 @@ func TestConfigSuccessful(t *testing.T) {
 func TestConfigFailure(t *testing.T) {
 
 	// attempt to read a non-existent config file
-	_, err := New(map[string]interface{}{}, "/does-not-exit")
+	_, err := New(map[string]interface{}{}, "/does-not-exit", false)
 	if err == nil {
 		t.Errorf("failed to error on unreadable config")
 	}
@@ -84,14 +84,14 @@ func TestEmptyEditor(t *testing.T) {
 	os.Setenv("EDITOR", "")
 
 	// initialize a config
-	conf, err := New(map[string]interface{}{}, mock.Path("conf/empty.yml"))
-	if err == nil {
-		t.Errorf("failed to return an error on empty editor")
+	conf, err := New(map[string]interface{}{}, mock.Path("conf/empty.yml"), false)
+	if err != nil {
+		t.Errorf("failed to initialize test: %v", err)
 	}
 
 	// set editor, and assert that it is respected
 	os.Setenv("EDITOR", "foo")
-	conf, err = New(map[string]interface{}{}, mock.Path("conf/empty.yml"))
+	conf, err = New(map[string]interface{}{}, mock.Path("conf/empty.yml"), false)
 	if err != nil {
 		t.Errorf("failed to init configs: %v", err)
 	}
@@ -101,7 +101,7 @@ func TestEmptyEditor(t *testing.T) {
 
 	// set visual, and assert that it overrides editor
 	os.Setenv("VISUAL", "bar")
-	conf, err = New(map[string]interface{}{}, mock.Path("conf/empty.yml"))
+	conf, err = New(map[string]interface{}{}, mock.Path("conf/empty.yml"), false)
 	if err != nil {
 		t.Errorf("failed to init configs: %v", err)
 	}

internal/config/editor.go

@@ -0,0 +1,41 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"runtime"
+)
+
+// Editor attempts to locate an editor that's appropriate for the environment.
+func Editor() (string, error) {
+
+	// default to `notepad.exe` on Windows
+	if runtime.GOOS == "windows" {
+		return "notepad", nil
+	}
+
+	// look for `nano` and `vim` on the `PATH`
+	def, _ := exec.LookPath("editor") // default `editor` wrapper
+	nano, _ := exec.LookPath("nano")
+	vim, _ := exec.LookPath("vim")
+
+	// set editor priority
+	editors := []string{
+		os.Getenv("VISUAL"),
+		os.Getenv("EDITOR"),
+		def,
+		nano,
+		vim,
+	}
+
+	// return the first editor that was found per the priority above
+	for _, editor := range editors {
+		if editor != "" {
+			return editor, nil
+		}
+	}
+
+	// return an error if no path is found
+	return "", fmt.Errorf("no editor set")
+}

internal/config/init.go

@@ -0,0 +1,23 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// Init initializes a config file
+func Init(confpath string, configs string) error {
+
+	// assert that the config directory exists
+	if err := os.MkdirAll(filepath.Dir(confpath), 0755); err != nil {
+		return fmt.Errorf("failed to create directory: %v", err)
+	}
+
+	// write the config file
+	if err := os.WriteFile(confpath, []byte(configs), 0644); err != nil {
+		return fmt.Errorf("failed to create file: %v", err)
+	}
+
+	return nil
+}

internal/config/init_test.go

@@ -0,0 +1,37 @@
+package config
+
+import (
+	"os"
+	"testing"
+)
+
+// TestInit asserts that configs are properly initialized
+func TestInit(t *testing.T) {
+
+	// initialize a temporary config file
+	confFile, err := os.CreateTemp("", "cheat-test")
+	if err != nil {
+		t.Errorf("failed to create temp file: %v", err)
+	}
+
+	// clean up the temp file
+	defer os.Remove(confFile.Name())
+
+	// initialize the config file
+	conf := "mock config data"
+	if err = Init(confFile.Name(), conf); err != nil {
+		t.Errorf("failed to init config file: %v", err)
+	}
+
+	// read back the config file contents
+	bytes, err := os.ReadFile(confFile.Name())
+	if err != nil {
+		t.Errorf("failed to read config file: %v", err)
+	}
+
+	// assert that the contents were written correctly
+	got := string(bytes)
+	if got != conf {
+		t.Errorf("failed to write configs: want: %s, got: %s", conf, got)
+	}
+}

internal/config/pager.go

@@ -0,0 +1,32 @@
+package config
+
+import (
+	"os"
+	"os/exec"
+	"runtime"
+)
+
+// Pager attempts to locate a pager that's appropriate for the environment.
+func Pager() string {
+
+	// default to `more` on Windows
+	if runtime.GOOS == "windows" {
+		return "more"
+	}
+
+	// if $PAGER is set, return the corresponding pager
+	if os.Getenv("PAGER") != "" {
+		return os.Getenv("PAGER")
+	}
+
+	// Otherwise, search for `pager`, `less`, and `more` on the `$PATH`. If
+	// none are found, return an empty pager.
+	for _, pager := range []string{"pager", "less", "more"} {
+		if path, err := exec.LookPath(pager); err != nil {
+			return path
+		}
+	}
+
+	// default to no pager
+	return ""
+}

internal/config/path.go

@@ -3,58 +3,10 @@ package config
 import (
 	"fmt"
 	"os"
-	"path"
-
-	"github.com/mitchellh/go-homedir"
 )
 
 // Path returns the config file path
-func Path(sys string) (string, error) {
-
-	var paths []string
-
-	// if CHEAT_CONFIG_PATH is set, return it
-	if os.Getenv("CHEAT_CONFIG_PATH") != "" {
-
-		// expand ~
-		expanded, err := homedir.Expand(os.Getenv("CHEAT_CONFIG_PATH"))
-		if err != nil {
-			return "", fmt.Errorf("failed to expand ~: %v", err)
-		}
-
-		return expanded, nil
-
-		// OSX config paths
-	} else if sys == "darwin" {
-
-		paths = []string{
-			path.Join(os.Getenv("XDG_CONFIG_HOME"), "/cheat/conf.yml"),
-			path.Join(os.Getenv("HOME"), ".config/cheat/conf.yml"),
-			path.Join(os.Getenv("HOME"), ".cheat/conf.yml"),
-		}
-
-		// Linux config paths
-	} else if sys == "linux" {
-
-		paths = []string{
-			path.Join(os.Getenv("XDG_CONFIG_HOME"), "/cheat/conf.yml"),
-			path.Join(os.Getenv("HOME"), ".config/cheat/conf.yml"),
-			path.Join(os.Getenv("HOME"), ".cheat/conf.yml"),
-			"/etc/cheat/conf.yml",
-		}
-
-		// Windows config paths
-	} else if sys == "windows" {
-
-		paths = []string{
-			fmt.Sprintf("%s/cheat/conf.yml", os.Getenv("APPDATA")),
-			fmt.Sprintf("%s/cheat/conf.yml", os.Getenv("PROGRAMDATA")),
-		}
-
-		// Unsupported platforms
-	} else {
-		return "", fmt.Errorf("unsupported os: %s", sys)
-	}
+func Path(paths []string) (string, error) {
 
 	// check if the config file exists on any paths
 	for _, p := range paths {

internal/config/path_test.go

@@ -0,0 +1,52 @@
+package config
+
+import (
+	"os"
+	"testing"
+)
+
+// TestPathConfigNotExists asserts that `Path` identifies non-existent config
+// files
+func TestPathConfigNotExists(t *testing.T) {
+
+	// package (invalid) cheatpaths
+	paths := []string{"/cheat-test-conf-does-not-exist"}
+
+	// assert
+	if _, err := Path(paths); err == nil {
+		t.Errorf("failed to identify non-existent config file")
+	}
+
+}
+
+// TestPathConfigExists asserts that `Path` identifies existent config files
+func TestPathConfigExists(t *testing.T) {
+
+	// initialize a temporary config file
+	confFile, err := os.CreateTemp("", "cheat-test")
+	if err != nil {
+		t.Errorf("failed to create temp file: %v", err)
+	}
+
+	// clean up the temp file
+	defer os.Remove(confFile.Name())
+
+	// package cheatpaths
+	paths := []string{
+		"/cheat-test-conf-does-not-exist",
+		confFile.Name(),
+	}
+
+	// assert
+	got, err := Path(paths)
+	if err != nil {
+		t.Errorf("failed to identify config file: %v", err)
+	}
+	if got != confFile.Name() {
+		t.Errorf(
+			"failed to return config path: want: %s, got: %s",
+			confFile.Name(),
+			got,
+		)
+	}
+}

internal/config/paths.go

@@ -0,0 +1,54 @@
+package config
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/mitchellh/go-homedir"
+)
+
+// Paths returns config file paths that are appropriate for the operating
+// system
+func Paths(
+	sys string,
+	home string,
+	envvars map[string]string,
+) ([]string, error) {
+
+	// if `CHEAT_CONFIG_PATH` is set, expand ~ and return it
+	if confpath, ok := envvars["CHEAT_CONFIG_PATH"]; ok {
+
+		// expand ~
+		expanded, err := homedir.Expand(confpath)
+		if err != nil {
+			return []string{}, fmt.Errorf("failed to expand ~: %v", err)
+		}
+
+		return []string{expanded}, nil
+	}
+
+	switch sys {
+	case "android", "darwin", "linux", "freebsd":
+		paths := []string{}
+
+		// don't include the `XDG_CONFIG_HOME` path if that envvar is not set
+		if xdgpath, ok := envvars["XDG_CONFIG_HOME"]; ok {
+			paths = append(paths, filepath.Join(xdgpath, "cheat", "conf.yml"))
+		}
+
+		paths = append(paths, []string{
+			filepath.Join(home, ".config", "cheat", "conf.yml"),
+			filepath.Join(home, ".cheat", "conf.yml"),
+			"/etc/cheat/conf.yml",
+		}...)
+
+		return paths, nil
+	case "windows":
+		return []string{
+			filepath.Join(envvars["APPDATA"], "cheat", "conf.yml"),
+			filepath.Join(envvars["PROGRAMDATA"], "cheat", "conf.yml"),
+		}, nil
+	default:
+		return []string{}, fmt.Errorf("unsupported os: %s", sys)
+	}
+}

internal/config/paths_test.go

@@ -0,0 +1,176 @@
+package config
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/davecgh/go-spew/spew"
+)
+
+// TestValidatePathsNix asserts that the proper config paths are returned on
+// *nix platforms
+func TestValidatePathsNix(t *testing.T) {
+
+	// mock the user's home directory
+	home := "/home/foo"
+
+	// mock some envvars
+	envvars := map[string]string{
+		"XDG_CONFIG_HOME": "/home/bar",
+	}
+
+	// specify the platforms to test
+	oses := []string{
+		"android",
+		"darwin",
+		"freebsd",
+		"linux",
+	}
+
+	// test each *nix os
+	for _, os := range oses {
+		// get the paths for the platform
+		paths, err := Paths(os, home, envvars)
+		if err != nil {
+			t.Errorf("paths returned an error: %v", err)
+		}
+
+		// specify the expected output
+		want := []string{
+			"/home/bar/cheat/conf.yml",
+			"/home/foo/.config/cheat/conf.yml",
+			"/home/foo/.cheat/conf.yml",
+			"/etc/cheat/conf.yml",
+		}
+
+		// assert that output matches expectations
+		if !reflect.DeepEqual(paths, want) {
+			t.Errorf(
+				"failed to return expected paths: want:\n%s, got:\n%s",
+				spew.Sdump(want),
+				spew.Sdump(paths),
+			)
+		}
+	}
+}
+
+// TestValidatePathsNixNoXDG asserts that the proper config paths are returned
+// on *nix platforms when `XDG_CONFIG_HOME is not set
+func TestValidatePathsNixNoXDG(t *testing.T) {
+
+	// mock the user's home directory
+	home := "/home/foo"
+
+	// mock some envvars
+	envvars := map[string]string{}
+
+	// specify the platforms to test
+	oses := []string{
+		"darwin",
+		"freebsd",
+		"linux",
+	}
+
+	// test each *nix os
+	for _, os := range oses {
+		// get the paths for the platform
+		paths, err := Paths(os, home, envvars)
+		if err != nil {
+			t.Errorf("paths returned an error: %v", err)
+		}
+
+		// specify the expected output
+		want := []string{
+			"/home/foo/.config/cheat/conf.yml",
+			"/home/foo/.cheat/conf.yml",
+			"/etc/cheat/conf.yml",
+		}
+
+		// assert that output matches expectations
+		if !reflect.DeepEqual(paths, want) {
+			t.Errorf(
+				"failed to return expected paths: want:\n%s, got:\n%s",
+				spew.Sdump(want),
+				spew.Sdump(paths),
+			)
+		}
+	}
+}
+
+// TestValidatePathsWindows asserts that the proper config paths are returned
+// on Windows platforms
+func TestValidatePathsWindows(t *testing.T) {
+
+	// mock the user's home directory
+	home := "not-used-on-windows"
+
+	// mock some envvars
+	envvars := map[string]string{
+		"APPDATA":     "/apps",
+		"PROGRAMDATA": "/programs",
+	}
+
+	// get the paths for the platform
+	paths, err := Paths("windows", home, envvars)
+	if err != nil {
+		t.Errorf("paths returned an error: %v", err)
+	}
+
+	// specify the expected output
+	want := []string{
+		"/apps/cheat/conf.yml",
+		"/programs/cheat/conf.yml",
+	}
+
+	// assert that output matches expectations
+	if !reflect.DeepEqual(paths, want) {
+		t.Errorf(
+			"failed to return expected paths: want:\n%s, got:\n%s",
+			spew.Sdump(want),
+			spew.Sdump(paths),
+		)
+	}
+}
+
+// TestValidatePathsUnsupported asserts that an error is returned on
+// unsupported platforms
+func TestValidatePathsUnsupported(t *testing.T) {
+	_, err := Paths("unsupported", "", map[string]string{})
+	if err == nil {
+		t.Errorf("failed to return error on unsupported platform")
+	}
+}
+
+// TestValidatePathsCheatConfigPath asserts that the proper config path is
+// returned when `CHEAT_CONFIG_PATH` is explicitly specified.
+func TestValidatePathsCheatConfigPath(t *testing.T) {
+
+	// mock the user's home directory
+	home := "/home/foo"
+
+	// mock some envvars
+	envvars := map[string]string{
+		"XDG_CONFIG_HOME":   "/home/bar",
+		"CHEAT_CONFIG_PATH": "/home/baz/conf.yml",
+	}
+
+	// get the paths for the platform
+	paths, err := Paths("linux", home, envvars)
+	if err != nil {
+		t.Errorf("paths returned an error: %v", err)
+	}
+
+	// specify the expected output
+	want := []string{
+		"/home/baz/conf.yml",
+	}
+
+	// assert that output matches expectations
+	if !reflect.DeepEqual(paths, want) {
+		t.Errorf(
+			"failed to return expected paths: want:\n%s, got:\n%s",
+			spew.Sdump(want),
+			spew.Sdump(paths),
+		)
+	}
+}

internal/display/faint.go

@@ -0,0 +1,18 @@
+package display
+
+import (
+	"fmt"
+
+	"github.com/cheat/cheat/internal/config"
+)
+
+// Faint returns an faint string
+func Faint(str string, conf config.Config) string {
+	// make `str` faint only if colorization has been requested
+	if conf.Colorize {
+		return fmt.Sprintf("\033[2m%s\033[0m", str)
+	}
+
+	// otherwise, return the string unmodified
+	return str
+}

internal/display/faint_test.go

@@ -0,0 +1,27 @@
+package display
+
+import (
+	"testing"
+
+	"github.com/cheat/cheat/internal/config"
+)
+
+// TestFaint asserts that Faint applies faint formatting
+func TestFaint(t *testing.T) {
+
+	// case: apply colorization
+	conf := config.Config{Colorize: true}
+	want := "\033[2mfoo\033[0m"
+	got := Faint("foo", conf)
+	if want != got {
+		t.Errorf("failed to faint: want: %s, got: %s", want, got)
+	}
+
+	// case: do not apply colorization
+	conf.Colorize = false
+	want = "foo"
+	got = Faint("foo", conf)
+	if want != got {
+		t.Errorf("failed to faint: want: %s, got: %s", want, got)
+	}
+}

internal/display/indent.go

@@ -0,0 +1,21 @@
+package display
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Indent prepends each line of a string with a tab
+func Indent(str string) string {
+
+	// trim superfluous whitespace
+	str = strings.TrimSpace(str)
+
+	// prepend each line with a tab character
+	out := ""
+	for _, line := range strings.Split(str, "\n") {
+		out += fmt.Sprintf("\t%s\n", line)
+	}
+
+	return out
+}

internal/display/indent_test.go

@@ -0,0 +1,12 @@
+package display
+
+import "testing"
+
+// TestIndent asserts that Indent prepends a tab to each line
+func TestIndent(t *testing.T) {
+	got := Indent("foo\nbar\nbaz")
+	want := "\tfoo\n\tbar\n\tbaz\n"
+	if got != want {
+		t.Errorf("failed to indent: want: %s, got: %s", want, got)
+	}
+}

internal/display/write.go

@@ -0,0 +1,36 @@
+package display
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+
+	"github.com/cheat/cheat/internal/config"
+)
+
+// Write writes output either directly to stdout, or through a pager,
+// depending upon configuration.
+func Write(out string, conf config.Config) {
+	// if no pager was configured, print the output to stdout and exit
+	if conf.Pager == "" {
+		fmt.Print(out)
+		os.Exit(0)
+	}
+
+	// otherwise, pipe output through the pager
+	parts := strings.Split(conf.Pager, " ")
+	pager := parts[0]
+	args := parts[1:]
+
+	// configure the pager
+	cmd := exec.Command(pager, args...)
+	cmd.Stdin = strings.NewReader(out)
+	cmd.Stdout = os.Stdout
+
+	// run the pager and handle errors
+	if err := cmd.Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "failed to write to pager: %v\n", err)
+		os.Exit(1)
+	}
+}

internal/installer/prompt.go

@@ -0,0 +1,37 @@
+package installer
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// Prompt prompts the user for a answer
+func Prompt(prompt string, def bool) (bool, error) {
+
+	// initialize a line reader
+	reader := bufio.NewReader(os.Stdin)
+
+	// display the prompt
+	fmt.Printf("%s: ", prompt)
+
+	// read the answer
+	ans, err := reader.ReadString('\n')
+	if err != nil {
+		return false, fmt.Errorf("failed to parse input: %v", err)
+	}
+
+	// normalize the answer
+	ans = strings.ToLower(strings.TrimSpace(ans))
+
+	// return the appropriate response
+	switch ans {
+	case "y":
+		return true, nil
+	case "":
+		return def, nil
+	default:
+		return false, nil
+	}
+}

internal/installer/run.go

@@ -0,0 +1,66 @@
+package installer
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/cheat/cheat/internal/config"
+	"github.com/cheat/cheat/internal/repo"
+)
+
+// Run runs the installer
+func Run(configs string, confpath string) error {
+
+	// determine the appropriate paths for config data and (optional) community
+	// cheatsheets based on the user's platform
+	confdir := filepath.Dir(confpath)
+
+	// create paths for community and personal cheatsheets
+	community := filepath.Join(confdir, "cheatsheets", "community")
+	personal := filepath.Join(confdir, "cheatsheets", "personal")
+
+	// set default cheatpaths
+	configs = strings.Replace(configs, "COMMUNITY_PATH", community, -1)
+	configs = strings.Replace(configs, "PERSONAL_PATH", personal, -1)
+
+	// locate and set a default pager
+	configs = strings.Replace(configs, "PAGER_PATH", config.Pager(), -1)
+
+	// locate and set a default editor
+	if editor, err := config.Editor(); err == nil {
+		configs = strings.Replace(configs, "EDITOR_PATH", editor, -1)
+	}
+
+	// prompt the user to download the community cheatsheets
+	yes, err := Prompt(
+		"Would you like to download the community cheatsheets? [Y/n]",
+		true,
+	)
+	if err != nil {
+		return fmt.Errorf("failed to prompt: %v", err)
+	}
+
+	// clone the community cheatsheets if so instructed
+	if yes {
+		// clone the community cheatsheets
+		fmt.Printf("Cloning community cheatsheets to %s.\n", community)
+		if err := repo.Clone(community); err != nil {
+			return fmt.Errorf("failed to clone cheatsheets: %v", err)
+		}
+
+		// also create a directory for personal cheatsheets
+		fmt.Printf("Cloning personal cheatsheets to %s.\n", personal)
+		if err := os.MkdirAll(personal, os.ModePerm); err != nil {
+			return fmt.Errorf("failed to create directory: %v", err)
+		}
+	}
+
+	// the config file does not exist, so we'll try to create one
+	if err = config.Init(confpath, configs); err != nil {
+		return fmt.Errorf("failed to create config file: %v", err)
+	}
+
+	return nil
+}

internal/mock/path.go

@@ -13,7 +13,7 @@ func Path(filename string) string {
 	// determine the path of this file during runtime
 	_, thisfile, _, _ := runtime.Caller(0)
 
-	// compute the config path
+	// compute the mock path
 	file, err := filepath.Abs(
 		path.Join(
 			filepath.Dir(thisfile),
@@ -22,7 +22,7 @@ func Path(filename string) string {
 		),
 	)
 	if err != nil {
-		panic(fmt.Errorf("failed to resolve config path: %v", err))
+		panic(fmt.Errorf("failed to resolve mock path: %v", err))
 	}
 
 	return file

internal/repo/clone.go

@@ -0,0 +1,25 @@
+package repo
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/go-git/go-git/v5"
+)
+
+// Clone clones the repo available at `url`
+func Clone(url string) error {
+
+	// clone the community cheatsheets
+	_, err := git.PlainClone(url, false, &git.CloneOptions{
+		URL:      "https://github.com/cheat/cheatsheets.git",
+		Depth:    1,
+		Progress: os.Stdout,
+	})
+
+	if err != nil {
+		return fmt.Errorf("failed to clone cheatsheets: %v", err)
+	}
+
+	return nil
+}

internal/repo/gitdir.go

@@ -0,0 +1,109 @@
+package repo
+
+import (
+	"fmt"
+	"os"
+	"strings"
+)
+
+// GitDir returns `true` if we are iterating over a directory contained within
+// a repositories `.git` directory.
+func GitDir(path string) (bool, error) {
+
+	/*
+		A bit of context is called for here, because this functionality has
+		previously caused a number of tricky, subtle bugs.
+
+		Fundamentally, here we are simply trying to avoid walking over the
+		contents of the `.git` directory. Doing so potentially makes
+		hundreds/thousands of needless syscalls, and can noticeably harm
+		performance on machines with slow disks.
+
+		The earliest effort to solve this problem involved simply returning
+		`fs.SkipDir` when the cheatsheet file path began with `.`, signifying a
+		hidden directory. This, however, caused two problems:
+
+		1. The `.cheat` directory was ignored
+		2. Cheatsheets installed by `brew` (which were by default installed to
+		`~/.config/cheat`) were ignored
+
+		See: https://github.com/cheat/cheat/issues/690
+
+		To remedy this, the exclusion criteria were narrowed, and the search
+		for a literal `.` was replaced with a search for a literal `.git`.
+		This, however, broke user installations that stored cheatsheets in
+		`git` submodules, because such an installation would contain a `.git`
+		file that pointed to the upstream repository.
+
+		See: https://github.com/cheat/cheat/issues/694
+
+		The next attempt at solving this was to search for a `.git` literal
+		string in the cheatsheet file path. If a match was not found, we would
+		continue to walk the directory, as before.
+
+		If a match *was* found, we determined whether `.git` referred to a file
+		or directory, and would only stop walking the path in the latter case.
+
+		This, however, caused crashes if a cheatpath contained a `.gitignore`
+		file. (Presumably, a crash would likewise occur on the presence of
+		`.gitattributes`, `.gitmodules`, etc.)
+
+		See: https://github.com/cheat/cheat/issues/699
+
+		Accounting for all of the above (hopefully?), the current solution is
+		not to search for `.git`, but `.git/` (including the directory
+		separator), and then only ceasing to walk the directory on a match.
+
+		To summarize, this code must account for the following possibilities:
+
+		1. A cheatpath is not a repository
+		2. A cheatpath is a repository
+		3. A cheatpath is a repository, and contains a `.git*` file
+		4. A cheatpath is a submodule
+
+		Care must be taken to support the above on both Unix and Windows
+		systems, which have different directory separators and line-endings.
+
+		There is a lot of nuance to all of this, and it would be worthwhile to
+		do two things to stop writing bugs here:
+
+		1. Build integration tests around all of this
+		2. Discard string-matching solutions entirely, and use `go-git` instead
+
+		NB: A reasonable smoke-test for ensuring that skipping is being applied
+		correctly is to run the following command:
+
+		    make && strace ./dist/cheat -l | wc -l
+
+		That check should be run twice: once normally, and once after
+		commenting out the "skip" check in `sheets.Load`.
+
+		The specific line counts don't matter; what matters is that the number
+		of syscalls should be significantly lower with the skip check enabled.
+	*/
+
+	// determine if the literal string `.git` appears within `path`
+	pos := strings.Index(path, fmt.Sprintf(".git%s", string(os.PathSeparator)))
+
+	// if it does not, we know for certain that we are not within a `.git`
+	// directory.
+	if pos == -1 {
+		return false, nil
+	}
+
+	// If `path` does contain the string `.git`, we need to determine if we're
+	// inside of a `.git` directory, or if `path` points to a cheatsheet that's
+	// stored within a `git` submodule.
+	//
+	// See: https://github.com/cheat/cheat/issues/694
+
+	// truncate `path` to the occurrence of `.git`
+	f, err := os.Stat(path[:pos+5])
+	if err != nil {
+		return false, fmt.Errorf("failed to stat path %s: %v", path, err)
+	}
+
+	// return true or false depending on whether the truncated path is a
+	// directory
+	return f.Mode().IsDir(), nil
+}

internal/repo/update.go

@@ -0,0 +1 @@
+package repo

internal/sheet/colorize.go

@@ -0,0 +1,37 @@
+package sheet
+
+import (
+	"bytes"
+
+	"github.com/cheat/cheat/internal/config"
+
+	"github.com/alecthomas/chroma/quick"
+)
+
+// Colorize applies syntax-highlighting to a cheatsheet's Text.
+func (s *Sheet) Colorize(conf config.Config) {
+
+	// if the syntax was not specified, default to bash
+	lex := s.Syntax
+	if lex == "" {
+		lex = "bash"
+	}
+
+	// write colorized text into a buffer
+	var buf bytes.Buffer
+	err := quick.Highlight(
+		&buf,
+		s.Text,
+		lex,
+		conf.Formatter,
+		conf.Style,
+	)
+
+	// if colorization somehow failed, do nothing
+	if err != nil {
+		return
+	}
+
+	// otherwise, swap the cheatsheet's Text with its colorized equivalent
+	s.Text = buf.String()
+}

internal/sheet/colorize_test.go

@@ -0,0 +1,34 @@
+package sheet
+
+import (
+	"testing"
+
+	"github.com/cheat/cheat/internal/config"
+)
+
+// TestColorize asserts that syntax-highlighting is correctly applied
+func TestColorize(t *testing.T) {
+
+	// mock configs
+	conf := config.Config{
+		Formatter: "terminal16m",
+		Style:     "solarized-dark",
+	}
+
+	// mock a sheet
+	s := Sheet{
+		Text: "echo 'foo'",
+	}
+
+	// colorize the sheet text
+	s.Colorize(conf)
+
+	// initialize expectations
+	want := "echo"
+	want += " 'foo'"
+
+	// assert
+	if s.Text != want {
+		t.Errorf("failed to colorize sheet: want: %s, got: %s", want, s.Text)
+	}
+}

internal/sheet/copy.go

@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"io"
 	"os"
-	"path"
+	"path/filepath"
 )
 
 // Copy copies a cheatsheet to a new location
@@ -22,7 +22,7 @@ func (s *Sheet) Copy(dest string) error {
 	defer infile.Close()
 
 	// create any necessary subdirectories
-	dirs := path.Dir(dest)
+	dirs := filepath.Dir(dest)
 	if dirs != "." {
 		if err := os.MkdirAll(dirs, 0755); err != nil {
 			return fmt.Errorf("failed to create directory: %s, %v", dirs, err)

internal/sheet/copy_test.go

@@ -1,7 +1,6 @@
 package sheet
 
 import (
-	"io/ioutil"
 	"os"
 	"path"
 	"testing"
@@ -13,7 +12,7 @@ func TestCopyFlat(t *testing.T) {
 
 	// mock a cheatsheet file
 	text := "this is the cheatsheet text"
-	src, err := ioutil.TempFile("", "foo-src")
+	src, err := os.CreateTemp("", "foo-src")
 	if err != nil {
 		t.Errorf("failed to mock cheatsheet: %v", err)
 	}
@@ -25,7 +24,7 @@ func TestCopyFlat(t *testing.T) {
 	}
 
 	// mock a cheatsheet struct
-	sheet, err := New("foo", src.Name(), []string{}, false)
+	sheet, err := New("foo", "community", src.Name(), []string{}, false)
 	if err != nil {
 		t.Errorf("failed to init cheatsheet: %v", err)
 	}
@@ -41,7 +40,7 @@ func TestCopyFlat(t *testing.T) {
 	}
 
 	// assert that the destination file contains the correct text
-	got, err := ioutil.ReadFile(outpath)
+	got, err := os.ReadFile(outpath)
 	if err != nil {
 		t.Errorf("failed to read destination file: %v", err)
 	}
@@ -60,7 +59,7 @@ func TestCopyDeep(t *testing.T) {
 
 	// mock a cheatsheet file
 	text := "this is the cheatsheet text"
-	src, err := ioutil.TempFile("", "foo-src")
+	src, err := os.CreateTemp("", "foo-src")
 	if err != nil {
 		t.Errorf("failed to mock cheatsheet: %v", err)
 	}
@@ -72,7 +71,13 @@ func TestCopyDeep(t *testing.T) {
 	}
 
 	// mock a cheatsheet struct
-	sheet, err := New("/cheat-tests/alpha/bravo/foo", src.Name(), []string{}, false)
+	sheet, err := New(
+		"/cheat-tests/alpha/bravo/foo",
+		"community",
+		src.Name(),
+		[]string{},
+		false,
+	)
 	if err != nil {
 		t.Errorf("failed to init cheatsheet: %v", err)
 	}
@@ -88,7 +93,7 @@ func TestCopyDeep(t *testing.T) {
 	}
 
 	// assert that the destination file contains the correct text
-	got, err := ioutil.ReadFile(outpath)
+	got, err := os.ReadFile(outpath)
 	if err != nil {
 		t.Errorf("failed to read destination file: %v", err)
 	}

internal/sheet/match.go

@@ -1,7 +0,0 @@
-package sheet
-
-// Match encapsulates search matches within cheatsheets
-type Match struct {
-	Line int
-	Text string
-}

internal/sheet/parse.go

@@ -0,0 +1,45 @@
+package sheet
+
+import (
+	"fmt"
+	"runtime"
+	"strings"
+
+	"gopkg.in/yaml.v1"
+)
+
+// Parse parses cheatsheet frontmatter
+func parse(markdown string) (frontmatter, string, error) {
+
+	// determine the appropriate line-break for the platform
+	linebreak := "\n"
+	if runtime.GOOS == "windows" {
+		linebreak = "\r\n"
+	}
+
+	// specify the frontmatter delimiter
+	delim := fmt.Sprintf("---%s", linebreak)
+
+	// initialize a frontmatter struct
+	var fm frontmatter
+
+	// if the markdown does not contain frontmatter, pass it through unmodified
+	if !strings.HasPrefix(markdown, delim) {
+		return fm, markdown, nil
+	}
+
+	// otherwise, split the frontmatter and cheatsheet text
+	parts := strings.SplitN(markdown, delim, 3)
+
+	// return an error if the frontmatter parses into the wrong number of parts
+	if len(parts) != 3 {
+		return fm, markdown, fmt.Errorf("failed to delimit frontmatter")
+	}
+
+	// return an error if the YAML cannot be unmarshalled
+	if err := yaml.Unmarshal([]byte(parts[1]), &fm); err != nil {
+		return fm, markdown, fmt.Errorf("failed to unmarshal frontmatter: %v", err)
+	}
+
+	return fm, parts[2], nil
+}

internal/sheet/parse_test.go

@@ -0,0 +1,95 @@
+package sheet
+
+import (
+	"testing"
+)
+
+// TestHasFrontmatter asserts that markdown is properly parsed when it contains
+// frontmatter
+func TestHasFrontmatter(t *testing.T) {
+
+	// stub our cheatsheet content
+	markdown := `---
+syntax: go
+tags: [ test ]
+---
+To foo the bar: baz`
+
+	// parse the frontmatter
+	fm, text, err := parse(markdown)
+
+	// assert expectations
+	if err != nil {
+		t.Errorf("failed to parse markdown: %v", err)
+	}
+
+	want := "To foo the bar: baz"
+	if text != want {
+		t.Errorf("failed to parse text: want: %s, got: %s", want, text)
+	}
+
+	want = "go"
+	if fm.Syntax != want {
+		t.Errorf("failed to parse syntax: want: %s, got: %s", want, fm.Syntax)
+	}
+
+	want = "test"
+	if fm.Tags[0] != want {
+		t.Errorf("failed to parse tags: want: %s, got: %s", want, fm.Tags[0])
+	}
+	if len(fm.Tags) != 1 {
+		t.Errorf("failed to parse tags: want: len 0, got: len %d", len(fm.Tags))
+	}
+}
+
+// TestHasFrontmatter asserts that markdown is properly parsed when it does not
+// contain frontmatter
+func TestHasNoFrontmatter(t *testing.T) {
+
+	// stub our cheatsheet content
+	markdown := "To foo the bar: baz"
+
+	// parse the frontmatter
+	fm, text, err := parse(markdown)
+
+	// assert expectations
+	if err != nil {
+		t.Errorf("failed to parse markdown: %v", err)
+	}
+
+	if text != markdown {
+		t.Errorf("failed to parse text: want: %s, got: %s", markdown, text)
+	}
+
+	if fm.Syntax != "" {
+		t.Errorf("failed to parse syntax: want: '', got: %s", fm.Syntax)
+	}
+
+	if len(fm.Tags) != 0 {
+		t.Errorf("failed to parse tags: want: len 0, got: len %d", len(fm.Tags))
+	}
+}
+
+// TestHasInvalidFrontmatter asserts that markdown is properly parsed when it
+// contains invalid frontmatter
+func TestHasInvalidFrontmatter(t *testing.T) {
+
+	// stub our cheatsheet content (with invalid frontmatter)
+	markdown := `---
+syntax: go
+tags: [ test ]
+To foo the bar: baz`
+
+	// parse the frontmatter
+	_, text, err := parse(markdown)
+
+	// assert that an error was returned
+	if err == nil {
+		t.Error("failed to error on invalid frontmatter")
+	}
+
+	// assert that the "raw" markdown was returned
+	if text != markdown {
+		t.Errorf("failed to parse text: want: %s, got: %s", markdown, text)
+	}
+}

internal/sheet/search.go

@@ -3,43 +3,22 @@ package sheet
 import (
 	"regexp"
 	"strings"
-
-	"github.com/mgutz/ansi"
 )
 
-// Search searches for regexp matches in a cheatsheet's text, and optionally
-// colorizes matching strings.
-func (s *Sheet) Search(reg *regexp.Regexp, colorize bool) []Match {
+// Search returns lines within a sheet's Text that match the search regex
+func (s *Sheet) Search(reg *regexp.Regexp) string {
 
 	// record matches
-	matches := []Match{}
+	matches := ""
 
 	// search through the cheatsheet's text line by line
-	// TODO: searching line-by-line is surely the "naive" approach. Revisit this
-	// later with an eye for performance improvements.
-	for linenum, line := range strings.Split(s.Text, "\n") {
+	for _, line := range strings.Split(s.Text, "\n\n") {
 
 		// exit early if the line doesn't match the regex
-		if !reg.MatchString(line) {
-			continue
+		if reg.MatchString(line) {
+			matches += line + "\n\n"
 		}
-
-		// init the match
-		m := Match{
-			Line: linenum + 1,
-			Text: strings.TrimSpace(line),
-		}
-
-		// colorize the matching text if so configured
-		if colorize {
-			m.Text = reg.ReplaceAllStringFunc(m.Text, func(matched string) string {
-				return ansi.Color(matched, "red+b")
-			})
-		}
-
-		// record the match
-		matches = append(matches, m)
 	}
 
-	return matches
+	return strings.TrimSpace(matches)
 }

internal/sheet/search_test.go

@@ -4,8 +4,6 @@ import (
 	"reflect"
 	"regexp"
 	"testing"
-
-	"github.com/davecgh/go-spew/spew"
 )
 
 // TestSearchNoMatch ensures that the expected output is returned when no
@@ -24,21 +22,21 @@ func TestSearchNoMatch(t *testing.T) {
 	}
 
 	// search the sheet
-	matches := sheet.Search(reg, false)
+	matches := sheet.Search(reg)
 
 	// assert that no matches were found
-	if len(matches) != 0 {
-		t.Errorf("failure: expected no matches: got: %s", spew.Sdump(matches))
+	if matches != "" {
+		t.Errorf("failure: expected no matches: got: %s", matches)
 	}
 }
 
-// TestSearchSingleMatchNoColor asserts that the expected output is returned
-// when a single match is returned, and no colorization is applied.
-func TestSearchSingleMatchNoColor(t *testing.T) {
+// TestSearchSingleMatch asserts that the expected output is returned
+// when a single match is returned
+func TestSearchSingleMatch(t *testing.T) {
 
 	// mock a cheatsheet
 	sheet := Sheet{
-		Text: "The quick brown fox\njumped over\nthe lazy dog.",
+		Text: "The quick brown fox\njumped over\n\nthe lazy dog.",
 	}
 
 	// compile the search regex
@@ -48,69 +46,28 @@ func TestSearchSingleMatchNoColor(t *testing.T) {
 	}
 
 	// search the sheet
-	matches := sheet.Search(reg, false)
+	matches := sheet.Search(reg)
 
 	// specify the expected results
-	want := []Match{
-		Match{
-			Line: 1,
-			Text: "The quick brown fox",
-		},
-	}
+	want := "The quick brown fox\njumped over"
 
 	// assert that the correct matches were returned
-	if !reflect.DeepEqual(matches, want) {
+	if matches != want {
 		t.Errorf(
 			"failed to return expected matches: want:\n%s, got:\n%s",
-			spew.Sdump(want),
-			spew.Sdump(matches),
+			want,
+			matches,
 		)
 	}
 }
 
-// TestSearchSingleMatchColorized asserts that the expected output is returned
-// when a single match is returned, and colorization is applied
-func TestSearchSingleMatchColorized(t *testing.T) {
+// TestSearchMultiMatch asserts that the expected output is returned
+// when a multiple matches are returned
+func TestSearchMultiMatch(t *testing.T) {
 
 	// mock a cheatsheet
 	sheet := Sheet{
-		Text: "The quick brown fox\njumped over\nthe lazy dog.",
-	}
-
-	// compile the search regex
-	reg, err := regexp.Compile("(?i)fox")
-	if err != nil {
-		t.Errorf("failed to compile regex: %v", err)
-	}
-
-	// search the sheet
-	matches := sheet.Search(reg, true)
-
-	// specify the expected results
-	want := []Match{
-		Match{
-			Line: 1,
-			Text: "The quick brown \x1b[1;31mfox\x1b[0m",
-		},
-	}
-
-	// assert that the correct matches were returned
-	if !reflect.DeepEqual(matches, want) {
-		t.Errorf(
-			"failed to return expected matches: want:\n%s, got:\n%s",
-			spew.Sdump(want),
-			spew.Sdump(matches),
-		)
-	}
-}
-
-// TestSearchMultiMatchNoColor asserts that the expected output is returned
-// when a multiple matches are returned, and no colorization is applied
-func TestSearchMultiMatchNoColor(t *testing.T) {
-
-	// mock a cheatsheet
-	sheet := Sheet{
-		Text: "The quick brown fox\njumped over\nthe lazy dog.",
+		Text: "The quick brown fox\n\njumped over\n\nthe lazy dog.",
 	}
 
 	// compile the search regex
@@ -120,66 +77,17 @@ func TestSearchMultiMatchNoColor(t *testing.T) {
 	}
 
 	// search the sheet
-	matches := sheet.Search(reg, false)
+	matches := sheet.Search(reg)
 
 	// specify the expected results
-	want := []Match{
-		Match{
-			Line: 1,
-			Text: "The quick brown fox",
-		},
-		Match{
-			Line: 3,
-			Text: "the lazy dog.",
-		},
-	}
+	want := "The quick brown fox\n\nthe lazy dog."
 
 	// assert that the correct matches were returned
 	if !reflect.DeepEqual(matches, want) {
 		t.Errorf(
 			"failed to return expected matches: want:\n%s, got:\n%s",
-			spew.Sdump(want),
-			spew.Sdump(matches),
-		)
-	}
-}
-
-// TestSearchMultiMatchColorized asserts that the expected output is returned
-// when a multiple matches are returned, and colorization is applied
-func TestSearchMultiMatchColorized(t *testing.T) {
-
-	// mock a cheatsheet
-	sheet := Sheet{
-		Text: "The quick brown fox\njumped over\nthe lazy dog.",
-	}
-
-	// compile the search regex
-	reg, err := regexp.Compile("(?i)the")
-	if err != nil {
-		t.Errorf("failed to compile regex: %v", err)
-	}
-
-	// search the sheet
-	matches := sheet.Search(reg, true)
-
-	// specify the expected results
-	want := []Match{
-		Match{
-			Line: 1,
-			Text: "\x1b[1;31mThe\x1b[0m quick brown fox",
-		},
-		Match{
-			Line: 3,
-			Text: "\x1b[1;31mthe\x1b[0m lazy dog.",
-		},
-	}
-
-	// assert that the correct matches were returned
-	if !reflect.DeepEqual(matches, want) {
-		t.Errorf(
-			"failed to return expected matches: want:\n%s, got:\n%s",
-			spew.Sdump(want),
-			spew.Sdump(matches),
+			want,
+			matches,
 		)
 	}
 }

internal/sheet/sheet.go

@@ -2,14 +2,11 @@ package sheet
 
 import (
 	"fmt"
-	"io/ioutil"
+	"os"
 	"sort"
-	"strings"
-
-	"github.com/tj/front"
 )
 
-// frontmatter is an un-exported helper struct used in parsing cheatsheets
+// Frontmatter encapsulates cheatsheet frontmatter data
 type frontmatter struct {
 	Tags   []string
 	Syntax string
@@ -17,31 +14,32 @@ type frontmatter struct {
 
 // Sheet encapsulates sheet information
 type Sheet struct {
-	Title    string
-	Path     string
-	Text     string
-	Tags     []string
-	Syntax   string
-	ReadOnly bool
+	Title     string
+	CheatPath string
+	Path      string
+	Text      string
+	Tags      []string
+	Syntax    string
+	ReadOnly  bool
 }
 
 // New initializes a new Sheet
 func New(
 	title string,
+	cheatpath string,
 	path string,
 	tags []string,
 	readOnly bool,
 ) (Sheet, error) {
 
 	// read the cheatsheet file
-	markdown, err := ioutil.ReadFile(path)
+	markdown, err := os.ReadFile(path)
 	if err != nil {
 		return Sheet{}, fmt.Errorf("failed to read file: %s, %v", path, err)
 	}
 
-	// parse the front-matter
-	var fm frontmatter
-	text, err := front.Unmarshal(markdown, &fm)
+	// parse the raw cheatsheet text
+	fm, text, err := parse(string(markdown))
 	if err != nil {
 		return Sheet{}, fmt.Errorf("failed to parse front-matter: %v", err)
 	}
@@ -54,11 +52,12 @@ func New(
 
 	// initialize and return a sheet
 	return Sheet{
-		Title:    title,
-		Path:     path,
-		Text:     strings.TrimSpace(string(text)) + "\n",
-		Tags:     tags,
-		Syntax:   fm.Syntax,
-		ReadOnly: readOnly,
+		Title:     title,
+		CheatPath: cheatpath,
+		Path:      path,
+		Text:      text,
+		Tags:      tags,
+		Syntax:    fm.Syntax,
+		ReadOnly:  readOnly,
 	}, nil
 }

internal/sheet/sheet_test.go

@@ -13,6 +13,7 @@ func TestSheetSuccess(t *testing.T) {
 	// initialize a sheet
 	sheet, err := New(
 		"foo",
+		"community",
 		mock.Path("sheet/foo"),
 		[]string{"alpha", "bravo"},
 		false,
@@ -61,6 +62,7 @@ func TestSheetFailure(t *testing.T) {
 	// initialize a sheet
 	_, err := New(
 		"foo",
+		"community",
 		mock.Path("/does-not-exist"),
 		[]string{"alpha", "bravo"},
 		false,
@@ -69,3 +71,20 @@ func TestSheetFailure(t *testing.T) {
 		t.Errorf("failed to return an error on unreadable sheet")
 	}
 }
+
+// TestSheetFrontMatterFailure asserts that an error is returned if the sheet's
+// frontmatter cannot be parsed.
+func TestSheetFrontMatterFailure(t *testing.T) {
+
+	// initialize a sheet
+	_, err := New(
+		"foo",
+		"community",
+		mock.Path("sheet/bad-fm"),
+		[]string{"alpha", "bravo"},
+		false,
+	)
+	if err == nil {
+		t.Errorf("failed to return an error on malformed front-matter")
+	}
+}

internal/sheets/load.go

@@ -2,11 +2,13 @@ package sheets
 
 import (
 	"fmt"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
 
 	cp "github.com/cheat/cheat/internal/cheatpath"
+	"github.com/cheat/cheat/internal/repo"
 	"github.com/cheat/cheat/internal/sheet"
 )
 
@@ -33,7 +35,7 @@ func Load(cheatpaths []cp.Cheatpath) ([]map[string]sheet.Sheet, error) {
 
 				// fail if an error occurred while walking the directory
 				if err != nil {
-					return fmt.Errorf("error walking path: %v", err)
+					return fmt.Errorf("failed to walk path: %v", err)
 				}
 
 				// don't register directories as cheatsheets
@@ -45,18 +47,35 @@ func Load(cheatpaths []cp.Cheatpath) ([]map[string]sheet.Sheet, error) {
 				// accessed. Eg: `cheat tar` - `tar` is the title)
 				title := strings.TrimPrefix(
 					strings.TrimPrefix(path, cheatpath.Path),
-					"/",
+					string(os.PathSeparator),
 				)
 
-				// ignore dotfiles. Otherwise, we'll likely load .git/*
-				if strings.HasPrefix(title, ".") {
-					return nil
+				// Don't walk the `.git` directory. Doing so creates
+				// hundreds/thousands of needless syscalls and could
+				// potentially harm performance on machines with slow disks.
+				skip, err := repo.GitDir(path)
+				if err != nil {
+					return fmt.Errorf("failed to identify .git directory: %v", err)
+				}
+				if skip {
+					return fs.SkipDir
 				}
 
 				// parse the cheatsheet file into a `sheet` struct
-				s, err := sheet.New(title, path, cheatpath.Tags, cheatpath.ReadOnly)
+				s, err := sheet.New(
+					title,
+					cheatpath.Name,
+					path,
+					cheatpath.Tags,
+					cheatpath.ReadOnly,
+				)
 				if err != nil {
-					return fmt.Errorf("could not create sheet: %v", err)
+					return fmt.Errorf(
+						"failed to load sheet: %s, path: %s, err: %v",
+						title,
+						path,
+						err,
+					)
 				}
 
 				// register the cheatsheet on its cheatpath, keyed by its title

internal/sheets/load_test.go

@@ -1,3 +1,62 @@
 package sheets
 
-// TODO
+import (
+	"path"
+	"testing"
+
+	"github.com/cheat/cheat/internal/cheatpath"
+	"github.com/cheat/cheat/internal/mock"
+)
+
+// TestLoad asserts that sheets on valid cheatpaths can be loaded successfully
+func TestLoad(t *testing.T) {
+
+	// mock cheatpaths
+	cheatpaths := []cheatpath.Cheatpath{
+		{
+			Name:     "community",
+			Path:     path.Join(mock.Path("cheatsheets"), "community"),
+			ReadOnly: true,
+		},
+		{
+			Name:     "personal",
+			Path:     path.Join(mock.Path("cheatsheets"), "personal"),
+			ReadOnly: false,
+		},
+	}
+
+	// load cheatsheets
+	sheets, err := Load(cheatpaths)
+	if err != nil {
+		t.Errorf("failed to load cheatsheets: %v", err)
+	}
+
+	// assert that the correct number of sheets loaded
+	// (sheet load details are tested in `sheet_test.go`)
+	want := 4
+	if len(sheets) != want {
+		t.Errorf(
+			"failed to load correct number of cheatsheets: want: %d, got: %d",
+			want,
+			len(sheets),
+		)
+	}
+}
+
+// TestLoadBadPath asserts that an error is returned if a cheatpath is invalid
+func TestLoadBadPath(t *testing.T) {
+
+	// mock a bad cheatpath
+	cheatpaths := []cheatpath.Cheatpath{
+		{
+			Name:     "badpath",
+			Path:     "/cheat/test/path/does/not/exist",
+			ReadOnly: true,
+		},
+	}
+
+	// attempt to load the cheatpath
+	if _, err := Load(cheatpaths); err == nil {
+		t.Errorf("failed to reject invalid cheatpath")
+	}
+}

internal/sheets/tags.go

@@ -0,0 +1,36 @@
+package sheets
+
+import (
+	"sort"
+
+	"github.com/cheat/cheat/internal/sheet"
+)
+
+// Tags returns a slice of all tags in use in any sheet
+func Tags(cheatpaths []map[string]sheet.Sheet) []string {
+
+	// create a map of all tags in use in any sheet
+	tags := make(map[string]bool)
+
+	// iterate over all tags on all sheets on all cheatpaths
+	for _, path := range cheatpaths {
+		for _, sheet := range path {
+			for _, tag := range sheet.Tags {
+				tags[tag] = true
+			}
+		}
+	}
+
+	// restructure the map into a slice
+	sorted := []string{}
+	for tag := range tags {
+		sorted = append(sorted, tag)
+	}
+
+	// sort the slice
+	sort.Slice(sorted, func(i, j int) bool {
+		return sorted[i] < sorted[j]
+	})
+
+	return sorted
+}

internal/sheets/tags_test.go

@@ -0,0 +1,51 @@
+package sheets
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/davecgh/go-spew/spew"
+
+	"github.com/cheat/cheat/internal/sheet"
+)
+
+// TestTags asserts that cheatsheet tags are properly returned
+func TestTags(t *testing.T) {
+
+	// mock cheatsheets available on multiple cheatpaths
+	cheatpaths := []map[string]sheet.Sheet{
+
+		// mock community cheatsheets
+		map[string]sheet.Sheet{
+			"foo": sheet.Sheet{Title: "foo", Tags: []string{"alpha"}},
+			"bar": sheet.Sheet{Title: "bar", Tags: []string{"alpha", "bravo"}},
+		},
+
+		// mock local cheatsheets
+		map[string]sheet.Sheet{
+			"bar": sheet.Sheet{Title: "bar", Tags: []string{"bravo", "charlie"}},
+			"baz": sheet.Sheet{Title: "baz", Tags: []string{"delta"}},
+		},
+	}
+
+	// consolidate the cheatsheets
+	tags := Tags(cheatpaths)
+
+	// specify the expected output
+	want := []string{
+		"alpha",
+		"bravo",
+		"charlie",
+		"delta",
+	}
+
+	// assert that the cheatsheets properly consolidated
+	if !reflect.DeepEqual(tags, want) {
+		t.Errorf(
+			"failed to return tags: want:\n%s, got:\n%s",
+			spew.Sdump(want),
+			spew.Sdump(tags),
+		)
+	}
+
+}

mocks/cheatsheets/community/bar

@@ -0,0 +1,4 @@
+---
+tags: [ community ]
+---
+This is the bar cheatsheet.

mocks/cheatsheets/community/foo

@@ -0,0 +1,4 @@
+---
+tags: [ community ]
+---
+This is the foo cheatsheet.

mocks/cheatsheets/personal/bat

@@ -0,0 +1,4 @@
+---
+tags: [ personal ]
+---
+This is the bat cheatsheet.

mocks/cheatsheets/personal/baz

@@ -0,0 +1,4 @@
+---
+tags: [ personal ]
+---
+This is the baz cheatsheet.

mocks/sheet/bad-fm

@@ -0,0 +1,4 @@
+---
+syntax: sh
+
+This is malformed frontmatter.

scripts/cheat.bash

@@ -0,0 +1,74 @@
+# cheat(1) completion                                      -*- shell-script -*-
+
+# generate cheatsheet completions, optionally using `fzf`
+_cheat_complete_cheatsheets()
+{
+  if [[ "$CHEAT_USE_FZF" = true ]]; then
+    FZF_COMPLETION_TRIGGER='' _fzf_complete "--no-multi" "$@" < <(
+      cheat -l | tail -n +2 | cut -d' ' -f1
+    )
+  else
+    COMPREPLY=( $(compgen -W "$(cheat -l | tail -n +2 | cut -d' ' -f1)" -- "$cur") )
+  fi
+}
+
+# generate tag completions, optionally using `fzf`
+_cheat_complete_tags()
+{
+  if [ "$CHEAT_USE_FZF" = true ]; then
+    FZF_COMPLETION_TRIGGER='' _fzf_complete "--no-multi" "$@" < <(cheat -T)
+  else
+    COMPREPLY=( $(compgen -W "$(cheat -T)" -- "$cur") )
+  fi
+}
+
+# implement the `cheat` autocompletions
+_cheat()
+{
+  local cur prev words cword split
+  _init_completion -s || return
+
+  # complete options that are currently being typed: `--col` => `--colorize`
+  if [[ $cur == -* ]]; then
+    COMPREPLY=( $(compgen -W '$(_parse_help "$1" | sed "s/=//g")' -- "$cur") )
+    [[ $COMPREPLY == *= ]] && compopt -o nospace
+    return
+  fi
+
+  # implement completions
+  case $prev in
+    --colorize|-c|\
+    --directories|-d|\
+    --init|\
+    --regex|-r|\
+    --search|-s|\
+    --tags|-T|\
+    --version|-v)
+      # noop the above, which should implement no completions
+      ;;
+    --edit|-e)
+      _cheat_complete_cheatsheets
+      ;;
+    --list|-l)
+      _cheat_complete_cheatsheets
+      ;;
+    --path|-p)
+      COMPREPLY=( $(compgen -W "$(cheat -d | cut -d':' -f1)" -- "$cur") )  
+      ;;
+    --rm)
+      _cheat_complete_cheatsheets
+      ;;
+    --tag|-t)
+      _cheat_complete_tags
+      ;;
+    *)
+      _cheat_complete_cheatsheets
+      ;;
+  esac
+
+  $split && return
+
+} &&
+complete -F _cheat cheat
+
+# ex: filetype=sh

scripts/cheat.fish

@@ -0,0 +1,13 @@
+complete -c cheat -f -a "(cheat -l | tail -n +2 | cut -d ' ' -f 1)"
+complete -c cheat -l init -d "Write a default config file to stdout"
+complete -c cheat -s c -l colorize -d "Colorize output"
+complete -c cheat -s d -l directories -d "List cheatsheet directories"
+complete -c cheat -s e -l edit -x -a "(cheat -l | tail -n +2 | cut -d ' ' -f 1)" -d "Edit cheatsheet"
+complete -c cheat -s l -l list -d "List cheatsheets"
+complete -c cheat -s p -l path -x -a "(cheat -d | cut -d ':' -f 1)" -d "Return only sheets found on given path"
+complete -c cheat -s r -l regex -d "Treat search phrase as a regex"
+complete -c cheat -s s -l search -x -d "Search cheatsheets for given phrase"
+complete -c cheat -s t -l tag -x -a "(cheat -T)" -d "Return only sheets matching the given tag"
+complete -c cheat -s T -l tags -d "List all tags in use"
+complete -c cheat -s v -l version -d "Print the version number"
+complete -c cheat -l rm -x -a "(cheat -l | tail -n +2 | cut -d ' ' -f 1)" -d "Remove (delete) cheatsheet"

scripts/cheat.zsh

@@ -0,0 +1,65 @@
+#compdef cheat
+
+local cheats taglist pathlist
+
+_cheat_complete_personal_cheatsheets()
+{
+  cheats=("${(f)$(cheat -l -t personal | tail -n +2 | cut -d' ' -f1)}")
+  _describe -t cheats 'cheats' cheats
+}
+
+_cheat_complete_full_cheatsheets()
+{
+  cheats=("${(f)$(cheat -l | tail -n +2 | cut -d' ' -f1)}")
+  _describe -t cheats 'cheats' cheats
+}
+
+_cheat_complete_tags()
+{
+  taglist=("${(f)$(cheat -T)}")
+  _describe -t taglist 'taglist' taglist
+}
+
+_cheat_complete_paths()
+{
+  pathlist=("${(f)$(cheat -d | cut -d':' -f1)}")
+  _describe -t pathlist 'pathlist' pathlist
+}
+
+_cheat() {
+
+  _arguments -C \
+    '(--init)--init[Write a default config file to stdout]: :->none' \
+    '(-c --colorize)'{-c,--colorize}'[Colorize output]: :->none' \
+    '(-d --directories)'{-d,--directories}'[List cheatsheet directories]: :->none' \
+    '(-e --edit)'{-e,--edit}'[Edit <sheet>]: :->personal' \
+    '(-l --list)'{-l,--list}'[List cheatsheets]: :->full' \
+    '(-p --path)'{-p,--path}'[Return only sheets found on path <name>]: :->pathlist' \
+    '(-r --regex)'{-r,--regex}'[Treat search <phrase> as a regex]: :->none' \
+    '(-s --search)'{-s,--search}'[Search cheatsheets for <phrase>]: :->none' \
+    '(-t --tag)'{-t,--tag}'[Return only sheets matching <tag>]: :->taglist' \
+    '(-T --tags)'{-T,--tags}'[List all tags in use]: :->none' \
+    '(-v --version)'{-v,--version}'[Print the version number]: :->none' \
+    '(--rm)--rm[Remove (delete) <sheet>]: :->personal' 
+
+  case $state in
+    (none)
+      ;;
+    (full)
+      _cheat_complete_full_cheatsheets
+      ;;
+    (personal)
+      _cheat_complete_personal_cheatsheets
+      ;;
+    (taglist)
+      _cheat_complete_tags
+      ;;
+    (pathlist)
+      _cheat_complete_paths
+      ;;
+    (*)
+      ;;
+  esac
+}
+
+compdef _cheat cheat

scripts/fzf.bash

@@ -1,11 +0,0 @@
-#!/bin/bash
-
-# This function enables you to choose a cheatsheet to view by selecting output
-# from `cheat -l`. `source` it in your shell to enable it. (Consider renaming
-# or aliasing it to something convenient.)
-
-# Arguments passed to this function (like --color) will be passed to the second
-# invokation of `cheat`.
-function cheat-fzf {
-  eval `cheat -l | tail -n +2 | fzf | awk -v vars="$*" '{ print "cheat " $1 " -t " $3, vars }'`
-}

scripts/git/cheatsheets

@@ -0,0 +1,46 @@
+#!/bin/sh -e
+
+pull() {
+  for d in `cheat -d | awk '{print $2}'`;
+  do
+      echo "Update $d"
+      cd "$d"
+      [ -d ".git" ] && git pull || :
+  done
+
+  echo
+  echo "Finished update"
+}
+
+push() {
+  for d in `cheat -d | grep -v "community" | awk '{print $2}'`;
+  do
+      cd "$d"
+      if [ -d ".git" ]
+      then
+          echo "Push modifications $d"
+          files=$(git ls-files -mo | tr '\n' ' ')
+          git add -A && git commit -m "Edited files: $files" && git push || :
+      else
+          echo "$(pwd) is not a git managed folder"
+          echo "First connect this to your personal git repository"
+      fi
+  done
+
+  echo
+  echo "Finished push operation"
+}
+
+
+if [ "$1" = "pull" ]; then
+  pull
+elif [ "$1" = "push" ]; then
+  push
+else
+  echo "Usage:
+  # pull changes
+  cheatsheets pull
+
+  # push changes
+  cheatsheets push"
+fi

vendor/github.com/Microsoft/go-winio/.gitignore

@@ -0,0 +1 @@
+*.exe

vendor/github.com/Microsoft/go-winio/CODEOWNERS

@@ -0,0 +1 @@
+  * @microsoft/containerplat

vendor/github.com/Microsoft/go-winio/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

vendor/github.com/Microsoft/go-winio/README.md

@@ -0,0 +1,37 @@
+# go-winio [![Build Status](https://github.com/microsoft/go-winio/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/go-winio/actions/workflows/ci.yml)
+
+This repository contains utilities for efficiently performing Win32 IO operations in
+Go. Currently, this is focused on accessing named pipes and other file handles, and
+for using named pipes as a net transport.
+
+This code relies on IO completion ports to avoid blocking IO on system threads, allowing Go
+to reuse the thread to schedule another goroutine. This limits support to Windows Vista and
+newer operating systems. This is similar to the implementation of network sockets in Go's net
+package.
+
+Please see the LICENSE file for licensing information.
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA)
+declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR
+appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
+
+We also require that contributors sign their commits using git commit -s or git commit --signoff to certify they either authored the work themselves
+or otherwise have permission to use it in this project. Please see https://developercertificate.org/ for more info, as well as to make sure that you can
+attest to the rules listed. Our CI uses the DCO Github app to ensure that all commits in a given PR are signed-off.
+
+
+## Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+
+
+## Special Thanks
+Thanks to natefinch for the inspiration for this library. See https://github.com/natefinch/npipe
+for another named pipe implementation.

vendor/github.com/Microsoft/go-winio/backup.go

@@ -0,0 +1,280 @@
+// +build windows
+
+package winio
+
+import (
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"io"
+	"io/ioutil"
+	"os"
+	"runtime"
+	"syscall"
+	"unicode/utf16"
+)
+
+//sys backupRead(h syscall.Handle, b []byte, bytesRead *uint32, abort bool, processSecurity bool, context *uintptr) (err error) = BackupRead
+//sys backupWrite(h syscall.Handle, b []byte, bytesWritten *uint32, abort bool, processSecurity bool, context *uintptr) (err error) = BackupWrite
+
+const (
+	BackupData = uint32(iota + 1)
+	BackupEaData
+	BackupSecurity
+	BackupAlternateData
+	BackupLink
+	BackupPropertyData
+	BackupObjectId
+	BackupReparseData
+	BackupSparseBlock
+	BackupTxfsData
+)
+
+const (
+	StreamSparseAttributes = uint32(8)
+)
+
+const (
+	WRITE_DAC              = 0x40000
+	WRITE_OWNER            = 0x80000
+	ACCESS_SYSTEM_SECURITY = 0x1000000
+)
+
+// BackupHeader represents a backup stream of a file.
+type BackupHeader struct {
+	Id         uint32 // The backup stream ID
+	Attributes uint32 // Stream attributes
+	Size       int64  // The size of the stream in bytes
+	Name       string // The name of the stream (for BackupAlternateData only).
+	Offset     int64  // The offset of the stream in the file (for BackupSparseBlock only).
+}
+
+type win32StreamId struct {
+	StreamId   uint32
+	Attributes uint32
+	Size       uint64
+	NameSize   uint32
+}
+
+// BackupStreamReader reads from a stream produced by the BackupRead Win32 API and produces a series
+// of BackupHeader values.
+type BackupStreamReader struct {
+	r         io.Reader
+	bytesLeft int64
+}
+
+// NewBackupStreamReader produces a BackupStreamReader from any io.Reader.
+func NewBackupStreamReader(r io.Reader) *BackupStreamReader {
+	return &BackupStreamReader{r, 0}
+}
+
+// Next returns the next backup stream and prepares for calls to Read(). It skips the remainder of the current stream if
+// it was not completely read.
+func (r *BackupStreamReader) Next() (*BackupHeader, error) {
+	if r.bytesLeft > 0 {
+		if s, ok := r.r.(io.Seeker); ok {
+			// Make sure Seek on io.SeekCurrent sometimes succeeds
+			// before trying the actual seek.
+			if _, err := s.Seek(0, io.SeekCurrent); err == nil {
+				if _, err = s.Seek(r.bytesLeft, io.SeekCurrent); err != nil {
+					return nil, err
+				}
+				r.bytesLeft = 0
+			}
+		}
+		if _, err := io.Copy(ioutil.Discard, r); err != nil {
+			return nil, err
+		}
+	}
+	var wsi win32StreamId
+	if err := binary.Read(r.r, binary.LittleEndian, &wsi); err != nil {
+		return nil, err
+	}
+	hdr := &BackupHeader{
+		Id:         wsi.StreamId,
+		Attributes: wsi.Attributes,
+		Size:       int64(wsi.Size),
+	}
+	if wsi.NameSize != 0 {
+		name := make([]uint16, int(wsi.NameSize/2))
+		if err := binary.Read(r.r, binary.LittleEndian, name); err != nil {
+			return nil, err
+		}
+		hdr.Name = syscall.UTF16ToString(name)
+	}
+	if wsi.StreamId == BackupSparseBlock {
+		if err := binary.Read(r.r, binary.LittleEndian, &hdr.Offset); err != nil {
+			return nil, err
+		}
+		hdr.Size -= 8
+	}
+	r.bytesLeft = hdr.Size
+	return hdr, nil
+}
+
+// Read reads from the current backup stream.
+func (r *BackupStreamReader) Read(b []byte) (int, error) {
+	if r.bytesLeft == 0 {
+		return 0, io.EOF
+	}
+	if int64(len(b)) > r.bytesLeft {
+		b = b[:r.bytesLeft]
+	}
+	n, err := r.r.Read(b)
+	r.bytesLeft -= int64(n)
+	if err == io.EOF {
+		err = io.ErrUnexpectedEOF
+	} else if r.bytesLeft == 0 && err == nil {
+		err = io.EOF
+	}
+	return n, err
+}
+
+// BackupStreamWriter writes a stream compatible with the BackupWrite Win32 API.
+type BackupStreamWriter struct {
+	w         io.Writer
+	bytesLeft int64
+}
+
+// NewBackupStreamWriter produces a BackupStreamWriter on top of an io.Writer.
+func NewBackupStreamWriter(w io.Writer) *BackupStreamWriter {
+	return &BackupStreamWriter{w, 0}
+}
+
+// WriteHeader writes the next backup stream header and prepares for calls to Write().
+func (w *BackupStreamWriter) WriteHeader(hdr *BackupHeader) error {
+	if w.bytesLeft != 0 {
+		return fmt.Errorf("missing %d bytes", w.bytesLeft)
+	}
+	name := utf16.Encode([]rune(hdr.Name))
+	wsi := win32StreamId{
+		StreamId:   hdr.Id,
+		Attributes: hdr.Attributes,
+		Size:       uint64(hdr.Size),
+		NameSize:   uint32(len(name) * 2),
+	}
+	if hdr.Id == BackupSparseBlock {
+		// Include space for the int64 block offset
+		wsi.Size += 8
+	}
+	if err := binary.Write(w.w, binary.LittleEndian, &wsi); err != nil {
+		return err
+	}
+	if len(name) != 0 {
+		if err := binary.Write(w.w, binary.LittleEndian, name); err != nil {
+			return err
+		}
+	}
+	if hdr.Id == BackupSparseBlock {
+		if err := binary.Write(w.w, binary.LittleEndian, hdr.Offset); err != nil {
+			return err
+		}
+	}
+	w.bytesLeft = hdr.Size
+	return nil
+}
+
+// Write writes to the current backup stream.
+func (w *BackupStreamWriter) Write(b []byte) (int, error) {
+	if w.bytesLeft < int64(len(b)) {
+		return 0, fmt.Errorf("too many bytes by %d", int64(len(b))-w.bytesLeft)
+	}
+	n, err := w.w.Write(b)
+	w.bytesLeft -= int64(n)
+	return n, err
+}
+
+// BackupFileReader provides an io.ReadCloser interface on top of the BackupRead Win32 API.
+type BackupFileReader struct {
+	f               *os.File
+	includeSecurity bool
+	ctx             uintptr
+}
+
+// NewBackupFileReader returns a new BackupFileReader from a file handle. If includeSecurity is true,
+// Read will attempt to read the security descriptor of the file.
+func NewBackupFileReader(f *os.File, includeSecurity bool) *BackupFileReader {
+	r := &BackupFileReader{f, includeSecurity, 0}
+	return r
+}
+
+// Read reads a backup stream from the file by calling the Win32 API BackupRead().
+func (r *BackupFileReader) Read(b []byte) (int, error) {
+	var bytesRead uint32
+	err := backupRead(syscall.Handle(r.f.Fd()), b, &bytesRead, false, r.includeSecurity, &r.ctx)
+	if err != nil {
+		return 0, &os.PathError{"BackupRead", r.f.Name(), err}
+	}
+	runtime.KeepAlive(r.f)
+	if bytesRead == 0 {
+		return 0, io.EOF
+	}
+	return int(bytesRead), nil
+}
+
+// Close frees Win32 resources associated with the BackupFileReader. It does not close
+// the underlying file.
+func (r *BackupFileReader) Close() error {
+	if r.ctx != 0 {
+		backupRead(syscall.Handle(r.f.Fd()), nil, nil, true, false, &r.ctx)
+		runtime.KeepAlive(r.f)
+		r.ctx = 0
+	}
+	return nil
+}
+
+// BackupFileWriter provides an io.WriteCloser interface on top of the BackupWrite Win32 API.
+type BackupFileWriter struct {
+	f               *os.File
+	includeSecurity bool
+	ctx             uintptr
+}
+
+// NewBackupFileWriter returns a new BackupFileWriter from a file handle. If includeSecurity is true,
+// Write() will attempt to restore the security descriptor from the stream.
+func NewBackupFileWriter(f *os.File, includeSecurity bool) *BackupFileWriter {
+	w := &BackupFileWriter{f, includeSecurity, 0}
+	return w
+}
+
+// Write restores a portion of the file using the provided backup stream.
+func (w *BackupFileWriter) Write(b []byte) (int, error) {
+	var bytesWritten uint32
+	err := backupWrite(syscall.Handle(w.f.Fd()), b, &bytesWritten, false, w.includeSecurity, &w.ctx)
+	if err != nil {
+		return 0, &os.PathError{"BackupWrite", w.f.Name(), err}
+	}
+	runtime.KeepAlive(w.f)
+	if int(bytesWritten) != len(b) {
+		return int(bytesWritten), errors.New("not all bytes could be written")
+	}
+	return len(b), nil
+}
+
+// Close frees Win32 resources associated with the BackupFileWriter. It does not
+// close the underlying file.
+func (w *BackupFileWriter) Close() error {
+	if w.ctx != 0 {
+		backupWrite(syscall.Handle(w.f.Fd()), nil, nil, true, false, &w.ctx)
+		runtime.KeepAlive(w.f)
+		w.ctx = 0
+	}
+	return nil
+}
+
+// OpenForBackup opens a file or directory, potentially skipping access checks if the backup
+// or restore privileges have been acquired.
+//
+// If the file opened was a directory, it cannot be used with Readdir().
+func OpenForBackup(path string, access uint32, share uint32, createmode uint32) (*os.File, error) {
+	winPath, err := syscall.UTF16FromString(path)
+	if err != nil {
+		return nil, err
+	}
+	h, err := syscall.CreateFile(&winPath[0], access, share, nil, createmode, syscall.FILE_FLAG_BACKUP_SEMANTICS|syscall.FILE_FLAG_OPEN_REPARSE_POINT, 0)
+	if err != nil {
+		err = &os.PathError{Op: "open", Path: path, Err: err}
+		return nil, err
+	}
+	return os.NewFile(uintptr(h), path), nil
+}

vendor/github.com/Microsoft/go-winio/ea.go

@@ -0,0 +1,137 @@
+package winio
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+)
+
+type fileFullEaInformation struct {
+	NextEntryOffset uint32
+	Flags           uint8
+	NameLength      uint8
+	ValueLength     uint16
+}
+
+var (
+	fileFullEaInformationSize = binary.Size(&fileFullEaInformation{})
+
+	errInvalidEaBuffer = errors.New("invalid extended attribute buffer")
+	errEaNameTooLarge  = errors.New("extended attribute name too large")
+	errEaValueTooLarge = errors.New("extended attribute value too large")
+)
+
+// ExtendedAttribute represents a single Windows EA.
+type ExtendedAttribute struct {
+	Name  string
+	Value []byte
+	Flags uint8
+}
+
+func parseEa(b []byte) (ea ExtendedAttribute, nb []byte, err error) {
+	var info fileFullEaInformation
+	err = binary.Read(bytes.NewReader(b), binary.LittleEndian, &info)
+	if err != nil {
+		err = errInvalidEaBuffer
+		return
+	}
+
+	nameOffset := fileFullEaInformationSize
+	nameLen := int(info.NameLength)
+	valueOffset := nameOffset + int(info.NameLength) + 1
+	valueLen := int(info.ValueLength)
+	nextOffset := int(info.NextEntryOffset)
+	if valueLen+valueOffset > len(b) || nextOffset < 0 || nextOffset > len(b) {
+		err = errInvalidEaBuffer
+		return
+	}
+
+	ea.Name = string(b[nameOffset : nameOffset+nameLen])
+	ea.Value = b[valueOffset : valueOffset+valueLen]
+	ea.Flags = info.Flags
+	if info.NextEntryOffset != 0 {
+		nb = b[info.NextEntryOffset:]
+	}
+	return
+}
+
+// DecodeExtendedAttributes decodes a list of EAs from a FILE_FULL_EA_INFORMATION
+// buffer retrieved from BackupRead, ZwQueryEaFile, etc.
+func DecodeExtendedAttributes(b []byte) (eas []ExtendedAttribute, err error) {
+	for len(b) != 0 {
+		ea, nb, err := parseEa(b)
+		if err != nil {
+			return nil, err
+		}
+
+		eas = append(eas, ea)
+		b = nb
+	}
+	return
+}
+
+func writeEa(buf *bytes.Buffer, ea *ExtendedAttribute, last bool) error {
+	if int(uint8(len(ea.Name))) != len(ea.Name) {
+		return errEaNameTooLarge
+	}
+	if int(uint16(len(ea.Value))) != len(ea.Value) {
+		return errEaValueTooLarge
+	}
+	entrySize := uint32(fileFullEaInformationSize + len(ea.Name) + 1 + len(ea.Value))
+	withPadding := (entrySize + 3) &^ 3
+	nextOffset := uint32(0)
+	if !last {
+		nextOffset = withPadding
+	}
+	info := fileFullEaInformation{
+		NextEntryOffset: nextOffset,
+		Flags:           ea.Flags,
+		NameLength:      uint8(len(ea.Name)),
+		ValueLength:     uint16(len(ea.Value)),
+	}
+
+	err := binary.Write(buf, binary.LittleEndian, &info)
+	if err != nil {
+		return err
+	}
+
+	_, err = buf.Write([]byte(ea.Name))
+	if err != nil {
+		return err
+	}
+
+	err = buf.WriteByte(0)
+	if err != nil {
+		return err
+	}
+
+	_, err = buf.Write(ea.Value)
+	if err != nil {
+		return err
+	}
+
+	_, err = buf.Write([]byte{0, 0, 0}[0 : withPadding-entrySize])
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// EncodeExtendedAttributes encodes a list of EAs into a FILE_FULL_EA_INFORMATION
+// buffer for use with BackupWrite, ZwSetEaFile, etc.
+func EncodeExtendedAttributes(eas []ExtendedAttribute) ([]byte, error) {
+	var buf bytes.Buffer
+	for i := range eas {
+		last := false
+		if i == len(eas)-1 {
+			last = true
+		}
+
+		err := writeEa(&buf, &eas[i], last)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return buf.Bytes(), nil
+}

vendor/github.com/Microsoft/go-winio/file.go

@@ -0,0 +1,329 @@
+//go:build windows
+// +build windows
+
+package winio
+
+import (
+	"errors"
+	"io"
+	"runtime"
+	"sync"
+	"sync/atomic"
+	"syscall"
+	"time"
+)
+
+//sys cancelIoEx(file syscall.Handle, o *syscall.Overlapped) (err error) = CancelIoEx
+//sys createIoCompletionPort(file syscall.Handle, port syscall.Handle, key uintptr, threadCount uint32) (newport syscall.Handle, err error) = CreateIoCompletionPort
+//sys getQueuedCompletionStatus(port syscall.Handle, bytes *uint32, key *uintptr, o **ioOperation, timeout uint32) (err error) = GetQueuedCompletionStatus
+//sys setFileCompletionNotificationModes(h syscall.Handle, flags uint8) (err error) = SetFileCompletionNotificationModes
+//sys wsaGetOverlappedResult(h syscall.Handle, o *syscall.Overlapped, bytes *uint32, wait bool, flags *uint32) (err error) = ws2_32.WSAGetOverlappedResult
+
+type atomicBool int32
+
+func (b *atomicBool) isSet() bool { return atomic.LoadInt32((*int32)(b)) != 0 }
+func (b *atomicBool) setFalse()   { atomic.StoreInt32((*int32)(b), 0) }
+func (b *atomicBool) setTrue()    { atomic.StoreInt32((*int32)(b), 1) }
+func (b *atomicBool) swap(new bool) bool {
+	var newInt int32
+	if new {
+		newInt = 1
+	}
+	return atomic.SwapInt32((*int32)(b), newInt) == 1
+}
+
+const (
+	cFILE_SKIP_COMPLETION_PORT_ON_SUCCESS = 1
+	cFILE_SKIP_SET_EVENT_ON_HANDLE        = 2
+)
+
+var (
+	ErrFileClosed = errors.New("file has already been closed")
+	ErrTimeout    = &timeoutError{}
+)
+
+type timeoutError struct{}
+
+func (e *timeoutError) Error() string   { return "i/o timeout" }
+func (e *timeoutError) Timeout() bool   { return true }
+func (e *timeoutError) Temporary() bool { return true }
+
+type timeoutChan chan struct{}
+
+var ioInitOnce sync.Once
+var ioCompletionPort syscall.Handle
+
+// ioResult contains the result of an asynchronous IO operation
+type ioResult struct {
+	bytes uint32
+	err   error
+}
+
+// ioOperation represents an outstanding asynchronous Win32 IO
+type ioOperation struct {
+	o  syscall.Overlapped
+	ch chan ioResult
+}
+
+func initIo() {
+	h, err := createIoCompletionPort(syscall.InvalidHandle, 0, 0, 0xffffffff)
+	if err != nil {
+		panic(err)
+	}
+	ioCompletionPort = h
+	go ioCompletionProcessor(h)
+}
+
+// win32File implements Reader, Writer, and Closer on a Win32 handle without blocking in a syscall.
+// It takes ownership of this handle and will close it if it is garbage collected.
+type win32File struct {
+	handle        syscall.Handle
+	wg            sync.WaitGroup
+	wgLock        sync.RWMutex
+	closing       atomicBool
+	socket        bool
+	readDeadline  deadlineHandler
+	writeDeadline deadlineHandler
+}
+
+type deadlineHandler struct {
+	setLock     sync.Mutex
+	channel     timeoutChan
+	channelLock sync.RWMutex
+	timer       *time.Timer
+	timedout    atomicBool
+}
+
+// makeWin32File makes a new win32File from an existing file handle
+func makeWin32File(h syscall.Handle) (*win32File, error) {
+	f := &win32File{handle: h}
+	ioInitOnce.Do(initIo)
+	_, err := createIoCompletionPort(h, ioCompletionPort, 0, 0xffffffff)
+	if err != nil {
+		return nil, err
+	}
+	err = setFileCompletionNotificationModes(h, cFILE_SKIP_COMPLETION_PORT_ON_SUCCESS|cFILE_SKIP_SET_EVENT_ON_HANDLE)
+	if err != nil {
+		return nil, err
+	}
+	f.readDeadline.channel = make(timeoutChan)
+	f.writeDeadline.channel = make(timeoutChan)
+	return f, nil
+}
+
+func MakeOpenFile(h syscall.Handle) (io.ReadWriteCloser, error) {
+	// If we return the result of makeWin32File directly, it can result in an
+	// interface-wrapped nil, rather than a nil interface value.
+	f, err := makeWin32File(h)
+	if err != nil {
+		return nil, err
+	}
+	return f, nil
+}
+
+// closeHandle closes the resources associated with a Win32 handle
+func (f *win32File) closeHandle() {
+	f.wgLock.Lock()
+	// Atomically set that we are closing, releasing the resources only once.
+	if !f.closing.swap(true) {
+		f.wgLock.Unlock()
+		// cancel all IO and wait for it to complete
+		cancelIoEx(f.handle, nil)
+		f.wg.Wait()
+		// at this point, no new IO can start
+		syscall.Close(f.handle)
+		f.handle = 0
+	} else {
+		f.wgLock.Unlock()
+	}
+}
+
+// Close closes a win32File.
+func (f *win32File) Close() error {
+	f.closeHandle()
+	return nil
+}
+
+// IsClosed checks if the file has been closed
+func (f *win32File) IsClosed() bool {
+	return f.closing.isSet()
+}
+
+// prepareIo prepares for a new IO operation.
+// The caller must call f.wg.Done() when the IO is finished, prior to Close() returning.
+func (f *win32File) prepareIo() (*ioOperation, error) {
+	f.wgLock.RLock()
+	if f.closing.isSet() {
+		f.wgLock.RUnlock()
+		return nil, ErrFileClosed
+	}
+	f.wg.Add(1)
+	f.wgLock.RUnlock()
+	c := &ioOperation{}
+	c.ch = make(chan ioResult)
+	return c, nil
+}
+
+// ioCompletionProcessor processes completed async IOs forever
+func ioCompletionProcessor(h syscall.Handle) {
+	for {
+		var bytes uint32
+		var key uintptr
+		var op *ioOperation
+		err := getQueuedCompletionStatus(h, &bytes, &key, &op, syscall.INFINITE)
+		if op == nil {
+			panic(err)
+		}
+		op.ch <- ioResult{bytes, err}
+	}
+}
+
+// asyncIo processes the return value from ReadFile or WriteFile, blocking until
+// the operation has actually completed.
+func (f *win32File) asyncIo(c *ioOperation, d *deadlineHandler, bytes uint32, err error) (int, error) {
+	if err != syscall.ERROR_IO_PENDING {
+		return int(bytes), err
+	}
+
+	if f.closing.isSet() {
+		cancelIoEx(f.handle, &c.o)
+	}
+
+	var timeout timeoutChan
+	if d != nil {
+		d.channelLock.Lock()
+		timeout = d.channel
+		d.channelLock.Unlock()
+	}
+
+	var r ioResult
+	select {
+	case r = <-c.ch:
+		err = r.err
+		if err == syscall.ERROR_OPERATION_ABORTED {
+			if f.closing.isSet() {
+				err = ErrFileClosed
+			}
+		} else if err != nil && f.socket {
+			// err is from Win32. Query the overlapped structure to get the winsock error.
+			var bytes, flags uint32
+			err = wsaGetOverlappedResult(f.handle, &c.o, &bytes, false, &flags)
+		}
+	case <-timeout:
+		cancelIoEx(f.handle, &c.o)
+		r = <-c.ch
+		err = r.err
+		if err == syscall.ERROR_OPERATION_ABORTED {
+			err = ErrTimeout
+		}
+	}
+
+	// runtime.KeepAlive is needed, as c is passed via native
+	// code to ioCompletionProcessor, c must remain alive
+	// until the channel read is complete.
+	runtime.KeepAlive(c)
+	return int(r.bytes), err
+}
+
+// Read reads from a file handle.
+func (f *win32File) Read(b []byte) (int, error) {
+	c, err := f.prepareIo()
+	if err != nil {
+		return 0, err
+	}
+	defer f.wg.Done()
+
+	if f.readDeadline.timedout.isSet() {
+		return 0, ErrTimeout
+	}
+
+	var bytes uint32
+	err = syscall.ReadFile(f.handle, b, &bytes, &c.o)
+	n, err := f.asyncIo(c, &f.readDeadline, bytes, err)
+	runtime.KeepAlive(b)
+
+	// Handle EOF conditions.
+	if err == nil && n == 0 && len(b) != 0 {
+		return 0, io.EOF
+	} else if err == syscall.ERROR_BROKEN_PIPE {
+		return 0, io.EOF
+	} else {
+		return n, err
+	}
+}
+
+// Write writes to a file handle.
+func (f *win32File) Write(b []byte) (int, error) {
+	c, err := f.prepareIo()
+	if err != nil {
+		return 0, err
+	}
+	defer f.wg.Done()
+
+	if f.writeDeadline.timedout.isSet() {
+		return 0, ErrTimeout
+	}
+
+	var bytes uint32
+	err = syscall.WriteFile(f.handle, b, &bytes, &c.o)
+	n, err := f.asyncIo(c, &f.writeDeadline, bytes, err)
+	runtime.KeepAlive(b)
+	return n, err
+}
+
+func (f *win32File) SetReadDeadline(deadline time.Time) error {
+	return f.readDeadline.set(deadline)
+}
+
+func (f *win32File) SetWriteDeadline(deadline time.Time) error {
+	return f.writeDeadline.set(deadline)
+}
+
+func (f *win32File) Flush() error {
+	return syscall.FlushFileBuffers(f.handle)
+}
+
+func (f *win32File) Fd() uintptr {
+	return uintptr(f.handle)
+}
+
+func (d *deadlineHandler) set(deadline time.Time) error {
+	d.setLock.Lock()
+	defer d.setLock.Unlock()
+
+	if d.timer != nil {
+		if !d.timer.Stop() {
+			<-d.channel
+		}
+		d.timer = nil
+	}
+	d.timedout.setFalse()
+
+	select {
+	case <-d.channel:
+		d.channelLock.Lock()
+		d.channel = make(chan struct{})
+		d.channelLock.Unlock()
+	default:
+	}
+
+	if deadline.IsZero() {
+		return nil
+	}
+
+	timeoutIO := func() {
+		d.timedout.setTrue()
+		close(d.channel)
+	}
+
+	now := time.Now()
+	duration := deadline.Sub(now)
+	if deadline.After(now) {
+		// Deadline is in the future, set a timer to wait
+		d.timer = time.AfterFunc(duration, timeoutIO)
+	} else {
+		// Deadline is in the past. Cancel all pending IO now.
+		timeoutIO()
+	}
+	return nil
+}

vendor/github.com/Microsoft/go-winio/fileinfo.go

@@ -0,0 +1,73 @@
+// +build windows
+
+package winio
+
+import (
+	"os"
+	"runtime"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+// FileBasicInfo contains file access time and file attributes information.
+type FileBasicInfo struct {
+	CreationTime, LastAccessTime, LastWriteTime, ChangeTime windows.Filetime
+	FileAttributes                                          uint32
+	pad                                                     uint32 // padding
+}
+
+// GetFileBasicInfo retrieves times and attributes for a file.
+func GetFileBasicInfo(f *os.File) (*FileBasicInfo, error) {
+	bi := &FileBasicInfo{}
+	if err := windows.GetFileInformationByHandleEx(windows.Handle(f.Fd()), windows.FileBasicInfo, (*byte)(unsafe.Pointer(bi)), uint32(unsafe.Sizeof(*bi))); err != nil {
+		return nil, &os.PathError{Op: "GetFileInformationByHandleEx", Path: f.Name(), Err: err}
+	}
+	runtime.KeepAlive(f)
+	return bi, nil
+}
+
+// SetFileBasicInfo sets times and attributes for a file.
+func SetFileBasicInfo(f *os.File, bi *FileBasicInfo) error {
+	if err := windows.SetFileInformationByHandle(windows.Handle(f.Fd()), windows.FileBasicInfo, (*byte)(unsafe.Pointer(bi)), uint32(unsafe.Sizeof(*bi))); err != nil {
+		return &os.PathError{Op: "SetFileInformationByHandle", Path: f.Name(), Err: err}
+	}
+	runtime.KeepAlive(f)
+	return nil
+}
+
+// FileStandardInfo contains extended information for the file.
+// FILE_STANDARD_INFO in WinBase.h
+// https://docs.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-file_standard_info
+type FileStandardInfo struct {
+	AllocationSize, EndOfFile int64
+	NumberOfLinks             uint32
+	DeletePending, Directory  bool
+}
+
+// GetFileStandardInfo retrieves ended information for the file.
+func GetFileStandardInfo(f *os.File) (*FileStandardInfo, error) {
+	si := &FileStandardInfo{}
+	if err := windows.GetFileInformationByHandleEx(windows.Handle(f.Fd()), windows.FileStandardInfo, (*byte)(unsafe.Pointer(si)), uint32(unsafe.Sizeof(*si))); err != nil {
+		return nil, &os.PathError{Op: "GetFileInformationByHandleEx", Path: f.Name(), Err: err}
+	}
+	runtime.KeepAlive(f)
+	return si, nil
+}
+
+// FileIDInfo contains the volume serial number and file ID for a file. This pair should be
+// unique on a system.
+type FileIDInfo struct {
+	VolumeSerialNumber uint64
+	FileID             [16]byte
+}
+
+// GetFileID retrieves the unique (volume, file ID) pair for a file.
+func GetFileID(f *os.File) (*FileIDInfo, error) {
+	fileID := &FileIDInfo{}
+	if err := windows.GetFileInformationByHandleEx(windows.Handle(f.Fd()), windows.FileIdInfo, (*byte)(unsafe.Pointer(fileID)), uint32(unsafe.Sizeof(*fileID))); err != nil {
+		return nil, &os.PathError{Op: "GetFileInformationByHandleEx", Path: f.Name(), Err: err}
+	}
+	runtime.KeepAlive(f)
+	return fileID, nil
+}

vendor/github.com/Microsoft/go-winio/hvsock.go

@@ -0,0 +1,316 @@
+//go:build windows
+// +build windows
+
+package winio
+
+import (
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"syscall"
+	"time"
+	"unsafe"
+
+	"github.com/Microsoft/go-winio/pkg/guid"
+)
+
+//sys bind(s syscall.Handle, name unsafe.Pointer, namelen int32) (err error) [failretval==socketError] = ws2_32.bind
+
+const (
+	afHvSock = 34 // AF_HYPERV
+
+	socketError = ^uintptr(0)
+)
+
+// An HvsockAddr is an address for a AF_HYPERV socket.
+type HvsockAddr struct {
+	VMID      guid.GUID
+	ServiceID guid.GUID
+}
+
+type rawHvsockAddr struct {
+	Family    uint16
+	_         uint16
+	VMID      guid.GUID
+	ServiceID guid.GUID
+}
+
+// Network returns the address's network name, "hvsock".
+func (addr *HvsockAddr) Network() string {
+	return "hvsock"
+}
+
+func (addr *HvsockAddr) String() string {
+	return fmt.Sprintf("%s:%s", &addr.VMID, &addr.ServiceID)
+}
+
+// VsockServiceID returns an hvsock service ID corresponding to the specified AF_VSOCK port.
+func VsockServiceID(port uint32) guid.GUID {
+	g, _ := guid.FromString("00000000-facb-11e6-bd58-64006a7986d3")
+	g.Data1 = port
+	return g
+}
+
+func (addr *HvsockAddr) raw() rawHvsockAddr {
+	return rawHvsockAddr{
+		Family:    afHvSock,
+		VMID:      addr.VMID,
+		ServiceID: addr.ServiceID,
+	}
+}
+
+func (addr *HvsockAddr) fromRaw(raw *rawHvsockAddr) {
+	addr.VMID = raw.VMID
+	addr.ServiceID = raw.ServiceID
+}
+
+// HvsockListener is a socket listener for the AF_HYPERV address family.
+type HvsockListener struct {
+	sock *win32File
+	addr HvsockAddr
+}
+
+// HvsockConn is a connected socket of the AF_HYPERV address family.
+type HvsockConn struct {
+	sock          *win32File
+	local, remote HvsockAddr
+}
+
+func newHvSocket() (*win32File, error) {
+	fd, err := syscall.Socket(afHvSock, syscall.SOCK_STREAM, 1)
+	if err != nil {
+		return nil, os.NewSyscallError("socket", err)
+	}
+	f, err := makeWin32File(fd)
+	if err != nil {
+		syscall.Close(fd)
+		return nil, err
+	}
+	f.socket = true
+	return f, nil
+}
+
+// ListenHvsock listens for connections on the specified hvsock address.
+func ListenHvsock(addr *HvsockAddr) (_ *HvsockListener, err error) {
+	l := &HvsockListener{addr: *addr}
+	sock, err := newHvSocket()
+	if err != nil {
+		return nil, l.opErr("listen", err)
+	}
+	sa := addr.raw()
+	err = bind(sock.handle, unsafe.Pointer(&sa), int32(unsafe.Sizeof(sa)))
+	if err != nil {
+		return nil, l.opErr("listen", os.NewSyscallError("socket", err))
+	}
+	err = syscall.Listen(sock.handle, 16)
+	if err != nil {
+		return nil, l.opErr("listen", os.NewSyscallError("listen", err))
+	}
+	return &HvsockListener{sock: sock, addr: *addr}, nil
+}
+
+func (l *HvsockListener) opErr(op string, err error) error {
+	return &net.OpError{Op: op, Net: "hvsock", Addr: &l.addr, Err: err}
+}
+
+// Addr returns the listener's network address.
+func (l *HvsockListener) Addr() net.Addr {
+	return &l.addr
+}
+
+// Accept waits for the next connection and returns it.
+func (l *HvsockListener) Accept() (_ net.Conn, err error) {
+	sock, err := newHvSocket()
+	if err != nil {
+		return nil, l.opErr("accept", err)
+	}
+	defer func() {
+		if sock != nil {
+			sock.Close()
+		}
+	}()
+	c, err := l.sock.prepareIo()
+	if err != nil {
+		return nil, l.opErr("accept", err)
+	}
+	defer l.sock.wg.Done()
+
+	// AcceptEx, per documentation, requires an extra 16 bytes per address.
+	const addrlen = uint32(16 + unsafe.Sizeof(rawHvsockAddr{}))
+	var addrbuf [addrlen * 2]byte
+
+	var bytes uint32
+	err = syscall.AcceptEx(l.sock.handle, sock.handle, &addrbuf[0], 0, addrlen, addrlen, &bytes, &c.o)
+	_, err = l.sock.asyncIo(c, nil, bytes, err)
+	if err != nil {
+		return nil, l.opErr("accept", os.NewSyscallError("acceptex", err))
+	}
+	conn := &HvsockConn{
+		sock: sock,
+	}
+	conn.local.fromRaw((*rawHvsockAddr)(unsafe.Pointer(&addrbuf[0])))
+	conn.remote.fromRaw((*rawHvsockAddr)(unsafe.Pointer(&addrbuf[addrlen])))
+	sock = nil
+	return conn, nil
+}
+
+// Close closes the listener, causing any pending Accept calls to fail.
+func (l *HvsockListener) Close() error {
+	return l.sock.Close()
+}
+
+/* Need to finish ConnectEx handling
+func DialHvsock(ctx context.Context, addr *HvsockAddr) (*HvsockConn, error) {
+	sock, err := newHvSocket()
+	if err != nil {
+		return nil, err
+	}
+	defer func() {
+		if sock != nil {
+			sock.Close()
+		}
+	}()
+	c, err := sock.prepareIo()
+	if err != nil {
+		return nil, err
+	}
+	defer sock.wg.Done()
+	var bytes uint32
+	err = windows.ConnectEx(windows.Handle(sock.handle), sa, nil, 0, &bytes, &c.o)
+	_, err = sock.asyncIo(ctx, c, nil, bytes, err)
+	if err != nil {
+		return nil, err
+	}
+	conn := &HvsockConn{
+		sock:   sock,
+		remote: *addr,
+	}
+	sock = nil
+	return conn, nil
+}
+*/
+
+func (conn *HvsockConn) opErr(op string, err error) error {
+	return &net.OpError{Op: op, Net: "hvsock", Source: &conn.local, Addr: &conn.remote, Err: err}
+}
+
+func (conn *HvsockConn) Read(b []byte) (int, error) {
+	c, err := conn.sock.prepareIo()
+	if err != nil {
+		return 0, conn.opErr("read", err)
+	}
+	defer conn.sock.wg.Done()
+	buf := syscall.WSABuf{Buf: &b[0], Len: uint32(len(b))}
+	var flags, bytes uint32
+	err = syscall.WSARecv(conn.sock.handle, &buf, 1, &bytes, &flags, &c.o, nil)
+	n, err := conn.sock.asyncIo(c, &conn.sock.readDeadline, bytes, err)
+	if err != nil {
+		if _, ok := err.(syscall.Errno); ok {
+			err = os.NewSyscallError("wsarecv", err)
+		}
+		return 0, conn.opErr("read", err)
+	} else if n == 0 {
+		err = io.EOF
+	}
+	return n, err
+}
+
+func (conn *HvsockConn) Write(b []byte) (int, error) {
+	t := 0
+	for len(b) != 0 {
+		n, err := conn.write(b)
+		if err != nil {
+			return t + n, err
+		}
+		t += n
+		b = b[n:]
+	}
+	return t, nil
+}
+
+func (conn *HvsockConn) write(b []byte) (int, error) {
+	c, err := conn.sock.prepareIo()
+	if err != nil {
+		return 0, conn.opErr("write", err)
+	}
+	defer conn.sock.wg.Done()
+	buf := syscall.WSABuf{Buf: &b[0], Len: uint32(len(b))}
+	var bytes uint32
+	err = syscall.WSASend(conn.sock.handle, &buf, 1, &bytes, 0, &c.o, nil)
+	n, err := conn.sock.asyncIo(c, &conn.sock.writeDeadline, bytes, err)
+	if err != nil {
+		if _, ok := err.(syscall.Errno); ok {
+			err = os.NewSyscallError("wsasend", err)
+		}
+		return 0, conn.opErr("write", err)
+	}
+	return n, err
+}
+
+// Close closes the socket connection, failing any pending read or write calls.
+func (conn *HvsockConn) Close() error {
+	return conn.sock.Close()
+}
+
+func (conn *HvsockConn) IsClosed() bool {
+	return conn.sock.IsClosed()
+}
+
+func (conn *HvsockConn) shutdown(how int) error {
+	if conn.IsClosed() {
+		return ErrFileClosed
+	}
+
+	err := syscall.Shutdown(conn.sock.handle, how)
+	if err != nil {
+		return os.NewSyscallError("shutdown", err)
+	}
+	return nil
+}
+
+// CloseRead shuts down the read end of the socket, preventing future read operations.
+func (conn *HvsockConn) CloseRead() error {
+	err := conn.shutdown(syscall.SHUT_RD)
+	if err != nil {
+		return conn.opErr("close", err)
+	}
+	return nil
+}
+
+// CloseWrite shuts down the write end of the socket, preventing future write operations and
+// notifying the other endpoint that no more data will be written.
+func (conn *HvsockConn) CloseWrite() error {
+	err := conn.shutdown(syscall.SHUT_WR)
+	if err != nil {
+		return conn.opErr("close", err)
+	}
+	return nil
+}
+
+// LocalAddr returns the local address of the connection.
+func (conn *HvsockConn) LocalAddr() net.Addr {
+	return &conn.local
+}
+
+// RemoteAddr returns the remote address of the connection.
+func (conn *HvsockConn) RemoteAddr() net.Addr {
+	return &conn.remote
+}
+
+// SetDeadline implements the net.Conn SetDeadline method.
+func (conn *HvsockConn) SetDeadline(t time.Time) error {
+	conn.SetReadDeadline(t)
+	conn.SetWriteDeadline(t)
+	return nil
+}
+
+// SetReadDeadline implements the net.Conn SetReadDeadline method.
+func (conn *HvsockConn) SetReadDeadline(t time.Time) error {
+	return conn.sock.SetReadDeadline(t)
+}
+
+// SetWriteDeadline implements the net.Conn SetWriteDeadline method.
+func (conn *HvsockConn) SetWriteDeadline(t time.Time) error {
+	return conn.sock.SetWriteDeadline(t)
+}

vendor/github.com/Microsoft/go-winio/pipe.go

@@ -0,0 +1,517 @@
+// +build windows
+
+package winio
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"runtime"
+	"syscall"
+	"time"
+	"unsafe"
+)
+
+//sys connectNamedPipe(pipe syscall.Handle, o *syscall.Overlapped) (err error) = ConnectNamedPipe
+//sys createNamedPipe(name string, flags uint32, pipeMode uint32, maxInstances uint32, outSize uint32, inSize uint32, defaultTimeout uint32, sa *syscall.SecurityAttributes) (handle syscall.Handle, err error)  [failretval==syscall.InvalidHandle] = CreateNamedPipeW
+//sys createFile(name string, access uint32, mode uint32, sa *syscall.SecurityAttributes, createmode uint32, attrs uint32, templatefile syscall.Handle) (handle syscall.Handle, err error) [failretval==syscall.InvalidHandle] = CreateFileW
+//sys getNamedPipeInfo(pipe syscall.Handle, flags *uint32, outSize *uint32, inSize *uint32, maxInstances *uint32) (err error) = GetNamedPipeInfo
+//sys getNamedPipeHandleState(pipe syscall.Handle, state *uint32, curInstances *uint32, maxCollectionCount *uint32, collectDataTimeout *uint32, userName *uint16, maxUserNameSize uint32) (err error) = GetNamedPipeHandleStateW
+//sys localAlloc(uFlags uint32, length uint32) (ptr uintptr) = LocalAlloc
+//sys ntCreateNamedPipeFile(pipe *syscall.Handle, access uint32, oa *objectAttributes, iosb *ioStatusBlock, share uint32, disposition uint32, options uint32, typ uint32, readMode uint32, completionMode uint32, maxInstances uint32, inboundQuota uint32, outputQuota uint32, timeout *int64) (status ntstatus) = ntdll.NtCreateNamedPipeFile
+//sys rtlNtStatusToDosError(status ntstatus) (winerr error) = ntdll.RtlNtStatusToDosErrorNoTeb
+//sys rtlDosPathNameToNtPathName(name *uint16, ntName *unicodeString, filePart uintptr, reserved uintptr) (status ntstatus) = ntdll.RtlDosPathNameToNtPathName_U
+//sys rtlDefaultNpAcl(dacl *uintptr) (status ntstatus) = ntdll.RtlDefaultNpAcl
+
+type ioStatusBlock struct {
+	Status, Information uintptr
+}
+
+type objectAttributes struct {
+	Length             uintptr
+	RootDirectory      uintptr
+	ObjectName         *unicodeString
+	Attributes         uintptr
+	SecurityDescriptor *securityDescriptor
+	SecurityQoS        uintptr
+}
+
+type unicodeString struct {
+	Length        uint16
+	MaximumLength uint16
+	Buffer        uintptr
+}
+
+type securityDescriptor struct {
+	Revision byte
+	Sbz1     byte
+	Control  uint16
+	Owner    uintptr
+	Group    uintptr
+	Sacl     uintptr
+	Dacl     uintptr
+}
+
+type ntstatus int32
+
+func (status ntstatus) Err() error {
+	if status >= 0 {
+		return nil
+	}
+	return rtlNtStatusToDosError(status)
+}
+
+const (
+	cERROR_PIPE_BUSY      = syscall.Errno(231)
+	cERROR_NO_DATA        = syscall.Errno(232)
+	cERROR_PIPE_CONNECTED = syscall.Errno(535)
+	cERROR_SEM_TIMEOUT    = syscall.Errno(121)
+
+	cSECURITY_SQOS_PRESENT = 0x100000
+	cSECURITY_ANONYMOUS    = 0
+
+	cPIPE_TYPE_MESSAGE = 4
+
+	cPIPE_READMODE_MESSAGE = 2
+
+	cFILE_OPEN   = 1
+	cFILE_CREATE = 2
+
+	cFILE_PIPE_MESSAGE_TYPE          = 1
+	cFILE_PIPE_REJECT_REMOTE_CLIENTS = 2
+
+	cSE_DACL_PRESENT = 4
+)
+
+var (
+	// ErrPipeListenerClosed is returned for pipe operations on listeners that have been closed.
+	// This error should match net.errClosing since docker takes a dependency on its text.
+	ErrPipeListenerClosed = errors.New("use of closed network connection")
+
+	errPipeWriteClosed = errors.New("pipe has been closed for write")
+)
+
+type win32Pipe struct {
+	*win32File
+	path string
+}
+
+type win32MessageBytePipe struct {
+	win32Pipe
+	writeClosed bool
+	readEOF     bool
+}
+
+type pipeAddress string
+
+func (f *win32Pipe) LocalAddr() net.Addr {
+	return pipeAddress(f.path)
+}
+
+func (f *win32Pipe) RemoteAddr() net.Addr {
+	return pipeAddress(f.path)
+}
+
+func (f *win32Pipe) SetDeadline(t time.Time) error {
+	f.SetReadDeadline(t)
+	f.SetWriteDeadline(t)
+	return nil
+}
+
+// CloseWrite closes the write side of a message pipe in byte mode.
+func (f *win32MessageBytePipe) CloseWrite() error {
+	if f.writeClosed {
+		return errPipeWriteClosed
+	}
+	err := f.win32File.Flush()
+	if err != nil {
+		return err
+	}
+	_, err = f.win32File.Write(nil)
+	if err != nil {
+		return err
+	}
+	f.writeClosed = true
+	return nil
+}
+
+// Write writes bytes to a message pipe in byte mode. Zero-byte writes are ignored, since
+// they are used to implement CloseWrite().
+func (f *win32MessageBytePipe) Write(b []byte) (int, error) {
+	if f.writeClosed {
+		return 0, errPipeWriteClosed
+	}
+	if len(b) == 0 {
+		return 0, nil
+	}
+	return f.win32File.Write(b)
+}
+
+// Read reads bytes from a message pipe in byte mode. A read of a zero-byte message on a message
+// mode pipe will return io.EOF, as will all subsequent reads.
+func (f *win32MessageBytePipe) Read(b []byte) (int, error) {
+	if f.readEOF {
+		return 0, io.EOF
+	}
+	n, err := f.win32File.Read(b)
+	if err == io.EOF {
+		// If this was the result of a zero-byte read, then
+		// it is possible that the read was due to a zero-size
+		// message. Since we are simulating CloseWrite with a
+		// zero-byte message, ensure that all future Read() calls
+		// also return EOF.
+		f.readEOF = true
+	} else if err == syscall.ERROR_MORE_DATA {
+		// ERROR_MORE_DATA indicates that the pipe's read mode is message mode
+		// and the message still has more bytes. Treat this as a success, since
+		// this package presents all named pipes as byte streams.
+		err = nil
+	}
+	return n, err
+}
+
+func (s pipeAddress) Network() string {
+	return "pipe"
+}
+
+func (s pipeAddress) String() string {
+	return string(s)
+}
+
+// tryDialPipe attempts to dial the pipe at `path` until `ctx` cancellation or timeout.
+func tryDialPipe(ctx context.Context, path *string, access uint32) (syscall.Handle, error) {
+	for {
+
+		select {
+		case <-ctx.Done():
+			return syscall.Handle(0), ctx.Err()
+		default:
+			h, err := createFile(*path, access, 0, nil, syscall.OPEN_EXISTING, syscall.FILE_FLAG_OVERLAPPED|cSECURITY_SQOS_PRESENT|cSECURITY_ANONYMOUS, 0)
+			if err == nil {
+				return h, nil
+			}
+			if err != cERROR_PIPE_BUSY {
+				return h, &os.PathError{Err: err, Op: "open", Path: *path}
+			}
+			// Wait 10 msec and try again. This is a rather simplistic
+			// view, as we always try each 10 milliseconds.
+			time.Sleep(10 * time.Millisecond)
+		}
+	}
+}
+
+// DialPipe connects to a named pipe by path, timing out if the connection
+// takes longer than the specified duration. If timeout is nil, then we use
+// a default timeout of 2 seconds.  (We do not use WaitNamedPipe.)
+func DialPipe(path string, timeout *time.Duration) (net.Conn, error) {
+	var absTimeout time.Time
+	if timeout != nil {
+		absTimeout = time.Now().Add(*timeout)
+	} else {
+		absTimeout = time.Now().Add(2 * time.Second)
+	}
+	ctx, _ := context.WithDeadline(context.Background(), absTimeout)
+	conn, err := DialPipeContext(ctx, path)
+	if err == context.DeadlineExceeded {
+		return nil, ErrTimeout
+	}
+	return conn, err
+}
+
+// DialPipeContext attempts to connect to a named pipe by `path` until `ctx`
+// cancellation or timeout.
+func DialPipeContext(ctx context.Context, path string) (net.Conn, error) {
+	return DialPipeAccess(ctx, path, syscall.GENERIC_READ|syscall.GENERIC_WRITE)
+}
+
+// DialPipeAccess attempts to connect to a named pipe by `path` with `access` until `ctx`
+// cancellation or timeout.
+func DialPipeAccess(ctx context.Context, path string, access uint32) (net.Conn, error) {
+	var err error
+	var h syscall.Handle
+	h, err = tryDialPipe(ctx, &path, access)
+	if err != nil {
+		return nil, err
+	}
+
+	var flags uint32
+	err = getNamedPipeInfo(h, &flags, nil, nil, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	f, err := makeWin32File(h)
+	if err != nil {
+		syscall.Close(h)
+		return nil, err
+	}
+
+	// If the pipe is in message mode, return a message byte pipe, which
+	// supports CloseWrite().
+	if flags&cPIPE_TYPE_MESSAGE != 0 {
+		return &win32MessageBytePipe{
+			win32Pipe: win32Pipe{win32File: f, path: path},
+		}, nil
+	}
+	return &win32Pipe{win32File: f, path: path}, nil
+}
+
+type acceptResponse struct {
+	f   *win32File
+	err error
+}
+
+type win32PipeListener struct {
+	firstHandle syscall.Handle
+	path        string
+	config      PipeConfig
+	acceptCh    chan (chan acceptResponse)
+	closeCh     chan int
+	doneCh      chan int
+}
+
+func makeServerPipeHandle(path string, sd []byte, c *PipeConfig, first bool) (syscall.Handle, error) {
+	path16, err := syscall.UTF16FromString(path)
+	if err != nil {
+		return 0, &os.PathError{Op: "open", Path: path, Err: err}
+	}
+
+	var oa objectAttributes
+	oa.Length = unsafe.Sizeof(oa)
+
+	var ntPath unicodeString
+	if err := rtlDosPathNameToNtPathName(&path16[0], &ntPath, 0, 0).Err(); err != nil {
+		return 0, &os.PathError{Op: "open", Path: path, Err: err}
+	}
+	defer localFree(ntPath.Buffer)
+	oa.ObjectName = &ntPath
+
+	// The security descriptor is only needed for the first pipe.
+	if first {
+		if sd != nil {
+			len := uint32(len(sd))
+			sdb := localAlloc(0, len)
+			defer localFree(sdb)
+			copy((*[0xffff]byte)(unsafe.Pointer(sdb))[:], sd)
+			oa.SecurityDescriptor = (*securityDescriptor)(unsafe.Pointer(sdb))
+		} else {
+			// Construct the default named pipe security descriptor.
+			var dacl uintptr
+			if err := rtlDefaultNpAcl(&dacl).Err(); err != nil {
+				return 0, fmt.Errorf("getting default named pipe ACL: %s", err)
+			}
+			defer localFree(dacl)
+
+			sdb := &securityDescriptor{
+				Revision: 1,
+				Control:  cSE_DACL_PRESENT,
+				Dacl:     dacl,
+			}
+			oa.SecurityDescriptor = sdb
+		}
+	}
+
+	typ := uint32(cFILE_PIPE_REJECT_REMOTE_CLIENTS)
+	if c.MessageMode {
+		typ |= cFILE_PIPE_MESSAGE_TYPE
+	}
+
+	disposition := uint32(cFILE_OPEN)
+	access := uint32(syscall.GENERIC_READ | syscall.GENERIC_WRITE | syscall.SYNCHRONIZE)
+	if first {
+		disposition = cFILE_CREATE
+		// By not asking for read or write access, the named pipe file system
+		// will put this pipe into an initially disconnected state, blocking
+		// client connections until the next call with first == false.
+		access = syscall.SYNCHRONIZE
+	}
+
+	timeout := int64(-50 * 10000) // 50ms
+
+	var (
+		h    syscall.Handle
+		iosb ioStatusBlock
+	)
+	err = ntCreateNamedPipeFile(&h, access, &oa, &iosb, syscall.FILE_SHARE_READ|syscall.FILE_SHARE_WRITE, disposition, 0, typ, 0, 0, 0xffffffff, uint32(c.InputBufferSize), uint32(c.OutputBufferSize), &timeout).Err()
+	if err != nil {
+		return 0, &os.PathError{Op: "open", Path: path, Err: err}
+	}
+
+	runtime.KeepAlive(ntPath)
+	return h, nil
+}
+
+func (l *win32PipeListener) makeServerPipe() (*win32File, error) {
+	h, err := makeServerPipeHandle(l.path, nil, &l.config, false)
+	if err != nil {
+		return nil, err
+	}
+	f, err := makeWin32File(h)
+	if err != nil {
+		syscall.Close(h)
+		return nil, err
+	}
+	return f, nil
+}
+
+func (l *win32PipeListener) makeConnectedServerPipe() (*win32File, error) {
+	p, err := l.makeServerPipe()
+	if err != nil {
+		return nil, err
+	}
+
+	// Wait for the client to connect.
+	ch := make(chan error)
+	go func(p *win32File) {
+		ch <- connectPipe(p)
+	}(p)
+
+	select {
+	case err = <-ch:
+		if err != nil {
+			p.Close()
+			p = nil
+		}
+	case <-l.closeCh:
+		// Abort the connect request by closing the handle.
+		p.Close()
+		p = nil
+		err = <-ch
+		if err == nil || err == ErrFileClosed {
+			err = ErrPipeListenerClosed
+		}
+	}
+	return p, err
+}
+
+func (l *win32PipeListener) listenerRoutine() {
+	closed := false
+	for !closed {
+		select {
+		case <-l.closeCh:
+			closed = true
+		case responseCh := <-l.acceptCh:
+			var (
+				p   *win32File
+				err error
+			)
+			for {
+				p, err = l.makeConnectedServerPipe()
+				// If the connection was immediately closed by the client, try
+				// again.
+				if err != cERROR_NO_DATA {
+					break
+				}
+			}
+			responseCh <- acceptResponse{p, err}
+			closed = err == ErrPipeListenerClosed
+		}
+	}
+	syscall.Close(l.firstHandle)
+	l.firstHandle = 0
+	// Notify Close() and Accept() callers that the handle has been closed.
+	close(l.doneCh)
+}
+
+// PipeConfig contain configuration for the pipe listener.
+type PipeConfig struct {
+	// SecurityDescriptor contains a Windows security descriptor in SDDL format.
+	SecurityDescriptor string
+
+	// MessageMode determines whether the pipe is in byte or message mode. In either
+	// case the pipe is read in byte mode by default. The only practical difference in
+	// this implementation is that CloseWrite() is only supported for message mode pipes;
+	// CloseWrite() is implemented as a zero-byte write, but zero-byte writes are only
+	// transferred to the reader (and returned as io.EOF in this implementation)
+	// when the pipe is in message mode.
+	MessageMode bool
+
+	// InputBufferSize specifies the size of the input buffer, in bytes.
+	InputBufferSize int32
+
+	// OutputBufferSize specifies the size of the output buffer, in bytes.
+	OutputBufferSize int32
+}
+
+// ListenPipe creates a listener on a Windows named pipe path, e.g. \\.\pipe\mypipe.
+// The pipe must not already exist.
+func ListenPipe(path string, c *PipeConfig) (net.Listener, error) {
+	var (
+		sd  []byte
+		err error
+	)
+	if c == nil {
+		c = &PipeConfig{}
+	}
+	if c.SecurityDescriptor != "" {
+		sd, err = SddlToSecurityDescriptor(c.SecurityDescriptor)
+		if err != nil {
+			return nil, err
+		}
+	}
+	h, err := makeServerPipeHandle(path, sd, c, true)
+	if err != nil {
+		return nil, err
+	}
+	l := &win32PipeListener{
+		firstHandle: h,
+		path:        path,
+		config:      *c,
+		acceptCh:    make(chan (chan acceptResponse)),
+		closeCh:     make(chan int),
+		doneCh:      make(chan int),
+	}
+	go l.listenerRoutine()
+	return l, nil
+}
+
+func connectPipe(p *win32File) error {
+	c, err := p.prepareIo()
+	if err != nil {
+		return err
+	}
+	defer p.wg.Done()
+
+	err = connectNamedPipe(p.handle, &c.o)
+	_, err = p.asyncIo(c, nil, 0, err)
+	if err != nil && err != cERROR_PIPE_CONNECTED {
+		return err
+	}
+	return nil
+}
+
+func (l *win32PipeListener) Accept() (net.Conn, error) {
+	ch := make(chan acceptResponse)
+	select {
+	case l.acceptCh <- ch:
+		response := <-ch
+		err := response.err
+		if err != nil {
+			return nil, err
+		}
+		if l.config.MessageMode {
+			return &win32MessageBytePipe{
+				win32Pipe: win32Pipe{win32File: response.f, path: l.path},
+			}, nil
+		}
+		return &win32Pipe{win32File: response.f, path: l.path}, nil
+	case <-l.doneCh:
+		return nil, ErrPipeListenerClosed
+	}
+}
+
+func (l *win32PipeListener) Close() error {
+	select {
+	case l.closeCh <- 1:
+		<-l.doneCh
+	case <-l.doneCh:
+	}
+	return nil
+}
+
+func (l *win32PipeListener) Addr() net.Addr {
+	return pipeAddress(l.path)
+}

vendor/github.com/Microsoft/go-winio/pkg/guid/guid.go

@@ -0,0 +1,228 @@
+// +build windows
+
+// Package guid provides a GUID type. The backing structure for a GUID is
+// identical to that used by the golang.org/x/sys/windows GUID type.
+// There are two main binary encodings used for a GUID, the big-endian encoding,
+// and the Windows (mixed-endian) encoding. See here for details:
+// https://en.wikipedia.org/wiki/Universally_unique_identifier#Encoding
+package guid
+
+import (
+	"crypto/rand"
+	"crypto/sha1"
+	"encoding"
+	"encoding/binary"
+	"fmt"
+	"strconv"
+)
+
+// Variant specifies which GUID variant (or "type") of the GUID. It determines
+// how the entirety of the rest of the GUID is interpreted.
+type Variant uint8
+
+// The variants specified by RFC 4122.
+const (
+	// VariantUnknown specifies a GUID variant which does not conform to one of
+	// the variant encodings specified in RFC 4122.
+	VariantUnknown Variant = iota
+	VariantNCS
+	VariantRFC4122
+	VariantMicrosoft
+	VariantFuture
+)
+
+// Version specifies how the bits in the GUID were generated. For instance, a
+// version 4 GUID is randomly generated, and a version 5 is generated from the
+// hash of an input string.
+type Version uint8
+
+var _ = (encoding.TextMarshaler)(GUID{})
+var _ = (encoding.TextUnmarshaler)(&GUID{})
+
+// NewV4 returns a new version 4 (pseudorandom) GUID, as defined by RFC 4122.
+func NewV4() (GUID, error) {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return GUID{}, err
+	}
+
+	g := FromArray(b)
+	g.setVersion(4) // Version 4 means randomly generated.
+	g.setVariant(VariantRFC4122)
+
+	return g, nil
+}
+
+// NewV5 returns a new version 5 (generated from a string via SHA-1 hashing)
+// GUID, as defined by RFC 4122. The RFC is unclear on the encoding of the name,
+// and the sample code treats it as a series of bytes, so we do the same here.
+//
+// Some implementations, such as those found on Windows, treat the name as a
+// big-endian UTF16 stream of bytes. If that is desired, the string can be
+// encoded as such before being passed to this function.
+func NewV5(namespace GUID, name []byte) (GUID, error) {
+	b := sha1.New()
+	namespaceBytes := namespace.ToArray()
+	b.Write(namespaceBytes[:])
+	b.Write(name)
+
+	a := [16]byte{}
+	copy(a[:], b.Sum(nil))
+
+	g := FromArray(a)
+	g.setVersion(5) // Version 5 means generated from a string.
+	g.setVariant(VariantRFC4122)
+
+	return g, nil
+}
+
+func fromArray(b [16]byte, order binary.ByteOrder) GUID {
+	var g GUID
+	g.Data1 = order.Uint32(b[0:4])
+	g.Data2 = order.Uint16(b[4:6])
+	g.Data3 = order.Uint16(b[6:8])
+	copy(g.Data4[:], b[8:16])
+	return g
+}
+
+func (g GUID) toArray(order binary.ByteOrder) [16]byte {
+	b := [16]byte{}
+	order.PutUint32(b[0:4], g.Data1)
+	order.PutUint16(b[4:6], g.Data2)
+	order.PutUint16(b[6:8], g.Data3)
+	copy(b[8:16], g.Data4[:])
+	return b
+}
+
+// FromArray constructs a GUID from a big-endian encoding array of 16 bytes.
+func FromArray(b [16]byte) GUID {
+	return fromArray(b, binary.BigEndian)
+}
+
+// ToArray returns an array of 16 bytes representing the GUID in big-endian
+// encoding.
+func (g GUID) ToArray() [16]byte {
+	return g.toArray(binary.BigEndian)
+}
+
+// FromWindowsArray constructs a GUID from a Windows encoding array of bytes.
+func FromWindowsArray(b [16]byte) GUID {
+	return fromArray(b, binary.LittleEndian)
+}
+
+// ToWindowsArray returns an array of 16 bytes representing the GUID in Windows
+// encoding.
+func (g GUID) ToWindowsArray() [16]byte {
+	return g.toArray(binary.LittleEndian)
+}
+
+func (g GUID) String() string {
+	return fmt.Sprintf(
+		"%08x-%04x-%04x-%04x-%012x",
+		g.Data1,
+		g.Data2,
+		g.Data3,
+		g.Data4[:2],
+		g.Data4[2:])
+}
+
+// FromString parses a string containing a GUID and returns the GUID. The only
+// format currently supported is the `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+// format.
+func FromString(s string) (GUID, error) {
+	if len(s) != 36 {
+		return GUID{}, fmt.Errorf("invalid GUID %q", s)
+	}
+	if s[8] != '-' || s[13] != '-' || s[18] != '-' || s[23] != '-' {
+		return GUID{}, fmt.Errorf("invalid GUID %q", s)
+	}
+
+	var g GUID
+
+	data1, err := strconv.ParseUint(s[0:8], 16, 32)
+	if err != nil {
+		return GUID{}, fmt.Errorf("invalid GUID %q", s)
+	}
+	g.Data1 = uint32(data1)
+
+	data2, err := strconv.ParseUint(s[9:13], 16, 16)
+	if err != nil {
+		return GUID{}, fmt.Errorf("invalid GUID %q", s)
+	}
+	g.Data2 = uint16(data2)
+
+	data3, err := strconv.ParseUint(s[14:18], 16, 16)
+	if err != nil {
+		return GUID{}, fmt.Errorf("invalid GUID %q", s)
+	}
+	g.Data3 = uint16(data3)
+
+	for i, x := range []int{19, 21, 24, 26, 28, 30, 32, 34} {
+		v, err := strconv.ParseUint(s[x:x+2], 16, 8)
+		if err != nil {
+			return GUID{}, fmt.Errorf("invalid GUID %q", s)
+		}
+		g.Data4[i] = uint8(v)
+	}
+
+	return g, nil
+}
+
+func (g *GUID) setVariant(v Variant) {
+	d := g.Data4[0]
+	switch v {
+	case VariantNCS:
+		d = (d & 0x7f)
+	case VariantRFC4122:
+		d = (d & 0x3f) | 0x80
+	case VariantMicrosoft:
+		d = (d & 0x1f) | 0xc0
+	case VariantFuture:
+		d = (d & 0x0f) | 0xe0
+	case VariantUnknown:
+		fallthrough
+	default:
+		panic(fmt.Sprintf("invalid variant: %d", v))
+	}
+	g.Data4[0] = d
+}
+
+// Variant returns the GUID variant, as defined in RFC 4122.
+func (g GUID) Variant() Variant {
+	b := g.Data4[0]
+	if b&0x80 == 0 {
+		return VariantNCS
+	} else if b&0xc0 == 0x80 {
+		return VariantRFC4122
+	} else if b&0xe0 == 0xc0 {
+		return VariantMicrosoft
+	} else if b&0xe0 == 0xe0 {
+		return VariantFuture
+	}
+	return VariantUnknown
+}
+
+func (g *GUID) setVersion(v Version) {
+	g.Data3 = (g.Data3 & 0x0fff) | (uint16(v) << 12)
+}
+
+// Version returns the GUID version, as defined in RFC 4122.
+func (g GUID) Version() Version {
+	return Version((g.Data3 & 0xF000) >> 12)
+}
+
+// MarshalText returns the textual representation of the GUID.
+func (g GUID) MarshalText() ([]byte, error) {
+	return []byte(g.String()), nil
+}
+
+// UnmarshalText takes the textual representation of a GUID, and unmarhals it
+// into this GUID.
+func (g *GUID) UnmarshalText(text []byte) error {
+	g2, err := FromString(string(text))
+	if err != nil {
+		return err
+	}
+	*g = g2
+	return nil
+}

vendor/github.com/Microsoft/go-winio/pkg/guid/guid_nonwindows.go

@@ -0,0 +1,15 @@
+// +build !windows
+
+package guid
+
+// GUID represents a GUID/UUID. It has the same structure as
+// golang.org/x/sys/windows.GUID so that it can be used with functions expecting
+// that type. It is defined as its own type as that is only available to builds
+// targeted at `windows`. The representation matches that used by native Windows
+// code.
+type GUID struct {
+	Data1 uint32
+	Data2 uint16
+	Data3 uint16
+	Data4 [8]byte
+}

vendor/github.com/Microsoft/go-winio/pkg/guid/guid_windows.go

@@ -0,0 +1,10 @@
+package guid
+
+import "golang.org/x/sys/windows"
+
+// GUID represents a GUID/UUID. It has the same structure as
+// golang.org/x/sys/windows.GUID so that it can be used with functions expecting
+// that type. It is defined as its own type so that stringification and
+// marshaling can be supported. The representation matches that used by native
+// Windows code.
+type GUID windows.GUID

vendor/github.com/Microsoft/go-winio/privilege.go

@@ -0,0 +1,203 @@
+// +build windows
+
+package winio
+
+import (
+	"bytes"
+	"encoding/binary"
+	"fmt"
+	"runtime"
+	"sync"
+	"syscall"
+	"unicode/utf16"
+
+	"golang.org/x/sys/windows"
+)
+
+//sys adjustTokenPrivileges(token windows.Token, releaseAll bool, input *byte, outputSize uint32, output *byte, requiredSize *uint32) (success bool, err error) [true] = advapi32.AdjustTokenPrivileges
+//sys impersonateSelf(level uint32) (err error) = advapi32.ImpersonateSelf
+//sys revertToSelf() (err error) = advapi32.RevertToSelf
+//sys openThreadToken(thread syscall.Handle, accessMask uint32, openAsSelf bool, token *windows.Token) (err error) = advapi32.OpenThreadToken
+//sys getCurrentThread() (h syscall.Handle) = GetCurrentThread
+//sys lookupPrivilegeValue(systemName string, name string, luid *uint64) (err error) = advapi32.LookupPrivilegeValueW
+//sys lookupPrivilegeName(systemName string, luid *uint64, buffer *uint16, size *uint32) (err error) = advapi32.LookupPrivilegeNameW
+//sys lookupPrivilegeDisplayName(systemName string, name *uint16, buffer *uint16, size *uint32, languageId *uint32) (err error) = advapi32.LookupPrivilegeDisplayNameW
+
+const (
+	SE_PRIVILEGE_ENABLED = 2
+
+	ERROR_NOT_ALL_ASSIGNED syscall.Errno = 1300
+
+	SeBackupPrivilege   = "SeBackupPrivilege"
+	SeRestorePrivilege  = "SeRestorePrivilege"
+	SeSecurityPrivilege = "SeSecurityPrivilege"
+)
+
+const (
+	securityAnonymous = iota
+	securityIdentification
+	securityImpersonation
+	securityDelegation
+)
+
+var (
+	privNames     = make(map[string]uint64)
+	privNameMutex sync.Mutex
+)
+
+// PrivilegeError represents an error enabling privileges.
+type PrivilegeError struct {
+	privileges []uint64
+}
+
+func (e *PrivilegeError) Error() string {
+	s := ""
+	if len(e.privileges) > 1 {
+		s = "Could not enable privileges "
+	} else {
+		s = "Could not enable privilege "
+	}
+	for i, p := range e.privileges {
+		if i != 0 {
+			s += ", "
+		}
+		s += `"`
+		s += getPrivilegeName(p)
+		s += `"`
+	}
+	return s
+}
+
+// RunWithPrivilege enables a single privilege for a function call.
+func RunWithPrivilege(name string, fn func() error) error {
+	return RunWithPrivileges([]string{name}, fn)
+}
+
+// RunWithPrivileges enables privileges for a function call.
+func RunWithPrivileges(names []string, fn func() error) error {
+	privileges, err := mapPrivileges(names)
+	if err != nil {
+		return err
+	}
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+	token, err := newThreadToken()
+	if err != nil {
+		return err
+	}
+	defer releaseThreadToken(token)
+	err = adjustPrivileges(token, privileges, SE_PRIVILEGE_ENABLED)
+	if err != nil {
+		return err
+	}
+	return fn()
+}
+
+func mapPrivileges(names []string) ([]uint64, error) {
+	var privileges []uint64
+	privNameMutex.Lock()
+	defer privNameMutex.Unlock()
+	for _, name := range names {
+		p, ok := privNames[name]
+		if !ok {
+			err := lookupPrivilegeValue("", name, &p)
+			if err != nil {
+				return nil, err
+			}
+			privNames[name] = p
+		}
+		privileges = append(privileges, p)
+	}
+	return privileges, nil
+}
+
+// EnableProcessPrivileges enables privileges globally for the process.
+func EnableProcessPrivileges(names []string) error {
+	return enableDisableProcessPrivilege(names, SE_PRIVILEGE_ENABLED)
+}
+
+// DisableProcessPrivileges disables privileges globally for the process.
+func DisableProcessPrivileges(names []string) error {
+	return enableDisableProcessPrivilege(names, 0)
+}
+
+func enableDisableProcessPrivilege(names []string, action uint32) error {
+	privileges, err := mapPrivileges(names)
+	if err != nil {
+		return err
+	}
+
+	p, _ := windows.GetCurrentProcess()
+	var token windows.Token
+	err = windows.OpenProcessToken(p, windows.TOKEN_ADJUST_PRIVILEGES|windows.TOKEN_QUERY, &token)
+	if err != nil {
+		return err
+	}
+
+	defer token.Close()
+	return adjustPrivileges(token, privileges, action)
+}
+
+func adjustPrivileges(token windows.Token, privileges []uint64, action uint32) error {
+	var b bytes.Buffer
+	binary.Write(&b, binary.LittleEndian, uint32(len(privileges)))
+	for _, p := range privileges {
+		binary.Write(&b, binary.LittleEndian, p)
+		binary.Write(&b, binary.LittleEndian, action)
+	}
+	prevState := make([]byte, b.Len())
+	reqSize := uint32(0)
+	success, err := adjustTokenPrivileges(token, false, &b.Bytes()[0], uint32(len(prevState)), &prevState[0], &reqSize)
+	if !success {
+		return err
+	}
+	if err == ERROR_NOT_ALL_ASSIGNED {
+		return &PrivilegeError{privileges}
+	}
+	return nil
+}
+
+func getPrivilegeName(luid uint64) string {
+	var nameBuffer [256]uint16
+	bufSize := uint32(len(nameBuffer))
+	err := lookupPrivilegeName("", &luid, &nameBuffer[0], &bufSize)
+	if err != nil {
+		return fmt.Sprintf("<unknown privilege %d>", luid)
+	}
+
+	var displayNameBuffer [256]uint16
+	displayBufSize := uint32(len(displayNameBuffer))
+	var langID uint32
+	err = lookupPrivilegeDisplayName("", &nameBuffer[0], &displayNameBuffer[0], &displayBufSize, &langID)
+	if err != nil {
+		return fmt.Sprintf("<unknown privilege %s>", string(utf16.Decode(nameBuffer[:bufSize])))
+	}
+
+	return string(utf16.Decode(displayNameBuffer[:displayBufSize]))
+}
+
+func newThreadToken() (windows.Token, error) {
+	err := impersonateSelf(securityImpersonation)
+	if err != nil {
+		return 0, err
+	}
+
+	var token windows.Token
+	err = openThreadToken(getCurrentThread(), syscall.TOKEN_ADJUST_PRIVILEGES|syscall.TOKEN_QUERY, false, &token)
+	if err != nil {
+		rerr := revertToSelf()
+		if rerr != nil {
+			panic(rerr)
+		}
+		return 0, err
+	}
+	return token, nil
+}
+
+func releaseThreadToken(h windows.Token) {
+	err := revertToSelf()
+	if err != nil {
+		panic(err)
+	}
+	h.Close()
+}