Repository: vmware/govmomi
Pull request #2832 (2022-04-26 11:57:08)

docs: Update documentation
## Description

- [x] Remove `$` from docs for easy copy and paste
- [x] Update installation instructions for recent `go` versions

Closes: #2830
Signed-off-by: Michael Gasch <mgasch@vmware.com>

## Type of change

Please mark options that are relevant:

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to
  not work as expected)
- [x] This change requires a documentation update
- [ ] Build related change

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide
instructions so we can reproduce. If applicable, please also list any relevant
details for your test configuration.

- [ ] Test Description 1
- [ ] Test Description 2

## Checklist:

- [ ] My code follows the CONTRIBUTION [guidelines](./../CONTRIBUTING.md) of
  this project
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged


Patch:
diff --git a/.github/workflows/govmomi-build.yaml b/.github/workflows/govmomi-build.yaml
index e6f00fad..b021852a 100644
--- a/.github/workflows/govmomi-build.yaml
+++ b/.github/workflows/govmomi-build.yaml
@@ -27,10 +27,6 @@ on:
   
   workflow_dispatch:
 
-concurrency:
-  group: govmomi-build-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
 jobs:
   artifacts:
     name: Build Snapshot Release (no upload)
@@ -54,9 +50,9 @@ jobs:
           path: |
             ~/.cache/go-build
             ~/go/pkg/mod
-          key: ${{ runner.os }}-go-1.18-${{ hashFiles('**/go.sum') }}
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
-            ${{ runner.os }}-go-1.18-
+            ${{ runner.os }}-go-
 
       - name: Create CHANGELOG
         env:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f19268b8..c6d69e54 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,18 +4,20 @@
 
 First, fork the repository on GitHub to your personal account.
 
-Note that `GOPATH` can be any directory, the example below uses `$HOME/govmomi`.
-Change `$USER` below to your Github username if they are not the same.
-
-```console
-$ export GOPATH=$HOME/govmomi
-$ go get github.com/vmware/govmomi
-
-$ cd $GOPATH/src/github.com/vmware/govmomi
-$ git config push.default nothing # anything to avoid pushing to vmware/govmomi by default
-$ git remote rename origin vmware
-$ git remote add $USER git@github.com:$USER/govmomi.git
-$ git fetch $USER
+Change `$USER` in the examples below to your Github username if they are not the
+same.
+
+```bash
+git clone https://github.com/vmware/govmomi.git && cd govmomi
+
+# prevent accidentally pushing to vmware/govmomi
+git config push.default nothing
+git remote rename origin vmware
+
+# add your fork
+git remote add $USER git@github.com:$USER/govmomi.git
+
+git fetch -av
 ```
 
 ## Contribution Flow
@@ -38,40 +40,40 @@ and **supported prefixes**, e.g. `govc: <message>`.
 
 ### Example 1 - Fix a Bug in `govmomi`
 
-```console
-$ git checkout -b issue-<number> vmware/master
-$ git add <files>
-$ git commit -m "fix: ..." -m "Closes: #<issue-number>"
-$ git push $USER issue-<number>
+```bash
+git checkout -b issue-<number> vmware/master
+git add <files>
+git commit -m "fix: ..." -m "Closes: #<issue-number>"
+git push $USER issue-<number>
 ```
 
 ### Example 2 - Add a new (non-breaking) API to `govmomi`
 
-```console
-$ git checkout -b issue-<number> vmware/master
-$ git add <files>
-$ git commit -m "Add API ..." -m "Closes: #<issue-number>"
-$ git push $USER issue-<number>
+```bash
+git checkout -b issue-<number> vmware/master
+git add <files>
+git commit -m "Add API ..." -m "Closes: #<issue-number>"
+git push $USER issue-<number>
 ```
 
 ### Example 3 - Add a Feature to `govc`
 
-```console
-$ git checkout -b issue-<number> vmware/master
-$ git add <files>
-$ git commit -m "govc: Add feature ..." -m "Closes: #<issue-number>"
-$ git push $USER issue-<number>
+```bash
+git checkout -b issue-<number> vmware/master
+git add <files>
+git commit -m "govc: Add feature ..." -m "Closes: #<issue-number>"
+git push $USER issue-<number>
 ```
 **Note**:  
 To register the new `govc` command package, add a blank `_` import to `govmomi/govc/main.go`.
 
 ### Example 4 - Fix a Bug in `vcsim`
 
