Complete Guide to SVN Trunk, Branches, and Tags

In Subversion repositories, the “trunk” represents the main development line where active code changes occur, “branches” are copies of the trunk used for parallel development or experimental features (which can be merged back), and “tags” are read-only snapshots of the repository at specific points in time, typically used to mark release versions. These directories are not technically enforced by Subversion but rather widely adopted conventions that help organize development workflows and maintain version history clarity.

Contents

• What Exactly Are Trunk, Branches, and Tags?
• The Technical Implementation: How SVN Handles These Directories
• Practical Usage and Best Practices
• Creating and Managing Branches and Tags
• Branch vs Tag: Key Differences and When to Use Each
• Advanced Repository Structures and Patterns

What Exactly Are Trunk, Branches, and Tags?

The “trunk,” “branches,” and “tags” directories in Subversion are conventions rather than technical requirements. As the Stack Overflow community explains, “in SVN the directory names themselves mean nothing — ‘trunk, branches and tags’ are simply a common convention that is used by most repositories.” Subversion doesn’t enforce any special meaning on these directories; it’s the development teams that assign semantic meaning to them through their workflows.

Trunk represents the main development line where all active changes occur. This is typically where your primary development happens and where features are integrated before release. The trunk is often considered the “stable” or “production-ready” branch that contains the latest working code.

Branches are created when you need to work on new features, bug fixes, or experiments without disrupting the main trunk development. According to Assembla’s best practices, “/branches are used in many ways, but most often to protect the development on /trunk.” Branches allow multiple developers to work in parallel on different features simultaneously.

Tags are essentially frozen snapshots of your codebase at specific points in time. As DevOpsSchool explains, “Every time you release a version (final release, release candidates (RC), and betas) you make a tag for it. This gives you a point-in-time copy of the code as it was at that state, allowing you to go back and reproduce any bugs if necessary in a past version, or re-release a past version exactly as it was.”

The Technical Implementation: How SVN Handles These Directories

Subversion implements branches and tags using a clever mechanism called “cheap copies” or “copy-on-write”. This is fundamentally different from traditional file copying systems. As stated in the official Subversion documentation, “Subversion does not have special commands for branching or tagging, but uses so-called ‘cheap copies’ instead.”

When you create a branch or tag, Subversion doesn’t duplicate all the files in your repository. Instead, it creates internal metadata that points to the specific revision and path where the original files exist. This means:

• Storage efficiency: Only a few bytes of metadata are added to the repository for each branch or tag, regardless of repository size
• Performance: Creating branches and tags is nearly instantaneous, even for very large repositories
• History preservation: The entire history of the original files is accessible through the new branch or tag

As TortoiseSVN documentation explains, “Cheap copies are similar to hard links in Unix, which means that instead of making a complete copy in the repository, an internal link is created, pointing to a specific tree/revision.”

This implementation has an important consequence: there’s no technical difference between a branch and a tag in Subversion. As the Subversion Book states, “Yes, in fact, it is. In Subversion, there’s no difference between a tag and a branch. Both are just ordinary directories that are created by copying.” The distinction is purely semantic and based on how your team uses and manages these directories.

Practical Usage and Best Practices

Standard Repository Structure

The most widely adopted repository structure follows the “project root” pattern recommended by the Subversion project. According to Apache Subversion’s official documentation, “A ‘project root’ contains exactly three subdirectories: /trunk, /branches, /tags.”

This structure typically looks like:

repository/
├── project1/
│   ├── trunk/
│   ├── branches/
│   └── tags/
├── project2/
│   ├── trunk/
│   ├── branches/
│   └── tags/

Trunk Usage Patterns

The trunk directory serves as the central development line. Best practices for trunk management include:

• Keep trunk stable: Only commit code that builds and passes tests
• Regular integration: Merge changes from branches back to trunk regularly
• Documentation: Maintain clear guidelines about what belongs in trunk vs branches
• Version control: Use tags from trunk to mark official releases

Branch Management Strategies

Branches should follow these best practices:

• Descriptive naming: Use meaningful branch names like feature-login-system or bugfix-memory-leak
• Regular cleanup: Delete merged branches to keep the repository clean
• Branch protection: Consider using repository hooks to prevent direct commits to trunk during development
• Merge tracking: Since Subversion 1.5, merge tracking helps manage the relationship between branches and trunk

Tagging Protocol

Tags should be treated as read-only snapshots:

• Release tagging: Create tags for every release (alpha, beta, RC, final)
• Consistent naming: Use version numbers like v1.0.0, v1.1.0-beta
• Never modify: Once created, tags should not be changed
• Tag early and often: Create tags for important milestones, not just final releases

As JavaRevisited blog emphasizes, “Main difference between branch and tag in subversion is that, tag is a read only copy of source code at any point and no further change on tag is accepted, while branch is mainly for development.”

Creating and Managing Branches and Tags

Creating Branches

To create a branch in Subversion, you need to copy the trunk (or another branch) to the branches directory:

# Create a branch from trunk
svn copy https://svn.example.com/project/trunk \
         https://svn.example.com/project/branches/feature-new-auth \
         -m "Creating new authentication feature branch"

This command creates a new directory feature-new-auth in the branches folder that contains a complete copy of the trunk at that specific revision.

Creating Tags

Creating tags follows the same pattern but uses the tags directory:

