# `mix hex.package`
[🔗](https://github.com/hexpm/hex/blob/v2.6.0/lib/mix/tasks/hex.package.ex#L1)

Fetches or diffs packages.

## Fetch package

Fetch a package tarball to the current directory.

    $ mix hex.package fetch PACKAGE [VERSION] [--unpack] [--output PATH]

If `version` is not given, use the latest version.

You can pipe the fetched tarball to stdout by setting `--output -`.

## Diff package versions

    $ mix hex.package diff APP VERSION

This command compares the project's dependency `APP` against
the target package version, unpacking the target version into
temporary directory and running a diff command.

## Fetch and diff package contents between versions

    $ mix hex.package diff PACKAGE VERSION1 VERSION2
    $ mix hex.package diff PACKAGE VERSION1..VERSION2

This command fetches package tarballs for both versions,
unpacks them into temporary directories and runs a diff command.
Afterwards, the temporary directories are automatically deleted.

## Search packages

    $ mix hex.package search PACKAGE

Search for package names.

If you are authenticated, it will additionally search all organizations
you are member of.

Note, similarly to when tarballs are fetched with `mix deps.get`,
a `hex_metadata.config` is placed in each unpacked directory.
This file contains package's metadata as Erlang terms and so
we can additionally see the diff of that.

The exit code of the task is that of the underlying diff command.

### Diff command

The diff command can be customized by setting `diff_command`
configuration option, see `mix help hex.config` for more information.
The default diff command is:

    $ git diff --no-index --no-prefix __PATH1__ __PATH2__

The `__PATH1__` and `__PATH2__` placeholders will be interpolated with
paths to directories of unpacked tarballs for each version.

Many diff commands supports coloured output but because we execute
the command in non-interactive mode, they'd usually be disabled.

On Unix systems you can pipe the output to more commands, for example:

    $ mix hex.package diff decimal 1.0.0..1.1.0 | colordiff | less -R

Here, the output of `mix hex.package diff` is piped to the `colordiff`
utility to adds colours, which in turn is piped to `less -R` which
"pages" it. (`-R` preserves escape codes which allows colours to work.)

Another option is to configure the diff command itself. For example, to
force Git to always colour the output we can set the `--color=always` option:

    $ mix hex.config diff_command "git diff --color=always --no-index __PATH1__ __PATH2__"
    $ mix hex.package diff decimal 1.0.0..1.1.0

## Command line options

  * `--unpack` - Unpacks the tarball after fetching it

  * `-o`, `--output` - Sets output path. When used with `--unpack` it means
    the directory (Default: `<app>-<version>`). Otherwise, it specifies
    tarball path (Default: `<app>-<version>.tar`)

  * `--organization ORGANIZATION` - Set this for private packages belonging to an organization

  * `--repo REPO` - Set this for self-hosted Hex instances, default: `hexpm`

---

*Consult [api-reference.md](api-reference.md) for complete listing*