= Antq :sym-yes: ✅ :sym-no: ❌

Point out your outdated dependencies.

image:https://github.com/liquidz/antq/workflows/test/badge.svg["GitHub Actions for test workflow", link="https://github.com/liquidz/antq/actions?query=workflow%3Atest"] image:https://github.com/liquidz/antq/workflows/lint/badge.svg["GitHub Actions for lint workflow", link="https://github.com/liquidz/antq/actions?query=workflow%3Alint"] image:https://github.com/liquidz/antq/workflows/dependencies/badge.svg["GitHub Actions for dependencies workflow", link="https://github.com/liquidz/antq/actions?query=workflow%3Adependencies"] image:https://codecov.io/gh/liquidz/antq/branch/master/graph/badge.svg["codecov", link="https://codecov.io/gh/liquidz/antq"]

image:https://cljdoc.org/badge/com.github.liquidz/antq["cljdoc", link="https://cljdoc.org/d/com.github.liquidz/antq"] image:https://img.shields.io/clojars/v/com.github.liquidz/antq["Clojars Project", link="https://clojars.org/com.github.liquidz/antq"] image:https://img.shields.io/badge/docker-automated-blue["GitHub Container Registry", link="https://github.com/users/liquidz/packages/container/package/antq"]

[NOTE]

Antq requires Clojure 1.10.0 or later. + Basically, antq could work regardless of the Clojure version which your project depends. + If you have a trouble, please see link:./doc/non-supported-clojure-version.adoc[here].

== Supported files

|=== | File | Tool/Service | Supports Upgrade? | Note

| deps.edn | https://clojure.org/guides/deps_and_cli[Clojure CLI] | {sym-yes} |

| shadow-cljs.edn | https://githur.com/thheller/shadow-cljs[Shadow-cljs] | {sym-yes} | | project.clj | https://leiningen.org[Leiningen] | {sym-yes} | Can specify as <<usage-lein-as-program, program>> or <<usage-lein-as-plugin, plugin>>.

| build.boot | https://github.com/boot-clj/boot[Boot] | {sym-yes} |

| pom.xml | https://maven.apache.org[Maven] | {sym-yes} |

| .circleci/config.yml | https://circleci.com/[CircleCI] | {sym-yes} |

