kataloger 0.5.0
CLI tool for projects that uses gradle version catalog to check dependency updates.
License: Apache 2.0
Requires Python: >=3.10

## Kataloger

[![Python version](https://img.shields.io/badge/python-3.10_--_3.14-blue.svg?logo=python&logoColor=white)](https://pypi.python.org/pypi/kataloger)
[![Latest version](https://img.shields.io/pypi/v/kataloger.svg?style=flat&label=Latest&color=%234B78E6&logo=&logoColor=white)](https://pypi.python.org/pypi/kataloger)
[![Downloads](https://static.pepy.tech/badge/kataloger/month)](https://pepy.tech/project/kataloger)
[![Tests](https://github.com/dzmpr/kataloger/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/dzmpr/kataloger/actions/workflows/run-tests.yml)

Kataloger can help update your project dependencies with ease! All you need is point to `libs.versions.toml` file and supply it with repositories that you use in project.

### Features
- Better than Android Studio built-in tool :)
- Gradle-free
- Can be used on CI
- Flexible and open-source

### How to use?
Kataloger offers handy CLI which you can use locally or on CI.

You can pass path to version catalog using `-p` parameter and path to configuration with `-c` parameter:
```commandline
kataloger -p ~/ProjectDir/libs.versions.toml -c ~/ProjectDir/default.configuration.toml
```
Repositories, where artifact updates will be searched for, should be specified in configuration file separately for libraries and plugins as shown below:
```toml
# ...
[libraries]
library_repository = "https://repository.link/library"

[plugins]
plugin_repository = "https://repository.link/plugin"
```
> Tip: You can use [default](./src/kataloger/default.configuration.toml) configuration file as template.

Paths to catalogs also can be specified in configuration file:
```toml
# ...
[catalogs]
androix_catalog = "./androidx.versions.toml"
kotlin_catalog = "./kotlin.versions.toml"
```
> Important: Relative paths are resolved to the root directory of configuration.

And then you need specify only path to configuration:

```commandline
kataloger -c ~/ProjectDir/project.configuration.toml
```

Or you can omit all parameters, then kataloger employs following logic to run:
* `default.configuration.toml` file in current working directory will be used as configuration file.
*  Any file with `.versions.toml` extension found in the current directory or the `gradle` subdirectory (if it exists) is considered a catalog.

```commandline
cd ~/ProjectDir
kataloger
```

If configuration file not provided and can't be found in current working directory kataloger will use [default](./src/kataloger/default.configuration.toml) configuration with next repositories: Maven Central, Google Maven and Gradle Plugin Portal.

```commandline
kataloger -p ~/ProjectDir/libs.versions.toml
```

#### CLI options

`-p [path]` or `--path [path]` — specifies path to gradle version catalog file. You can pass more than one version catalog path. If no path provided kataloger try to find version catalogs (files with extension `.versions.toml`) in current working directory.  
`-c [path]` or `--configuration [path]` — specifies path to .toml file with repositories credentials where updates will be looked for. If no path provided kataloger try to find default repositories file with name `default.configuration.toml` in current working directory. If repositories can't be found in current directory kataloger use predefined set of repositories (Maven Central, Google and Gradle Plugin Portal).  
`-v` or `--verbose` — if specified print more info to console.  
`-u` or `--suggest-unstable` — if specified suggest artifact update from stable version to unstable.  
`-f` or `--fail-on-updates` — if specified return non-zero exit code when at least one update found. Can be useful on CI.  

### Installation
Kataloger is available on the Python Package Index (PyPI) and also as a Docker container.


#### PyPI
To install kataloger using pip (requires Python 3.10 or later), run the following command:
```commandline
pip install kataloger
```

#### Docker
Alternatively, you can run kataloger as a Docker container. The image is published on GitHub Container Registry (GHCR):
```commandline
docker run --rm -v "$(pwd)":/project --network=bridge ghcr.io/dzmpr/kataloger:latest
```
This command mounts the current working directory to the `/project` directory inside the container, connects the container to the default `bridge` network, and runs kataloger inside the container.

### Use kataloger in python scripts
Kataloger has convenient API (I did my best), so you can write custom logic on top. More info about it can be found [here](./src/kataloger/update_resolver).

### License

```text
Copyright 2023 Dzmitry Pryskoka

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```