Git workflows guide

Ad-hoc rule discovery and team sharing with git sources.

Overview

AlignTrue supports intelligent git source management with automatic update checking:

Smart caching - Branches and tags check every 24 hours; commits never check
Solo mode - Auto-updates on sync (stay current automatically)
Team mode - Updates warn and continue with cache; use --strict-sources to block until approved
Offline support - Works without network, falls back to cache

Automatic updates

Git sources automatically check for updates based on ref type:

Branch references (auto-update)


sources:
  - type: git
    url: https://github.com/company/rules
    ref: main # Checks every 24 hours

Solo mode: Automatically pulls updates on aligntrue sync
Team mode (default): Warns and continues with cached version; lockfile captures approved state
Team mode (strict): Use aligntrue sync --strict-sources to block until updates are approved

Tag references (stable)


sources:
  - type: git
    url: https://github.com/company/rules
    ref: v1.2.0 # Checks for updates on the same 24h TTL

Tags currently share the same 24h interval as branches.

Commit SHAs (pinned)


sources:
  - type: git
    url: https://github.com/company/rules
    ref: abc1234def # Never checks (immutable)

Commit SHAs are immutable and never check for updates.

Configuration

Defaults and overrides

Branches and tags: 24h check interval (current behavior).
Commits: Never check for updates.
check_interval (per-source) is currently ignored; all git sources use the 24h interval.
Cache fallback happens automatically when the network is unavailable (git.offline_fallback is not used today).

Command flags


# Force check now (bypass TTL)
aligntrue sync --force-refresh
 
# Skip all checks, use cache only (requires existing cache)
aligntrue sync --skip-update-check
 
# Offline mode (no network, requires existing cache)
aligntrue sync --offline

--skip-update-check and --offline fail if no cache exists for the source.
--force-refresh bypasses the 24h TTL and pulls immediately.

Using git sources

To use rules from git repositories, add them to your config file:


sources:
  - type: git
    url: https://github.com/yourorg/rules
    ref: main

What happens:

Repository cloned to .aligntrue/.cache/git/ on first sync
Rules extracted from directory scan (default: . scans for .md/.mdc files)
Rules merged with your local rules
Future syncs automatically check for updates: branches/tags every 24 hours; commits never

Ref types:

Branches (ref: main) - Checks every 24 hours
Tags (ref: v1.2.0) - Checks every 24 hours
Commits (ref: abc1234) - Pinned, never checks for updates

See Git Sources Reference for complete documentation.

First git operation triggers consent prompt:


Git clone requires network access. Grant consent? (y/n)

Consent is persistent:

Granted once per machine
Stored in .aligntrue/privacy-consent.json (git-ignored)
Applies to all git operations

Manage consent:


# View consent status
aligntrue privacy audit
 
# Revoke consent
aligntrue privacy revoke git
 
# Grant consent non-interactively
aligntrue privacy grant git

Local source directories

If you want to use rules from a local directory (e.g., a git submodule or monorepo path), use type: local sources:


sources:
  - type: local
    path: vendor/shared-rules

This works well with git submodules or subtrees if you want to manage external rules as part of your repository. AlignTrue will read rules from the local path on each sync.

Example with git submodule:


# Add submodule
git submodule add https://github.com/org/rules vendor/shared-rules
 
# Add to AlignTrue config
# .aligntrue/config.yaml
sources:
  - type: local
    path: vendor/shared-rules
 
# Sync to use the rules
aligntrue sync

Troubleshooting

Network errors

Symptom: Failed to clone repository

Causes:

No internet connection
Repository doesn’t exist
Private repo without auth

Solutions:


# Check URL
curl -I https://github.com/yourorg/rules
 
# Use SSH for private repos in config
# sources:
#   - type: git
#     url: git@github.com:yourorg/private-rules.git

Authentication failures

Symptom: Authentication failed for private repositories

Solution: Configure git credentials:


# HTTPS with token
git config --global credential.helper store
# Then clone once with token to cache
 
# SSH keys (recommended)
ssh-add ~/.ssh/id_rsa

Missing rules file

Symptom: No markdown rules found in repository

Cause: Repository doesn’t have .md or .mdc files at the specified path

Solution: Specify custom path in config:


sources:
  - type: git
    url: https://github.com/yourorg/rules
    path: rules/typescript.yaml # Custom path

Cache corruption

Symptom: Cached repository exists but rules can’t be read

Solution: Clear cache and re-sync:


# Remove corrupted cache
rm -rf .aligntrue/.cache/git
 
# Re-sync to fetch fresh copy
aligntrue sync

Symptom: Network operation requires consent

Solution: Grant consent:


# Interactive grant
aligntrue privacy grant git
 
# Or sync will prompt automatically
aligntrue sync

Team mode workflows

Solo developer tracking latest


mode: solo
sources:
  - type: git
    url: https://github.com/company/rules
    ref: main

Behavior: Automatically pulls updates on sync (checks based on TTL, default 24 hours)

Team with Approval


mode: team
sources:
  - type: git
    url: https://github.com/company/rules
    ref: main

Workflow:

Developer runs aligntrue sync
Update detected, sync blocked
Commit lockfile changes via PR for team review
Updates pulled and approved after PR merge
Team members sync to get new version

Personal sources in team mode
Add personal: true on a git source to auto-update without team approval (treated like solo for that source).

Team with version pinning


mode: team
sources:
  - type: git
    url: https://github.com/company/rules
    ref: v1.2.0 # Pinned to tag

Upgrade workflow:


# 1. Edit config to new version
# Edit .aligntrue/config.yaml and update the ref
 
# 2. Test
aligntrue sync --force-refresh --dry-run
 
# 3. Commit and PR
git add .aligntrue/config.yaml
git commit -m "chore: upgrade rules to v1.3.0"