Skip to content

submodule.md

Latest commit

 

History

History
259 lines (192 loc) · 6.94 KB

submodule.md

File metadata and controls

259 lines (192 loc) · 6.94 KB
title Git Submodule Installation
description Set up HVE-Core as a git submodule for version-controlled team consumption
author Microsoft
ms.date 2025-12-02
ms.topic how-to
keywords
git submodule
installation
github copilot
version control
teams
estimated_reading_time 7

Git submodules provide version-controlled, reproducible HVE-Core consumption. Every team member gets the exact same version, and updates are explicit commits.

When to Use This Method

✅ Use this when:

  • Your team needs reproducible setups (same version for everyone)
  • You want to pin HVE-Core to a specific version
  • Updates should be deliberate, reviewed commits
  • HVE-Core dependency should be tracked in version control

❌ Consider alternatives when:

How It Works

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.

your-project/
├── .gitmodules          ← Defines submodule URL
├── lib/
│   └── hve-core/        ← Submodule (points to specific commit)
│       └── .github/
│           ├── agents/
│           ├── prompts/
│           └── instructions/
└── .vscode/
    └── settings.json    ← Points to lib/hve-core paths

Quick Start

Use the hve-core-installer agent:

  1. Open GitHub Copilot Chat (Ctrl+Alt+I)
  2. Select hve-core-installer from the agent picker
  3. Say: "Install HVE-Core using git submodule"
  4. Follow the guided setup

Manual Setup

Step 1: Add the Submodule

# From your project root
git submodule add https://github.com/microsoft/hve-core.git lib/hve-core
git commit -m "Add HVE-Core as submodule"

This creates a .gitmodules file:

[submodule "lib/hve-core"]
    path = lib/hve-core
    url = https://github.com/microsoft/hve-core.git
    branch = main

Step 2: Configure VS Code Settings

Create or update .vscode/settings.json:

{
  "chat.modeFilesLocations": {
    "lib/hve-core/.github/agents": true,
    ".github/agents": true
  },
  "chat.promptFilesLocations": {
    "lib/hve-core/.github/prompts": true,
    ".github/prompts": true
  },
  "chat.instructionsFilesLocations": {
    "lib/hve-core/.github/instructions": true,
    ".github/instructions": true
  }
}

Step 3: Configure Devcontainer (Codespaces)

Update .devcontainer/devcontainer.json to initialize submodules automatically:

{
  "name": "My Project with HVE-Core",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "onCreateCommand": "git submodule update --init --recursive",

  "customizations": {
    "vscode": {
      "extensions": [
        "github.copilot",
        "github.copilot-chat"
      ]
    }
  }
}

Team Member Onboarding

When team members clone your project, they need to initialize submodules.

Option A: Clone with submodules (recommended):

git clone --recurse-submodules https://github.com/your-org/your-project.git

Option B: Initialize after clone:

git clone https://github.com/your-org/your-project.git
cd your-project
git submodule update --init --recursive

Option C: Configure git to auto-recurse:

git config --global submodule.recurse true
# Now all git operations auto-update submodules

Updating HVE-Core

Task Command
Check for updates cd lib/hve-core && git fetch && git log HEAD..origin/main --oneline
Update to latest git submodule update --remote lib/hve-core
Pin to specific commit cd lib/hve-core && git checkout <sha>
Track different branch git config submodule.lib/hve-core.branch develop

After updating, commit the change:

git add lib/hve-core
git commit -m "Update HVE-Core submodule to latest"

Auto-Update on Container Rebuild

To update HVE-Core when rebuilding your devcontainer:

{
  "updateContentCommand": "git submodule update --remote lib/hve-core || true"
}

Version Pinning

Submodules pin to a specific commit by default. To verify or change the pinned version:

Check current version:

cd lib/hve-core
git log -1 --oneline

Pin to a specific tag or commit:

cd lib/hve-core
git checkout v1.2.0  # or a specific commit SHA
cd ..
git add lib/hve-core
git commit -m "Pin HVE-Core to v1.2.0"

Verification

After setup, verify HVE-Core is working:

  1. Check lib/hve-core/ contains the HVE-Core repository
  2. Open Copilot Chat (Ctrl+Alt+I)
  3. Click the agent picker dropdown
  4. Verify HVE-Core agents appear (task-planner, task-researcher, etc.)

Troubleshooting

Submodule folder is empty

The submodule wasn't initialized:

git submodule update --init --recursive

Agents not appearing

  • Check settings paths: Verify .vscode/settings.json paths match submodule location
  • Reload window: Ctrl+Shift+P → "Developer: Reload Window"
  • Verify submodule content: ls lib/hve-core/.github/agents/

"Detached HEAD" warning in submodule

This is normal for submodules. The submodule points to a specific commit, not a branch. To work on the submodule:

cd lib/hve-core
git checkout main

Merge conflicts in submodule pointer

When multiple team members update the submodule:

git checkout --theirs lib/hve-core  # Accept their version
# OR
git checkout --ours lib/hve-core    # Keep your version
git add lib/hve-core
git commit

Comparison with Other Methods

Aspect Submodule Multi-Root Clone
Version controlled ✅ Yes ⚠️ Partial ❌ No
Team reproducibility ✅ Same version ⚠️ May vary ⚠️ May vary
Update control ✅ Explicit commits ⚠️ Automatic ⚠️ Automatic
In workspace ✅ Subfolder ✅ Workspace root ❌ External
Initial setup 🟡 Medium 🟡 Medium 🟢 Easy

Next Steps

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.