GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

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

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
dabed001c8ac7da3f2e4368ae1f279080c627cbd

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/submodule.md

281lines · modecode

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