search

nikolassv / bartib

A simple timetracker for the command line. It saves a log of all tracked activities as a plaintext file and allows you to create flexible reports.
GNU General Public License v3.0
669 stars 35 forks source link

Add example of usage in -h #54

Closed bjornasm closed 3 months ago

bjornasm commented 4 months ago

Hi,

This is just a small request, but it would be great if there was an example of usage when you print the help information. Now you have:

> bartib -h    
bartib 1.1.0
Nikolas Schmidt-Voigt <nikolas.schmidt-voigt@posteo.de>
A simple timetracker

USAGE:
    bartib.exe [OPTIONS] <SUBCOMMAND>

FLAGS:
(...)

However it isn't specified how you actually start timetracking before you try f.ex bartib start and the following is printed:

>bartib start 
error: The following required arguments were not provided:
    --description <DESCRIPTION>
    --project <PROJECT>

USAGE:
    bartib.exe start [OPTIONS] --description <DESCRIPTION> --project <PROJECT>

It would be nice if bartib -h (and bartib without flags) could have that usage information as well, f.ex:

bartib 1.1.0
Nikolas Schmidt-Voigt <nikolas.schmidt-voigt@posteo.de>
A simple timetracker

USAGE:
    bartib.exe [OPTIONS] <SUBCOMMAND>
    Starting a project:
    bartib.exe start [OPTIONS] --description <DESCRIPTION> --project <PROJECT>

FLAGS:
(...)
RossBarnie commented 3 months ago

There's little we can do here that isn't repeating what's already been included in the README and in the docs as you describe them. I notice you omitted the SUBCOMMANDS section that does give a description of the start command but I realise it's buried under other subcommands. I propose we do something similar to what you've suggested but promote using the existing documentation, so the new output would be:

bartib 1.1.0
Nikolas Schmidt-Voigt <nikolas.schmidt-voigt@posteo.de>
A simple timetracker

USAGE:
    bartib.exe [OPTIONS] <SUBCOMMAND>

FLAGS:
(...)

SUBCOMMANDS:
(...)

To get help for a specific command, run `bartib [SUBCOMMAND] --help`
To get started, view the `start` help with `bartib start --help`

Would this help?

bjornasm commented 3 months ago

@RossBarnie - yes, that is perfect, by mentioning that there will be more info about each sub command by running bartib [SUBCOMMAND] --help the user will know where to find information about specific flags etc. I appreciate that it has to be somewhat layered to not overbloat bartib --help.