Merge pull request #2832 from embano1/issue-2830

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,19 +98,19 @@ Closes: #1234
 BREAKING: Add ctx to funcXYZ()
 EOF
 
-$ git push $USER issue-<number>
+git push $USER issue-<number>
 ```
 
 ### Stay in sync with Upstream
 
 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,25 +122,25 @@ 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
 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:

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`

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,21 +122,21 @@ 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.
 
     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`

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