hackage-cli: CLI tool for Hackage

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

With hackage-cli you can manage .cabal files, e.g. (bulk-)upload revised variants.


[Skip to Readme]

Properties

Versions 0.0.3.4, 0.0.3.6, 0.1.0.0, 0.1.0.1
Change log CHANGELOG.md
Dependencies aeson (>=1.2.4.0 && <2.1), base (>=4.10.0.0 && <4.16), bytestring (>=0.10.4.0 && <0.12), Cabal (>=3.4.1.0 && <3.5), containers (>=0.5.0.0 && <0.7), deepseq (>=1.4.0.0 && <1.5), directory (>=1.2.0.1 && <1.3 || >=1.3.0.0 && <1.4), filepath (>=1.4.0.0 && <1.5), hackage-cli, http-io-streams (>=0.1.0.0 && <0.2), io-streams (>=1.5.0.1 && <1.6), microlens (>=0.4.8.3 && <4.13), microlens-mtl (>=0.1.11.1 && <0.3), microlens-th (>=0.4.1.3 && <0.5), mtl (>=2.2.2 && <2.4), netrc (>=0.2.0.0 && <0.3), optparse-applicative (>=0.14 && <0.18), pretty (>=1.1.2 && <1.2), process-extras (>=0.7.4 && <0.8), semigroups (>=0.18.3 && <0.21), stringsearch (>=0.3.6 && <0.4), tagsoup (>=0.14 && <0.15), tar (>=0.5 && <0.6), text (>=1.2 && <2.1), time (>=1.5.0.1 && <1.13), unordered-containers (>=0.2.7 && <0.3), zlib (>=0.6.1 && <0.7) [details]
License GPL-3.0-or-later
Author Herbert Valerio Riedel
Maintainer Andreas Abel
Category Development
Home page https://github.com/hackage-trustees/hackage-cli
Bug tracker https://github.com/hackage-trustees/hackage-cli/issues
Source repo head: git clone https://github.com/hackage-trustees/hackage-cli.git
Uploaded by AndreasAbel at 2022-02-22T13:49:01Z

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for hackage-cli-0.0.3.4

[back to package description]

hackage-cli

A command-line tool to manage package metadata revisions on Hackage.

Caveat: this is a developer tool and work-in-progress. Check known bugs at the issue tracker.

Command-line reference

hackage-cli - CLI tool for Hackage

Usage: hackage-cli [--version] [--verbose] [--hostname HOSTNAME] COMMAND

Available options:
  -h,--help                Show this help text
  --version                output version information and exit
  --verbose                enable verbose output
  --hostname HOSTNAME      Hackage hostname (default: "hackage.haskell.org")

Available commands:
  pull-cabal               download .cabal files for a package
  push-cabal               upload revised .cabal files
  sync-cabal               upadate/sync local .cabal file with latest revision
                           on Hackage
  push-candidate           upload package candidate(s)
  list-versions            list versions for a package
  check-revision           validate revision
  index-sha256sum          generate sha256sum-format file
  add-bound                add bound to the library section of a package. .cabal
                           file is edited in place

Each command has a sub-`--help` text. Hackage credentials are expected to be
stored in an `${HOME}/.netrc`-entry for the respective Hackage hostname. E.g.
"machine hackage.haskell.org login MyUserName password TrustNo1". All
interactions with Hackage occur TLS-encrypted via the HTTPS protocol.

(Section created 2015-04-26, last updated 2018-03-21.)

How to: bulk revision

Suppose that all versions starting with 1.2.3 of the package pkg-x on hackage need the additional bound < 4.5.6 on their dependency pkg-y, typically to prevent compilation attempts with pkg-y-4.5.6 and up that will fail.

With hackage-cli this can be done in a typical workflow that consists of

  1. downloading the .cabal files,
  2. adding bounds (with hackage-cli), or making other revisions (manually),
  3. re-uploading the modified .cabal files.

We walk through a typical workflow:

  1. Download the relevant pkg-x.cabal files to a new temporary directory:

    $ cd $(mktemp)
    $ hackage-cli pull-cabal pkg-x '>= 1.2.3'
    
  2. Adding bound pkg-y < 4.5.6 to all of them:

    $ hackage-cli add-bound pkg-y '< 4.5.6' *.cabal
    

    This will write a new line

      build-depends: pkg-y < 4.5.6
    

    to the library section of each of the .cabal files. There must be exactly one library section, otherwise hackage-cli will crash or produce a garbage result.

    If this bound does not further constrain the existing version range for pkg-y, it will not be added unless --force is used. (E.g., one of the cabal files could already have a bound pkg-y < 3.0.0 or so---this file will remain unchanged.)

    You can of course add more bounds using add-bound or make further manual changes to .cabal files.

  3. Review the changes via a trial upload:

    $ hackage-cli push-cabal --incr-rev *.cabal
    

    (The flag --incr-rev will increment the x-revision field by 1 during the upload. Existing revisions cannot be overwritten.)

    During (trial) upload you will see for each .cabal file a summary of what will be changed. Hackage might reject your revision, if it does not match the criteria of what it thinks is legal. Note that the legality check of the Hackage server is neither complete nor sound, so some legal revisions might be rejected, and some illegal ones accepted. You bear the responsibility for correct revisions yourself.

  4. Upload!

    $ hackage-cli push-cabal --incr-rev --publish *.cabal
    

    Adding the flag --publish will actually commit the revisions to Hackage.

(Section created 2022-02-21.)

License

(Section created 2022-02-21.)