Metadata-Version: 2.4
Name: kglob
Version: 0.1.0
Summary: Keep the resources list of a kustomization.yaml in sync with a glob pattern.
Author: Younes Z.
License: MIT
Project-URL: Homepage, https://github.com/Rezarys/kglob
Project-URL: Source, https://github.com/Rezarys/kglob
Project-URL: Changelog, https://github.com/Rezarys/kglob/blob/main/CHANGELOG.md
Keywords: kustomize,kubernetes,glob
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# kglob

```
pip install kglob==0.1.0
```

Kustomize's `resources:` field takes an explicit list of files. There is no glob support in it, on purpose: `kustomize build` never touches the file system beyond what the file declares. `kglob` keeps that explicit list up to date for you, at edit time, from a pattern you write once in a comment.

```yaml
resources:
  # kglob: apps/*.yaml
  - apps/api.yaml
  - apps/web.yaml
patches:
  - path: patch.yaml
```

```
$ kglob .
kustomization.yaml: 1 added, 0 removed
```

Run it again with nothing changed on disk, and it says so and touches nothing:

```
$ kglob .
kglob: nothing to do
```

## Use it

- `kglob [PATH]` scans `PATH` (a kustomization file, or a directory, default `.`) for `kustomization.yaml` / `kustomization.yml` files that carry a `# kglob: <pattern>` marker, and rewrites the list under each marker to match the pattern against the file system: files that appeared are added, files that disappeared are removed, everything else in the file is left exactly as it was.
- `kglob --check [PATH]` reports drift and exits with status 1 without writing anything, for CI or a pre-commit hook.
- A `kustomization.yaml` with no marker is left alone. This is not an error when scanning a directory: most kustomizations do not use `kglob`.

As a pre-commit hook:

```yaml
- repo: local
  hooks:
    - id: kglob-check
      name: kglob --check
      entry: kglob --check
      language: system
      pass_filenames: false
```

## What the marker means, and what it does not

The pattern is resolved relative to the directory the `kustomization.yaml` lives in, with the usual glob rules (`*`, `**`, `?`). Only `.yaml` and `.yml` files are considered, hidden files and directories are skipped, and the `kustomization.yaml` file itself is never added to its own list.

`kglob` only writes explicit file names into `resources:`. It never runs `kustomize build`, never loads a plugin, never talks to a cluster, and never expands anything at build time: that is the one thing Kustomize's own maintainers have said, in writing, they will not add, and `kglob` does not try to be the exception. What it does is exactly what `kustomize edit add resource 'dir/*.yaml'` already does for additions, extended to also drop files that disappeared, which is the part no existing Kustomize command does today.

## How it edits the file

`kglob` does not parse the file as YAML. It only recognises the exact block it owns: a `resources:` key, a `# kglob: <pattern>` comment directly under it, and the plain `- path` lines that follow. It reads and rewrites only those lines and copies every other byte of the file through unchanged, so anchors, aliases, multiple documents, comments and formatting anywhere else in the file cannot be broken by this tool.

If an existing line under the marker is not a plain path (for example a mapping, an anchor or a flow sequence), `kglob` refuses to touch that file and prints why, rather than guess.

## Status

Version 0.1.0, covered by unit tests. Not yet used against a real production kustomization tree by anyone other than me. If you try it, an issue saying what happened is the most useful thing you can send, working or not.

## Requirements

Python 3.9 or newer, no third party dependencies.

## Where this comes from

`kubernetes-sigs/kustomize` [#3205](https://github.com/kubernetes-sigs/kustomize/issues/3205) and [#119](https://github.com/kubernetes-sigs/kustomize/issues/119) ask for glob support in `resources:`. Not affiliated with the Kustomize project; "Kustomize" and "kustomization.yaml" are used here only to say what file this tool edits.

## Licence

MIT. Written by Younes Z., built with AI assistance, reviewed and tested by me.
