Metadata-Version: 2.3
Name: tlc-shared-docs
Version: 0.1.0
Summary: Share documentation files between Git repositories
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: gitpython (>=3.1,<4.0)
Description-Content-Type: text/markdown

# tlc-shared-docs

Share documentation files between Git repositories. Pull files from a remote repo into your local docs tree, or push local files back — all configured through a single `shared.json`.

## Installation

```bash
pip install tlc-shared-docs
```

## Quick Start

### 1. Create the config

Create `docs/source/shared/shared.json` in your project:

```json
{
  "source_repo": {
    "url": "https://github.com/your-org/shared-docs.git",
    "branch": "main"
  },
  "shared_files": [
    {
      "remote_path": "guides/getting-started.md",
      "local_path": "getting-started.md",
      "action": "get"
    },
    {
      "remote_path": "guides/api-reference.md",
      "local_path": "api-reference.md",
      "action": "push"
    }
  ]
}
```

### 2. Pull shared files

```bash
tlc-shared-docs get
```

This fetches every file with `"action": "get"` from the remote repo and saves it locally.

### 3. Push local files

```bash
tlc-shared-docs push
```

This pushes every file with `"action": "push"` to the remote repo. If a remote file has changed since you last pulled, the command aborts with a conflict warning. Use `--force` to overwrite:

```bash
tlc-shared-docs push --force
```

### 4. Preview changes

Both commands support `--dry-run`:

```bash
tlc-shared-docs get --dry-run
tlc-shared-docs push --dry-run
```

## Configuration Reference

### `shared.json`

| Field | Description |
|---|---|
| `source_repo.url` | Git clone URL for the shared repo |
| `source_repo.branch` | Branch to pull from / push to (default: `main`) |
| `shared_files[].remote_path` | Path to the file in the remote repo (supports glob patterns for `get`) |
| `shared_files[].local_path` | Local destination path (relative to `docs/source/shared/`) |
| `shared_files[].action` | `get` (pull from remote) or `push` (push to remote). Default: `get` |

### Wildcard / glob patterns

The `remote_path` field supports glob patterns for `get` actions, allowing you to fetch multiple files with a single entry:

```json
{
  "remote_path": "stories/**/*",
  "local_path": "stories",
  "action": "get"
}
```

Supported patterns:
- `*` — matches any file in a single directory (e.g., `docs/*.md`)
- `**/*` — matches files recursively across directories (e.g., `stories/**/*`)
- `?` — matches a single character (e.g., `chapter?.md`)
- `[seq]` — matches any character in the set (e.g., `file[0-9].txt`)

When using globs, `local_path` acts as the **destination directory**. Matched files preserve their directory structure relative to the non-glob prefix of the pattern. For example:

| Pattern | Matched remote file | `local_path` | Written to |
|---|---|---|---|
| `stories/**/*` | `stories/ch1/intro.md` | `mystories` | `mystories/ch1/intro.md` |
| `Global/*.gitignore` | `Global/Vim.gitignore` | `ignores` | `ignores/Vim.gitignore` |
| `*.md` | `README.md` | `docs` | `docs/README.md` |

### Local path resolution

- **Relative paths** (e.g., `guide.md`) resolve relative to `docs/source/shared/`.
- **Absolute paths** (starting with `/`, e.g., `/src/docs/guide.md`) resolve relative to the project root.

### Git ignore

On first run, `tlc-shared-docs get` creates `docs/source/shared/` with a `.gitignore` that tracks only `shared.json` — all fetched files are ignored so they don't bloat your repo.

The auto-generated `docs/source/shared/.gitignore` contains:

```gitignore
# Auto-generated by tlc-shared-docs
# Ignore all fetched shared files; only track the config
*
!.gitignore
!shared.json
```

This means:
- `shared.json` is committed to your repo (so teammates share the same config)
- All fetched/pushed doc files are ignored locally
- The `.gitignore` itself is also tracked

## Requirements

- Python 3.9+
- Git installed and on `PATH`
- Valid Git credentials for the source repo

