microsoft/hve-core

Public

mirrored from https://github.com/microsoft/hve-coreAvailable

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

hve-core-v2.3.4

Find a branch or tag

Branches

hve-core-v2.3.4

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/submodule.md

259lines · modeblame

Raw Download

Latest commit unavailable.

unknown

`6329fc0d`Bill Berry7 months ago	1	`---`
	2	`title: Git Submodule Installation`
	3	`description: Set up HVE-Core as a git submodule for version-controlled team consumption`
	4	`author: Microsoft`
	5	`ms.date: 2025-12-02`
	6	`ms.topic: how-to`
	7	`keywords:`
	8	`- git submodule`
	9	`- installation`
	10	`- github copilot`
	11	`- version control`
	12	`- teams`
	13	`estimated_reading_time: 7`
	14	`---`
	15
	16	`Git submodules provide version-controlled, reproducible HVE-Core consumption. Every team member gets the exact same version, and updates are explicit commits.`
	17
	18	`## When to Use This Method`
	19
	20	`✅ Use this when:`
	21
	22	`* Your team needs reproducible setups (same version for everyone)`
	23	`* You want to pin HVE-Core to a specific version`
	24	`* Updates should be deliberate, reviewed commits`
	25	`* HVE-Core dependency should be tracked in version control`
	26
	27	`❌ Consider alternatives when:`
	28
	29	`* You want automatic updates → [Multi-Root Workspace](multi-root.md)`
	30	`* You're a solo developer without version pinning needs → [Multi-Root Workspace](multi-root.md)`
	31
	32	`## How It Works`
	33
	34	A git submodule embeds HVE-Core as a nested repository within your project. The `.gitmodules` file tracks the repository URL, and your project's git history tracks the exact commit.
	35
	36	```text
	37	`your-project/`
	38	`├── .gitmodules ← Defines submodule URL`
	39	`├── lib/`
	40	`│ └── hve-core/ ← Submodule (points to specific commit)`
	41	`│ └── .github/`
`712b0b7b`Allen Greaves5 months ago	42	`│ ├── agents/`
`6329fc0d`Bill Berry7 months ago	43	`│ ├── prompts/`
	44	`│ └── instructions/`
	45	`└── .vscode/`
	46	`└── settings.json ← Points to lib/hve-core paths`
	47	```
	48
	49	`## Quick Start`
	50
	51	Use the `hve-core-installer` agent:
	52
	53	1. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
	54	2. Select `hve-core-installer` from the agent picker
	55	`3. Say: "Install HVE-Core using git submodule"`
	56	`4. Follow the guided setup`
	57
	58	`## Manual Setup`
	59
	60	`### Step 1: Add the Submodule`
	61
	62	```bash
	63	`# From your project root`
	64	`git submodule add https://github.com/microsoft/hve-core.git lib/hve-core`
	65	`git commit -m "Add HVE-Core as submodule"`
	66	```
	67
	68	This creates a `.gitmodules` file:
	69
	70	```ini
	71	`[submodule "lib/hve-core"]`
	72	`path = lib/hve-core`
	73	`url = https://github.com/microsoft/hve-core.git`
	74	`branch = main`
	75	```
	76
	77	`### Step 2: Configure VS Code Settings`
	78
	79	Create or update `.vscode/settings.json`:
	80
	81	```jsonc
	82	`{`
`67fb2ab0`Copilot5 months ago	83	`"chat.agentFilesLocations": {`
`712b0b7b`Allen Greaves5 months ago	84	`"lib/hve-core/.github/agents": true,`
`712b0b7b`Allen Greaves5 months ago	85	`".github/agents": true`
`6329fc0d`Bill Berry7 months ago	86	`},`
	87	`"chat.promptFilesLocations": {`
	88	`"lib/hve-core/.github/prompts": true,`
	89	`".github/prompts": true`
	90	`},`
	91	`"chat.instructionsFilesLocations": {`
	92	`"lib/hve-core/.github/instructions": true,`
	93	`".github/instructions": true`
	94	`}`
	95	`}`
	96	```
	97
	98	`### Step 3: Configure Devcontainer (Codespaces)`
	99
	100	Update `.devcontainer/devcontainer.json` to initialize submodules automatically:
	101
	102	```jsonc
	103	`{`
	104	`"name": "My Project with HVE-Core",`
	105	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
	106
	107	`"onCreateCommand": "git submodule update --init --recursive",`
	108
	109	`"customizations": {`
	110	`"vscode": {`
	111	`"extensions": [`
	112	`"github.copilot",`
	113	`"github.copilot-chat"`
	114	`]`
	115	`}`
	116	`}`
	117	`}`
	118	```
	119
	120	`## Team Member Onboarding`
	121
	122	`When team members clone your project, they need to initialize submodules.`
	123
	124	`Option A: Clone with submodules (recommended):`
	125
	126	```bash
	127	`git clone --recurse-submodules https://github.com/your-org/your-project.git`
	128	```
	129
	130	`Option B: Initialize after clone:`
	131
	132	```bash
	133	`git clone https://github.com/your-org/your-project.git`
	134	`cd your-project`
	135	`git submodule update --init --recursive`
	136	```
	137
	138	`Option C: Configure git to auto-recurse:`
	139
	140	```bash
	141	`git config --global submodule.recurse true`
	142	`# Now all git operations auto-update submodules`
	143	```
	144
	145	`## Updating HVE-Core`
	146
	147	`\| Task \| Command \|`
	148	`\|------------------------\|-----------------------------------------------------------------------\|`
	149	\| Check for updates \| `cd lib/hve-core && git fetch && git log HEAD..origin/main --oneline` \|
