babashka / neil

A CLI to add common aliases and features to deps.edn-based projects
MIT License
377 stars 27 forks source link

Improve helptext in toplevel `neil -h` and for subcommands #155

Closed teodorlu closed 1 year ago

teodorlu commented 1 year ago

Please answer the following questions and leave the below in as part of your PR.


Rationale: neil -h helptext is getting verbose. This PR moves the neil dep upgrade helptext into neil dep upgrade -h.

Summary:

  1. I think this change makes the helptext a bit easier to read / skim
  2. I still think the toplevel helptext is too verbose

Remaining work:

  1. I'd like to propose some helptext for neil dep versions, then consider merging.

New toplevel helptext output:

$ neil-dev -h
Usage: neil <subcommand> <options>

Most subcommands support the options:
  --alias      Override alias name.
  --deps-file  Override deps.edn file name.

Subcommands:

add
  dep    Alias for `neil dep add`.
  test   adds cognitect test runner to :test alias.
  build  adds tools.build build.clj file and :build alias.
  kaocha adds kaocha test runner to :kaocha alias.
  nrepl  adds nrepl server to :nrepl alias.

dep
  add: Adds --lib, a fully qualified symbol, to deps.edn :deps.
    Run `neil dep add --help` to see all options.

  search: Search Clojars for a string in any attribute of an artifact
    Run `neil dep search --help` to see all options.

  upgrade: Upgrade libs in the deps.edn file.
    Run `neil dep upgrade --help` to see all options.

  update: Alias for `upgrade`.

license
  list   Lists commonly-used licenses available to be added to project. Takes an optional search string to filter results.
  search Alias for `list`
  add    Writes license text to a file
    Options:
    --license The key of the license to use (e.g. epl-1.0, mit, unlicense). --license option name may be elided when license key is provided as first argument.
    --file    The file to write. Defaults to 'LICENSE'.

new
  Create a project using deps-new
    Run `neil new --help` to see all options.

version
  Commands for managing the :version key in the deps.edn project config.
    Run `neil version --help` to see all options.

test
  Run tests. Assumes `neil add test`. Run `neil test --help` to see all options.

New neil dep upgrade -h helptext:

$ neil-dev dep upgrade -h
Usage: neil dep upgrade [lib] [options]

  neil dep upgrade [options]            Upgrade all libraries
  neil dep upgrade LIB [options]        Upgrade a single library
  neil dep upgrade --lib LIB [options]  Upgrade a single library

Options:

  --lib                         Fully qualified library name.
  --dry-run                     dep upgrade only. Prevents updates to deps.edn.
  --alias      <alias>          Add to alias <alias>.
  --no-aliases                  Prevents updates to alias :extra-deps when upgrading.

Examples:

  neil dep upgrade                           ; upgrade all deps.
  neil dep upgrade --dry-run                 ; print deps that would be upgraded.
  neil dep upgrade --alias lint`             ; update only deps for the `lint` alias.
  neil dep upgrade :lib clj-kondo/clj-kondo  ; update a single dep.
teodorlu commented 1 year ago

I added helptext for neil dep versions (#108)

Toplevel:

$ neil-dev -h
...
dep
...
  versions: List available versions of a library (Clojars libraries only)
    Run `neil dep versions -h` to see all options.
$ neil-dev dep versions -h
Usage: neil dep versions LIB

List available versions of a Clojure dependency. Only supports Clojars.

  $ neil dep versions http-kit/http-kit
  :lib http-kit/http-kit :version 2.7.0-alpha1
  :lib http-kit/http-kit :version 2.7.0-SNAPSHOT
  :lib http-kit/http-kit :version 2.6.0
  :lib http-kit/http-kit :version 2.6.0-RC1
  :lib http-kit/http-kit :version 2.6.0-alpha1
  :lib http-kit/http-kit :version 2.5.3
  :lib http-kit/http-kit :version 2.5.3-SNAPSHOT
  :lib http-kit/http-kit :version 2.5.2
  :lib http-kit/http-kit :version 2.5.1
  :lib http-kit/http-kit :version 2.5.0