Adding Documentation from Git Repositories

Learn how to add and manage documentation from git repositories in OpenGround

Overview

OpenGround can extract documentation directly from git repositories using shallow clones and sparse checkout for efficiency. This is ideal for versioned documentation that uses git tags.

Supported File Types

When extracting from git repositories, OpenGround processes the following file extensions:

• .md - Markdown
• .mdx - MDX (Markdown with JSX)
• .rst - reStructuredText
• .txt - Plain text
• .ipynb - Jupyter Notebooks
• .html - HTML
• .htm - HTML

Basic Usage

1. Add documentation with source URL

   Use the add command with the --source flag to specify a git repository:

   openground add library-name \
     --source https://github.com/example/example.git \
     -y
   

   The -y flag skips the confirmation prompt between extract and ingest.

2. Verify the library was added

   List all libraries in your database:

   openground list-libraries
   # or
   openground ls
   

Specifying Documentation Paths

If documentation is in a specific subdirectory, use the --docs-path flag:

openground add fastapi \
  --source https://github.com/tiangolo/fastapi.git \
  --docs-path docs/ \
  -y

Multiple Documentation Paths

You can specify multiple paths by using the --docs-path flag multiple times:

openground add library-name \
  --source https://github.com/example/example.git \
  --docs-path docs/ \
  --docs-path wiki/ \
  --docs-path guides/ \
  -y

Indexing Entire Repository

If you don’t specify --docs-path, OpenGround will index the entire repository:

# Indexes all supported files in the repository
openground add library-name \
  --source https://github.com/example/example.git \
  -y

Version Management

Using Git Tags

The --version flag allows you to specify a git tag to checkout:

openground add fastapi \
  --source https://github.com/tiangolo/fastapi.git \
  --docs-path docs/ \
  --version v0.109.0 \
  -y

This corresponds to the tag in the git repository (e.g., v0.109.0, 1.0.0, etc.).

Default Version

If no version is specified, OpenGround defaults to latest:

# Uses version "latest"
openground add library-name \
  --source https://github.com/example/example.git \
  -y

Multiple Versions

You can store multiple versions of the same library independently:

# Add version 1.0.0
openground add mylib \
  --source https://github.com/example/mylib.git \
  --version v1.0.0 \
  -y

# Add version 2.0.0
openground add mylib \
  --source https://github.com/example/mylib.git \
  --version v2.0.0 \
  -y

# Query specific version
openground query "how to install" --library mylib --version v1.0.0

The --version flag only works with git repositories. Sitemap sources always use latest, and local path sources use date-based versions (e.g., local-2026-02-28).

Parsing GitHub Web URLs

OpenGround can automatically parse GitHub and GitLab web URLs:

# Web URL with branch/tag and path
openground add library-name \
  --source https://github.com/user/repo/tree/v1.0/docs \
  -y

OpenGround will automatically extract:

• Repository URL: https://github.com/user/repo.git
• Version: v1.0
• Docs path: docs

All Available Flags

openground add LIBRARY [OPTIONS]

Arguments

• LIBRARY - Name of the library (required)

Options

• --source, -s TEXT - Git repo URL (e.g., https://github.com/user/repo.git)
• --version, -v TEXT - Git tag to checkout (e.g., v1.0.0, defaults to latest)
• --docs-path, -d TEXT - Path(s) to documentation within the repo (can be specified multiple times)
• --yes, -y - Skip confirmation prompt between extract and ingest
• --sources-file TEXT - Path to a custom sources.json file

The following flags are for sitemap sources only and are ignored for git repositories:

• --filter-keyword, -f - Not applicable to git repos
• --trim-query-params - Not applicable to git repos

Using Sources Files

When you add documentation with --source, OpenGround automatically saves the configuration to ~/.openground/sources.json. This allows you to re-add or update the library later using just the name:

1. First time: Add with source

   openground add fastapi \
     --source https://github.com/tiangolo/fastapi.git \
     --docs-path docs/ \
     --version v0.109.0 \
     -y
   

   This saves the configuration to ~/.openground/sources.json.

2. Later: Add by name only

   # Uses saved configuration
   openground add fastapi --version v0.110.0 -y
   

   The source URL and docs path are retrieved from sources.json.

See Managing sources.json files for more details.

Updating Documentation

To update an existing library with changes from the source:

openground update library-name --version latest -y

This efficiently updates only changed pages by comparing content hashes. The update command is an alias for add when a library already exists.

Git with Version

openground add fastembed \
  --source https://github.com/qdrant/fastembed.git \
  --docs-path docs/ \
  --version v0.7.4 \
  -y

Advanced: Direct Extract Command

For advanced use cases, you can use the extract-git command separately:

openground extract-git \
  --repo-url https://github.com/example/example.git \
  --docs-path docs/ \
  --library library-name \
  --version v1.0.0

Then embed separately:

openground embed library-name --version v1.0.0

The extract-git command requires at least one --docs-path argument. Use / to extract the entire repository.

Examples

FastAPI Documentation

openground add fastapi \
  --source https://github.com/tiangolo/fastapi.git \
  --docs-path docs/ \
  --version v0.109.0 \
  -y

Multiple Versions Workflow

# Add stable version
openground add myframework \
  --source https://github.com/org/myframework.git \
  --docs-path documentation/ \
  --version v3.2.1 \
  -y

# Add latest development version
openground add myframework \
  --source https://github.com/org/myframework.git \
  --docs-path documentation/ \
  --version latest \
  -y

# Query specific version
openground query "authentication" --library myframework --version v3.2.1

Entire Repository

# Index all markdown files in repository
openground add awesome-project \
  --source https://github.com/user/awesome-project.git \
  -y