chore: Tidy up 1Password docs

jackjen · Mar 24, 2022 · b0ea806 · b0ea806
1 parent 10a0de4
commit b0ea806
Show file tree

Hide file tree

Showing 5 changed files with 54 additions and 83 deletions.
diff --git a/assets/chezmoi.io/docs/reference/templates/functions/onepassword.md b/assets/chezmoi.io/docs/reference/templates/functions/onepassword.md
@@ -2,14 +2,15 @@
 
 `onepassword` returns structured data from [1Password](https://1password.com/)
 using the [1Password
-CLI](https://support.1password.com/command-line-getting-started/) (`op`). *uuid*
-is passed to `op item get $UUID --format json` and the output from `op`. The
-output from `op` is cached so calling `onepassword` multiple times with the same
-*uuid* will only invoke `op` once. If the optional *vault-uuid* is supplied, it
-will be passed along to the `op item get` call, which can significantly improve
-performance. If the optional *account-name* is supplied, it will be passed along
-to the `op item get` call, which will help it look in the right account, in case
-you have multiple accounts (e.g., personal and work accounts).
+CLI](https://support.1password.com/command-line-getting-started/) (`op`).
+*uuid* is passed to `op item get $UUID --format json` and the output from `op`
+is parsed as JSON. The output from `op` is cached so calling `onepassword`
+multiple times with the same *uuid* will only invoke `op` once. If the optional
+*vault-uuid* is supplied, it will be passed along to the `op item get` call,
+which can significantly improve performance. If the optional *account-name* is
+supplied, it will be passed along to the `op item get` call, which will help it
+look in the right account, in case you have multiple accounts (e.g., personal
+and work accounts).
 
 If there is no valid session in the environment, by default you will be
 interactively prompted to sign in.
@@ -27,11 +28,13 @@ interactively prompted to sign in.
 
     ```
     {{ range (onepassword "$UUID").fields -}}
-    {{- if and (eq .label "password") (eq .purpose "PASSWORD") }}{{ .value }}{{ end -}}
-    {{- end }}
+    {{   if and (eq .label "password") (eq .purpose "PASSWORD") -}}
+    {{     .value -}}
+    {{   end -}}
+    {{ end }}
     ```
 
-    ??? info
+    !!! info
 
         For 1Password CLI 1.x.
 
@@ -54,7 +57,7 @@ interactively prompted to sign in.
     the other functions. Testing the output of this function is recommended:
 
     ```console
-    chezmoi execute-template "{{- onepassword \"$UUID\" | toJson -}}" | jq .
+    $ chezmoi execute-template "{{ onepassword \"$UUID\" | toJson }}" | jq .
     ```
 
 !!! warning
@@ -65,13 +68,6 @@ interactively prompted to sign in.
     using *account-name*, it is recommended that you use the *account-uuid*.
     This can be found using `op account list`.
 
-    This issue does not exist when using biometric authentication and 1Password
+    This issue does not occur when using biometric authentication and 1Password
     8, or if you allow chezmoi to prompt you for 1Password authentication
     (`1password.prompt = true`).
-
-!!! info
-
-    In earlier versions of chezmoi, if *vault-uuid* or *account-name* were
-    empty strings, they would be added to the resulting `op` command-line
-    (`--vault ''`). This causes errors in 1Password CLI 2.0, so those arguments
-    will no longer be added.
diff --git a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDetailsFields.md b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDetailsFields.md
@@ -13,7 +13,7 @@ times with the same *uuid* will only invoke `op` once. If the optional
 *vault-uuid* is supplied, it will be passed along to the `op get` call, which
 can significantly improve performance. If the optional *account-name* is
 supplied, it will be passed along to the `op get` call, which will help it look
-in the right account, in case you have multiple accounts (e.g., personal and
+in the right account, in case you have multiple accounts (e.g. personal and
 work accounts).
 
 !!! example
@@ -81,7 +81,7 @@ work accounts).
     function is recommended:
 
     ```console
-    chezmoi execute-template "{{- onepasswordDetailsFields \"$UUID\" | toJson -}}" | jq .
+    $ chezmoi execute-template "{{ onepasswordDetailsFields \"$UUID\" | toJson }}" | jq .
     ```
 
 !!! warning
@@ -92,13 +92,6 @@ work accounts).
     using *account-name*, it is recommended that you use the *account-uuid*.
     This can be found using `op account list`.
 
-    This issue does not exist when using biometric authentication and 1Password
+    This issue does not occur when using biometric authentication and 1Password
     8, or if you allow chezmoi to prompt you for 1Password authentication
     (`1password.prompt = true`).
-
-!!! info
-
-    In earlier versions of chezmoi, if *vault-uuid* or *account-name* were
-    empty strings, they would be added to the resulting `op` command-line
-    (`--vault ''`). This causes errors in 1Password CLI 2.0, so those arguments
-    will no longer be added.
diff --git a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDocument.md b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDocument.md
@@ -2,16 +2,16 @@
 
 `onepasswordDocument` returns a document from
 [1Password](https://1password.com/) using the [1Password
-CLI](https://support.1password.com/command-line-getting-started/) (`op`). *uuid*
-is passed to `op get document $UUID` and the output from `op` is returned. The
-output from `op` is cached so calling `onepasswordDocument` multiple times with
-the same *uuid* will only invoke `op` once. If the optional *vault-uuid* is
-supplied, it will be passed along to the `op get` call, which can significantly
-improve performance. If the optional *account-name* is supplied, it will be
-passed along to the `op get` call, which will help it look in the right account,
-in case you have multiple accounts (e.g., personal and work accounts). If there
-is no valid session in the environment, by default you will be interactively
-prompted to sign in.
+CLI](https://support.1password.com/command-line-getting-started/) (`op`).
+*uuid* is passed to `op get document $UUID` and the output from `op` is
+returned. The output from `op` is cached so calling `onepasswordDocument`
+multiple times with the same *uuid* will only invoke `op` once. If the optional
+*vault-uuid* is supplied, it will be passed along to the `op get` call, which
+can significantly improve performance. If the optional *account-name* is
+supplied, it will be passed along to the `op get` call, which will help it look
+in the right account, in case you have multiple accounts (e.g., personal and
+work accounts). If there is no valid session in the environment, by default you
+will be interactively prompted to sign in.
 
 !!! example
 
@@ -31,13 +31,6 @@ prompted to sign in.
     recommended that you use the *account-uuid*. This can be found using `op
     account list`.
 
-    This issue does not exist when using biometric authentication and 1Password
+    This issue does not occur when using biometric authentication and 1Password
     8, or if you allow chezmoi to prompt you for 1Password authentication
     (`1password.prompt = true`).
-
-!!! info
-
-    In earlier versions of chezmoi, if *vault-uuid* or *account-name* were
-    empty strings, they would be added to the resulting `op` command-line
-    (`--vault ''`). This causes errors in 1Password CLI 2.0, so those arguments
-    will no longer be added.
diff --git a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordItemFields.md b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordItemFields.md
@@ -1,8 +1,8 @@
-# `onepasswordItemFields` _uuid_ [_vault-uuid_ [*account-name*]]
+# `onepasswordItemFields` *uuid* [*vault-uuid* [*account-name*]]
 
 `onepasswordItemFields` returns structured data from
 [1Password](https://1password.com/) using the [1Password
-CLI](https://support.1password.com/command-line-getting-started/) (`op`). _uuid_
+CLI](https://support.1password.com/command-line-getting-started/) (`op`). *uuid*
 is passed to `op item get $UUID --format json`, the output from `op` is parsed
 as JSON, and each element of `details.sections` are iterated over and any
 `fields` are returned as a map indexed by each field's `n`.
@@ -26,7 +26,7 @@ interactively prompted to sign in.
     $ op item get abcdefghijklmnopqrstuvwxyz --fields exampleLabel
     ```
 
-    ??? info
+    !!! info
 
         For 1Password CLI 1.x.
 
@@ -85,7 +85,7 @@ interactively prompted to sign in.
     }
     ```
 
-    ??? info
+    !!! info
 
         For 1Password CLI 1.x, the output is this:
 
@@ -139,7 +139,7 @@ interactively prompted to sign in.
     this function is recommended:
 
     ```console
-    chezmoi execute-template "{{- onepasswordItemFields \"$UUID\" | toJson -}}" | jq .
+    $ chezmoi execute-template "{{ onepasswordItemFields \"$UUID\" | toJson }}" | jq .
     ```
 
 !!! warning
@@ -150,13 +150,6 @@ interactively prompted to sign in.
     using *account-name*, it is recommended that you use the *account-uuid*.
     This can be found using `op account list`.
 
-    This issue does not exist when using biometric authentication and 1Password
+    This issue does not occur when using biometric authentication and 1Password
     8, or if you allow chezmoi to prompt you for 1Password authentication
     (`1password.prompt = true`).
-
-!!! info
-
-    In earlier versions of chezmoi, if *vault-uuid* or *account-name* were
-    empty strings, they would be added to the resulting `op` command-line
-    (`--vault ''`). This causes errors in 1Password CLI 2.0, so those arguments
-    will no longer be added.
diff --git a/assets/chezmoi.io/docs/user-guide/password-managers/1password.md b/assets/chezmoi.io/docs/user-guide/password-managers/1password.md
@@ -6,22 +6,24 @@ expose data as a template function.
 
 !!! note
 
-    [1Password CLI 2.0](https://developer.1password.com/) has been released.
+    The[1Password CLI 2.0](https://developer.1password.com/) has been released.
     Examples will be shown using the changed details for this version and
     examples for 1Password CLI 1.x will follow.
 
 Log in and get a session using:
 
 ```console
-# For 1Password 2.x. Neither step is necessary with biometric authentication.
 $ op account add --address $SUBDOMAIN.1password.com --email $EMAIL
 $ eval $(op signin --account $SUBDOMAIN)
 ```
 
-??? info
+This is not necessary if you are using biometric authentication.
+
+!!! info
+
+    For 1Password CLI 1.x, use:
 
     ```console
-    # For 1Password 1.x
     $ eval $(op signin $SUBDOMAIN.1password.com $EMAIL)
     ```
 
@@ -80,11 +82,13 @@ or:
 
 ```
 {{ range (onepassword "$UUID").fields -}}
-{{- if and (eq .label "password") (eq .purpose "PASSWORD") }}{{ .value }}{{ end -}}
-{{- end }}
+{{   if and (eq .label "password") (eq .purpose "PASSWORD") -}}
+{{     .value -}}
+{{   end -}}
+{{ end }}
 ```
 
-??? info
+!!! info
 
     1Password CLI 1.x returns a simpler structure:
 
@@ -134,10 +138,10 @@ allows the fields to be queried by key:
 ```
 
 Additional fields may be obtained with `onePasswordItemFields`; not all objects
-in 1Password have item fields, so it is worth testing before using:
+in 1Password have item fields. This can be tested with:
 
 ```console
-chezmoi execute-template "{{- onepasswordItemFields \"$UUID\" | toJson -}}" | jq .
+$ chezmoi execute-template "{{ onepasswordItemFields \"$UUID\" | toJson }}" | jq .
 ```
 
 Documents can be retrieved with:
@@ -153,15 +157,15 @@ Documents can be retrieved with:
     substitution. This removes any trailing newline added by your editor when
     saving the template.
 
-## 1Password sign-in prompt
+## Sign-in prompt
 
 chezmoi will verify the availability and validity of a session token in the
 current environment. If it is missing or expired, you will be interactively
 prompted to sign-in again.
 
 In the past chezmoi used to simply exit with an error when no valid session was
-available. If you'd like to restore that behavior, set the following option in
-your configuration file:
+available. If you'd like to restore this behavior, set the the
+`onepassword.prompt` configuration variable to `false`, for example:
 
 ```toml title="~/.config/chezmoi/chezmoi.toml"
 [onepassword]
@@ -171,13 +175,5 @@ your configuration file:
 !!! danger
 
     Do not use the prompt on shared machines. A session token verified or
-    acquired interactively will be passed to the 1Password CLI through a command
-    line parameter, which is visible to other users of the same system.
-
-!!! info
-
-    If you're using [1Password CLI
-    2.0](https://developer.1password.com/docs/cli/), then the structure of the
-    data returned by the `onepassword`, `onepasswordDetailsFields`, and
-    `onePasswordItemFiles` template functions is different and templates will
-    need to be updated.
+    acquired interactively will be passed to the 1Password CLI through a
+    command line parameter, which is visible to other users of the same system.