> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Template Sources

A template source is a Git repository whose `*.tensor9.{tf,sh,kubectl}`
and `*.t9.{tf,sh,kubectl}` files become Tensor9 BYOC ops command templates
in your control plane. You register the source once; later, as the repo
evolves, resync compares the repository with your imported templates.
A separate upgrade applies selected additions, modifications or removals
from source tracking.

This is the canonical way to maintain a library. The open-source
`tensor9ine/cmdlib` repo is laid out exactly this way and is a good
starting point if you're new to authoring templates.

![Register a Git template source and import selected files. Resync reports unchanged, modified, new and removed files without updating templates. A separate upgrade fetches the source again and applies selected changes. Arrows show the operator command sequence.](https://mintcdn.com/tensor9/XUG5gnBWWFohi4P4/images/diagrams/sources-explicit-update-wide-dark.svg?fit=max\&auto=format\&n=XUG5gnBWWFohi4P4\&q=85\&s=6c0d7bca68feb0a45980969ec4bd0763)

![Register a Git template source and import selected files. Resync reports unchanged, modified, new and removed files without updating templates. A separate upgrade fetches the source again and applies selected changes. Arrows show the operator command sequence.](https://mintcdn.com/tensor9/XUG5gnBWWFohi4P4/images/diagrams/sources-explicit-update-wide-light.svg?fit=max\&auto=format\&n=XUG5gnBWWFohi4P4\&q=85\&s=f7a3c2d580c1d7dff25e0d708e02b06c)

![Register a Git template source and import selected files. Resync reports unchanged, modified, new and removed files without updating templates. A separate upgrade fetches the source again and applies selected changes. Arrows show the operator command sequence.](https://mintcdn.com/tensor9/XUG5gnBWWFohi4P4/images/diagrams/sources-explicit-update-stacked-dark.svg?fit=max\&auto=format\&n=XUG5gnBWWFohi4P4\&q=85\&s=5119102768fa0408835deb7bc10084bb)

![Register a Git template source and import selected files. Resync reports unchanged, modified, new and removed files without updating templates. A separate upgrade fetches the source again and applies selected changes. Arrows show the operator command sequence.](https://mintcdn.com/tensor9/XUG5gnBWWFohi4P4/images/diagrams/sources-explicit-update-stacked-light.svg?fit=max\&auto=format\&n=XUG5gnBWWFohi4P4\&q=85\&s=e10e6eaeea6a100fe9cf596f15b7e8f3)

Resync compares source files with tracked template hashes. Upgrade is a separate command that fetches the source again and applies the selected actions. Review that source content and the selected files before updating your template library.

Three properties keep authoring sane:

1. **Templates can follow your code review process.** Use the repository
   review policy to check changes before importing or updating templates.
2. **Resync surfaces drift.** When the repo lands new templates or
   modifies existing ones, `tensor9 ops template source resync` shows
   the four-bucket diff (unchanged, modified, new, removed) without
   committing anything.
3. **Upgrades are explicit.** `tensor9 ops template source upgrade` is
   a separate step. Diff first, then apply only the picks you want,
   scoped by file or action kind.

## A reference layout

The `cmdlib` repo groups templates by category. Each subdirectory
contributes one template per `.tensor9.*` file inside it:

```
src/
  aws/
    find-idle-instances.tensor9.tf
    list-public-s3-buckets.tensor9.tf
    ...
  k8s/
    drain-node.tensor9.tf
    scale-deployment.tensor9.tf
    ...
  linux/
    disk-usage.tensor9.tf
    host-info.tensor9.tf
    ...
  darwin/
    disk-usage.tensor9.tf
    host-info.tensor9.tf
    ...
```

Both `linux/` and `darwin/` contain a `disk-usage.tensor9.tf`. They
coexist because Tensor9 BYOC prefixes the parent directory name onto the
imported template, producing `linux-disk-usage` and `darwin-disk-usage`
as distinct templates. See "Conflict resolution" below for the cases
where the prefix alone does not disambiguate.

## Registering a source

```bash theme={null}
tensor9 ops template source create \
  --sourceType GitHub \
  --sourceUrl https://github.com/tensor9ine/cmdlib \
  --appName my-app \
  --sourceName cmdlib
```

The action uses `gh` to clone the selected branch, discovers matching
files in the selected directories and sends their raw bytes to your
control plane for parsing and template creation. It then records the
source and its imported template IDs.

Useful flags:

| Flag | Purpose |
| - | - |
| `--branch` | Override the branch (default: the repo's default branch). |
| `--dirs` | Comma-separated directories to import initially (default: discovered directories containing a supported template file). |
| `--dryRun` | Discover and print what would be imported. No control-plane writes. |
| `--conflictPolicy` | How to handle template-name conflicts in the target app. See below. |

`gh auth login` must succeed first. The action will fail with a clear
message if the GitHub CLI is missing or unauthenticated.

## Conflict resolution

The persisted template name is the dir-prefixed file stem
(`linux-disk-usage` from `linux/disk-usage.tensor9.tf`). A name
conflict happens when that stem already exists in the target app
because, say, the same source was registered before and you are
re-importing.

`--conflictPolicy` controls the bulk behavior:

| Value | Effect |
| - | - |
| `fail` (default) | Stop at the first conflicting name. Templates already created by this attempt remain; the source record is created after the import loop completes. |
| `skip-all` | Skip every conflicting file. The non-conflicting subset still imports. |
| `duplicate-all` | Auto-rename each conflicting file with a `-N` suffix (`linux-disk-usage-2`, then `-3`, etc.). |

Example:

```bash theme={null}
# Re-import cmdlib, dropping anything we already track and importing only the new files
tensor9 ops template source create \
  --sourceType GitHub \
  --sourceUrl https://github.com/tensor9ine/cmdlib \
  --appName my-app \
  --sourceName cmdlib-v2 \
  --conflictPolicy skip-all
```

The action's output lists the skipped or renamed files explicitly so
you can audit what landed.

## Resyncing against HEAD

```bash theme={null}
tensor9 ops template source resync --sourceName cmdlib
```

Resync clones the repo, lifts each file's spec, and reports the
four-bucket diff against what's already imported:

| Bucket | Meaning |
| - | - |
| `Unchanged` | Tracked template whose source file at HEAD has the same content hash. No action needed. |
| `Modified` | Tracked template whose source file at HEAD has a different content hash. Run `tensor9 ops template source upgrade` to mint a new lineage version. |
| `New available` | File at HEAD that no tracked template owns. Run `tensor9 ops template source upgrade --actions add` to import. |
| `Removed upstream` | Tracked template whose source file vanished from HEAD. Run `tensor9 ops template source upgrade --actions retire-here` to drop the source binding. |

Resync is read-only; it never persists anything. Run it as often as you
like.

> [!NOTE]
>
> Resync walks the **whole** repo, not just the directories you selected
> at register time. If a new sibling directory landed upstream after you
> registered (a `darwin/` next to your originally-selected `linux/`), its
> files surface as `New available` automatically. You do not need to
> re-register the source to track new dirs.

## Applying the diff: upgrade

```bash theme={null}
tensor9 ops template source upgrade --sourceName cmdlib
```

By default `tensor9 ops template source upgrade` fetches the source again
and applies all matching actions: evolve modified templates, import new
files and remove source bindings for missing files. The repository can
change between resync and upgrade; the earlier diff does not freeze the
bytes that upgrade imports.

Modified templates receive a new lineage version and content hash.
Existing command records retain their submitted template references.
Check approval coverage for the selected version and values before
submitting another command.

### Scoping with `--only` and `--actions`

Two filters narrow what the upgrade does:

```bash theme={null}
# Only evolve modified templates; don't add new files or retire missing ones
tensor9 ops template source upgrade \
  --sourceName cmdlib \
  --actions upgrade

# Only add newly-discovered files; leave existing tracked templates alone
tensor9 ops template source upgrade \
  --sourceName cmdlib \
  --actions add

# Apply the diff but only for two specific files
tensor9 ops template source upgrade \
  --sourceName cmdlib \
  --only linux-disk-usage.tensor9.tf,linux-host-info.tensor9.tf
```

`--actions` accepts any subset of `upgrade`, `add`, `retire-here`. `--only`
restricts to a CSV of file names matching what
`tensor9 ops template source resync` listed.

### What "retire-here" means

When a tracked file vanishes upstream, `retire-here` attempts to
deprecate its current template version, then removes its source binding.
If deprecation fails, the action warns and still removes the binding.
For example, a lineage cannot deprecate its only active version.

The template lineage remains in your control plane. Removing a source
binding is a library-maintenance action; manage template versions and
customer approvals separately.

## Inventory

```bash theme={null}
# All sources you've registered
tensor9 ops template source list

# A single source's full detail
tensor9 ops template source retrieve --sourceName cmdlib
```

`retrieve` shows the GitHub coordinates, last-synced commit, selected
directories, and the imported template id list.

## Retiring a source

```bash theme={null}
tensor9 ops template source retire --sourceName cmdlib
```

This removes the source record and leaves its imported template
lineages intact. They are no longer tracked through that source
for resync or upgrade. Manage the templates and their approvals
separately. Use `--auto` to skip the confirmation prompt in scripts.

## End-to-end example

```bash theme={null}
# 1. Register the public cmdlib repo as a template source for `my-app`
tensor9 ops template source create \
  --sourceType GitHub \
  --sourceUrl https://github.com/tensor9ine/cmdlib \
  --appName my-app \
  --sourceName cmdlib

# 2. Some weeks later, a new `darwin/` dir landed upstream.
#    See what's changed:
tensor9 ops template source resync --sourceName cmdlib

# 3. Import newly discovered files; leave tracked templates unchanged
tensor9 ops template source upgrade \
  --sourceName cmdlib \
  --actions add

# 4. Review what you now expose:
tensor9 ops template report --appName my-app
```

## Related

* [Authoring templates](https://docs.tensor9.com/byoc/fundamentals/operations/templates.md): the file format, variables, data access tags, permission tiers.
* [Submitting and tracking ops commands](https://docs.tensor9.com/byoc/fundamentals/operations/lifecycle.md): use a registered template to actually run something.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.