tlc-shared-docs 0.1.0

Share documentation files between Git repositories

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

pip install tlc-shared-docs

Quick Start

1. Create the config

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

{
  "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

tlc-shared-docs get

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

3. Push local files

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:

tlc-shared-docs push --force

4. Preview changes

Both commands support --dry-run:

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:

{
  "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:

# 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