1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
# gitgrip Manifest Schema Specification
# Version: 1
#
# This document describes the structure of a gitgrip gripspace.yml file.
# The workspace file defines a multi-repository workspace configuration.
# Schema version (required)
version: 1
# Gripspace includes (optional)
# Include repos, scripts, env, hooks, and linkfiles from other gripspace repositories.
# Gripspaces are cloned into .gitgrip/spaces/<name>/ and their manifests are merged.
# Local manifest values always win on conflict.
# Supports recursive includes (max depth: 5) with cycle detection.
gripspaces:
- url: "https://github.com/org/base-gripspace.git"
rev: "main" # Optional: pin to branch/tag/commit (default: remote HEAD)
# Manifest repository self-tracking (optional)
# If specified, gitgrip will include the manifest repo in sync/branch/push operations
manifest:
# Git URL for the manifest repository (required)
url: "git@github.com:org/workspace-manifest.git"
# Default branch (defaults to "main")
default_branch: "main"
# Files to copy from manifest repo to workspace root (optional)
copyfile:
- src: "envsetup.sh" # Source path relative to manifest repo
dest: "envsetup.sh" # Destination path relative to workspace root
# Symlinks from workspace to manifest repo (optional)
linkfile:
- src: "config/shared.yaml"
dest: ".config/shared.yaml"
# Composed files (optional)
# Generate files by concatenating parts from gripspaces and/or local manifest repo.
# Processed on every `gr sync` and `gr link --apply`.
composefile:
- dest: "CLAUDE.md" # Destination path relative to workspace root
separator: "\n\n" # Optional separator between parts (default: "\n\n")
parts:
- gripspace: "base-gripspace" # Read from .gitgrip/spaces/base-gripspace/
src: "CODI.md" # Source path relative to gripspace root
- src: "PRIVATE_DOCS.md" # Read from manifest content dir (spaces/main/ or manifests/)
# Platform override for self-hosted instances (optional)
platform:
type: "github" # github, gitlab, azure-devops, bitbucket
base_url: "https://github.mycompany.com"
# Repository definitions (required, at least one)
repos:
# Key is the repository name used in gitgrip commands
frontend:
# Git URL - SSH or HTTPS (required)
url: "git@github.com:org/frontend.git"
# Local path relative to workspace root (required)
path: "./frontend"
# Default branch (defaults to "main")
default_branch: "main"
# Groups for selective operations (optional)
# Use with: gr sync --group=core
groups:
- core
- web
# Mark as reference/read-only repo (optional, defaults to false)
# Reference repos are synced but excluded from branch/commit/PR operations
reference: false
# Platform override (optional, auto-detected from URL)
platform:
type: "github"
base_url: null # Only needed for self-hosted instances
# Files to copy after clone/sync (optional)
copyfile:
- src: "README.md"
dest: "docs/FRONTEND_README.md"
# Symlinks to create (optional)
linkfile:
- src: ".env.example"
dest: ".env"
# Agent context for AI tools (optional)
# Machine-readable metadata for AI coding agents
agent:
description: "React web frontend"
language: "typescript"
build: "pnpm build"
test: "pnpm test"
lint: "pnpm lint"
format: "pnpm format"
backend:
url: "git@github.com:org/backend.git"
path: "./backend"
groups:
- core
- api
agent:
description: "Rust API server"
language: "rust"
build: "cargo build"
test: "cargo test"
lint: "cargo clippy"
format: "cargo fmt"
# Reference repositories (read-only)
reference-lib:
url: "https://github.com/external/lib.git"
path: "./ref/lib"
reference: true # Excluded from branch/commit operations
# Global settings (optional)
settings:
# Prefix for PR titles (defaults to "[cross-repo]")
pr_prefix: "[cross-repo]"
# Merge strategy for linked PRs
# all-or-nothing: All PRs must merge together or none
# independent: Each PR can be merged separately
merge_strategy: "all-or-nothing"
# Workspace configuration (optional)
# Includes scripts, hooks, env, CI, and agent metadata
workspace:
# Environment variables available to workspace scripts
env:
NODE_ENV: "development"
WORKSPACE_NAME: "myproject"
# Named scripts runnable via `gr run <name>`
scripts:
build:
description: "Build all packages"
command: "npm run build"
cwd: "." # Working directory (optional)
test:
description: "Run all tests"
# Multi-step scripts
steps:
- name: "Lint"
command: "npm run lint"
cwd: "./frontend"
- name: "Unit tests"
command: "npm test"
- name: "Integration tests"
command: "npm run test:integration"
# Lifecycle hooks (optional)
hooks:
# Run after `gr sync`
post-sync:
- command: "npm install"
cwd: "./frontend"
- command: "cargo build"
cwd: "./backend"
# Run after `gr checkout`
post-checkout:
- command: "./scripts/setup-env.sh"
# CI/CD pipelines runnable via `gr ci run <name>`
ci:
pipelines:
test:
description: "Run full test suite"
steps:
- name: "Install dependencies"
command: "npm ci"
- name: "Run tests"
command: "npm test"
continue_on_error: false
- name: "Upload coverage"
command: "npm run coverage:upload"
env:
COVERAGE_TOKEN: "${COVERAGE_TOKEN}"
# Agent context for AI tools (optional)
# Workspace-level metadata for AI coding agents
agent:
description: "Multi-repo web application workspace"
conventions:
- "Use conventional commits (feat:, fix:, chore:)"
- "All PRs require review before merge"
- "Use gr commands, never raw git"
workflows:
deploy: "gr pr merge && ./scripts/deploy.sh"
release: "gr run release"
# Supported platform types:
# - github: GitHub.com or GitHub Enterprise
# - gitlab: GitLab.com or self-hosted GitLab
# - azure-devops: Azure DevOps (dev.azure.com) or Azure DevOps Server
# - bitbucket: Bitbucket Cloud or Bitbucket Server
# Path rules:
# - Paths must be relative to workspace root
# - Paths cannot start with ".." or "/"
# - Paths cannot contain "/../"
# - These rules prevent directory traversal attacks