microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

1a96b7384cd85a53b6036e7275d391fcb75cd11d

Find a branch or tag

Branches

1a96b7384cd85a53b6036e7275d391fcb75cd11d

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/submodule.md

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

microsoft/hve-core

Branches

Tags

Clone