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
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.
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 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:
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.
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
Git Multiple Paths
GitHub Web URL
From Sources File
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