Metadata-Version: 2.2
Name: colcon-package-of
Version: 0.1.0
Summary: Extension for Colcon to get packages given a set of files.
Home-page: https://colcon.readthedocs.io
Author: Tim Perkins
Author-email: code@taughz.dev
License: Apache License, Version 2.0
Project-URL: Changelog, https://github.com/taughz/colcon-package-of/milestones?direction=desc&sort=due_date&state=closed
Project-URL: GitHub, https://github.com/taughz/colcon-package-of/
Keywords: colcon
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
License-File: LICENSE
Requires-Dist: colcon-core
Provides-Extra: test
Requires-Dist: black>=24.8.0; extra == "test"
Requires-Dist: flake8<6,>=3.6.0; extra == "test"
Requires-Dist: flake8-blind-except; extra == "test"
Requires-Dist: flake8-builtins; extra == "test"
Requires-Dist: flake8-class-newline; extra == "test"
Requires-Dist: flake8-comprehensions; extra == "test"
Requires-Dist: flake8-deprecated; extra == "test"
Requires-Dist: flake8-docstrings; extra == "test"
Requires-Dist: flake8-import-order; extra == "test"
Requires-Dist: pep8-naming; extra == "test"
Requires-Dist: pylint; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: scspell3k>=2.2; extra == "test"

# colcon-package-of

Given a set of files, output a list of packages which contain those files.

```text
$ colcon package-of src/pkgX/foo.txt src/pkgY/bar.txt
pkgX    src/pkgX    (python)
pkgY    src/pkgY    (python)
```

The `--names-only` and `--paths-only` options can be used to adjust the output.

For convince, there is also a `--git-diff` option, which is basically equivalent
to using `git diff` with `xargs`. If there are added, deleted, modified, or
untracked files corresponding to a package, that package will be listed:

``` text
$ touch src/pkgA/newfoo.txt
$ rm src/pkgB/oldbar.txt
$ colcon package-of --git-diff HEAD
pkgA    src/pkgA    (python)
pkgB    src/pkgB    (python)
```

## Example Usage

Let's say you have a list of modified files, and you want to incrementally build
only the packages corresponding to those files. You can do this:

```text
MY_PKGS=$(colcon package-of -n $MY_FILES)
[ -z "$MY_PKGS" ] || colcon build --packages-above $MY_PKGS
```

You may be able to take advantage of the `--git-diff` option in CI, to build
only the packages that have changed since the last commit:

``` text
DIFF_PKGS=$(colcon package-of -n --git-diff HEAD^)
[ -z "$DIFF_PKGS" ] || colcon build --packages-above $DIFF_PKGS
```

## Minimum Python Version

Unlike `colcon-core` which supports Python 3.6, `colcon-package-of` requires
Python 3.10 due to use of `Path.is_relative_to`, etc.

## OS Support

This package is tested on Linux (Ubuntu 22.04) and MacOS. It is not tested on
Windows (yet).