-```console
-$ git checkout -b issue-<number> vmware/master
-$ git add <files>
-$ git commit -m "vcsim: Fix ..." -m "Closes: #<issue-number>"
-$ git push $USER issue-<number>
+```bash
+git checkout -b issue-<number> vmware/master
+git add <files>
+git commit -m "vcsim: Fix ..." -m "Closes: #<issue-number>"
+git push $USER issue-<number>
 ```
 
 ### Example 5 - Document Breaking (API) Changes
@@ -84,10 +86,10 @@ The text after `BREAKING:` is used in the corresponding highlighted section.
 Thus these details should be stated at the body of the commit message.
 Multi-line strings are supported.
 
-```console
-$ git checkout -b issue-<number> vmware/master
-$ git add <files>
-$ cat << EOF | git commit -F -
+```bash
+git checkout -b issue-<number> vmware/master
+git add <files>
+cat << EOF | git commit -F -
 Add ctx to funcXYZ
 
 This commit introduces context.Context to function XYZ
@@ -96,7 +98,7 @@ Closes: #1234
 BREAKING: Add ctx to funcXYZ()
 EOF
 
-$ git push $USER issue-<number>
+git push $USER issue-<number>
 ```
 
 ### Stay in sync with Upstream
@@ -104,11 +106,11 @@ $ git push $USER issue-<number>
 When your branch gets out of sync with the vmware/master branch, use the
 following to update (rebase):
 
-```console
-$ git checkout issue-<number>
-$ git fetch -a
-$ git rebase vmware/master
-$ git push --force-with-lease $USER issue-<number>
+```bash
+git checkout issue-<number>
+git fetch -a
+git rebase vmware/master
+git push --force-with-lease $USER issue-<number>
 ```
 
 ### Updating Pull Requests
@@ -120,13 +122,13 @@ is to assist the reviewer(s) to easily detect and review the recent changes.
 In case of small PRs, it's ok to squash and force-push (see further below)
 directly instead.
 
-```console
+```bash
 # incorporate review feedback
-$ git add .
+git add .
 
 # create a fixup commit which will be merged into your (original) <commit>
-$ git commit --fixup <commit>
-$ git push $USER issue-<number>
+git commit --fixup <commit>
+git push $USER issue-<number>
 ```
 
 Be sure to add a comment to the PR indicating your new changes are ready to
@@ -134,11 +136,11 @@ review, as Github does not generate a notification when you git push.
 
 Once the review is complete, squash and push your final commit(s):
 
-```console
+```bash
 # squash all commits into one
 # --autosquash will automatically detect and merge fixup commits
-$ git rebase -i --autosquash vmware/master
-$ git push --force-with-lease $USER issue-<number>
+git rebase -i --autosquash vmware/master
+git push --force-with-lease $USER issue-<number>
 ```
 
 ### Code Style
@@ -165,8 +167,8 @@ section in the `CHANGELOG`.
 The following example creates a commit referencing the `issue: 1234` and puts
 the commit message in the `govc` `CHANGELOG` section:
 
-```console
-$ git commit -s -m "govc: Add CLI command X" -m "Closes: #1234"
+```bash
+git commit -s -m "govc: Add CLI command X" -m "Closes: #1234"
 ```
 
 Currently the following prefixes are used:
diff --git a/README.md b/README.md
index 7440c627..96588f02 100644
--- a/README.md
+++ b/README.md
@@ -39,8 +39,8 @@ See [godoc.org][godoc] for documentation.
 
 ### govmomi (Package)
 
-```console
-$ go get -u github.com/vmware/govmomi
+```bash
+go get -u github.com/vmware/govmomi
 ```
 
 ### Binaries and Docker Images for `govc` and `vcsim`
diff --git a/govc/README.md b/govc/README.md
index 19f96605..d78138d1 100644
--- a/govc/README.md
+++ b/govc/README.md
@@ -16,22 +16,22 @@ You can find prebuilt `govc` binaries on the [releases page](https://github.com/
 
 You can download and install a binary locally like this:
 
-```console
+```bash
 # extract govc binary to /usr/local/bin
 # note: the "tar" command must run with root permissions
-$ curl -L -o - "https://github.com/vmware/govmomi/releases/latest/download/govc_$(uname -s)_$(uname -m).tar.gz" | tar -C /usr/local/bin -xvzf - govc
+curl -L -o - "https://github.com/vmware/govmomi/releases/latest/download/govc_$(uname -s)_$(uname -m).tar.gz" | tar -C /usr/local/bin -xvzf - govc
 ```
 
 ### Source
 