# Create a tag from trunk (typically before release)
svn copy https://svn.example.com/project/trunk \
         https://svn.example.com/project/tags/v1.0.0 \
         -m "Tagging release version 1.0.0"

Working with Branches

Once you’ve created a branch, developers can:

1. Check out the branch: svn checkout https://svn.example.com/project/branches/feature-new-auth
2. Make changes: Work on the feature as usual
3. Commit changes: All changes go to the branch, not trunk
4. Merge back when ready: Use svn merge to bring changes from branch to trunk

Managing the Repository

Over time, your repository structure might evolve. Consider these management practices:

• Regular cleanup: Delete merged branches to maintain repository hygiene
• Archive old projects: Move inactive projects to an archive structure
• Repository migration: Plan for migration to other version control systems if needed
• Access control: Use SVN’s access control to limit who can create/modify branches and tags

Branch vs Tag: Key Differences and When to Use Each

Fundamental Differences

While technically identical in Subversion, branches and tags serve different purposes:

When to Use Branches

Use branches when:

• You need to develop a new feature that will take time
• Multiple developers need to work on related changes
• You’re experimenting with significant changes
• You need to maintain parallel versions (like maintenance branches)
• You’re implementing bug fixes that shouldn’t block trunk development

When to Use Tags

Use tags when:

• You’re preparing a release (alpha, beta, final)
• You want to mark an important milestone
• You need to create a reproducible build for testing
• You want to preserve a specific state for historical reference
• You’re creating release candidates for distribution

Common Misconceptions

Many SVN users struggle with the conceptual differences between branches and tags because Subversion doesn’t enforce these distinctions technically. The key is to remember:

• Tags are conceptual - they represent points in time, not ongoing development
• Branches are active - they’re meant for continued development
• Both use the same mechanism - cheap copies via svn copy
• Enforcement is procedural - your team’s processes and conventions matter more than technical restrictions

As VersionsApp documentation notes, “To create a branch or tag, all you need to do is copy the entire trunk folder over to a new subfolder in the branches or tags folder.”

Advanced Repository Structures and Patterns

Beyond the Basic Three-Directory Structure

While the trunk/branches/tags pattern is standard, some projects benefit from more complex structures:

repository/
├── project/
│   ├── trunk/
│   ├── branches/
│   ├── tags/
│   ├── releases/          # For actual distribution files
│   ├── documentation/     # Project documentation
│   └── assets/           # Non-code assets

Multi-Project Repositories

For organizations managing multiple related projects:

repository/
├── core/
│   ├── trunk/
│   ├── branches/
│   └── tags/
├── webapp/
│   ├── trunk/
│   ├── branches/
│   └── tags/
└── mobile/
    ├── trunk/
    ├── branches/
    └── tags/

Environment-Specific Branches

Some teams create branches for different environments:

branches/
├── development/
├── testing/
├── staging/
└── production/

Feature Branch Workflow

A popular modern workflow involves:

1. Create feature branch from trunk
2. Develop feature in branch
3. Submit pull request for code review
4. Merge to trunk after approval
5. Create release tag from trunk

Maintenance Branches

For projects requiring long-term support:

branches/
├── main/                 # Current development
├── maintenance/1.x/      # For 1.x series bug fixes
└── maintenance/2.x/      # For 2.x series bug fixes

Repository Cleanup and Maintenance

Over time, repositories can become cluttered. Consider these practices:

• Regular branch pruning: Remove merged and obsolete branches
• Tag management: Archive old tags or move them to a separate structure
• Repository analysis: Use tools to identify unused branches and tags
• Migration planning: Plan for eventual migration to Git or other systems

As Server Stack Exchange suggests, you can create the initial structure programmatically:

svn mkdir -m "Creating basic directory structure" \
    file:///path/to/repo/trunk \
    file:///path/to/repo/tags \
    file:///path/to/repo/branches

Conclusion

Understanding the trunk, branches, and tags concept in Subversion is crucial for effective version control management. These directories, while technically just conventional naming patterns, form the foundation of most SVN workflows and provide essential structure for organizing development activities.

Key takeaways:

1. Trunk represents your main development line where active changes occur and should remain stable
2. Branches enable parallel development for features, experiments, and bug fixes without disrupting trunk
3. Tags create immutable snapshots of your codebase at specific points, typically used for releases
4. Technically identical: Both branches and tags use Subversion’s “cheap copy” mechanism and are just directories created by copying
5. Semantic difference: The real distinction lies in how your team uses and manages these directories procedurally

For best results, establish clear guidelines for when and how to create branches and tags, maintain consistent naming conventions, and regularly clean up obsolete branches to keep your repository organized and manageable. Consider your project’s specific needs when designing your repository structure, and don’t be afraid to adapt the basic trunk/branches/tags pattern to better suit your workflow.

Sources

1. What do “branch”, “tag” and “trunk” mean in Subversion repositories? - Stack Overflow
2. About “trunk”, “tags” & “branches” - VersionsApp Documentation
3. Subversion Best Practices - Apache Subversion
4. Trunk vs Branch vs Tag in Subversion/SVN - DevOpsSchool
5. Difference between trunk, tags and branches in SVN - JavaRevisited
6. Branching / Tagging - TortoiseSVN Documentation
7. Tags - Subversion Book
8. SVN Best Practices - Assembla Help Center
9. SVN tag and branch structure - Atlassian Documentation
10. How/when to create trunk, branches and tags directories in a new Subversion repository? - Server Fault