diff options
| author | EuAndreh <eu@euandre.org> | 2025-05-09 05:21:33 -0300 |
|---|---|---|
| committer | EuAndreh <eu@euandre.org> | 2025-05-09 10:27:21 -0300 |
| commit | b90a8152cb5d0731a670a36e396c07c1b00de58c (patch) | |
| tree | 23418b4dfac0ad8fdd94816c6c8de50d0dbcedb8 /doc/uuid.eo.1.adoc | |
| parent | Support UUIDv7, with -vN for choosing (diff) | |
| download | uuid-b90a8152cb5d0731a670a36e396c07c1b00de58c.tar.gz uuid-b90a8152cb5d0731a670a36e396c07c1b00de58c.tar.xz | |
doc/: Add uuid.en.{0,3,7.{CHANGELOG,README,TODOs,recipes,tutorial,why}}.adoc
Diffstat (limited to 'doc/uuid.eo.1.adoc')
| -rw-r--r-- | doc/uuid.eo.1.adoc | 40 |
1 files changed, 35 insertions, 5 deletions
diff --git a/doc/uuid.eo.1.adoc b/doc/uuid.eo.1.adoc index a0d507b..e64c665 100644 --- a/doc/uuid.eo.1.adoc +++ b/doc/uuid.eo.1.adoc @@ -4,29 +4,40 @@ == NAME -uuid - generate or validate a UUIDv4 +uuid - generate a UUID version 4 or 7, or validate a UUID string. == SYNOPSYS -*uuid* [_STRING_] +*uuid* [-v (4|7)] *uuid* [_STRING_] == 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 +45,7 @@ dir="$PWD"/"$(uuid)"/data === Validate a given UUID +[source, sh] .... ID="$(basename -- "$directory")" if ! uuid "$ID"; then @@ -48,6 +60,14 @@ fi 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 @@ -71,12 +91,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 .... @@ -84,7 +106,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 @@ -107,7 +137,7 @@ None. == CONFORMING TO -The v4 UUID defined in *RFC 9562*. +The versions 4 and 7 of the UUID defined in *RFC 9562*. |