When working with multiple remote repositories, especially when syncing changes from upstream (such as in a forked repository), it’s important to have a well-structured system for organizing and tracking branches. This ensures clarity, ease of maintenance, and the ability to manage branches effectively. In this post, we’ll walk through the decision-making process for setting up a clear naming convention and syncing branches between your repository and an upstream one.

The Problem: Syncing with Upstream Repositories

When you contribute to a project that’s not under your control (i.e., it’s an upstream repository), you often need to synchronize changes from that repository to your own. This process typically involves fetching changes from the upstream repository and pushing them to your origin (your repository), but things can get messy when:

1. The upstream repository has many branches.
2. You want to track multiple upstream branches without interfering with your existing workflow.
3. The upstream repository’s branch names could conflict with your own or have characters you want to avoid.

The goal is to safely and clearly sync branches from the upstream repository into your own repository without creating confusion or conflicts.

1. Key Challenges to Address

a. Avoiding Name Conflicts

One of the primary challenges is avoiding conflicts in branch names. If the upstream repository has branch names like main, develop, or release, these could collide with your own branches, especially if you’re working in a shared or collaborative project.

b. Handling Upstream Branches

Upstream repositories may not always follow the same naming conventions as your own. For example:

• Your repository might use main, while the upstream one uses master.
• You might have extra long or descriptive branch names, such as feature/add-new-feature.

Having a robust system for identifying where each branch originates from will keep things organized.

2. Approach to Solving the Problem

The idea is to create a system where upstream branches are mirrored in your repository with a clear, safe naming convention that avoids conflicts and is easy to manage.

Naming Scheme

We discussed two key alternatives for naming upstream branches:

1. Prefix-based naming:

   • This involves adding a prefix to the branch name, indicating the origin of the branch. For example:

     upstream.<domain>.<owner>.<project>.<branch>
     

   • Pros:

     • Keeps the naming system clear and prevents conflicts with your own branches.
     • Easy to identify the origin of the branch just by looking at the name.
     • Safe across different servers (GitHub, GitLab, etc.).

   • Cons:

     • Might look verbose, but the clarity it provides far outweighs this downside.

2. Hashing encoding:

   • An alternative to the prefix method involves using hashing to guarantee uniqueness for each upstream repository. This encoding ensures that no matter how complex the upstream URL or branch name, you have a unique identifier.

   • Pros:

     • Guarantees uniqueness across different upstream repositories.
     • Compact and avoids the need to use human-readable prefixes.

   • Cons:

     • Less human-readable (harder to interpret the name without decoding).
     • Adds unnecessary complexity for most cases.

   After considering these two methods, we decided that prefix-based naming was the cleaner and simpler option, which still provides clarity without the overhead of encoding.

Separator Choice

Another important consideration was the separator used between the components of the branch name.

1. Slash (/):

   • Often used in Git for grouping or folder-like structures (e.g., feature/xyz).
   • Problem: Since Git treats slashes as directory structures, it can cause unexpected behavior or interfere with the visibility of branches in some Git UIs.

2. Dash (-):

   • This is a popular separator in Git branch names (e.g., feature/add-new-feature).
   • Problem: The downside is that it can conflict with existing dash-separated names in project or organization names (e.g., awesome-project-name).

3. Dot (.):

   • After considering the pros and cons of dashes, we chose to use dots (.) as separators. The main reason for this is that dots do not have any special meaning in Git and do not conflict with other naming conventions.
   • Pros:
     • Clarity: Dots separate each component clearly (e.g., upstream.gitlab.company.project.main).
     • No conflict: Works well even when the project or org names contain dashes.
     • Professional appearance.
   • Cons:
     • None significant — dots work well in practice.

3. The Final Solution

Based on the discussion above, we arrived at the following strategy:

Step 1: Use Dots as Separators

We decided to use dots (.) to separate different parts of the branch name to avoid ambiguity and ensure clarity. The format for the branch names would look like this:

upstream.<domain>.<owner>.<project>.<branch>

For example:

upstream.gitlab.company.project.main

This naming scheme guarantees:

• Clarity in identifying where the branch originated.
• No name conflicts with your own branches.
• No special folder structure issues (as would happen with slashes).

Step 2: Push Upstream Branches to Origin

The following Bash script automates the process of fetching and pushing upstream branches to your origin with the new names:

#!/bin/bash

# Get upstream URL
UPSTREAM_URL=$(git remote get-url upstream)

# Extract server domain (without .com if present)
UPSTREAM_DOMAIN=$(echo "$UPSTREAM_URL" | sed -E 's#(https?://)?([^/]+)/.*#\2#' | sed 's/\.com$//')

# Extract owner and project
UPSTREAM_OWNER=$(basename -s .git $(dirname "$UPSTREAM_URL"))
UPSTREAM_PROJECT=$(basename -s .git "$UPSTREAM_URL")

# Compose the prefix
PREFIX="upstream.${UPSTREAM_DOMAIN}.${UPSTREAM_OWNER}.${UPSTREAM_PROJECT}"

# Fetch latest from upstream
git fetch upstream

# Push each upstream branch to origin with a namespaced branch name
for branch in $(git for-each-ref --format='%(refname:strip=3)' refs/remotes/upstream/); do
    remote_branch="${PREFIX}.${branch}"

    # Push upstream branch into origin with new name
    git push origin refs/remotes/upstream/${branch}:refs/heads/${remote_branch}
done

Explanation

• The script fetches all branches from the upstream repository.
• It then renames each branch with a new name that includes the upstream information (e.g., upstream.gitlab.company.project.main).
• The branches are pushed to origin, making it easy to track changes from upstream while keeping everything organized.

4. Conclusion

This strategy provides a clear and safe system for syncing upstream branches into your repository. By using dots as separators and a consistent naming convention, you can avoid conflicts and keep things simple. The solution:

• Is easy to implement.
• Helps avoid confusion about branch origins.
• Guarantees clarity and future-proofing.

While other strategies, like hashing, might offer uniqueness, they add unnecessary complexity for most use cases. Stick with dots and clear prefixes for the best results.

Final Thoughts

Managing multiple remotes and branches can become complex, but by establishing a clear, consistent naming convention, you can keep your Git workflows organized and efficient. This approach not only helps with upstream synchronization but also makes it easier for other developers to understand where each branch originated from, minimizing errors and confusion.

Let me know if you have any questions or additional suggestions! Happy Git syncing! 🚀

Note

This post was developed collaboratively between me and ChatGPT, an AI language model by OpenAI. The ideas, discussion, and final decisions were shaped through a process of interactive brainstorming and refinement. After that, final formatting and edition was done by hand. You can download a detailed discussion of the process.

#human-ai-collaboration