How to Manage Branches
If you need to work with Infrahub's branch-based version control system, this guide shows you how to create, delete, and manage branches using the VSCode extension.
Prerequisites
- Infrahub VSCode extension installed
- At least one configured Infrahub server
- Appropriate permissions to create/delete branches on your server
Step 1: View existing branches
To see all branches on a server:
- Open the Infrahub icon in the Activity Bar
- Expand the "Infrahub Servers" tree view
- Click on your server to expand it
- You'll see all branches listed with:
- Branch name
- "(default)" marker for the main branch
- Branch metadata when available
Step 2: Create a new branch
From the tree view
- Right-click on your server in the Infrahub Servers view
- Select New Branch from the context menu
- Enter the branch name (for example, "feature-network-update")
- Optionally add a description
- Press Enter to create the branch
Naming conventions
Follow these branch naming patterns for clarity:
feature-[description]
- New featuresfix-[issue-number]
- Bug fixesupdate-[component]
- Updates to existing componentstest-[scenario]
- Testing branchesdev-[username]
- Personal development branches
Example: feature-datacenter-schema
Step 3: Delete a branch
To remove a branch you no longer need:
- Expand your server in the tree view
- Right-click on the branch to delete
- Select Delete Branch
- Confirm the deletion when prompted
Warning: Branch deletion is permanent. Ensure you've merged or saved any important changes before deleting.
Step 4: Work with branch-specific data
Execute queries on specific branches
When running GraphQL queries:
- Right-click on a query in the Infrahub YAML view
- Select Execute GraphQL Query
- Choose your server
- Select the target branch from the list
- The query runs against that branch's data
Compare data across branches
To compare data between branches, execute the same query on different branches:
query BranchComparison {
NetworkDevice {
count
edges {
node {
hostname {
value
}
_updated_at
}
}
}
}
Run this query on:
- Main branch - baseline data
- Feature branch - modified data
- Compare the results to see differences
Step 5: Branch workflow examples
Feature development workflow
-
Create Feature Branch
Name: feature-add-firewall-schema
Description: Adding firewall device schema and relationships -
Develop and Test
- Modify schemas
- Test queries against the branch
- Validate changes
-
Merge Process
- Review changes
- Merge via Infrahub UI or API
- Delete feature branch after merge
Hotfix workflow
-
Create Hotfix Branch
Name: fix-device-status-issue
Description: Urgent fix for device status validation -
Apply Fix
- Make necessary corrections
- Test on hotfix branch
-
Deploy
- Merge to main
- Verify fix
- Clean up branch
Step 6: Advanced branch management
Working with long-lived branches
For branches that persist over time:
# Document branch purposes in your project
# branches.yml
branches:
- name: develop
purpose: Integration branch for ongoing development
merge_target: main
- name: staging
purpose: Pre-production testing
merge_target: main
- name: feature-q4-updates
purpose: Q4 feature development
merge_target: develop
Branch metadata tracking
Track branch information in your queries:
query BranchInfo {
Branch {
edges {
node {
name
description
created_at
branched_from
is_default
has_schema_changes
}
}
}
}
Validation
To ensure branch operations are working:
- Creation Verification: New branch appears in tree view immediately
- Query Testing: Execute a query against the new branch
- Deletion Confirmation: Deleted branch disappears from tree view
- Refresh Check: Tree view updates every 10 seconds automatically
Best practices
Branch lifecycle
- Create with descriptive names
- Develop in isolation
- Test thoroughly on the branch
- Review changes before merging
- Merge when ready
- Delete after successful merge
Naming strategy
Use consistent prefixes:
feature-
for new functionalityfix-
for bug fixesupdate-
for updatestest-
for experimentsrelease-
for release preparation
Documentation
Document active branches:
## Active Branches
### feature-network-redesign
- **Created**: 2024-01-15
- **Owner**: Network Team
- **Purpose**: Redesigning network schema for multi-vendor support
- **Target Merge**: 2024-02-01
### fix-validation-error
- **Created**: 2024-01-20
- **Owner**: DevOps
- **Purpose**: Fix schema validation for IP addresses
- **Target Merge**: ASAP
Troubleshooting
Branch creation fails
- Check server permissions
- Verify branch name doesn't already exist
- Ensure valid characters in branch name (alphanumeric, hyphens, underscores)
Branch not appearing
- Wait 10 seconds for automatic refresh
- Manually reload VSCode window if needed
- Check server connectivity
Cannot delete branch
- Verify you have deletion permissions
- Ensure branch isn't protected
- Check if branch is the default branch (cannot be deleted)