Commit 0e343a88e5
Verified · cmc
Layout: unified · split
.gitbay/wiki/Users.org +28
| @@ -656,6 +656,34 @@ someone else. | |||
| 656 | You are never mailed about your own actions, and only verified primary | 656 | You are never mailed about your own actions, and only verified primary |
| 657 | addresses receive anything. Delivery retries on relay failure. | 657 | addresses receive anything. Delivery retries on relay failure. |
| 658 | 658 | ||
| 659 | * Output rules | ||
| 660 | |||
| 661 | =--json= is the contract; the plain output is for a person at a | ||
| 662 | terminal, and follows these rules so every noun reads the same way. | ||
| 663 | |||
| 664 | - A list command prints one row per item, tab-separated, no header. | ||
| 665 | Columns run identifier, state, then description; a trailing column | ||
| 666 | may carry a word (=due 2027-01-01=, =via team=). The =gitbay= CLI pads | ||
| 667 | the tabs into aligned columns when stdout is a terminal and leaves | ||
| 668 | them as tabs when piped, so =cut -f= sees the same bytes stock ssh | ||
| 669 | prints. Under =--json= nothing is touched. | ||
| 670 | - An empty list prints nothing on stdout and one line on stderr saying | ||
| 671 | what was empty (=no open issues in krz/gitbay=). | ||
| 672 | - A mutation prints one line: verb, object, identifier | ||
| 673 | (=created krz/gitbay#7=). A second line appears only for something | ||
| 674 | to copy: a URL, a token shown once. | ||
| 675 | - A bad invocation prints =usage:= and the command's registered usage, | ||
| 676 | the same text =help <noun>= shows. Exit 2. | ||
| 677 | - A refusal says who may and what to do instead: =only admins of acme | ||
| 678 | can manage teams; ask one to add you=. Exit 4. A thing that does not | ||
| 679 | exist, or that you may not know exists, is exit 3. | ||
| 680 | - stdout is the result; stderr is everything else: progress, a note | ||
| 681 | that output was truncated, errors. | ||
| 682 | - Verbs: =create= and =delete= for things with their own identity | ||
| 683 | (repository, issue, release, team), =add= and =remove= for attaching | ||
| 684 | something to them (a key, a member, a label on an issue), =set= for | ||
| 685 | a value, =revoke= for a credential, =show= and =list= for reads. | ||
| 686 | |||
| 659 | * Scripting | 687 | * Scripting |
| 660 | 688 | ||
| 661 | Every read command takes =--json= and emits one envelope: | 689 | Every read command takes =--json= and emits one envelope: |