-#### Install via `go get`
+#### Install via `go install`
 
 To build `govc` from source, first install the [Go
 toolchain](https://golang.org/dl/). You can then install the latest `govc` from
 Github using:
 
-```console
-$ go get -u github.com/vmware/govmomi/govc
+```bash
+go install github.com/vmware/govmomi/govc@latest
 ```
 
 **Note:** `govmomi` and its binaries use [Go
@@ -46,8 +46,8 @@ source.
 If you've made local modifications to the repository at
 `$GOPATH/src/github.com/vmware/govmomi`, you can install using:
 
-```console
-$ go install github.com/vmware/govmomi/govc
+```bash
+go install github.com/vmware/govmomi/govc
 ```
 
 #### Install via `goreleaser`
@@ -61,18 +61,18 @@ defined in [.goreleaser.yaml](./../.goreleaser.yml) and automatically set as
 Install `goreleaser` as per the installation
 [instructions](https://goreleaser.com/install/), then:
 
-```console
-$ git clone https://github.com/vmware/govmomi.git
-$ cd govmomi
+```bash
+git clone https://github.com/vmware/govmomi.git
+cd govmomi
 
 # pick a tag (>=v0.25.0)
-$ RELEASE=v0.25.0
+RELEASE=v0.25.0
 
-$ git checkout ${RELEASE}
+git checkout ${RELEASE}
 
 # build for the host OS/ARCH, otherwise omit --single-target
 # binaries are placed in respective subdirectories in ./dist/
-$ goreleaser build --rm-dist --single-target
+goreleaser build --rm-dist --single-target
 ```
 
 ## Usage
@@ -122,10 +122,10 @@ using environment variables. The following environment variables are used by
 
 * `GOVC_TLS_CA_CERTS`: Override system root certificate authorities.
 
-    ```console
-    $ export GOVC_TLS_CA_CERTS=~/.govc_ca.crt
+    ```bash
+    export GOVC_TLS_CA_CERTS=~/.govc_ca.crt
     # Use path separator to specify multiple files:
-    $ export GOVC_TLS_CA_CERTS=~/ca-certificates/bar.crt:~/ca-certificates/foo.crt
+    export GOVC_TLS_CA_CERTS=~/ca-certificates/bar.crt:~/ca-certificates/foo.crt
     ```
 
 * `GOVC_TLS_KNOWN_HOSTS`: File(s) for thumbprint based certificate verification.
@@ -133,10 +133,10 @@ using environment variables. The following environment variables are used by
     Thumbprint based verification can be used in addition to or as an alternative to
     `GOVC_TLS_CA_CERTS` for self-signed certificates.  Example:
 
-    ```console
-    $ export GOVC_TLS_KNOWN_HOSTS=~/.govc_known_hosts
-    $ govc about.cert -u host -k -thumbprint | tee -a $GOVC_TLS_KNOWN_HOSTS
-    $ govc about -u user:pass@host
+    ```bash
+    export GOVC_TLS_KNOWN_HOSTS=~/.govc_known_hosts
+    govc about.cert -u host -k -thumbprint | tee -a $GOVC_TLS_KNOWN_HOSTS
+    govc about -u user:pass@host
     ```
 
 * `GOVC_TLS_HANDSHAKE_TIMEOUT`: Limits the time spent performing the TLS handshake.
@@ -193,7 +193,7 @@ The`-debug` flag traces vSphere API calls similar to the `-trace` flag, but save
 When the `-debug` flag is specified, the default behavior is to put the output in `~/.govmomi/debug/<run timestamp>`.
 In that directory will be four (4) files per API call.
 
-```
+```bash
 1-0001.req.headers #headers from the request sent to the API
 1-0001.req.xml #body content from request sent to the API
 1-0001.res.headers #headers from the response from the API
@@ -229,21 +229,22 @@ by setting the debug path to a dash: `export GOVC_DEBUG_PATH=-`
 
 If you're using environment variables to set `GOVC_URL`, verify the values are set as expected:
 
-```console
-$ govc env
+```bash
+govc env
 ```
 
 ### Connection issues
 
 Check your proxy settings:
 
-```console
-$ env | grep -i https_proxy
+```bash
+env | grep -i https_proxy
 ```
 
-Test connection using curl:
-```console
-$ curl --verbose -k -X POST https://x.x.x.x/sdk
+Test connection using `curl`:
+
+```bash
+curl --verbose -k -X POST https://x.x.x.x/sdk
 ```
 
 ### MSYS2 (Windows)
@@ -258,8 +259,8 @@ cookies, resulting in a `NotAuthenticated` error. For example, running `govc`
 directly against the vCenter vpxd endpoint at `http://127.0.0.1:8085`. Set the
 environment variable `GOVMOMI_INSECURE_COOKIES=true` to workaround this:
 
-```console
-$ GOVMOMI_INSECURE_COOKIES=true govc ls -u http://user:pass@127.0.0.1:8085
+```bash
+GOVMOMI_INSECURE_COOKIES=true govc ls -u http://user:pass@127.0.0.1:8085
 ```
 
 ## Examples
@@ -290,8 +291,8 @@ When new `govc` commands or flags are added, the PATCH version will be
 incremented.  This enables you to require a minimum version from within a
 script, for example:
 
-```console
-$ govc version -require 0.24
+```bash
+govc version -require 0.24
 ```
 
 ## Projects using `govc`
diff --git a/vapi/library/finder/README.md b/vapi/library/finder/README.md
index 12d243f8..1e2b9003 100644
--- a/vapi/library/finder/README.md
+++ b/vapi/library/finder/README.md
@@ -38,7 +38,8 @@ While a system that has few content library objects benefits from wildcard searc
 ## `govc library.ls`
 
 ### Listing all the objects in the content library
-```shell
+
+```console
 $ govc library.ls '*/*/'
 /ISOs/CentOS-7-x86_64-Minimal-1804/CentOS-7-x86_64-Minimal-1804.iso
 /ISOs/CoreOS Production/coreos_production_iso_image.iso
@@ -72,7 +73,8 @@ $ govc library.ls '*/*/'
 ## `govc library.info`
 
 ### Getting the info for all the objects in the content library
-```shell
+
+```console
 $ govc library.info '*/*/'
 Name:       CentOS-7-x86_64-Minimal-1804.iso
   Path:     /ISOs/CentOS-7-x86_64-Minimal-1804/CentOS-7-x86_64-Minimal-1804.iso
diff --git a/vcsim/README.md b/vcsim/README.md
index 03e9587c..3d616a37 100644
--- a/vcsim/README.md
+++ b/vcsim/README.md
@@ -15,23 +15,23 @@ You can find prebuilt `vcsim` binaries on the [releases page](https://github.com
 
 You can download and install a binary locally like this:
 
-``` console
+```bash
 # extract vcsim binary to /usr/local/bin
 # note: the "tar" command must run with root permissions
-$ curl -L -o - https://github.com/vmware/govmomi/releases/latest/download/vcsim_$(uname -s)_$(uname -m).tar.gz | tar -C /usr/local/bin -xvzf - vcsim
+curl -L -o - https://github.com/vmware/govmomi/releases/latest/download/vcsim_$(uname -s)_$(uname -m).tar.gz | tar -C /usr/local/bin -xvzf - vcsim
 ```
 
 ### Source
 
-#### Install via `go get`
+#### Install via `go install`
 
 To build `vcsim` from source, first install the [Go
 toolchain](https://golang.org/dl/). You can then install the latest `vcsim` from
 Github using:
 
-```console
-$ go get -u github.com/vmware/govmomi/vcsim
-$ $GOPATH/bin/vcsim -h
+```bash
+go install github.com/vmware/govmomi/vcsim@latest
+$GOPATH/bin/vcsim -h
 ```
 
 **Note:** `govmomi` and its binaries use [Go
@@ -54,18 +54,18 @@ defined in [.goreleaser.yaml](./../.goreleaser.yml) and automatically set as
 Install `goreleaser` as per the installation
 [instructions](https://goreleaser.com/install/), then:
 
-```console
-$ git clone https://github.com/vmware/govmomi.git
-$ cd govmomi
+```bash
+git clone https://github.com/vmware/govmomi.git
+cd govmomi
 
 # pick a tag (>=v0.25.0)
-$ RELEASE=v0.25.0
+RELEASE=v0.25.0
 
-$ git checkout ${RELEASE}
+git checkout ${RELEASE}
 
 # build for the host OS/ARCH, otherwise omit --single-target
 # binaries are placed in respective subdirectories in ./dist/
-$ goreleaser build --rm-dist --single-target
+goreleaser build --rm-dist --single-target
 ```
 
 ## Usage
@@ -156,8 +156,8 @@ The following examples illustrate how **vcsim** flags can be used to change the
 generated inventory.  Each example assumes **GOVC_URL** is set to vcsim's default
 [listen address](#listen-address):
 
-```console
-$ export GOVC_URL=https://user:pass@127.0.0.1:8989
+```bash
+export GOVC_URL=https://user:pass@127.0.0.1:8989
 ```
 
 ### Default vCenter inventory
@@ -381,8 +381,8 @@ implement any method documented in the [VMware vSphere API Reference][apiref].
 
 To see the list of supported methods:
 
-```console
-$ curl -sk https://user:pass@127.0.0.1:8989/about
+```bash
+curl -sk https://user:pass@127.0.0.1:8989/about
 ```
 
 [apiref]:https://code.vmware.com/apis/196/vsphere
@@ -392,28 +392,28 @@ $ curl -sk https://user:pass@127.0.0.1:8989/about
 The default vcsim listen address is `127.0.0.1:8989`.  Use the `-l` flag to
 listen on another address:
 
-```console
-$ vcsim -l 10.118.69.224:8989 # specific address
+```bash
+vcsim -l 10.118.69.224:8989 # specific address
 
-$ vcsim -l :8989 # any address
+vcsim -l :8989 # any address
 ```
 
 When given a port value of `0`, an unused port will be chosen.  You can then
 source the GOVC_URL from another process, for example:
 
-```console
-$ govc_sim_env=$TMPDIR/vcsim-$(uuidgen)
+```bash
+govc_sim_env=$TMPDIR/vcsim-$(uuidgen)
 
-$ mkfifo $govc_sim_env
+mkfifo $govc_sim_env
 
-$ vcsim -l 127.0.0.1:0 -E $govc_sim_env &
+vcsim -l 127.0.0.1:0 -E $govc_sim_env &
 
-$ eval "$(cat $govc_sim_env)"
+eval "$(cat $govc_sim_env)"
 
 # ... run tests ...
 
-$ kill $GOVC_SIM_PID
-$ rm -f $govc_sim_env
+kill $GOVC_SIM_PID
+rm -f $govc_sim_env
 ```
 
 Tests written in Go can also use the [simulator package](https://godoc.org/github.com/vmware/govmomi/simulator)


Test patch:
diff --git a/.github/workflows/govmomi-go-tests.yaml b/.github/workflows/govmomi-go-tests.yaml
index 52de2cbb..1cc36926 100644
--- a/.github/workflows/govmomi-go-tests.yaml
+++ b/.github/workflows/govmomi-go-tests.yaml
@@ -28,7 +28,6 @@ jobs:
       matrix:
         go-version: ["1.17", "1.18"]
         platform: ["ubuntu-20.04"]
-      fail-fast: false
 
     runs-on: ${{ matrix.platform }}
     timeout-minutes: 10
@@ -49,9 +48,9 @@ jobs:
           path: |
             ~/.cache/go-build
             ~/go/pkg/mod
-          key: ${{ runner.os }}-go-${{ matrix.go-version }}-${{ hashFiles('**/go.sum') }}
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
-            ${{ runner.os }}-go-${{ matrix.go-version }}-
+            ${{ runner.os }}-go-
 
       - name: Run Tests
         env:
diff --git a/.github/workflows/govmomi-govc-tests.yaml b/.github/workflows/govmomi-govc-tests.yaml
index 7bbc856d..bdc80a95 100644
--- a/.github/workflows/govmomi-govc-tests.yaml
+++ b/.github/workflows/govmomi-govc-tests.yaml
@@ -21,21 +21,16 @@ on:
   pull_request:
     branches: ["main", "master"]
 
-concurrency:
-  group: govmomi-govc-tests-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
 jobs:
   govc-tests:
     name: Run govc Tests
     strategy:
-      fail-fast: false
       matrix:
         go-version: ["1.17", "1.18"]
         platform: ["ubuntu-20.04"]
         cmd: ["govc-test"]
         experimental: [false]
-        timeout: [20]
+        timeout: [10]
         include:
           - go-version: "1.18"
             platform: "ubuntu-20.04"
@@ -68,9 +63,9 @@ jobs:
           path: |
             ~/.cache/go-build
             ~/go/pkg/mod
-          key: ${{ runner.os }}-go-${{ matrix.go-version }}-${{ hashFiles('**/go.sum') }}
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
-            ${{ runner.os }}-go-${{ matrix.go-version }}-
+            ${{ runner.os }}-go-
 
       - name: Run ${{ matrix.cmd }}
         run: |
@@ -102,9 +97,9 @@ jobs:
           path: |
             ~/.cache/go-build
             ~/go/pkg/mod
-          key: ${{ runner.os }}-go-${{ matrix.go-version }}-${{ hashFiles('**/go.sum') }}
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
-            ${{ runner.os }}-go-${{ matrix.go-version }}-
+            ${{ runner.os }}-go-
 
       - name: Run "make doc"
         run: |