Git Branch Management and Project Initialization

January 22, 2025 (1y ago) · 4 min read

DevOps

Originally published on LinkedIn, 22 January 2025. Republished here with light editing.

Table of Contents#

  1. Project Background and Problem Statement
  2. Branch Merging Workflow
  3. Resolving Merge Conflicts
  4. Pull Request Operations
  5. Best Practices and Considerations

1. Project Background and Problem Statement#

In real-world development scenarios, we often encounter situations where multiple branches need to be merged. This tutorial is based on a practical case study where a project has two branches (main and master):

  • main branch: Initially created, containing project documentation
  • master branch: Subsequently created, containing project initialization files

The objective is to merge these branches and ultimately maintain only the main branch as the primary branch.

2. Branch Merging Workflow#

2.1 Basic Merge Commands#

# 1. Confirm current branch
git checkout main
 
# 2. Check branch status
git status
 
# 3. Attempt branch merge
git merge master

2.2 Handling Unrelated Histories#

If you encounter the following error:

fatal: refusing to merge unrelated histories

This indicates that the two branches have no common commit history. Solution:

git merge master --allow-unrelated-histories

3. Resolving Merge Conflicts#

3.1 Conflict Identification#

When executing the merge command, you might encounter a message like this:

Auto-merging .gitignore
CONFLICT (add/add): Merge conflict in .gitignore
Automatic merge failed; fix conflicts and then commit the result.

3.2 Conflict Resolution Steps#

  1. Open the conflicting file and locate conflict markers:
<<<<<<< HEAD
(content from current branch)
=======
(content from branch being merged)
>>>>>>> master

2. Content Integration Example (using .gitignore):

# Compiled class file
*.class

# Log file
*.log

# BlueJ files
*.ctxt

# Mobile Tools for Java (J2ME)
.mtj.tmp/

# Package Files #
*.jar
*.war
*.nar
*.ear
*.zip
*.tar.gz
*.rar

# Virtual machine crash logs
hs_err_pid*
replay_pid*

# Build targets
target/
!.mvn/wrapper/maven-wrapper.jar
!**/src/main/**/target/
!**/src/test/**/target/

### IntelliJ IDEA ###
.idea/modules.xml
.idea/jarRepositories.xml
.idea/compiler.xml
.idea/libraries/
*.iws
*.iml
*.ipr

### Eclipse ###
.apt_generated
.classpath
.factorypath
.project
.settings
.springBeans
.sts4-cache

### NetBeans ###
/nbproject/private/
/nbbuild/
/dist/
/nbdist/
/.nb-gradle/
build/
!**/src/main/**/build/
!**/src/test/**/build/

### VS Code ###
.vscode/

### Mac OS ###
.DS_Store

3. Commit resolved conflicts:

git add .gitignore
git commit -m "Merge master into main: resolve .gitignore conflict"
git push origin main

4. Pull Request Operations#

4.1 Creating a Pull Request#

  • Select branches to compare in the GitHub interface
  • Provide a meaningful title and description for the Pull Request

4.2 Pull Request Example#

Title:

Sync changes from main to master branch and merge code

Description:

## Purpose
Synchronize contents between main and master branches to combine project documentation with initialization files.

## Changes included
- Merge documentation files from main branch
- Combine .gitignore configurations
- Include initial project setup files
- Update README.md and other documentation

## Notes
- This sync will help maintain consistent content across branches
- After successful merge, we plan to keep only the main branch as the primary branch

5. Best Practices and Considerations#

5.1 Project Initialization Recommendations#

  1. Determine the primary branch name (main or master) before project creation
  2. Create a .gitignore file with appropriate rules based on project type
  3. Maintain and update project documentation (README.md, etc.) regularly

5.2 Branch Management Guidelines#

  1. Define clear branch purposes and avoid unnecessary branch creation
  2. Synchronize and clean up branches regularly
  3. Maintain consistent and meaningful branch naming conventions
  4. Back up important operations before execution

5.3 Merge Operation Precautions#

  1. Verify current branch status before merging
  2. Carefully review all changes when resolving conflicts
  3. Write clear and descriptive commit messages
  4. Validate functionality after merging

5.4 Documentation Maintenance Guidelines#

  1. Keep project documentation up to date
  2. Document important operations and decisions
  3. Maintain clear documentation structure and complete content
  4. Add comments and explanations when appropriate

Conclusion#

This tutorial, based on real project experience, provides a detailed overview of Git branch management and project initialization. For beginners, we recommend:

  1. Understanding the purpose of each command
  2. Practicing these operations in small projects
  3. Carefully reading error messages when encountering issues
  4. Developing good version control habits

Through standardized Git operations and project management, you can make project development more organized and efficient. We hope this tutorial helps you better understand and use Git for project management.

This technical guide is designed to help developers better understand Git branch management and project initialization. Feel free to share and contribute your insights in the comments below.

LinkedIn