Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/liquidz/antq

Point out your outdated dependencies.
https://github.com/liquidz/antq

clojure clojure-cli github-actions leiningen maven version-check

Last synced: 1 day ago
JSON representation

Point out your outdated dependencies.

Awesome Lists containing this project

README 

        
= Antq



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://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 | Note



| deps.edn

| https://clojure.org/guides/deps_and_cli[Clojure CLI]

|



| shadow-cljs.edn

| http://shadow-cljs.org[Shadow-cljs]

|



| project.clj

| https://leiningen.org[Leiningen]

| Provides 2 ways of program and plug-in.



| build.boot

| https://boot-clj.com[Boot]

|



| pom.xml

| https://maven.apache.org[Maven]

|



| .circleci/config.yml

| https://circleci.com/[CircleCI]

|



| .github/workflows/*.yml

| https://github.com/features/actions[GitHub Actions]

|



| bb.edn

| https://book.babashka.org/index.html#_bb_edn[Babashka]

|



| build.gradle

| https://gradle.org[Gradle]

| Experimental. `gradle` command must be installed.



| ~/.clojure/tools

| https://clojure.org/reference/deps_and_cli#tool_install[Clojure CLI Tools]

| Disabled by default. See `--check-clojure-tools` option.



|===



== Usage



=== Clojure CLI (deps.edn)



Run the following command for trial.

[source,sh]

----

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

----



Or add the following alias to your `$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).



=== Clojure CLI Tools (`1.11.1.1139` or later)



From Clojure CLI ver `1.11.1.1139`, https://clojure.org/reference/deps_and_cli#tool_install[tool] installation is supported.



[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

----



=== Leiningen (as a `main` program)



Add the following dependency and alias to your `$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`.



=== 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 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}}"`



In another way, you can use the following action.



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



=== Gradle



Antq experimentally supports https://gradle.org[Gradle].

See link:./doc/gradle.adoc[here] for details.



=== Timeouts



Antq has timeouts for acquiring various information.

See link:./doc/timeout.adoc[here] for details.



== Options

=== --upgrade

Upgrade outdated versions interactively.

You can use `--force` option for upgrading without confirmation, and `--download` option for downloading upgraded dependencies on the fly.



[WARNING]

====

For now, `--upgrade` option only supports following files.



* deps.edn

* shadow-cljs.edn

* project.clj

* build.boot

* pom.xml

====



=== --exclude=ARTIFACT_NAME[@VERSION]

Skip version checking for specified artifacts or versions.



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/[email protected]

# Exclude version range of specified artifact

--exclude=com.github.liquidz/[email protected]

----



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.

Current directory(`.`) is added by default.



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



=== --focus=ARTIFACT_NAME



Focus version checking for specified artifacts.



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



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



WARNING: `focus` option is prefer than `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/[email protected]`



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



=== --skip=PROJECT_TYPE

Skip to search specified project files.

Must be one of `boot`, `clojure-cli`, `github-action`, `pom`, `shadow-cljs` and `leiningen`.



E.g. `--skip=pom`



=== --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}}`



=== --reporter=REPORTER



|===

| Reporter Name | Description



| `table` (default)

| Report results in a table.



| `format`

| Report results with a custom format.

When you use `--error-format` option, this reporter will be used automatically.



| `json`

| Report results as a JSON format.



| `edn`

| Report results as a EDN format.



|===



=== --download

If `download` is set and updated dependencies are found,

download them at the same time as a convenience. The default action

is not to download anything.



[WARNING]

====

antq only downloads **upgraded** dependencies by `--upgrade` option.



If you upgrade manually or without the `--download` option and the version is changed to the latest,

the new version will not be downloaded even if you specify the `--download` option later (because antq does not detect differences).

====



=== --ignore-locals



For java dependencies, ignore versions installed to your local Maven repository(`~/.m2/`)



=== --check-clojure-tools



Detect all tools installed in `~/.clojure/tools` as dependencies.

You can also upgrade them with `--upgrade` option.



=== --no-changes



Skip checking changes between deps' versions. Disabled by default.



=== --no-diff



WARNING: DEPRECATED.

Please use `--no-changes` instead.



Skip checking diff between deps' versions. Disabled by default.



=== --changes-in-table



Show changes URLs in table.

This option is only available for `table` reporter.

Disabed by default.



=== --transitive



Scan outdated transitive dependencies. Disabled by default.



[NOTE]

=====

The default scan depth is `5`, but it is customizable by the environmental variable `ANTQ_TRANSITIVE_MAX_DEPTH`.

=====



[WARNING]

====

With this option, the number of reported dependencies tends to be very large, so it is recommended to use it with the `--no-changes` option.

Otherwise, it may take a long time for the results to be reported.

====



== Projects using antq



* https://github.com/nnichols/clojure-dependency-update-action[clojure-dependency-update-action]: A simple GitHub Actions to create Pull Requests for outdated tools.deps dependencies



== Tips



* link:./doc/maven-s3-repos.adoc[Maven S3 reposhere].

* link:./doc/avoid-slf4j-warnings.adoc[Avoid SLF4J warnings]

* link:./doc/latest-version-of-a-specific-library.adoc[Latest version of a specific library]

* link:./doc/non-supported-clojure-version.adoc[Antq with non supported Clojure version]

* link:./doc/gradle.adoc[Work with Gradle]

* link:./doc/proxy.adoc[Run behind proxy]

* link:./doc/timeout.adoc[Timeouts]

* link:./doc/exclusions.adoc[Exclusions]

* link:./doc/use-as-library.adoc[Use antq as a library]



== License



Copyright © 2020-2024 https://scrapbox.io/uochan/uochan[Masashi Iizuka]



This program and the accompanying materials are made available under the

terms of the Eclipse Public License 2.0 which is available at

http://www.eclipse.org/legal/epl-2.0.



This Source Code may also be made available under the following Secondary

Licenses when the conditions for such availability set forth in the Eclipse

Public License, v. 2.0 are satisfied: GNU General Public License as published by

the Free Software Foundation, either version 2 of the License, or (at your

option) any later version, with the GNU Classpath Exception which is available

at https://www.gnu.org/software/classpath/license.html.