Have you ever found yourself struggling with sensitive files that shouldn't be committed to your main repository? Or perhaps you have common utilities that you reuse across projects but don't want to maintain multiple copies of? What if I told you there's a secret development pattern that can solve these problems and more?
Enter the side repository — a complementary codebase that works alongside your main project, offering a hidden chamber of possibilities that many developers overlook.
What Exactly Is a Side Repository?
A side repository is exactly what it sounds like: a secondary Git repository that exists parallel to your main project repository. It's not a fork or a branch, but a completely separate repository with its own history, purpose, and contents that somehow integrates with your primary codebase.
Think of it as your project's secret vault — a place to store valuable assets that don't belong in your main codebase but are still essential to your workflow.
Why You Might Need a Secret Chamber
You might be wondering: "My .gitignore works fine, why complicate things?" Here's where side repositories shine:
1. Sensitive Configuration Management
While .gitignore helps you avoid committing sensitive files, it doesn't help you share or back them up. A side repo can store:
-
.envfiles with different configurations - API keys and credentials
- Development certificates
- License files
All while keeping them organized and versioned, but separate from your main code.
2. Team Resources Without the Noise
Ever had to send a configuration file to a new team member or found yourself saying, "Oh, you need to create this file locally"? A side repo eliminates these friction points by providing:
- A shared storage for development tools
- Template configurations that new team members can access
- Documentation that doesn't belong in the main repo
3. Cross-Project Resource Management
Perhaps the most powerful use case is maintaining resources that span multiple projects:
- Shared scripts and utilities
- Common CI/CD configurations
- Design assets and templates
- Database seeds or fixtures
Making It Even Easier with git-popper
For those who want a more streamlined approach to managing side repositories, check out git-popper, a minimalist side repository manager that automates the integration between your main and side repositories.
This tool, available at https://github.com/francescobianco/git-popper, simplifies the entire process with a declarative approach:
## Use this as side repository
FROM https://github.com/your-side-repo.git
## Store and sync local files into this remote directory of the repository
WORKDIR projects/2025/myproject
## Sync local files into side repo to prevent losing secret files
ADD .env
ADD .secrets
ADD Makefile-dev
With git-popper, you can define which files to synchronize in a .gitpopper configuration file and use simple commands to maintain the connection between repositories:
git-popper sync # Synchronize changes between repositories
git-popper pull # Get latest changes from side repository
git-popper push # Push changes to side repository
It's an elegant solution that takes the manual work out of the patterns described below.
Setting Up Your Secret Chamber
Creating a side repository is straightforward:
- Create a new repository (private if it contains sensitive information)
- Structure it according to your needs
- Clone it alongside your main repository
projects/
├── main-project/ # Your main repository
└── main-project-side/ # Your side repository
Integration Patterns
There are several ways to integrate a side repository with your main project:
1. The Symlink Approach
Create symbolic links from your main project to files in your side repository:
ln -s ../main-project-side/config/.env .env
ln -s ../main-project-side/scripts ./scripts
2. The Copy-on-Setup Approach
Copy necessary files during project setup:
# In your setup script
cp -r ../main-project-side/config/* ./config/
3. The Automation Tool Approach
Create a simple script that manages synchronization:
#!/bin/bash
# sync-side-repo.sh
rsync -av --exclude='.git' ../main-project-side/shared/ ./
4. The Git Submodule Approach (Advanced)
For more sophisticated integration, Git submodules can link repositories:
git submodule add git@github.com:your-org/main-project-side.git side
Real-World Success Stories
At my company, we implemented a side repository pattern for our microservices architecture. Each service had its own repository, but we maintained a shared side repository containing:
- Common Docker configurations
- Shared authentication utilities
- Local development environment setup
- Database migration tools
This approach reduced duplication by 70% and cut onboarding time for new developers from days to hours.
Pitfalls to Avoid
Like any pattern, side repositories come with potential downsides:
- Drift - If not properly maintained, your side repo can become out of sync
- Dependency Management - Creating circular dependencies between repos
- Overuse - Using the side repo as a dumping ground for anything
Is a Side Repository Right for You?
A side repository makes the most sense when:
- You have sensitive configurations that need version control
- Your team frequently shares non-code resources
- You maintain similar setups across multiple projects
- You need controlled access to certain resources
If you're nodding your head to any of these points, it might be time to open your own secret chamber.
Getting Started Today
Begin small:
- Identify files that are currently in your
.gitignorebut would benefit from version control - Create a private repository
- Move those files there with a clear organization structure
- Implement one of the integration patterns described above or try git-popper for a more automated approach
You can install git-popper quickly with:
curl -fsSL https://raw.githubusercontent.com/francescobianco/git-popper/main/bin/git-popper | sudo tee /usr/local/bin/git-popper > /dev/null && sudo chmod +x /usr/local/bin/git-popper
Conclusion
The side repository pattern isn't revolutionary, but it's remarkably effective. It provides a clean separation of concerns, keeps your main repository focused, and solves common development workflow issues that every team faces.
Have you used side repositories in your projects? What integration patterns worked best for you? Share your experiences in the comments!
Francesco Bianco is a senior developer with over a decade of experience optimizing development workflows and architecture patterns across enterprise applications.
Top comments (0)