Hackage :: [Package]

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.6, 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.0.2
Change log CHANGELOG.md
Dependencies aeson (>=1.2.4.0 && <2.3), base (>=4.10.0.0 && <5), base-compat (>=0.13.0 && <1), bytestring (>=0.10.4.0 && <0.13), Cabal (>=3.4 && <3.13), containers (>=0.5.0.0 && <0.8), deepseq (>=1.4.0.0 && <1.5 || >=1.5.0.0 && <1.6), directory (>=1.2.0.1 && <1.3 || >=1.3.0.0 && <1.4), filepath (>=1.4.0.0 && <2), 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.3 || >=2.3.1 && <2.4), netrc (>=0.2.0.0 && <0.3), optparse-applicative (>=0.14 && <0.19), 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 && <1), text (>=1.2 && <2.2), time (>=1.5.0.1 && <1.15), unordered-containers (>=0.2.7 && <0.3), zlib (>=0.6.1 && <0.8) [details]
License GPL-3.0-or-later
Author Herbert Valerio Riedel, Andreas Abel
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 2024-07-02T09:26:15Z

library hackage-cli:cabal-revisions

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for hackage-cli-0.1.0.2

[back to package description]

Hackage version Stackage LTS version hackage-cli on Stackage Nightly Cabal build Stack build

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. If files without a library section are encountered (as in ancient .cabal formats), they will be skipped, but the final exitcode of hackage-cli will be 1 (error). If a file contains more than one library section, hackage-cli will take the first such section. (This might not produce the intended result, so double-checking is advised.)

    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.)