wdx doc

Manage docs: a project’s text, kept by wdx outside its repository.

A doc belongs to a project and is there for every person and agent as soon as it is written. Every change of its content is a new revision, made on the revision it was read at: get a copy with doc get --out, change it, and write it back with doc update --base. Its status says whether it is agreed on: wip, review, approved or rejected; changing its content makes it wip.

Its folder, such as /hub/initial, is only where TIDE shows it, / for the top: a folder given is cleaned (whitespace dropped, lowercased, one / between its parts and at its start) and then has a-z, 0-9, _, - and / only. Names stay unique within a project whatever the folder.

Command	What it does
`wdx doc create`	Create a doc, from a file or empty
`wdx doc get`	Print a doc’s content, or write it to a file to change
`wdx doc history`	List a doc’s revisions
`wdx doc list`	List a project’s docs
`wdx doc remove`	Delete a doc and all its revisions
`wdx doc rename`	Rename a doc
`wdx doc set`	Change a doc’s folder, status or labels
`wdx doc sync-to-git`	Write a project’s docs, read-only, into a directory of its repository
`wdx doc update`	Write a doc’s content as a new revision

wdx doc create

Create a doc, from a file or empty.

wdx doc create [--project-id <id> | --project-name <name>] [--name <name>] [--path <file> | --path -] [--folder <folder>] [--format <ext>] [--labels <a,b>] [--status <status>] [flags]

Its content is the file --path names, stdin with --path -, or nothing. The name is the file’s without its extension unless --name is given, and is required without a file; names have letters, numbers, _ and - only, and are unique within a project whatever their case. The format, the extension its copies get, is the file’s, else md. Labels have lowercase letters, numbers, _ and - only. Content is UTF-8 text of at most 2 MiB.

A name the project has is refused: changing a doc’s content is doc update.

Flags

Flag	Default	Description
`--folder <folder>`		folder TIDE shows it in, such as /hub/initial (default: /, the top)
`--format <extension>`		extension of its copies, such as md or txt (default: the file’s, else md)
`--labels <labels>`	`[]`	labels to give it, comma-separated
`--name <name>`		name of the doc (default: the file’s, without its extension)
`--path <file>`		file to take the content from, - for stdin (default: empty)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--status <status>`		status to create it in: wip, review, approved or rejected (default: wip)
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --project-id or --project-name

Examples

# Add a file of the project you are in as a doc
wdx doc create --path docs/auth.md

# Name it, label it and pick the project
wdx doc create --project-name app --path notes.md --name auth-rfc --labels auth,rfc

# In a folder
wdx doc create --path docs/auth.md --folder /hub/initial

# From stdin, as JSON
wdx doc create --name auth-rfc --path - --status review --json

Output

The doc, at revision 1. With --json: {“result”: “created”, “doc”: {…}}

With --json, result is one of: created.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_argument`	1	an argument is empty or malformed
`invalid_name`	1	the name is not allowed
`name_taken`	1	something else has this name
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

With --node, also: code_not_set_up, code_wrong, connection_lost, daemon_unavailable, hub_unreachable, hub_version_unsupported, node_key_mismatch, node_not_found, node_offline, node_version_unsupported, not_logged_in, remote_access_off, remote_not_for_agents, route_not_allowed, session_closed, session_required, too_many_streams.

wdx doc get

Print a doc’s content, or write it to a file to change.

wdx doc get (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--revision <n>] [--out <file> [--overwrite]] [flags]

The latest revision unless --revision is given, printed byte for byte, as cat does. With --out it is written to a file of yours to edit, then given back with doc update --base and the revision it was read at; a file there is replaced only with --overwrite.

Flags

Flag	Default	Description
`--id <id>`		id of the doc
`--name <name>`		name of the doc (case-insensitive)
`--out <file>`		file to write it to, read-write, instead of printing it
`--overwrite`		with `--out`, replace the file if there is one
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--revision <revision>`	`0`	the revision to get (default: the latest)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Print a doc of the project you are in
wdx doc get --name auth-rfc

# Write it to a file to change
wdx doc get --name auth-rfc --out auth-rfc.md

# Get it again after it changed
wdx doc get --name auth-rfc --out auth-rfc.md --overwrite

# An earlier revision, as JSON
wdx doc get --id doc-1a2b3c4d --revision 3 --json

Output

The content alone; with --out, the revision written and where. With --json: {“doc”: {…}, “revision”: …, “content”: “…”}, without content with --out

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`path_exists`	1	something is already at the path, as the directory to clone into
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx doc history

List a doc’s revisions.

wdx doc history (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [flags]

Every revision is kept until the doc is removed; doc get --revision reads one.

Flags

Flag	Default	Description
`--id <id>`		id of the doc
`--name <name>`		name of the doc (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# The revisions of a doc of the project you are in
wdx doc history --name auth-rfc

# By id, as JSON
wdx doc history --id doc-1a2b3c4d --json

Output

The revisions, latest first, without content. With --json: {“revisions”: […]}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx doc list

List a project’s docs.

wdx doc list [--project-id <id> | --project-name <name>] [--labels <a,b>] [--status <status>] [flags]

Without a project flag, the docs of the project the working directory is in. With --labels, only those that have every one of them.

Flags

Flag	Default	Description
`--labels <labels>`	`[]`	labels a doc must all have, comma-separated
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--status <status>`		the status a doc must be in
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --project-id or --project-name

