microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

hve-core-v2.3.6

Find a branch or tag

Branches

hve-core-v2.3.6

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/submodule.md

259lines · modecode

Raw Download

Latest commit unavailable.

unknown

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/`
42	`│ ├── agents/`
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	`{`
83	`"chat.agentFilesLocations": {`
84	`"lib/hve-core/.github/agents": true,`
85	`".github/agents": true`
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"
215	* Verify submodule content: `ls lib/hve-core/.github/agents/`
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
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 \|`
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 -->`
257	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
258	`then carefully refined by our team of discerning human reviewers.*`
259	`<!-- markdownlint-enable MD036 -->`
260

microsoft/hve-core

Branches

Tags

Clone