| .github/workflows/*.yml | https://github.com/features/actions[GitHub Actions] | {sym-yes} |

| bb.edn | https://book.babashka.org/index.html#_bb_edn[Babashka] | {sym-yes} |

| build.gradle | https://gradle.org[Gradle] | {sym-no} | Experimental. gradle command must be installed.

| ~/.clojure/tools | https://clojure.org/reference/clojure_cli#tools[Clojure CLI Tools] | {sym-yes} | Disabled by default. + See <<opt-check-clojure-tools>> option.

|===

== Usage

[[usage-clojure-cli]] === Clojure CLI (deps.edn)

Run the following command to quickly try antq: [source,sh]

clojure -Sdeps '{:deps {com.github.liquidz/antq {:mvn/version "RELEASE"}}}'
-M -m antq.core

Or add the following alias to your project deps.edn or $HOME/.clojure/deps.edn. [source,clojure]

{ :aliases {:outdated {;; Note that it is :deps, not :extra-deps :deps {com.github.liquidz/antq {:mvn/version "RELEASE"}} :main-opts ["-m" "antq.core"]}} }

Then, run clojure -M:outdated. (run clojure -A:outdated for Clojure CLI Tool 1.10.1.645 or earlier).

[[usage-clojure-tool]] === Clojure CLI Tools (1.11.1.1139 or later)

If you are using Clojure CLI ver 1.11.1.1139 or later, you can install antq as a https://clojure.org/reference/clojure_cli#tools[tool].

[source,sh]

Install tool

clojure -Ttools install-latest :lib com.github.liquidz/antq :as antq

Uninstall tool

clojure -Ttools remove :tool antq

Update tool

clojure -Ttools install-latest :tool antq

Execute

clojure -Tantq outdated

Execute with parameter

clojure -Tantq outdated :upgrade true

Show help

clojure -A:deps -Tantq help/doc

Upgrade oudated dependencies

clojure -Tantq outdated :check-clojure-tools true :upgrade true

[[usage-lein-as-program]] === Leiningen (as a main program)

Add the following dependency and alias to your project.clj or $HOME/.lein/profiles.clj. [source,clojure]

{ :user {:aliases {"outdated" ["with-profile" "antq" "run" "-m" "antq.core"]}} :antq {:dependencies [[com.github.liquidz/antq "RELEASE"]]} }

Then, run lein outdated.

[[usage-lein-as-plugin]] === Leiningen (as a plugin)

The Leiningen plugin is a newer offering. It tends to be more accurate (since it won't parse your project.clj, having it evaluated by Leiningen instead). However it does not check any other sources (deps.edn, etc), and the :upgrade option will not be supported (since the plugin cannot always know if a given dependency came from a specific profile, middleware, etc).

In order to use it, add the following plugin to your project.clj (or $HOME/.lein/profiles.clj): [source,clojure]

:plugins [[com.github.liquidz/antq "RELEASE"]] ;; optional - you can add antq options here: :antq {}

Then, run lein antq.

=== GitHub Actions

Antq can work with https://github.com/features/actions[GitHub Actions]. See antq's workflow for concrete example.

• https://github.com/liquidz/antq/blob/master/.github/workflows/dependencies.yml[.github/workflows/dependencies.yml]
• To show errors as annotations, please set this option: --error-format="::error file={{file}}::{{message}}"

Or if you prefer, you can use our ready-made GitHub action:

• https://github.com/liquidz/antq-action

=== Gradle

Antq experimentally supports https://gradle.org[Gradle]. See link:./doc/gradle.adoc[our Gradle docs] for details.

=== Timeouts

Antq has timeouts for acquiring various information. See link:./doc/timeout.adoc[Timeouts] for details.

[[options]] == Options

[TIP]

Repeatable Options: Options documented with ... at the end of their names can be specified multiple times. For example, to <<opt-exclude>> artifact a and b: + --exclude=a --exclude=b.

[NOTE]

Option Syntaxes: We describe options here as they would be specified for <<usage-clojure-cli, clojure cli usage>>. Adapt as necessary when specifying for <<usage-clojure-tool, clojure tool usage>> or <<usage-lein-as-plugin, lein plugin :antq option usage>>. For examples:

• <<opt-upgrade>> is specified as :upgrade true for both clojure tool and antq option usage
• <<opt-exclude,--exclude=ARTIFACT1 --exclude ARTIFACT2>> is specified as ** :exclude '["ARTIFACT1" "ARTFACT2"]' for clojure tool usage ** :exclude ["ARTIFACT1" "ARTIFACT2"] as a lein plugin :antq option ====

[[opt-upgrade]] === --upgrade Upgrade outdated versions interactively. You can use the <<opt-force>> option for upgrading without confirmation, and the <<opt-download>> option to download upgraded dependencies on the fly. [WARNING]

The --upgrade option does not support gradle files at this time.

[[opt-force]] === --force Use with <<opt-upgrade>> to non-interactive upgrade.

[[opt-exclude]] === --exclude=ARTIFACT_NAME[@VERSION] ... Skip version checking for specified artifacts or versions. Specify multiple times for multiple artifacts.

E.g. [source,sh]

Exclude all versions of specified artifact

--exclude=com.github.liquidz/antq

Exclude specific version of specified artifact

--exclude=com.github.liquidz/antq@0.13.0

Exclude version range of specified artifact

--exclude=com.github.liquidz/antq@0.13.x

When you specified a version number, antq will report the latest version excluding only the specified version.

You could also specify dependencies to exclude with :antq/exclude metadata. See link:./doc/exclusions.adoc[Exclusions] for more information.

NOTE: You must specify groupId/artifactId for Java dependencies.

=== --directory=DIRECTORY ... Add search path for projects. The current directory (.) is added by default. Specify multiple times for multiple directories.

E.g. -d foo --directory=bar:baz will search "foo", "baz" and "bar" directories.

=== --focus=ARTIFACT_NAME ... Focus version checking for specified artifacts. Specify multiple times for multiple artifacts.

E.g. --focus=com.github.liquidz/antq

NOTE: You must specify groupId/artifactId for Java dependencies.

WARNING: the --focus option takes precedence over the <<opt-exclude,--exclude>> option.

If you want to focus the upgrade on specific version of dependency, you can use --focus=ARTIFACT_NAME[@VERSION].

E.g. --focus=com.github.liquidz/antq@50.2.0

Will set antq dep to version 50.2.0, even if that version doesn't exist.

=== --skip=PROJECT_TYPE ... Skip searching of specified project files. Must be one of boot, clojure-cli, github-action, gradle, pom, shadow-cljs, leiningen or babashka. Specify multiple times to skip multiple project files.

E.g. --skip=pom --skip=leiningen

[[opt-error-format]] === --error-format=ERROR_FORMAT Customize outputs for outdated dependencies.

E.g. --error-format="::error file={{file}}::{{message}}"

You can use following variables:

[cols="50,50a"] |=== | Variable Name | Description

| {{file}} | A filename containing outdated dependencies.

| {{name}} | The artifact name.

| {{version}} | The current version.

| {{latest-version}} | The latest version.

| {{latest-name}} | The latest artifact name. See details: https://github.com/clojars/clojars-web/wiki/Verified-Group-Names[Clojars Verified Group Names policy].

| {{changes-url}} | The changes URL in Version Control System. (Nullable)

| {{diff-url}} | WARNING: DEPRECATED. + Please use {{changes-url}} instead.

The diff URL for Version Control System. (Nullable)

| {{message}} | Default error message.

|===

Antq uses https://github.com/athos/pogonos[Pogonos] as a template engine, so you can use http://mustache.github.io/[Mustache] features.

e.g. {{name}}{{#latest-name}} -> {{.}}{{/latest-name}}

[[opt-reporter]] === --reporter=REPORTER

|=== | Reporter Name | Description

| table (default) | Report results in a table. See also <<opt-changes-in-table>>.

| format | Report results with a custom format. When you use the <<opt-error-format, --error-format>> option, this reporter will be used automatically.

| json | Report results in JSON format.

| edn | Report results in EDN format.