git-bug icon indicating copy to clipboard operation
git-bug copied to clipboard

Standard output of each CLI command should align with tenet #2 of the Unix philosophy

Open smoyer64 opened this issue 2 years ago • 1 comments

This tenet is stated as:

Expect the output of every program to become the input to another, as yet unknown, program. Don't clutter output with extraneous information. Avoid stringently columnar or binary input formats. Don't insist on interactive input.

This issue can includes four tasks:

  1. Make sure all output from packages other than commands is sent to StdErr. A perfect example of the correct way to inform a human user than an action has completed can be found at: https://github.com/MichaelMure/git-bug/blob/bc5f618eba812859bf87ce2c31b278bd518d4555/cache/repo_cache.go#L194.
  2. Make sure that all output from the commands package is properly split between StdErr and StdOut so that a human reader sees the full context of what has occurred but a program processing the output of the command is presented only with data that's easy for a machine to process. A great example of how this should be done can be found at: https://github.com/MichaelMure/git-bug/blob/bc5f618eba812859bf87ce2c31b278bd518d4555/commands/user_create.go#L73
  3. Add minimal tests for all CLI commands to verify the output text is correct.
  4. Make sure that all CLI commands that return errors also return a non-zero exit code. If a command is executed successfully, it should return a zero exit code.

smoyer64 avatar Jul 15 '22 00:07 smoyer64

Make sure all output from packages other than commands is sent to StdErr.

I would go even further than that, no package from the core (cache and below layers) should write on the console, unless extreme cases. This is because those messages should be relayed to and rendered by each of the UI in their own way (cli, tui, webui ...). Of course that doesn't apply if the core itself crash before that.

MichaelMure avatar Jul 15 '22 09:07 MichaelMure