Examples

# The docs of the project you are in
wdx doc list

# The approved docs labeled auth, as JSON
wdx doc list --project-name app --labels auth --status approved --json

Output

The docs by folder, then name, without content; an empty list when there are none. With --json: {“docs”: […]}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_argument`	1	an argument is empty or malformed
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx doc remove

Delete a doc and all its revisions.

wdx doc remove (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--yes] [flags]

You are asked first, as nothing brings it back; --yes answers in advance, and with --json, or without a terminal, it is required.

Flags

Flag	Default	Description
`--id <id>`		id of the doc
`--name <name>`		name of the doc (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--yes`		remove it without asking
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name
with --json: one of --yes

Examples

# Remove a doc of the project you are in
wdx doc remove --name auth-rfc

# From a script
wdx doc remove --id doc-1a2b3c4d --yes --json

Output

The removed doc, as it was before. With --json: {“result”: “removed”, “doc”: {…}}

With --json, result is one of: removed.

Errors

Code	Exit	When
`cancelled`	1	the question was answered no
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx doc rename

Rename a doc.

wdx doc rename (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] --new-name <name> [flags]

Its id, content, revisions and status stay as they are; changing only the case of its name is a rename.

Flags

Flag	Default	Description
`--id <id>`		id of the doc
`--name <name>`		name of the doc (case-insensitive)
`--new-name <name>`		the doc’s new name
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--new-name is required
exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Rename a doc of the project you are in
wdx doc rename --name auth-rfc --new-name auth-design

# By id, as JSON
wdx doc rename --id doc-1a2b3c4d --new-name auth-design --json

Output

The doc’s name before and now. With --json: {“result”: “updated”, “doc”: {…}}

With --json, result is one of: updated or unchanged.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_name`	1	the name is not allowed
`name_taken`	1	something else has this name
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx doc set

Change a doc’s folder, status or labels.

wdx doc set (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--folder <folder>] [--status <status>] [--add-labels <a,b>] [--remove-labels <a,b>] [flags]

Its content and revision stay as they are, and no base is needed. Removing a label it does not have is not an error.

Flags

Flag	Default	Description
`--add-labels <labels>`	`[]`	labels to add, comma-separated
`--folder <folder>`		folder to move it to, such as /hub/initial; / is the top
`--id <id>`		id of the doc
`--name <name>`		name of the doc (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--remove-labels <labels>`	`[]`	labels to remove, comma-separated
`--status <status>`		status to give it: wip, review, approved or rejected
`--node <name>`		run the command on the node of this name, another of your account, through a session

at least one of --folder, --status, --add-labels or --remove-labels
exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Approve a doc of the project you are in
wdx doc set --name auth-rfc --status approved

# Change its labels, as JSON
wdx doc set --id doc-1a2b3c4d --add-labels auth --remove-labels draft --json

# Move it to a folder
wdx doc set --name auth-rfc --folder /hub/initial

Output

The doc’s status, folder and labels now. With --json: {“result”: “updated”, “doc”: {…}}

With --json, result is one of: updated or unchanged.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_argument`	1	an argument is empty or malformed
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx doc sync-to-git

Write a project’s docs, read-only, into a directory of its repository.

wdx doc sync-to-git [--project-id <id> | --project-name <name>] --path <dir> [flags]

--path is relative to the project’s main checkout, wherever this runs, and is created when missing. Each doc’s latest revision is written as <name>.<format>; a file of that name that wdx did not write is left as it is. Files wdx wrote there of docs that are gone are removed, and only those: .wdx-docs lists what it wrote. Nothing is staged or committed. The setting docs.git_path has the daemon do this on every change.

Flags

Flag	Default	Description
`--path <dir>`		dir to write into, relative to the project’s main checkout
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--path is required
at most one of --project-id or --project-name

Examples

# Write the docs of the project you are in
wdx doc sync-to-git --path docs/wdx

# Of another project, as JSON
wdx doc sync-to-git --project-name app --path docs/wdx --json

Output

How many docs were written and where, and the files removed or skipped. With --json: {“result”: “synced”, “path”: “…”, “written”: […], “removed”: […], “skipped”: […]}

With --json, result is one of: synced.

Errors

Code	Exit	When
`checkout_missing`	1	none of the project’s checkouts is left on disk
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_path`	1	the path cannot be used
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx doc update

Write a doc’s content as a new revision.

wdx doc update (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] --path <file> --base <n> [flags]

--base is the revision the change was made on, as doc get printed it. If the doc has a newer revision, nothing is written: get it again, apply the change to it and update with the new base, so that no change is lost. A new revision makes the doc wip, whatever it was; content equal to the latest makes none and changes nothing.

Flags

Flag	Default	Description
`--base <revision>`	`0`	the revision the change was made on
`--id <id>`		id of the doc
`--name <name>`		name of the doc (case-insensitive)
`--path <file>`		file holding the new content, - for stdin
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--base is required
--path is required
exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Write back a changed copy
wdx doc update --name auth-rfc --path auth-rfc.md --base 4

# From stdin, as JSON
wdx doc update --id doc-1a2b3c4d --path - --base 4 --json

Output

The doc’s revision now. With --json: {“result”: “updated”, “doc”: {…}, “previous_status”: …}

With --json, result is one of: updated or unchanged.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`doc_changed`	1	the doc has a newer revision than the base given
`invalid_argument`	1	an argument is empty or malformed
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git