| @@ -727,10 +727,9 @@ terminal, and follows these rules so every noun reads the same way. |
| 727 | |
727 | |
| 728 | - A list command prints one row per item, tab-separated, no header. |
728 | - A list command prints one row per item, tab-separated, no header. |
| 729 | Columns run identifier, state, then description; a trailing column |
729 | Columns run identifier, state, then description; a trailing column |
| 730 | may carry a word (=due 2027-01-01=, =via team=). The =gitbay= CLI pads |
730 | may carry a word (=due 2027-01-01=, =via team=). Piped, a timestamp in |
| 731 | the tabs into aligned columns when stdout is a terminal and leaves |
731 | a row is RFC3339 to the second, UTC. Under =--json= nothing is |
| 732 | them as tabs when piped, so =cut -f= sees the same bytes stock ssh |
732 | touched. |
| 733 | prints. Under =--json= nothing is touched. |
| |
| 734 | - An empty list prints nothing on stdout and =nothing to list= on |
733 | - An empty list prints nothing on stdout and =nothing to list= on |
| 735 | stderr. |
734 | stderr. |
| 736 | - A mutation prints one line: verb, object, identifier |
735 | - A mutation prints one line: verb, object, identifier |
| @@ -748,6 +747,43 @@ terminal, and follows these rules so every noun reads the same way. |
| 748 | something to them (a key, a member, a label on an issue), =set= for |
747 | something to them (a key, a member, a label on an issue), =set= for |
| 749 | a value, =revoke= for a credential, =show= and =list= for reads. |
748 | a value, =revoke= for a credential, =show= and =list= for reads. |
| 750 | |
749 | |
| |
750 | ** At a terminal |
| |
751 | |
| |
752 | The =gitbay= CLI sends a leading =--term=<cols>[,color]= argument on |
| |
753 | the SSH command line when stdout is a terminal (OpenSSH's multiplexed |
| |
754 | sessions, which the CLI uses, do not forward a session's =SetEnv=). |
| |
755 | The server strips =--term=<v>= wherever it appears in the argument |
| |
756 | list. The server then prints: |
| |
757 | |
| |
758 | - lists under a header, padded, fitted to the width (the title or |
| |
759 | description column is cut with =…= first), states in colour, ages as |
| |
760 | =2h ago=, and the next page as a command on stderr (piped output |
| |
761 | keeps a =next\t<cursor>= row instead); |
| |
762 | - =show= views with a title line, aligned fields, the body rendered |
| |
763 | from markdown or org, one line per event, and comments under a rule; |
| |
764 | a sub-table (labels, revisions, and the like) carries a section label |
| |
765 | line in both terminal and piped output; timestamps as |
| |
766 | =2026-09-23 23:26 UTC=. =wiki show= piped prints the page source |
| |
767 | verbatim; the rendered page is terminal-only; |
| |
768 | - help with flag descriptions, defaults, and examples; =gitbay --help= |
| |
769 | groups commands under WORK, REPOSITORIES, YOU and INSTANCE; |
| |
770 | =help --json= adds =flags= and =examples=. |
| |
771 | |
| |
772 | =NO_COLOR=, =TERM=dumb= and =--no-color= drop the colour. =show=, |
| |
773 | =diff= and =log= at a terminal go through =$GITBAY_PAGER=, else |
| |
774 | =$PAGER=, else =less= (with =LESS=FRX= when =LESS= is unset); an empty |
| |
775 | =GITBAY_PAGER= turns paging off. Paging never applies to =--follow=, |
| |
776 | =--json=, or piped output. |
| |
777 | |
| |
778 | Stock ssh without the CLI's multiplexing gets the plain output unless |
| |
779 | it passes the same leading argument or sets the environment variable |
| |
780 | sshd is told to accept: |
| |
781 | |
| |
782 | #+begin_src sh |
| |
783 | ssh git@gitbay.org --term=120,color issue list krz/gitbay |
| |
784 | ssh -o SetEnv=GITBAY_TERM=120,color git@gitbay.org issue list krz/gitbay |
| |
785 | #+end_src |
| |
786 | |
| 751 | * Scripting |
787 | * Scripting |
| 752 | |
788 | |
| 753 | Every read command takes =--json= and emits one envelope: |
789 | Every read command takes =--json= and emits one envelope: |