diff options
| author | EuAndreh <eu@euandre.org> | 2025-05-07 07:02:57 -0300 |
|---|---|---|
| committer | EuAndreh <eu@euandre.org> | 2025-05-07 07:16:33 -0300 |
| commit | d3cb41376ac0be31ed2b6649dd8d6b42674ebeaf (patch) | |
| tree | df7eeb84a91114b6624a0f0fe7c1b11fa7e5ae1f /doc | |
| parent | tests/{cli-opts,integration}.sh: Add test implementations (diff) | |
| download | uuid-d3cb41376ac0be31ed2b6649dd8d6b42674ebeaf.tar.gz uuid-d3cb41376ac0be31ed2b6649dd8d6b42674ebeaf.tar.xz | |
Support UUIDv7, with -vN for choosing
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/uuid.en.1.adoc | 42 |
1 files changed, 38 insertions, 4 deletions
diff --git a/doc/uuid.en.1.adoc b/doc/uuid.en.1.adoc index 6366acb..dc6bc3e 100644 --- a/doc/uuid.en.1.adoc +++ b/doc/uuid.en.1.adoc @@ -4,12 +4,13 @@ == NAME -uuid - generate or validate a UUIDv4 +uuid - generate a UUID version 4 or 7, or validate a UUID string. == SYNOPSYS +*uuid* [-v (4|7)] *uuid* [_STRING_] @@ -17,16 +18,27 @@ uuid - generate or validate a UUIDv4 == EXAMPLES -=== Print a UUID on the terminal +=== Print a (version 4) UUID on the terminal +[source,sh] .... $ uuid d3891787-c952-af17-d697-0df3b85981e1 .... +=== Print a verson 7 UUID on the terminal + +[source,sh] +.... +$ uuid -v 7 +d3891787-c952-af17-d697-0df3b85981e1 +.... + + === Create a new UUID as part of a path +[source,sh] .... dir="$PWD"/"$(uuid)"/data .... @@ -34,6 +46,7 @@ dir="$PWD"/"$(uuid)"/data === Validate a given UUID +[source,sh] .... ID="$(basename -- "$directory")" if ! uuid "$ID"; then @@ -50,6 +63,17 @@ The *uuid* utility generates a new UUID when no _STRING_ is given and write it to _stdout_. If a _STRING_ is given, *uuid* validates it and exits, and produces no output. +The *-v* option allows for choosing which type of UUID to be emitted, either +version 4 ("the random one") or version 7 ("the sortable one"). When omitted, +version 4 is chosen as default. + + + +== OPTIONS + +*-v NUMBER*:: Choose the UUID version *NUMBER* to be generated. Supported +values are 4 (the default) and 7. + == OPERANDS @@ -75,12 +99,14 @@ Not used. The UUIDv4 format is made of byte blocks encoded as hexadecimals, using a <hyphen-minus>('`-`') as the block separator: +[source,sh] .... XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX .... An example output is: +[source,sh] .... cb46d0c0-b2aa-4a6c-a119-8deace2544a2 .... @@ -88,7 +114,15 @@ cb46d0c0-b2aa-4a6c-a119-8deace2544a2 === STDERR -Not used. +Errors on UUID validation are sent to the standard error. For instance: + +[source,sh] +.... +$ uuid not-a-uuid-123 1>/dev/null +uuid: str isn't of the correct length +.... + +When valid, validation emits nothing and exits with 0. === INPUT FILES @@ -111,7 +145,7 @@ None. == CONFORMING TO -The v4 UUID defined in *RFC 9562*. +The versions 4 and 7 of the UUID defined in *RFC 9562*. |