150	\| Update to latest \| `git submodule update --remote lib/hve-core` \|
151	\| Pin to specific commit \| `cd lib/hve-core && git checkout <sha>` \|
152	\| Track different branch \| `git config submodule.lib/hve-core.branch develop` \|
153
154	`After updating, commit the change:`
155
156	```bash
157	`git add lib/hve-core`
158	`git commit -m "Update HVE-Core submodule to latest"`
159	```
160
161	`### Auto-Update on Container Rebuild`
162
163	`To update HVE-Core when rebuilding your devcontainer:`
164
165	```jsonc
166	`{`
167	`"updateContentCommand": "git submodule update --remote lib/hve-core \|\| true"`
168	`}`
169	```
170
171	`## Version Pinning`
172
173	`Submodules pin to a specific commit by default. To verify or change the pinned version:`
174
175	`Check current version:`
176
177	```bash
178	`cd lib/hve-core`
179	`git log -1 --oneline`
180	```
181
182	`Pin to a specific tag or commit:`
183
184	```bash
185	`cd lib/hve-core`
186	`git checkout v1.2.0 # or a specific commit SHA`
187	`cd ..`
188	`git add lib/hve-core`
189	`git commit -m "Pin HVE-Core to v1.2.0"`
190	```
191
192	`## Verification`
193
194	`After setup, verify HVE-Core is working:`
195
196	1. Check `lib/hve-core/` contains the HVE-Core repository
197	2. Open Copilot Chat (`Ctrl+Alt+I`)
198	`3. Click the agent picker dropdown`
199	`4. Verify HVE-Core agents appear (task-planner, task-researcher, etc.)`
200
201	`## Troubleshooting`
202
203	`### Submodule folder is empty`
204
205	`The submodule wasn't initialized:`
206
207	```bash
208	`git submodule update --init --recursive`
209	```
210
211	`### Agents not appearing`
212
213	* Check settings paths: Verify `.vscode/settings.json` paths match submodule location
214	* Reload window: `Ctrl+Shift+P` → "Developer: Reload Window"
`712b0b7b`Allen Greaves5 months ago	215	* Verify submodule content: `ls lib/hve-core/.github/agents/`
`6329fc0d`Bill Berry7 months ago	216
	217	`### "Detached HEAD" warning in submodule`
	218
	219	`This is normal for submodules. The submodule points to a specific commit, not a branch. To work on the submodule:`
	220
	221	```bash
	222	`cd lib/hve-core`
	223	`git checkout main`
	224	```
	225
	226	`### Merge conflicts in submodule pointer`
	227
	228	`When multiple team members update the submodule:`
	229
	230	```bash
	231	`git checkout --theirs lib/hve-core # Accept their version`
	232	`# OR`
	233	`git checkout --ours lib/hve-core # Keep your version`
	234	`git add lib/hve-core`
	235	`git commit`
	236	```
	237
	238	`## Comparison with Other Methods`
	239
`5113e3ba`Allen Greaves6 months ago	240	`\| Aspect \| Submodule \| Multi-Root \| Clone \|`
	241	`\|----------------------\|---------------------\|-------------------\|---------------\|`
	242	`\| Version controlled \| ✅ Yes \| ⚠️ Partial \| ❌ No \|`
	243	`\| Team reproducibility \| ✅ Same version \| ⚠️ May vary \| ⚠️ May vary \|`
	244	`\| Update control \| ✅ Explicit commits \| ⚠️ Automatic \| ⚠️ Automatic \|`
	245	`\| In workspace \| ✅ Subfolder \| ✅ Workspace root \| ❌ External \|`
	246	`\| Initial setup \| 🟡 Medium \| 🟡 Medium \| 🟢 Easy \|`
`6329fc0d`Bill Berry7 months ago	247
	248	`## Next Steps`
	249
	250	`* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task`
	251	`* [RPI Workflow](../../rpi/README.md) - Research, Plan, Implement methodology`
	252	`* [Back to Installation Guide](../install.md) - Compare other methods`
	253
	254	`---`
	255
	256	`<!-- markdownlint-disable MD036 -->`
`b4e75565`Bill Berry5 months ago	257	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
`6329fc0d`Bill Berry7 months ago	258	`then carefully refined by our team of discerning human reviewers.*`
`6329fc0d`Bill Berry7 months ago	259	`<!-- markdownlint-enable MD036 -->`

microsoft/hve-core

Branches

Tags

Clone